refactor(ida): decide IDA admission once for doctor and provider readiness (#10926)

* refactor(ida): decide IDA admission once for doctor and provider readiness

* refactor(ida): make both admission projections handle each refusal kind explicitly

* fix(ida): give doctor the runtime's repair for an invalid IDA registration
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 16:57:59 +08:00
1 parent 71c2843772
commit 7fe4c3ded5
5 files changed
+232 -91

No files matched your search

+83
View File
@@ -0,0 +1,83 @@
import { constants } from "node:fs";
import { access, stat } from "node:fs/promises";
import {
privateRuntimeRootCapability,
type PrivateRuntimeRootCapability,
} from "../process/PrivateRuntimeRoot.js";
import type { IdaConfiguration } from "./IdaConfiguration.js";
import { resolveIdaWorkspaceParent } from "./IdaWorkspace.js";
/** The repair for a workspaceRoot REA cannot create entries in. */
export const IDA_WORKSPACE_ROOT_REMEDIATION =
"Set workspaceRoot to an existing directory REA can create entries in, or omit it to use the system temporary directory; see docs/providers/ida-provider.md.";
/** Why IDA's local prerequisites refuse a parsed registration. */
export type IdaAdmissionRefusal =
| {
readonly kind: "private_workspace_unavailable";
readonly privacy: Extract<
PrivateRuntimeRootCapability,
{ readonly available: false }
>;
}
| { readonly kind: "workspace_unusable"; readonly reason: string };
/**
* IDA's admission of a parsed registration: the one decision doctor and the
* provider's readiness both project, so they cannot disagree. Attach mode
* needs nothing local. Headless mode needs private workspace authority and a
* workspace parent REA can create entries in. Nothing is created and IDA is
* not launched.
*/
export type IdaAdmission =
| {
readonly admitted: true;
/** The private workspace headless mode will allocate under. */
readonly workspace?: {
readonly root: string | undefined;
readonly proof: string;
};
}
| {
readonly admitted: false;
readonly workspaceRoot: string | undefined;
readonly refusal: IdaAdmissionRefusal;
};
export const admitIdaConfiguration = async (
configuration: IdaConfiguration,
): Promise<IdaAdmission> => {
if (configuration.mode !== "headless") return { admitted: true };
const root = configuration.workspaceRoot;
const privacy = privateRuntimeRootCapability();
if (!privacy.available)
return {
admitted: false,
workspaceRoot: root,
refusal: { kind: "private_workspace_unavailable", privacy },
};
const unusable = await workspaceParentUnusable(root);
return unusable === undefined
? { admitted: true, workspace: { root, proof: privacy.proof } }
: {
admitted: false,
workspaceRoot: root,
refusal: { kind: "workspace_unusable", reason: unusable },
};
};
/** Resolve the workspace parent as allocation will, without creating entries. */
const workspaceParentUnusable = async (
root: string | undefined,
): Promise<string | undefined> => {
try {
const parent = await resolveIdaWorkspaceParent(root);
if (!(await stat(parent)).isDirectory())
return `IDA workspaceRoot ${root ?? "the system temporary directory"} is not a directory.`;
await access(parent, constants.W_OK | constants.X_OK);
return undefined;
} catch (cause: unknown) {
return `IDA workspaceRoot ${root ?? "the system temporary directory"} is not a usable directory: ${cause instanceof Error ? cause.message : String(cause)}`;
}
};
+67 -37
View File
@@ -6,9 +6,14 @@ import {
readIdaConfiguration,
type IdaConfiguration,
} from "./IdaConfiguration.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { Result } from "../domain/result.js";
import type { ConfigurationError } from "../domain/configurationErrors.js";
import { inspectIdaWorkspaceReadiness } from "./IdaWorkspaceReadiness.js";
import {
admitIdaConfiguration,
IDA_WORKSPACE_ROOT_REMEDIATION,
type IdaAdmission,
} from "./IdaAdmission.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
/** Client settings consulted by this readiness probe. */
@@ -30,14 +35,14 @@ export const inspectIdaRegistration = async (
...(signal === undefined ? {} : { signal }),
}));
const valid = parsed?.ok === true;
const admission =
parsed?.ok === true ? await admitIdaConfiguration(parsed.value) : undefined;
const workspaceChecks =
parsed?.ok === true && parsed.value.mode === "headless"
? [await inspectPrivateWorkspace(parsed.value.workspaceRoot)]
: [];
admission === undefined ? [] : privateWorkspaceChecks(admission);
return {
id: "ida",
configured: path !== undefined,
available: valid && workspaceChecks.every(({ ok }) => ok),
available: admission?.admitted === true,
providerVersion: null,
registrationEnvironment:
valid && path !== undefined ? { REA_IDA_MCP_CONFIG: path } : {},
@@ -55,9 +60,12 @@ export const inspectIdaRegistration = async (
: parsed !== undefined && !parsed.ok
? parsed.error.message
: "IDA MCP registration is not configured.",
// An invalid registration carries the repair runtime readiness reports.
remediation: valid
? null
: "Set REA_IDA_MCP_CONFIG to your upstream IDA MCP registration JSON; see docs/providers/ida-provider.md.",
: parsed !== undefined && !parsed.ok
? projectAnalysisError(parsed.error).remediation.action
: "Set REA_IDA_MCP_CONFIG to your upstream IDA MCP registration JSON; see docs/providers/ida-provider.md.",
classification:
path === undefined ? "missing_analysis_engine" : "config_drift",
},
@@ -66,35 +74,57 @@ export const inspectIdaRegistration = async (
};
};
const inspectPrivateWorkspace = async (
workspaceRoot: string | undefined,
): Promise<DoctorProviderCheck> => {
const { privacy, unusable } =
await inspectIdaWorkspaceReadiness(workspaceRoot);
return {
name: "private_workspace",
ok: privacy.available && unusable === undefined,
code: !privacy.available
? privacy.code
: unusable === undefined
? null
: "invalid_configuration",
detail: !privacy.available
? privacy.reason
: (unusable ??
`Private workspace authority is available (${privacy.proof}) under ${workspaceRoot ?? "the system temporary directory"}.`),
remediation: !privacy.available
? privacy.remediation
: unusable === undefined
? null
: "Set workspaceRoot to an existing directory REA can create entries in, or omit it to use the system temporary directory; see docs/providers/ida-provider.md.",
classification:
!privacy.available && privacy.code === "runtime_missing"
? "missing_dependency"
: !privacy.available && privacy.code === "runtime_unavailable"
? "runtime_failure"
: unusable !== undefined
? "config_drift"
: "unsupported_host",
};
/** Project IDA's admission into the doctor's private workspace check. */
const privateWorkspaceChecks = (
admission: IdaAdmission,
): readonly DoctorProviderCheck[] => {
if (admission.admitted)
return admission.workspace === undefined
? []
: [
{
name: "private_workspace",
ok: true,
code: null,
detail: `Private workspace authority is available (${admission.workspace.proof}) under ${admission.workspace.root ?? "the system temporary directory"}.`,
remediation: null,
classification: "unsupported_host",
},
];
const { refusal } = admission;
switch (refusal.kind) {
case "workspace_unusable":
return [
{
name: "private_workspace",
ok: false,
code: "invalid_configuration",
detail: refusal.reason,
remediation: IDA_WORKSPACE_ROOT_REMEDIATION,
classification: "config_drift",
},
];
case "private_workspace_unavailable": {
const { privacy } = refusal;
return [
{
name: "private_workspace",
ok: false,
code: privacy.code,
detail: privacy.reason,
remediation: privacy.remediation,
classification:
privacy.code === "runtime_missing"
? "missing_dependency"
: privacy.code === "runtime_unavailable"
? "runtime_failure"
: "unsupported_host",
},
];
}
default: {
const unreachable: never = refusal;
return unreachable;
}
}
};
+33
View File
@@ -14,6 +14,7 @@ import {
RecordingIdaMcp,
createIdaTarget,
} from "../../tests/fixtures/idaMcp.js";
import { inspectIdaRegistration } from "./IdaDoctor.js";
import { IdaProvider } from "./IdaProvider.js";
it.each([
@@ -54,6 +55,19 @@ it.each([
expect(snapshot.availability.diagnostics).not.toHaveProperty(
"configuration_remediation",
);
// Doctor reports the runtime's repair for a selected registration.
if (selected && snapshot.availability.status === "unavailable") {
const doctor = await inspectIdaRegistration(path, {
retain: () => undefined,
run: (operation) => operation(),
});
expect(
doctor.checks.find(({ name }) => name === "registration"),
).toMatchObject({
ok: false,
remediation: snapshot.availability.remediation,
});
}
expect(connect).not.toHaveBeenCalled();
} finally {
const closed = await provider.closeOwnedResources();
@@ -143,6 +157,25 @@ it.each(["missing", "file", "directory", "omitted"] as const)(
)?.reason,
).toContain("direct call edges");
} else expect(snapshot.availability.status).toBe("available");
// Doctor projects the same admission, so it agrees on the outcome,
// reason and repair.
const doctor = await inspectIdaRegistration(registration, {
retain: () => undefined,
run: (operation) => operation(),
});
expect(doctor.available).toBe(
snapshot.availability.status === "available",
);
const workspaceCheck = doctor.checks.find(
({ name }) => name === "private_workspace",
);
if (snapshot.availability.status === "unavailable")
expect(workspaceCheck).toMatchObject({
ok: false,
detail: snapshot.availability.reason,
remediation: snapshot.availability.remediation,
});
else expect(workspaceCheck).toMatchObject({ ok: true });
expect((await readdir(root)).sort()).toEqual(before);
expect(connect).not.toHaveBeenCalled();
} finally {
+49 -32
View File
@@ -45,7 +45,11 @@ import {
import { idaCapabilities } from "./IdaProviderCapabilities.js";
import { IDA_PROVIDER_IDENTITY } from "./IdaProviderMetadata.js";
import { IdaSessionClient } from "./IdaSessionClient.js";
import { inspectIdaWorkspaceReadiness } from "./IdaWorkspaceReadiness.js";
import {
admitIdaConfiguration,
IDA_WORKSPACE_ROOT_REMEDIATION,
type IdaAdmission,
} from "./IdaAdmission.js";
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
@@ -234,38 +238,11 @@ export class IdaProvider implements AnalysisProviderCandidate {
},
});
}
if (config.value.mode === "headless") {
const { privacy, unusable } = await inspectIdaWorkspaceReadiness(
config.value.workspaceRoot,
const admission = await admitIdaConfiguration(config.value);
if (!admission.admitted)
return unavailable(
idaRefusalAvailability(admission, registrationDiagnostics),
);
if (!privacy.available)
return unavailable({
status: "unavailable",
code: privacy.code,
reason: privacy.reason,
remediation: privacy.remediation,
diagnostics: {
...registrationDiagnostics,
mode: "headless",
private_workspace_available: false,
windows_native_failure: { stage: privacy.failureStage },
},
});
if (unusable !== undefined)
return unavailable({
status: "unavailable",
code: "open_options_invalid",
reason: unusable,
remediation:
"Set workspaceRoot to an existing directory REA can create entries in, or omit it to use the system temporary directory; see docs/providers/ida-provider.md.",
diagnostics: {
...registrationDiagnostics,
mode: "headless",
workspace_root: config.value.workspaceRoot ?? null,
private_workspace_available: false,
},
});
}
return {
availability: {
status: "available" as const,
@@ -459,3 +436,43 @@ const readIdaConfigurationNotConfigured = () =>
"Set REA_IDA_MCP_CONFIG to an upstream IDA MCP JSON registration; see docs/providers/ida-provider.md.",
),
);
/** Project IDA's admission refusal into provider availability. */
const idaRefusalAvailability = (
admission: Extract<IdaAdmission, { readonly admitted: false }>,
registrationDiagnostics: Readonly<Record<string, unknown>>,
): Extract<ProviderAvailability, { status: "unavailable" }> => {
const { refusal } = admission;
switch (refusal.kind) {
case "private_workspace_unavailable":
return {
status: "unavailable",
code: refusal.privacy.code,
reason: refusal.privacy.reason,
remediation: refusal.privacy.remediation,
diagnostics: {
...registrationDiagnostics,
mode: "headless",
private_workspace_available: false,
windows_native_failure: { stage: refusal.privacy.failureStage },
},
};
case "workspace_unusable":
return {
status: "unavailable",
code: "open_options_invalid",
reason: refusal.reason,
remediation: IDA_WORKSPACE_ROOT_REMEDIATION,
diagnostics: {
...registrationDiagnostics,
mode: "headless",
workspace_root: admission.workspaceRoot ?? null,
private_workspace_available: false,
},
};
default: {
const unreachable: never = refusal;
return unreachable;
}
}
};
-22
View File
@@ -1,22 +0,0 @@
import { constants } from "node:fs";
import { access, stat } from "node:fs/promises";
import { privateRuntimeRootCapability } from "../process/PrivateRuntimeRoot.js";
import { resolveIdaWorkspaceParent } from "./IdaWorkspace.js";
/** Inspect local prerequisites without creating a workspace or launching IDA. */
export const inspectIdaWorkspaceReadiness = async (
root: string | undefined,
) => {
const privacy = privateRuntimeRootCapability();
let unusable: string | undefined;
try {
const parent = await resolveIdaWorkspaceParent(root);
if (!(await stat(parent)).isDirectory())
unusable = `IDA workspaceRoot ${root ?? "the system temporary directory"} is not a directory.`;
else await access(parent, constants.W_OK | constants.X_OK);
} catch (cause: unknown) {
unusable = `IDA workspaceRoot ${root ?? "the system temporary directory"} is not a usable directory: ${cause instanceof Error ? cause.message : String(cause)}`;
}
return { privacy, unusable };
};