fix(ida): report missing tools when a compatibility profile mismatches (#2307)

A profile mismatch reached the caller as a bare AnalysisProtocolError,
which projects to `unreadable_output` with a generic message. The error
already named every missing tool, but none of that detail survived, so
the only way to identify the cause was to log the JSON-RPC traffic and
notice the exchange stopping after `tools/list`.

Throw a ProviderAdapterError instead, carrying the mode, the expected
profile and the missing tool names through the diagnostics channel that
already surfaces in `details`. Document which upstream versions each
profile accepts, since upstream `main` now serves neither.

Refs #2301

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
vtx
2026-10-13 21:58:36 +08:00
committed by GitHub
co-authored by morluto
parent 48a683ac8c
commit beca34f522
4 changed files with 112 additions and 6 deletions
+70
View File
@@ -31,6 +31,7 @@ const LIVE_PEER = {
const fixture = async (
mode: "attached" | "headless" = "attached",
timeoutMs = 1000,
protocol?: "native",
) => {
const { root, target } = await createIdaTarget();
roots.push(root);
@@ -41,6 +42,7 @@ const fixture = async (
args: [],
env: {},
mode,
...(protocol === undefined ? {} : { protocol }),
timeoutMs,
workspaceRoot: root,
},
@@ -709,6 +711,74 @@ describe("headless IDA non-busy health payloads", () => {
});
});
describe("IDA compatibility profile mismatch", () => {
it("reports the native profile for an incompatible catalog", async () => {
const { producer, client } = await fixture("attached", 1000, "native");
producer.tools = [];
const result = await client.execute("health", {});
expect(result.ok).toBe(false);
if (result.ok) throw new Error("Expected incompatible native catalog");
expect(projectAnalysisError(result.error).details).toMatchObject({
diagnostics: {
mode: "attached",
expected_profile: "native",
missing_tools: expect.arrayContaining(["decompile"]),
},
});
expect(producer.calls).toEqual([]);
expect((await client.close()).ok).toBe(true);
});
it("names every missing tool so the caller can identify the upstream profile", async () => {
const { producer, client } = await fixture("headless");
producer.tools = [
"idb_open",
"idb_list",
"server_health",
"list_funcs",
"lookup_funcs",
"find_regex",
"decompile",
"disasm",
"callees",
"xrefs_to",
];
const result = await client.execute("health", {});
expect(result.ok, "an incomplete profile cannot serve analysis").toBe(
false,
);
if (result.ok) return;
const projected = projectAnalysisError(result.error);
expect(
projected.details,
"the absent tool and the expected profile are both reported",
).toMatchObject({
provider_id: "ida",
diagnostics: {
mode: "headless",
expected_profile: "database-supervisor",
missing_tools: ["idb_close"],
},
});
});
it("reports the legacy profile when an attached producer serves modern tools", async () => {
const { producer, client } = await fixture("attached");
producer.tools = ["server_health", "lookup_funcs", "decompile", "disasm"];
const result = await client.execute("health", {});
expect(result.ok, "an incomplete profile cannot serve analysis").toBe(
false,
);
if (result.ok) return;
expect(
projectAnalysisError(result.error).details,
"attached mode names the legacy profile it expected",
).toMatchObject({
diagnostics: { mode: "attached", expected_profile: "legacy-1.4" },
});
});
});
describe("headless IDA lifecycle boundaries", () => {
it("never closes an unowned worker even when open echoes the requested private identity", async () => {
const { producer, client } = await fixture("headless");
+21 -4
View File
@@ -483,10 +483,27 @@ export class IdaSessionClient implements AnalysisClient {
? legacyTools
: modernTools;
const missing = expected.filter((name) => !tools.has(name));
if (missing.length > 0)
throw new AnalysisProtocolError(
`IDA MCP ${this.config.protocol === "native" ? "native attached" : this.config.mode} compatibility profile is missing tools: ${missing.join(", ")}. Native attached mode requires the native IDA MCP tool catalog; legacy attached mode requires the legacy 1.4 profile; headless mode requires the database supervisor profile. See docs/ida-provider.md.`,
);
if (missing.length > 0) {
const summary = `IDA MCP ${this.config.protocol === "native" ? "native attached" : this.config.mode} compatibility profile is missing tools: ${missing.join(", ")}. Native attached mode requires the native IDA MCP tool catalog; legacy attached mode requires the legacy 1.4 profile; headless mode requires the database supervisor profile. See docs/ida-provider.md.`;
// The caller cannot act on a profile mismatch it never sees, so the
// missing names travel as adapter diagnostics rather than a bare message.
throw new ProviderAdapterError("ida", "initialize", {
userMessage: summary,
diagnostics: {
reason: summary,
mode: this.config.mode,
expected_profile:
this.config.protocol === "native"
? "native"
: this.config.mode === "attached"
? "legacy-1.4"
: "database-supervisor",
missing_tools: [...missing],
recovery:
"Install an IDA MCP build that serves the selected profile; see docs/ida-provider.md.",
},
});
}
if (this.config.mode === "headless") {
this.#workspace = await IdaWorkspace.allocate(
this.target,