Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
perf(mcp)!: compact repeated session discovery facts (#1988)
Ysopwnable6395e8d3007d
diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.mdindex 45240351d..1960c6d1c 100644--- a/.agents/skills/reverse-engineer-anything/SKILL.md+++ b/.agents/skills/reverse-engineer-anything/SKILL.md@@ -115,8 +115,14 @@ ask when matches are ambiguous. Never choose an example app on the user's behalfIn a target-free session, use `open_binary` to bind any archive/package ornative target whose analysis tool operates on the active target. Do not call anunadvertised tool; inspect `binary_session` with `{}` and its-`result.tool_availability` for availability reasons and remediation. The tool-list stays complete; availability depends on the operation, target, and host.+`result.tool_availability` for availability reasons and remediation. Expand each+group's `names` into entries, inheriting the inventory-level client requirements+unless the group overrides them. In its closed effect and annotation vocabularies,+listed flags are true and omitted known flags are false. The grouped name union+is the complete tool inventory; use `tools/list` for canonical tool schemas.+Provider candidate facts describe possible providers, while top-level session+capabilities describe the current route and `analysis_provider_binding` names the+selected provider. Do not treat those scopes as interchangeable.## Work summary-firstdiff --git a/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md b/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.mdindex 5e5f6251d..515a6c9d4 100644--- a/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md+++ b/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md@@ -11,14 +11,14 @@ main and an older release expose the same arguments.## Choose the remedy from the observed failure-| Observation | Meaning and next step |-| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| No REA tools in the active session | Inspect registration with `rea doctor --client codex --json`. A skill installation alone does not register MCP. |-| Missing, malformed or stale registration | Prepare a scoped setup plan; apply only authorized changes with backups. |-| Aligned registration, but no connected tools | Restart/reconnect the client. Doctor checks registration; it cannot establish the current agent's connection. Inspect the client's launch error if reconnection fails. |-| `MCP tool call requires approval, but approval policy is never` | Codex rejected the call before REA executed it. Do not install an engine or repeat setup to solve this client-policy decision. See the approval section below. |-| REA returns `provider_unavailable` or an unavailable tool entry | Read that operation's provider diagnostics or `binary_session.result.tool_availability`. Resolve only the prerequisite needed for the task; a complete tool catalog does not imply every operation is available. |-| `rea` is missing in a child shell, or Node is incompatible | Inspect the actual shell PATH and launcher/runtime. A prefix installation may be absent from a login shell's PATH; this does not establish a broken MCP registration. |+| Observation | Meaning and next step |+| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| No REA tools in the active session | Inspect registration with `rea doctor --client codex --json`. A skill installation alone does not register MCP. |+| Missing, malformed or stale registration | Prepare a scoped setup plan; apply only authorized changes with backups. |+| Aligned registration, but no connected tools | Restart/reconnect the client. Doctor checks registration; it cannot establish the current agent's connection. Inspect the client's launch error if reconnection fails. |+| `MCP tool call requires approval, but approval policy is never` | Codex rejected the call before REA executed it. Do not install an engine or repeat setup to solve this client-policy decision. See the approval section below. |+| REA returns `provider_unavailable` or an unavailable tool entry | Read that operation's provider diagnostics or `binary_session.result.tool_availability`. Expand each group's tool names and inherit the shared client requirements unless overridden. Use the operation's availability, reason, and remediation; a complete tool catalog does not imply every operation is available. |+| `rea` is missing in a child shell, or Node is incompatible | Inspect the actual shell PATH and launcher/runtime. A prefix installation may be absent from a login shell's PATH; this does not establish a broken MCP registration. |If the client cannot launch its shell/sandbox helper or read the installed skill,inspect its launch diagnostic. For example, Codex can refuse helper aliases whendiff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.mdindex 9f09ad82f..a045e5a62 100644--- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md+++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md@@ -50,10 +50,19 @@ runs and may change files or use the network. Hardened-runtime targets need the`get-task-allow` entitlement.Use `binary_session` with no arguments to check the open target, selected-provider, and alignment. Its default `result.tool_availability` includes the-complete tool inventory with availability reasons and remediation. When choosing-a tool, use its entry in that result; `tools/list` retains the complete catalog-when the target or provider state changes.+provider, and alignment. Its default `result.tool_availability` carries a+complete inventory grouped by shared facts. Expand each group's `names` and+inherit the inventory-level client requirements unless a group overrides them;+availability, reasons, remediation, modes, and flags remain inline. The+`effects` and `annotations` arrays name true flags from fixed vocabularies, so an+omitted known flag is false. `tools/list` remains the canonical source for full+tool schemas when target or provider state changes.++Provider capability groups carry provider identity and ordered limitations.+Prepend each set's `shared_limitations` to a group's `limitations` to recover the+operation's full ordered list. Candidate capabilities describe possible+providers. Top-level session capabilities describe the current route, and+`analysis_provider_binding` identifies the selected provider.## DOS MZ with Ghidradiff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.mdindex b8d8d6fb8..93f890f20 100644--- a/docs/mcp-contracts.md+++ b/docs/mcp-contracts.md@@ -113,17 +113,48 @@ Schema does not express those cross-field invariants.Call `binary_session` with `{}` and read `result.tool_availability` to choose acallable operation for the current target, provider, host, and negotiated client-capabilities. The default result includes the complete inventory with each-tool's availability, reason, and remediation. Each entry also reports required-and optional negotiated client features plus the currently missing features.-The optional inputs `expected_package_version`, `expected_catalog_digest`, and+capabilities. The default result contains the complete inventory in groups that+share status facts. `tool_availability.client_requirements` is the baseline for+each group; a group's optional `client_requirements` replaces that baseline for+the group's tools. Expand each group's `names` into one tool entry, carrying its+surface, availability, reason, remediation, default-mode status, modes, and+client requirements. Compare the union of group names with `tools/list` when+checking that a client received the full catalog. An operation absent from all+groups is missing from the complete inventory; it is not an implicit+unavailable entry.++The `effects` and `annotations` arrays list the true members of their fixed+vocabularies. A known member omitted from either array is false. This applies+only to these closed flag sets; it does not make an omitted tool, provider, mode,+or limitation false. Keep availability reasons, remediation, client-feature+requirements, and mode facts inline with the grouped tool names. The optional+inputs `expected_package_version`, `expected_catalog_digest`, and`expected_server_path` compare the live session with the caller's expectations.+`server_identity.catalog` contains catalog counts and schema digests. Grouped+tool availability carries the name set and current per-tool facts; `tools/list`+is the canonical source for complete tool definitions, including input and+output schemas. Clients that previously read `server_identity.catalog.tools`+should expand `tool_availability.groups` and use `tools/list` for schemas. The+same catalog identity summary is returned by CLI `capabilities` and `providers`;+MCP tool definitions remain available through `tools/list`.++Provider capabilities are grouped by provider identity and shared facts. In each+set, `shared_limitations` is the ordered common prefix; append a group's ordered+`limitations` suffix to recover each operation's exact limitations. Group+`effects` arrays use the same true-only closed-vocabulary rule as tool+availability. Expand every group operation while retaining its provider+identity, availability, reason, rejection code, effects, and ordered+limitations.+`binary_session.analysis_provider_candidates` is authoritative for deep-engine-discovery. Target-free discovery is sorted by provider ID, reports host-availability and `unknown` target support, and does not create an analysis-client. `open_binary.provider_id` accepts a concrete provider ID or `auto`; it-uses the same parser and selection policy as CLI `--provider` and+discovery. Each candidate's capability sets describe that possible provider;+they do not select it. The top-level `capabilities` describe the current route,+while `analysis_provider_binding` identifies the concrete selected route. These+fields are not interchangeable. Target-free discovery is sorted by provider ID,+reports host availability and `unknown` target support, and does not create an+analysis client. `open_binary.provider_id` accepts a concrete provider ID or+`auto`; it uses the same parser and selection policy as CLI `--provider` and`REA_ANALYSIS_PROVIDER`. A successful deep open exposes one immutable provider,concrete version, selection source, and complete analysis profile through`analysis_provider_binding`. Ambiguity and unknown, unavailable, or unsupporteddiff --git a/scripts/lib/mcp-verifier-results.mjs b/scripts/lib/mcp-verifier-results.mjsindex 7ac038a0a..def0effbb 100644--- a/scripts/lib/mcp-verifier-results.mjs+++ b/scripts/lib/mcp-verifier-results.mjs@@ -1,5 +1,11 @@import { analysisErrorProjectionSchema } from "../../dist/contracts/errorSchemas.js";import { toolContract } from "../../dist/contracts/toolContracts.js";+import {+ expandProviderCapabilities,+ expandToolAvailability,+ providerCapabilitySet,+} from "../../dist/contracts/toolOutputSchemaPrimitives.js";+import { compareUnicodeCodePoints } from "../../dist/domain/unicodeCodePointOrder.js";/** Read the textual JSON projection from one MCP tool call. */export const mcpTextValue = (result) => {@@ -10,6 +16,10 @@ export const mcpTextValue = (result) => {const jsonValue = (result) => JSON.parse(mcpTextValue(result));+/** Sort canonical contract names using REA's code-point ordering. */+export const sortVerifierNames = (names) =>+ [...names].sort(compareUnicodeCodePoints);+/** Read the complete canonical diagnostic from an MCP tool failure. */export const requireMcpToolError = (result) => {if (result.isError !== true) throw new Error("Expected an MCP tool failure");@@ -35,6 +45,44 @@ const operationResultKey = (contract) => {return evidence ? "normalized_result" : "result";};+/** Expand compact session metadata once at the verifier boundary. */+export const expandMcpSessionStatus = (status) => ({+ ...status,+ capabilities: expandProviderCapabilities(status.capabilities),+ analysis_provider_candidates: expandProviderCandidates(+ status.analysis_provider_candidates,+ ),+ tool_availability: expandToolAvailability(status.tool_availability),+});++/** Expand provider capability groups while retaining candidate identity/state. */+export const expandProviderCandidates = (candidates) =>+ candidates.map((candidate) => ({+ ...candidate,+ capabilities: expandProviderCapabilities(+ providerCapabilitySet.array().parse(candidate.capabilities),+ ),+ }));++/** Expand CLI provider capability groups at the same owning boundary. */+export const expandProviderOutput = (providers) => ({+ ...providers,+ capabilities: expandProviderCapabilities(+ providerCapabilitySet.array().parse(providers.capabilities),+ ),+ analysis_provider_candidates: expandProviderCandidates(+ providers.analysis_provider_candidates,+ ),+});++/** Expand the CLI capabilities command's compact provider descriptor groups. */+export const expandCapabilitiesOutput = (capabilities) => ({+ ...capabilities,+ capabilities: expandProviderCapabilities(+ providerCapabilitySet.array().parse(capabilities.capabilities),+ ),+});+/** Validate an Evidence-producing tool output and return its normalized result. */export const requireMcpEvidenceResult = (result, operation) => {const contract = toolContract(operation);@@ -48,7 +96,10 @@ export const requireMcpLifecycleResult = (result, operation) => {const contract = toolContract(operation);if (operationResultKey(contract) !== "result")throw new Error(`${operation} requires the Evidence result extractor`);- return requireOutput(result, operation, contract).result;+ const projected = requireOutput(result, operation, contract).result;+ return operation === "binary_session"+ ? expandMcpSessionStatus(projected)+ : projected;};/** Project a mixed verifier call using its exact named canonical output schema. */@@ -58,7 +109,10 @@ export const requireMcpOperationResult = (contract = toolContract(operation),) => {const key = operationResultKey(contract);- return requireOutput(result, operation, contract)[key];+ const projected = requireOutput(result, operation, contract)[key];+ return operation === "binary_session"+ ? expandMcpSessionStatus(projected)+ : projected;};/** Verify provider identity directly from the tool result. */diff --git a/scripts/lib/native-value-e2e.mjs b/scripts/lib/native-value-e2e.mjsindex e65700b06..513259b30 100644--- a/scripts/lib/native-value-e2e.mjs+++ b/scripts/lib/native-value-e2e.mjs@@ -11,6 +11,7 @@ import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";import { parseEvidence } from "../../dist/domain/evidence.js";import { analysisProfileSchema } from "../../dist/domain/analysisProfile.js";import { nativeValueTraceSchema } from "../../dist/domain/native/nativeValueTrace.js";+import { requireMcpLifecycleResult } from "./mcp-verifier-results.mjs";import { verifyGhidraBoundaries } from "./real-ghidra-boundaries.mjs";const defaultEntrypoint = fileURLToPath(new URL("../rea.mjs", import.meta.url));@@ -172,13 +173,16 @@ async function verifyNativeValueAdapters({ timeout: 180000 },);assert.notEqual(opened.isError, true, JSON.stringify(opened));- const inventory = await client.callTool({+ const inventoryReply = await client.callTool({name: "binary_session",arguments: {},});- assert.notEqual(inventory.isError, true, JSON.stringify(inventory));+ const inventory = requireMcpLifecycleResult(+ inventoryReply,+ "binary_session",+ );assert.ok(- inventory.structuredContent?.result?.tool_availability.some(+ inventory.tool_availability.some((tool) => tool.name === "trace_native_values" && tool.available,),"Native value tracing is unavailable in real provider discovery",@@ -267,11 +271,14 @@ async function verifyNativeValueAdapters(arguments: {},});assert.notEqual(closed.isError, true, JSON.stringify(closed));- const status = await client.callTool({+ const statusReply = await client.callTool({name: "binary_session",arguments: {},});- assert.equal(status.structuredContent?.result?.open, false);+ assert.equal(+ requireMcpLifecycleResult(statusReply, "binary_session").open,+ false,+ );assert.deepEqual((await readdir(env.TMPDIR)).filter((name) =>name.startsWith("rea-ghidra-"),diff --git a/scripts/lib/verify-package-core.mjs b/scripts/lib/verify-package-core.mjsindex 5371edffc..a78b516da 100644--- a/scripts/lib/verify-package-core.mjs+++ b/scripts/lib/verify-package-core.mjs@@ -2,6 +2,10 @@ import { execFile } from "node:child_process";import { lstat } from "node:fs/promises";import { promisify } from "node:util";import { Ajv2020 } from "ajv/dist/2020.js";+import {+ requireMcpLifecycleResult,+ sortVerifierNames,+} from "./mcp-verifier-results.mjs";/** Promisified child_process execution helper. */export const exec = promisify(execFile);@@ -46,11 +50,10 @@ export const verifyCompleteToolCatalog = async (client, options) => {{ name: "binary_session", arguments: {} },options,);- const availability = status.structuredContent?.result?.tool_availability;- if (!Array.isArray(availability))- throw new Error("packaged MCP omitted tool availability");- const expected = availability.map(({ name }) => name).sort();- const observed = listed.tools.map(({ name }) => name).sort();+ const expanded = requireMcpLifecycleResult(status, "binary_session");+ const availability = expanded.tool_availability;+ const expected = sortVerifierNames(availability.map(({ name }) => name));+ const observed = sortVerifierNames(listed.tools.map(({ name }) => name));if (JSON.stringify(observed) !== JSON.stringify(expected))throw new Error("packaged MCP tool inventory diverged from session metadata",diff --git a/scripts/verify-claude-client.mjs b/scripts/verify-claude-client.mjsindex 30bc66ba7..2c0d79bc0 100644--- a/scripts/verify-claude-client.mjs+++ b/scripts/verify-claude-client.mjs@@ -5,11 +5,16 @@ import { tmpdir } from "node:os";import { join } from "node:path";import { fileURLToPath } from "node:url";import Ajv2020 from "ajv/dist/2020.js";+import { CATALOG_IDENTITY } from "../dist/catalogIdentity.js";import {TOOL_CONTRACTS,toolContract,} from "../dist/contracts/toolContracts.js";import { exec } from "./lib/verify-package-core.mjs";+import {+ expandMcpSessionStatus,+ sortVerifierNames,+} from "./lib/mcp-verifier-results.mjs";import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";import { createAnthropicModelFixture } from "./verify/clients/anthropic-model-fixture.mjs";@@ -58,6 +63,8 @@ await writeFile('export function result() { return { clientCompatibility: "REA_CLIENT_FIXTURE", count: 7 }; }\n',);let skillRequested = false;+let sessionRequested = false;+let sessionStatusSeen = false;let skillLoaded = false;let expectedSkillBody;let evidenceSeen = false;@@ -73,7 +80,7 @@ const containsText = (value, text) => {return Object.values(value).some((nested) => containsText(nested, text));return false;};-const extractEvidence = (value) => {+const extractInlineResult = (value, matches) => {if (typeof value === "string") {try {// Native Claude appends this resource hint to tool results. Original bodies remain intact in request artifacts.@@ -81,20 +88,16 @@ const extractEvidence = (value) => {/\n\n<system-reminder>\n<total_tokens>\d+ tokens left<\/total_tokens>\n<\/system-reminder>$/u,"",);- return extractEvidence(JSON.parse(json));+ return extractInlineResult(JSON.parse(json), matches);} catch {return undefined;}}if (value && typeof value === "object") {- if (- typeof value.evidence_id === "string" &&- value.normalized_result?.graph?.nodes?.length > 0- )- return value;+ if (matches(value)) return value;for (const nested of Object.values(value)) {- const evidence = extractEvidence(nested);- if (evidence) return evidence;+ const result = extractInlineResult(nested, matches);+ if (result) return result;}}return undefined;@@ -125,10 +128,12 @@ const fixture = await createAnthropicModelFixture({0,-"analyze_javascript_application".length,);- const expected = TOOL_CONTRACTS.map((t) => prefix + t.name).sort();+ const expected = sortVerifierNames(+ TOOL_CONTRACTS.map((t) => prefix + t.name),+ );const reaTools = tools.filter((t) => t.name.startsWith(prefix));assert.deepEqual(- reaTools.map((t) => t.name).sort(),+ sortVerifierNames(reaTools.map((t) => t.name)),expected,"Claude must forward the complete REA catalog after connection",);@@ -146,11 +151,61 @@ const fixture = await createAnthropicModelFixture({schemasChecked++;}}+ if (mode === "call" && !sessionStatusSeen) {+ const observedStatus = extractInlineResult(+ body.messages,+ (value) =>+ Boolean(value.result?.server_identity) &&+ Array.isArray(value.result?.tool_availability?.groups),+ );+ if (observedStatus) {+ const parsedStatus =+ toolContract("binary_session").outputSchema.parse(observedStatus);+ const status = {+ ...parsedStatus,+ result: expandMcpSessionStatus(parsedStatus.result),+ };+ assert.deepEqual(+ status.result.server_identity.catalog,+ CATALOG_IDENTITY,+ "binary_session must return the exact compact catalog counts and digests",+ );+ assert.equal(+ Object.hasOwn(status.result.server_identity.catalog, "tools"),+ false,+ "binary_session must not inline the duplicated canonical tool catalog",+ );+ assert.deepEqual(+ sortVerifierNames(+ status.result.tool_availability.map((entry) => entry.name),+ ),+ sortVerifierNames(TOOL_CONTRACTS.map((contract) => contract.name)),+ "binary_session must retain complete canonical tool availability",+ );+ sessionStatusSeen = true;+ } else {+ assert(+ !sessionRequested,+ "Claude must return the inline binary_session result before continuing",+ );+ const session = tools.find(+ (tool) => tool.name === `${prefix}binary_session`,+ );+ assert(session, "Claude must expose the REA binary_session tool");+ sessionRequested = true;+ return call(session.name, {});+ }+ }skillLoaded ||=expectedSkillBody !== undefined &&containsText(body.messages, expectedSkillBody) &&containsText(body.messages, skillDirectory);- const observed = extractEvidence(body.messages);+ const observed = extractInlineResult(+ body.messages,+ (value) =>+ typeof value.evidence_id === "string" &&+ value.normalized_result?.graph?.nodes?.length > 0,+ );if (observed) {const evidence = toolContract("analyze_javascript_application",@@ -184,7 +239,7 @@ const fixture = await createAnthropicModelFixture({await writeFile(join(lab, "claude-evidence.json"), bytes);evidenceSeen = true;}- if (mode === "chat" || evidenceSeen) {+ if (mode === "chat" || (sessionStatusSeen && evidenceSeen)) {finalSeen = true;return [{ type: "text", text: "REA_CLIENT_COMPATIBILITY_OK" }];}@@ -294,6 +349,7 @@ try {"Skill","WaitForMcpServers","mcp__rea__analyze_javascript_application",+ ...(mode === "call" ? ["mcp__rea__binary_session"] : []),],},}),@@ -324,7 +380,7 @@ try {assert.equal(parsed.result, "REA_CLIENT_COMPATIBILITY_OK");assert.deepEqual(parsed.permission_denials, []);assert(finalSeen);- if (mode === "call") assert(evidenceSeen && skillLoaded);+ if (mode === "call") assert(evidenceSeen && skillLoaded && sessionStatusSeen);} catch (cause) {failure = cause;if (typeof cause?.stdout === "string")@@ -355,6 +411,7 @@ try {schemasChecked,pendingServerWaits,evidenceSeen,+ sessionStatusSeen,skillLoaded,artifactDigest,finalSeen,diff --git a/scripts/verify-package-capabilities.mjs b/scripts/verify-package-capabilities.mjsindex 2137a4c5a..acf848974 100644--- a/scripts/verify-package-capabilities.mjs+++ b/scripts/verify-package-capabilities.mjs@@ -1,13 +1,19 @@import { json, run } from "./lib/verify-package-core.mjs";+import {+ expandCapabilitiesOutput,+ expandProviderOutput,+} from "./lib/mcp-verifier-results.mjs";/** Verify packaged capabilities, providers, and non-Linux search results. */export async function verifyPackageCapabilitiesAndSearch({ cli, environment }) {- const capabilities = json(- await run(cli, ["capabilities", "--json"], environment),+ const capabilities = expandCapabilitiesOutput(+ json(await run(cli, ["capabilities", "--json"], environment)),);if (!Array.isArray(capabilities.capabilities))throw new Error("packaged capabilities CLI failed");- const providers = json(await run(cli, ["providers", "--json"], environment));+ const providers = expandProviderOutput(+ json(await run(cli, ["providers", "--json"], environment)),+ );const candidates = providers.analysis_provider_candidates;if (!Array.isArray(candidates) ||diff --git a/scripts/verify-package-mcp.mjs b/scripts/verify-package-mcp.mjsindex 7bb22715d..0d03abab1 100644--- a/scripts/verify-package-mcp.mjs+++ b/scripts/verify-package-mcp.mjs@@ -1,4 +1,7 @@-import { requireMcpToolError } from "./lib/mcp-verifier-results.mjs";+import {+ requireMcpLifecycleResult,+ requireMcpToolError,+} from "./lib/mcp-verifier-results.mjs";import assert from "node:assert/strict";import { join } from "node:path";import { execFile } from "node:child_process";@@ -21,14 +24,14 @@ const verifyMcpToolsAndPrompts = async (client, mcpOptions) => {};const verifyMcpTargetFree = async (client, mcpOptions) => {- const status = await client.callTool(+ const result = await client.callTool({ name: "binary_session", arguments: {} },mcpOptions,);- const currentDocument =- status.structuredContent?.result?.tool_availability?.find(- ({ name }) => name === "current_document",- );+ const status = requireMcpLifecycleResult(result, "binary_session");+ const currentDocument = status.tool_availability.find(+ ({ name }) => name === "current_document",+ );if (currentDocument?.available !== false ||currentDocument.reason !== "target_required"@@ -67,15 +70,13 @@ const verifyMcpOpenAndBind = async (client, mcpOptions) => {);if (opened.isError === true)throw new Error("packaged MCP could not open a binary");- const providerStatusEnvelope = json(- prompts.mcpText(- await client.callTool(- { name: "binary_session", arguments: {} },- mcpOptions,- ),+ const providerStatus = requireMcpLifecycleResult(+ await client.callTool(+ { name: "binary_session", arguments: {} },+ mcpOptions,),+ "binary_session",);- const providerStatus = providerStatusEnvelope.result;if (providerStatus.analysis_provider_binding?.provider?.id !== "hopper" ||providerStatus.analysis_provider_binding?.selection_source !== "request"diff --git a/scripts/verify-packaged-ghidra-windows.mjs b/scripts/verify-packaged-ghidra-windows.mjsindex b38072c8c..2c5f15e62 100644--- a/scripts/verify-packaged-ghidra-windows.mjs+++ b/scripts/verify-packaged-ghidra-windows.mjs@@ -1,7 +1,10 @@#!/usr/bin/env nodeimport assert from "node:assert/strict";-import { requireMcpOperationResult } from "./lib/mcp-verifier-results.mjs";+import {+ expandProviderOutput,+ requireMcpOperationResult,+} from "./lib/mcp-verifier-results.mjs";import { verifyGhidraCompactReferences } from "./lib/real-ghidra-compact-references.mjs";import { execFile } from "node:child_process";import { createHash } from "node:crypto";@@ -230,14 +233,16 @@ const assertCleanup = async () => {assert.equal(entries.length, 0, "Provider runtime cleanup left files.");};try {- const providers = JSON.parse(- (- await exec(process.execPath, [entry, "providers", "--json"], {- env: environment,- cwd: callerDirectory,- timeout: 30_000,- })- ).stdout,+ const providers = expandProviderOutput(+ JSON.parse(+ (+ await exec(process.execPath, [entry, "providers", "--json"], {+ env: environment,+ cwd: callerDirectory,+ timeout: 30_000,+ })+ ).stdout,+ ),);assert.equal(providers.analysis_provider_binding, null);assert.ok(Array.isArray(providers.analysis_provider_candidates));diff --git a/scripts/verify-published-package.mjs b/scripts/verify-published-package.mjsindex 12859d4bb..8c0281d56 100644--- a/scripts/verify-published-package.mjs+++ b/scripts/verify-published-package.mjs@@ -10,6 +10,11 @@ import { pathToFileURL } from "node:url";import { lt, rcompare } from "semver";import { CATALOG_IDENTITY } from "../dist/catalogIdentity.js";+import { TOOL_CONTRACTS } from "../dist/contracts/toolContracts.js";+import {+ requireMcpLifecycleResult,+ sortVerifierNames,+} from "./lib/mcp-verifier-results.mjs";import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";const verifierRun = createVerifierRun();@@ -54,27 +59,39 @@ try {await client.connect(transport);const tools = await client.listTools();const toolNames = tools.tools.map(({ name }) => name);- const canonicalToolNames = new Set(- CATALOG_IDENTITY.tools.map(({ name }) => name),- );+ const canonicalToolNames = new Set(TOOL_CONTRACTS.map(({ name }) => name));const unknownToolNames = toolNames.filter((name) => !canonicalToolNames.has(name),);+ const publishedToolNames = new Set(toolNames);+ const missingToolNames = [...canonicalToolNames].filter(+ (name) => !publishedToolNames.has(name),+ );publishedToolCount = toolNames.length;if (publishedToolCount === 0 ||- new Set(toolNames).size !== publishedToolCount ||- unknownToolNames.length > 0+ publishedToolNames.size !== publishedToolCount ||+ unknownToolNames.length > 0 ||+ missingToolNames.length > 0)throw new Error(- `Published MCP exposed an invalid capability-scoped tool projection (${String(publishedToolCount)} tools, unknown: ${unknownToolNames.join(", ") || "none"})`,+ `Published MCP exposed an invalid canonical tool catalog (${String(publishedToolCount)} tools, unknown: ${unknownToolNames.join(", ") || "none"}, missing: ${missingToolNames.join(", ") || "none"})`,);- const status = await client.callTool({+ const statusReply = await client.callTool({name: "binary_session",arguments: {},});- if (status.isError === true)- throw new Error("Published target-free MCP session check failed");+ const status = requireMcpLifecycleResult(statusReply, "binary_session");+ const availabilityNames = sortVerifierNames(+ status.tool_availability.map(({ name }) => name),+ );+ if (+ JSON.stringify(availabilityNames) !==+ JSON.stringify(sortVerifierNames(canonicalToolNames))+ )+ throw new Error(+ "Published binary_session omitted canonical tool availability",+ );update = await verifyPublishedUpdate({ version, canaryRoot });} catch (cause) {throw new Error(`Published package verification failed: ${stderr}`, {diff --git a/scripts/verify-real-hopper.mjs b/scripts/verify-real-hopper.mjsindex 97ad4ac9e..12400cb94 100644--- a/scripts/verify-real-hopper.mjs+++ b/scripts/verify-real-hopper.mjs@@ -30,6 +30,7 @@ import {requireMcpOperationResult,requireMcpLifecycleResult,requireMcpEvidenceResult,+ sortVerifierNames,requireWorkflowEvidenceProvider,} from "./lib/mcp-verifier-results.mjs";import {@@ -283,8 +284,10 @@ try {const availableTools = initialStatus.tool_availability;if (!Array.isArray(availableTools))throw new Error("The real session omitted tool availability");- const expectedNames = availableTools.map(({ name }) => name).sort();- const actualNames = listed.tools.map(({ name }) => name).sort();+ const expectedNames = sortVerifierNames(+ availableTools.map(({ name }) => name),+ );+ const actualNames = sortVerifierNames(listed.tools.map(({ name }) => name));if (JSON.stringify(actualNames) !== JSON.stringify(expectedNames)) {const expected = new Set(expectedNames);const actual = new Set(actualNames);diff --git a/scripts/verify/android/failure-recovery.mjs b/scripts/verify/android/failure-recovery.mjsindex adcf41d74..8e1816aed 100644--- a/scripts/verify/android/failure-recovery.mjs+++ b/scripts/verify/android/failure-recovery.mjs@@ -1,4 +1,8 @@-import { requireMcpToolError } from "../../lib/mcp-verifier-results.mjs";+import {+ requireMcpLifecycleResult,+ requireMcpToolError,+ sortVerifierNames,+} from "../../lib/mcp-verifier-results.mjs";import assert from "node:assert/strict";import {access,@@ -273,22 +277,23 @@ const verifyAndroidReadiness = async ({try {await client.connect(transport);const catalog = await client.listTools();- const catalogNames = catalog.tools.map(({ name }) => name).sort();- const status = await client.callTool({+ const catalogNames = sortVerifierNames(+ catalog.tools.map(({ name }) => name),+ );+ const statusReply = await client.callTool({name: "binary_session",arguments: {},});- assert.notEqual(status.isError, true, JSON.stringify(status));- const availability = status.structuredContent?.result?.tool_availability;- assert.ok(Array.isArray(availability));+ const status = requireMcpLifecycleResult(statusReply, "binary_session");+ const availability = status.tool_availability;assert.deepEqual(- availability.map(({ name }) => name).sort(),- TOOL_CONTRACTS.map(({ name }) => name).sort(),+ sortVerifierNames(availability.map(({ name }) => name)),+ sortVerifierNames(TOOL_CONTRACTS.map(({ name }) => name)),"Readiness must retain one availability record for the complete canonical catalog",);assert.deepEqual(catalogNames,- TOOL_CONTRACTS.map(({ name }) => name).sort(),+ sortVerifierNames(TOOL_CONTRACTS.map(({ name }) => name)),"Readiness must not truncate the SDK tool catalog",);const byName = new Map(availability.map((item) => [item.name, item]));diff --git a/src/application/CapabilityInventory.test.ts b/src/application/CapabilityInventory.test.tsindex a267f2b58..6508d3142 100644--- a/src/application/CapabilityInventory.test.ts+++ b/src/application/CapabilityInventory.test.ts@@ -1,6 +1,15 @@import { describe, expect, it } from "vitest";-import { buildCapabilityInventory } from "./CapabilityInventory.js";+import {+ buildCapabilityInventory,+ compactToolAvailability,+} from "./CapabilityInventory.js";+import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";+import {+ expandToolAvailability,+ toolAvailabilityInventory,+ type ToolAvailability,+} from "../contracts/toolOutputSchemaPrimitives.js";it("reports module syntax and native resolution availability separately", () => {const input = { open: false, capabilities: [] };@@ -55,22 +64,25 @@ const status = (open: options.open ?? false,...(options.kind === undefined ? {} : { kind: options.kind }),...(options.format === undefined ? {} : { format: options.format }),- capabilities: (options.capabilities ?? []).map((capability) => ({- ...capability,- availability_code: capability.available- ? null- : (capability.availability_code ?? null),- effects: {- mutates_artifact: false,- launches_process: false,- may_show_ui: false,- may_access_network: false,- may_write_filesystem: false,- changes_permissions: false,- requires_root: false,- },- limitations: [],- })),+ capabilities:+ options.capabilities === undefined || options.capabilities.length === 0+ ? []+ : [+ {+ provider: { id: "fixture", name: "Fixture", version: "1" },+ shared_limitations: [],+ groups: options.capabilities.map((capability) => ({+ operations: [capability.operation],+ effects: [],+ limitations: [],+ available: capability.available,+ reason: capability.reason,+ availability_code: capability.available+ ? null+ : (capability.availability_code ?? null),+ })),+ },+ ],});const entry = (@@ -171,6 +183,152 @@ describe("capability failure reasons", () => {});});+describe("compact tool availability", () => {+ it("round-trips complete facts, omitted modes, and per-group client requirements", () => {+ const full = buildCapabilityInventory(status(), enabledPolicy);+ const alternateRequirements = {+ required: ["roots"],+ optional: [],+ missing_required: ["roots"],+ missing_optional: [],+ } satisfies ToolAvailability["client_requirements"];+ const withOverride = full.map((entry, index) =>+ index === 1+ ? {+ ...entry,+ available: false as const,+ reason: "client_capability_missing" as const,+ remediation: "Use an MCP client with roots support.",+ client_requirements: alternateRequirements,+ }+ : entry,+ );+ const compact = compactToolAvailability(withOverride);+ const expanded = expandToolAvailability(compact).toSorted((left, right) =>+ left.name.localeCompare(right.name),+ );++ expect(expanded).toEqual(+ withOverride.toSorted((left, right) =>+ left.name.localeCompare(right.name),+ ),+ );+ expect(compact.client_requirements).toEqual(+ withOverride[0]?.client_requirements,+ );+ expect(+ compact.groups.find((group) => group.client_requirements !== undefined)+ ?.client_requirements,+ ).toEqual(alternateRequirements);+ expect(compact.groups.every((group) => group.names.length > 0)).toBe(true);+ const names = compact.groups.flatMap((group) => group.names).sort();+ expect(names).toEqual(TOOL_CONTRACTS.map(({ name }) => name).sort());+ expect(new Set(names).size).toBe(names.length);+ expect(expanded.some((entry) => !Object.hasOwn(entry, "modes"))).toBe(true);+ });++ it("preserves an empty inventory with an explicit empty client baseline", () => {+ const compact = compactToolAvailability([]);+ expect(compact).toEqual({+ client_requirements: {+ required: [],+ optional: [],+ missing_required: [],+ missing_optional: [],+ },+ groups: [],+ });+ expect(expandToolAvailability(compact)).toEqual([]);+ });++ it("rejects malformed compact facts and accepts an equivalent explicit baseline", () => {+ const compact = compactToolAvailability(+ buildCapabilityInventory(status(), enabledPolicy),+ );+ const firstGroup = compact.groups[0];+ expect(firstGroup).toBeDefined();+ if (firstGroup === undefined) throw new Error("Expected tool groups");+ const availableIndex = compact.groups.findIndex((group) => group.available);+ if (availableIndex < 0) throw new Error("Expected an available tool group");++ const malformedInventories = [+ {+ ...compact,+ groups: compact.groups.map((group, index) =>+ index === 0+ ? { ...group, effects: [...group.effects, "unknown_effect"] }+ : group,+ ),+ },+ {+ ...compact,+ groups: compact.groups.map((group, index) =>+ index === 0+ ? {+ ...group,+ annotations: [...group.annotations, "unknown_hint"],+ }+ : group,+ ),+ },+ {+ ...compact,+ groups: compact.groups.map((group, index) =>+ index === 0 ? { ...group, names: [] } : group,+ ),+ },+ {+ ...compact,+ groups: compact.groups.map((group, index) =>+ index === 0 ? { ...group, names: [""] } : group,+ ),+ },+ {+ ...compact,+ groups: compact.groups.map((group, index) =>+ index === availableIndex+ ? { ...group, reason: "provider_missing" }+ : group,+ ),+ },+ {+ ...compact,+ groups: compact.groups.map((group, index) =>+ index === availableIndex+ ? { ...group, remediation: "unexpected remediation" }+ : group,+ ),+ },+ ];+ for (const malformed of malformedInventories)+ expect(toolAvailabilityInventory.safeParse(malformed).success).toBe(+ false,+ );++ const inheritedGroup = compact.groups.find(+ (group) => group.client_requirements === undefined,+ );+ expect(inheritedGroup).toBeDefined();+ if (inheritedGroup === undefined)+ throw new Error("Expected an inherited client-requirements group");+ const explicitBaseline = {+ ...compact,+ groups: compact.groups.map((group) =>+ group === inheritedGroup+ ? { ...group, client_requirements: compact.client_requirements }+ : group,+ ),+ };+ const parsedOverride =+ toolAvailabilityInventory.safeParse(explicitBaseline);+ expect(parsedOverride.success).toBe(true);+ if (parsedOverride.success)+ expect(expandToolAvailability(parsedOverride.data)).toEqual(+ expandToolAvailability(compact),+ );+ });+});+describe("partial navigation availability", () => {it("allows explicit documents when the provider has no current-document getter", () => {const capabilities = [@@ -258,6 +416,36 @@ describe("partial navigation availability", () => {remediation: "Navigation requires macOS.",});});++ it("lists shared missing operations once in combined remediation", () => {+ const availability = entry(+ "get_navigation_context",+ status({ open: true, kind: "executable" }),+ );++ expect(availability).toMatchObject({+ reason: "provider_missing",+ remediation:+ "Configure a provider for one of: current_document, current_address, resolve_containing_procedure.",+ modes: [+ {+ name: "current_selection",+ missing_operations: [+ "current_document",+ "current_address",+ "resolve_containing_procedure",+ ],+ },+ {+ name: "explicit_document",+ missing_operations: [+ "current_address",+ "resolve_containing_procedure",+ ],+ },+ ],+ });+ });});it("reports host denial before target mismatch but keeps composed workflow prerequisites", () => {diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.tsindex d11a582b2..ec3842376 100644--- a/src/application/CapabilityInventory.ts+++ b/src/application/CapabilityInventory.ts@@ -5,9 +5,14 @@ import type {} from "./OptionalObservationProviders.js";import {- providerCapability,+ expandProviderCapabilities,+ providerCapabilitySet,+ toolAvailabilityInventory,+ TOOL_ANNOTATION_NAMES,+ TOOL_EFFECT_NAMES,type ClientFeatureAvailability,type ProviderCapability,+ type ToolAvailabilityInventory,type ToolAvailability,type ToolAvailabilityMode,type ToolUnavailabilityReason,@@ -26,7 +31,9 @@ const statusSchema = z.object({open: z.boolean(),kind: z.enum(["executable", "database", "archive", "artifact"]).optional(),format: z.string().optional(),- capabilities: z.array(providerCapability),+ capabilities: z+ .array(providerCapabilitySet)+ .transform(expandProviderCapabilities),});type ToolAvailabilityReason = "available" | ToolUnavailabilityReason;@@ -214,6 +221,60 @@ export const buildCapabilityInventory = (}).sort((left, right) => compareUnicodeCodePoints(left.name, right.name));};+type ClientRequirements = ToolAvailability["client_requirements"];+type MutableAvailabilityGroup = Omit<+ ToolAvailabilityInventory["groups"][number],+ "names"+> & { names: string[] };++const EMPTY_CLIENT_REQUIREMENTS: ClientRequirements = {+ required: [],+ optional: [],+ missing_required: [],+ missing_optional: [],+};++/** Compact repeated metadata while retaining every operation's current availability inline. */+export const compactToolAvailability = (+ availability: readonly ToolAvailability[],+): ToolAvailabilityInventory => {+ const clientRequirements =+ availability[0]?.client_requirements ?? EMPTY_CLIENT_REQUIREMENTS;+ const groups = new Map<string, MutableAvailabilityGroup>();++ for (const entry of availability) {+ const effects = TOOL_EFFECT_NAMES.filter((name) => entry.effects[name]);+ const annotations = TOOL_ANNOTATION_NAMES.filter(+ (name) => entry.annotations[name],+ );+ const groupFacts = {+ surface: entry.surface,+ effects,+ annotations,+ available: entry.available,+ reason: entry.reason,+ remediation: entry.remediation,+ ...(entry.default_mode_available === undefined+ ? {}+ : { default_mode_available: entry.default_mode_available }),+ ...(entry.modes === undefined ? {} : { modes: [...entry.modes] }),+ ...(JSON.stringify(entry.client_requirements) ===+ JSON.stringify(clientRequirements)+ ? {}+ : { client_requirements: entry.client_requirements }),+ };+ const key = JSON.stringify(groupFacts);+ const existing = groups.get(key);+ if (existing) existing.names.push(entry.name);+ else groups.set(key, { ...groupFacts, names: [entry.name] });+ }++ return toolAvailabilityInventory.parse({+ client_requirements: clientRequirements,+ groups: [...groups.values()],+ });+};+const availabilityFor = (context: AvailabilityContext): Availability => {// These built-in workflows accept a caller-selected endpoint; they do not load the optional passive provider.if (@@ -626,14 +687,15 @@ const navigationContextAvailability = (};if (availableMode !== undefined)return { ...facts, reason: "available", remediation: null };+ const missingOperations = [+ ...new Set(modes.flatMap((mode) => mode.missing_operations)),+ ];return {...facts,reason: failure?.reason ?? "provider_missing",remediation:specificFailureRemediation ??- `Configure a provider for one of: ${modes- .flatMap((mode) => mode.missing_operations)- .join(", ")}.`,+ `Configure a provider for one of: ${missingOperations.join(", ")}.`,};};diff --git a/src/application/binary/BinarySessionStatus.test.ts b/src/application/binary/BinarySessionStatus.test.tsnew file mode 100644index 000000000..a72b7ed80--- /dev/null+++ b/src/application/binary/BinarySessionStatus.test.ts@@ -0,0 +1,391 @@+import { describe, expect, it } from "vitest";++import type {+ CapabilityDescriptor,+ ProviderIdentity,+} from "../AnalysisProvider.js";+import {+ expandProviderCapabilities,+ type ProviderCapabilitySet,+} from "../../contracts/toolOutputSchemaPrimitives.js";+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";+import type { AnalysisProviderCandidateStatus } from "./AnalysisProviderRegistry.js";+import type {+ SessionProviderRoute,+ SessionProviderRouter,+} from "./SessionProviderRouter.js";+import { binarySessionStatus } from "./BinarySessionStatus.js";++type ProjectedStatus = {+ capabilities: ProviderCapabilitySet[];+ analysis_provider_candidates: {+ provider: ProviderIdentity;+ availability: unknown;+ target_support: unknown;+ selected: boolean;+ capabilities: ProviderCapabilitySet[];+ }[];+};++const providerA: ProviderIdentity = {+ id: "provider-a",+ name: "Provider A",+ version: "1.0",+};+const providerB: ProviderIdentity = {+ id: "provider-b",+ name: "Provider B",+ version: "2.0",+};++const MUTATING_EFFECTS = {+ mutates_artifact: true,+ launches_process: false,+ may_show_ui: false,+ may_access_network: false,+ may_write_filesystem: false,+ changes_permissions: false,+ requires_root: false,+};++type DescriptorOptions = {+ readonly launchesProcess?: boolean;+} & (+ | {+ readonly available?: true;+ readonly reason?: never;+ readonly availabilityCode?: never;+ }+ | {+ readonly available: false;+ readonly reason?: string;+ readonly availabilityCode?: "architecture_unsupported";+ }+);++const descriptor = (+ provider: ProviderIdentity,+ operation: CapabilityDescriptor["operation"],+ limitations: readonly string[],+ options: DescriptorOptions = {},+): CapabilityDescriptor => {+ const availability =+ options.available === false+ ? {+ available: false as const,+ reason: options.reason ?? "Unavailable",+ ...(options.availabilityCode === undefined+ ? {}+ : { availabilityCode: options.availabilityCode }),+ }+ : { available: true as const, reason: null };+ return {+ provider,+ operation,+ ...availability,+ effects: {+ mutatesArtifact: true,+ launchesProcess: options.launchesProcess ?? false,+ mayShowUi: false,+ mayAccessNetwork: false,+ mayWriteFilesystem: false,+ changesPermissions: false,+ requiresRoot: false,+ },+ limitations,+ };+};++const candidate = (+ provider: ProviderIdentity,+ capabilities: readonly CapabilityDescriptor[],+): AnalysisProviderCandidateStatus => ({+ provider,+ availability: {+ status: "available",+ code: null,+ reason: null,+ diagnostics: {},+ },+ targetSupport: {+ status: "unknown",+ code: null,+ reason: "No target is open.",+ diagnostics: {},+ },+ selected: true,+ capabilities,+});++const project = (+ routeCapabilities: readonly CapabilityDescriptor[],+ candidates: readonly AnalysisProviderCandidateStatus[],+ runtimeUnavailability: ReadonlyMap<+ string,+ { readonly reason: string }+ > = new Map(),+): ProjectedStatus => {+ const route = {+ capabilities: new Map(+ routeCapabilities.map((capability) => [capability.operation, capability]),+ ),+ binding: null,+ } as unknown as SessionProviderRoute;+ const router = {+ candidateStatuses: () => candidates,+ } as unknown as SessionProviderRouter;+ return binarySessionStatus({+ target: undefined,+ route,+ router,+ runtimeUnavailability,+ runId: undefined,+ runtimeLineageSnapshots: [],+ requestActivitySnapshots: [],+ }) as unknown as ProjectedStatus;+};++const expandCanonicalCapabilities = (sets: readonly ProviderCapabilitySet[]) =>+ [...expandProviderCapabilities(sets)].sort((left, right) =>+ compareUnicodeCodePoints(left.operation, right.operation),+ );++const selectedCapabilities = [+ descriptor(providerA, "xrefs", ["Shared limitation"]),+ descriptor(providerA, "procedure_info", ["Shared limitation"]),+ descriptor(providerA, "read_bytes", ["Shared limitation", "beta detail"]),+];+const otherCapabilities = [+ descriptor(providerB, "read_bytes", ["Different limitation"], {+ launchesProcess: true,+ available: false,+ reason: "Architecture unsupported",+ availabilityCode: "architecture_unsupported",+ }),+];++const expectedRouteCapabilities: ProviderCapabilitySet[] = [+ {+ provider: providerA,+ shared_limitations: ["Shared limitation"],+ groups: [+ {+ operations: ["procedure_info"],+ effects: ["mutates_artifact"],+ limitations: [],+ available: false,+ reason: "Runtime operation failure",+ availability_code: null,+ },+ {+ operations: ["read_bytes"],+ effects: ["mutates_artifact"],+ limitations: ["beta detail"],+ available: true,+ reason: null,+ availability_code: null,+ },+ {+ operations: ["xrefs"],+ effects: ["mutates_artifact"],+ limitations: [],+ available: true,+ reason: null,+ availability_code: null,+ },+ ],+ },+];+const expectedExpandedRouteCapabilities = [+ {+ provider: providerA,+ operation: "procedure_info",+ available: false,+ reason: "Runtime operation failure",+ availability_code: null,+ effects: MUTATING_EFFECTS,+ limitations: ["Shared limitation"],+ },+ {+ provider: providerA,+ operation: "read_bytes",+ available: true,+ reason: null,+ availability_code: null,+ effects: MUTATING_EFFECTS,+ limitations: ["Shared limitation", "beta detail"],+ },+ {+ provider: providerA,+ operation: "xrefs",+ available: true,+ reason: null,+ availability_code: null,+ effects: MUTATING_EFFECTS,+ limitations: ["Shared limitation"],+ },+];+const expectedCandidateCapabilities: ProviderCapabilitySet[] = [+ {+ provider: providerA,+ shared_limitations: ["Shared limitation"],+ groups: [+ {+ operations: ["procedure_info", "xrefs"],+ effects: ["mutates_artifact"],+ limitations: [],+ available: true,+ reason: null,+ availability_code: null,+ },+ {+ operations: ["read_bytes"],+ effects: ["mutates_artifact"],+ limitations: ["beta detail"],+ available: true,+ reason: null,+ availability_code: null,+ },+ ],+ },+ {+ provider: providerB,+ shared_limitations: ["Different limitation"],+ groups: [+ {+ operations: ["read_bytes"],+ effects: ["mutates_artifact", "launches_process"],+ limitations: [],+ available: false,+ reason: "Architecture unsupported",+ availability_code: "architecture_unsupported",+ },+ ],+ },+];+const expectedCandidateStatusFacts = [+ expect.objectContaining({+ provider: providerA,+ target_support: {+ status: "unknown",+ code: null,+ reason: "No target is open.",+ diagnostics: {},+ },+ capabilities: [expectedCandidateCapabilities[0]],+ }),+ expect.objectContaining({+ provider: providerB,+ capabilities: [expectedCandidateCapabilities[1]],+ }),+];+const expectedExpandedCandidateCapabilities = [+ [+ {+ provider: providerA,+ operation: "procedure_info",+ available: true,+ reason: null,+ availability_code: null,+ effects: MUTATING_EFFECTS,+ limitations: ["Shared limitation"],+ },+ {+ provider: providerA,+ operation: "read_bytes",+ available: true,+ reason: null,+ availability_code: null,+ effects: MUTATING_EFFECTS,+ limitations: ["Shared limitation", "beta detail"],+ },+ {+ provider: providerA,+ operation: "xrefs",+ available: true,+ reason: null,+ availability_code: null,+ effects: MUTATING_EFFECTS,+ limitations: ["Shared limitation"],+ },+ ],+ [+ {+ provider: providerB,+ operation: "read_bytes",+ available: false,+ reason: "Architecture unsupported",+ availability_code: "architecture_unsupported",+ effects: { ...MUTATING_EFFECTS, launches_process: true },+ limitations: ["Different limitation"],+ },+ ],+];++describe("binary session provider capability projection", () => {+ it("preserves provider scope and route overlays while factoring exact prefixes", () => {+ const selectedBefore = structuredClone(selectedCapabilities);+ const otherBefore = structuredClone(otherCapabilities);+ const status = project(+ selectedCapabilities,+ [+ candidate(providerA, selectedCapabilities),+ candidate(providerB, otherCapabilities),+ ],+ new Map([["procedure_info", { reason: "Runtime operation failure" }]]),+ );+ expect(selectedCapabilities).toEqual(selectedBefore);+ expect(otherCapabilities).toEqual(otherBefore);+ expect(status.capabilities).toEqual(expectedRouteCapabilities);+ expect(expandCanonicalCapabilities(status.capabilities)).toEqual(+ expectedExpandedRouteCapabilities,+ );+ expect(status.analysis_provider_candidates).toEqual(+ expectedCandidateStatusFacts,+ );+ const selectedCandidate = status.analysis_provider_candidates[0];+ const otherCandidate = status.analysis_provider_candidates[1];+ expect(selectedCandidate).toBeDefined();+ expect(otherCandidate).toBeDefined();+ expect(+ expandCanonicalCapabilities(selectedCandidate?.capabilities ?? []),+ ).toEqual(expectedExpandedCandidateCapabilities[0]);+ expect(+ expandCanonicalCapabilities(otherCandidate?.capabilities ?? []),+ ).toEqual(expectedExpandedCandidateCapabilities[1]);+ });++ it("keeps empty route and candidate capability collections empty", () => {+ const status = project([], [candidate(providerA, [])]);+ expect(status.capabilities).toEqual([]);+ expect(status.analysis_provider_candidates[0]?.capabilities).toEqual([]);+ });++ it("preserves repeated limitations in their original order", () => {+ const capabilities = [+ descriptor(providerA, "procedure_info", [+ "Repeated",+ "Repeated",+ "left detail",+ ]),+ descriptor(providerA, "xrefs", ["Repeated", "Repeated", "right detail"]),+ ];+ const status = project(capabilities, []);++ expect(status.capabilities[0]).toMatchObject({+ shared_limitations: ["Repeated", "Repeated"],+ groups: [+ { operations: ["procedure_info"], limitations: ["left detail"] },+ { operations: ["xrefs"], limitations: ["right detail"] },+ ],+ });+ expect(+ expandCanonicalCapabilities(status.capabilities).map(+ ({ limitations }) => limitations,+ ),+ ).toEqual([+ ["Repeated", "Repeated", "left detail"],+ ["Repeated", "Repeated", "right detail"],+ ]);+ });+});diff --git a/src/application/binary/BinarySessionStatus.ts b/src/application/binary/BinarySessionStatus.tsindex 8fbe4aa2b..4794bed49 100644--- a/src/application/binary/BinarySessionStatus.ts+++ b/src/application/binary/BinarySessionStatus.ts@@ -4,9 +4,14 @@ import type { JsonValue } from "../../domain/jsonValue.js";import type { ProviderOperationHealth } from "../../domain/providerOperationHealth.js";import type {CapabilityDescriptor,+ ProviderIdentity,ProviderRequestActivitySnapshot,ProviderRuntimeLineageSnapshot,} from "../AnalysisProvider.js";+import {+ PROVIDER_EFFECT_NAMES,+ type ProviderCapabilitySet,+} from "../../contracts/toolOutputSchemaPrimitives.js";import type {SessionProviderRoute,SessionProviderRouter,@@ -38,7 +43,7 @@ export const binarySessionStatus = ({requestActivitySnapshots,providerOperationHealth,}: BinarySessionStatusInput): JsonValue => {- const capabilities = [...route.capabilities.values()]+ const routeCapabilities = [...route.capabilities.values()].filter(({ operation }) => operation !== "inventory_artifact").sort((left, right) =>compareUnicodeCodePoints(left.operation, right.operation),@@ -52,8 +57,8 @@ export const binarySessionStatus = ({available: false as const,reason: unavailable.reason,};- })- .map(capabilityStatus);+ });+ const capabilities = providerCapabilitySets(routeCapabilities);const analysisProviderBinding =route.binding === null? null@@ -69,13 +74,14 @@ export const binarySessionStatus = ({availability: structuredClone(candidate.availability),target_support: structuredClone(candidate.targetSupport),selected: candidate.selected,- capabilities: candidate.capabilities- .slice()- .filter(({ operation }) => operation !== "inventory_artifact")- .sort((left, right) =>- compareUnicodeCodePoints(left.operation, right.operation),- )- .map(capabilityStatus),+ capabilities: providerCapabilitySets(+ candidate.capabilities+ .slice()+ .filter(({ operation }) => operation !== "inventory_artifact")+ .sort((left, right) =>+ compareUnicodeCodePoints(left.operation, right.operation),+ ),+ ),}));const common = {capabilities,@@ -187,17 +193,109 @@ const processLineageStatus = (})),};-const capabilityStatus = (- descriptor: Omit<CapabilityDescriptor, "available" | "reason"> & {- readonly available: boolean;- readonly reason: string | null;- },-) => ({- operation: descriptor.operation,- available: descriptor.available,- reason: descriptor.reason,- availability_code: descriptor.availabilityCode ?? null,- effects: {+type CapabilityEffectName = (typeof PROVIDER_EFFECT_NAMES)[number];+type CapabilityAvailabilityCode = Exclude<+ CapabilityDescriptor["availabilityCode"],+ undefined+>;+type CapabilityProjection = Omit<CapabilityDescriptor, "available" | "reason"> &+ (+ | { readonly available: true; readonly reason: null }+ | { readonly available: false; readonly reason: string }+ );+type ProviderCapabilityGroup = ProviderCapabilitySet["groups"][number];++/** Group inline capability facts without merging distinct providers or states. */+const providerCapabilitySets = (+ descriptors: readonly CapabilityProjection[],+): ProviderCapabilitySet[] => {+ const providers = new Map<+ string,+ {+ readonly identity: ProviderIdentity;+ readonly descriptors: CapabilityProjection[];+ }+ >();+ for (const descriptor of descriptors) {+ const key = JSON.stringify([+ descriptor.provider.id,+ descriptor.provider.name,+ descriptor.provider.version,+ ]);+ const provider = providers.get(key);+ if (provider === undefined)+ providers.set(key, {+ identity: descriptor.provider,+ descriptors: [descriptor],+ });+ else provider.descriptors.push(descriptor);+ }+ return [...providers.values()].map(({ identity, descriptors: owned }) => {+ const sharedLimitations = commonLimitationsPrefix(owned);+ const groups = new Map<string, ProviderCapabilityGroup>();+ for (const descriptor of owned) {+ const effects = enabledCapabilityEffects(descriptor);+ const limitations = descriptor.limitations.slice(+ sharedLimitations.length,+ );+ const availabilityCode: CapabilityAvailabilityCode | null =+ descriptor.availabilityCode ?? null;+ const status = descriptor.available+ ? {+ available: true as const,+ reason: null,+ availability_code: null,+ }+ : {+ available: false as const,+ reason: descriptor.reason,+ availability_code: availabilityCode,+ };+ const key = JSON.stringify([+ effects,+ limitations,+ status.available,+ status.reason,+ status.availability_code,+ ]);+ const group = groups.get(key);+ if (group === undefined)+ groups.set(key, {+ operations: [descriptor.operation],+ effects,+ limitations,+ ...status,+ });+ else group.operations.push(descriptor.operation);+ }+ return {+ provider: providerSummary(identity),+ shared_limitations: sharedLimitations,+ groups: [...groups.values()],+ };+ });+};++const commonLimitationsPrefix = (+ descriptors: readonly CapabilityProjection[],+): string[] => {+ const first = descriptors[0]?.limitations;+ if (first === undefined) return [];+ let length = first.length;+ for (const descriptor of descriptors.slice(1)) {+ length = Math.min(length, descriptor.limitations.length);+ let index = 0;+ while (index < length && first[index] === descriptor.limitations[index])+ index++;+ length = index;+ }+ return first.slice(0, length);+};++const enabledCapabilityEffects = (+ descriptor: CapabilityProjection,+): CapabilityEffectName[] => {+ const effectValues = {mutates_artifact: descriptor.effects.mutatesArtifact,launches_process: descriptor.effects.launchesProcess,may_show_ui: descriptor.effects.mayShowUi,@@ -205,9 +303,9 @@ const capabilityStatus = (may_write_filesystem: descriptor.effects.mayWriteFilesystem,changes_permissions: descriptor.effects.changesPermissions,requires_root: descriptor.effects.requiresRoot,- },- limitations: [...descriptor.limitations],-});+ } satisfies Record<CapabilityEffectName, boolean>;+ return PROVIDER_EFFECT_NAMES.filter((name) => effectValues[name]);+};const providerOperationHealthStatus = (health: ProviderOperationHealth | null | undefined,diff --git a/src/catalogIdentity.ts b/src/catalogIdentity.tsindex 408ec68e0..050f5c7dc 100644--- a/src/catalogIdentity.ts+++ b/src/catalogIdentity.ts@@ -74,15 +74,4 @@ export const CATALOG_IDENTITY = {get digests() {return (catalogDigests ??= createCatalogDigests());},- tools: sortedToolContracts.map(({ name, kind, effects, annotations }) => ({- name,- surface: kind,- effects: { ...effects },- annotations: {- read_only: annotations.readOnlyHint ?? false,- destructive: annotations.destructiveHint ?? false,- idempotent: annotations.idempotentHint ?? false,- open_world: annotations.openWorldHint ?? true,- },- })),} as const;diff --git a/src/contracts/toolOutputSchemaPrimitives.ts b/src/contracts/toolOutputSchemaPrimitives.tsindex b8d7815f3..618301797 100644--- a/src/contracts/toolOutputSchemaPrimitives.ts+++ b/src/contracts/toolOutputSchemaPrimitives.ts@@ -108,12 +108,73 @@ export const providerCapability = z.discriminatedUnion("available", []);export type ProviderCapability = z.output<typeof providerCapability>;+/** Listed effects are true; all other members of this closed vocabulary are false. */+export const PROVIDER_EFFECT_NAMES = Object.keys(+ providerCapabilityFacts.effects.shape,+) as (keyof z.output<typeof providerCapabilityFacts.effects>)[];+export const providerIdentity = z.object({id: z.string(),name: z.string(),version: z.string().nullable(),});+const providerCapabilityGroupFacts = {+ operations: z.array(z.string().min(1)).min(1),+ effects: z.array(providerCapabilityFacts.effects.keyof()),+ limitations: z.array(z.string()),+};++const providerCapabilityGroup = z.discriminatedUnion("available", [+ z.strictObject({+ ...providerCapabilityGroupFacts,+ available: z.literal(true),+ reason: z.null(),+ availability_code: z.null(),+ }),+ z.strictObject({+ ...providerCapabilityGroupFacts,+ available: z.literal(false),+ reason: z.string().nullable(),+ availability_code: z.enum(PROVIDER_REJECTION_CODES).nullable(),+ }),+]);++/** Shared limitations precede each group's suffix, preserving exact source order. */+export const providerCapabilitySet = z.strictObject({+ provider: providerIdentity,+ shared_limitations: z.array(z.string()),+ groups: z.array(providerCapabilityGroup),+});+export type ProviderCapabilitySet = z.output<typeof providerCapabilitySet>;++/** Decode one status scope without losing provider identity or limitation order. */+export const expandProviderCapabilities = (+ sets: readonly ProviderCapabilitySet[],+): readonly (ProviderCapability & {+ readonly provider: z.output<typeof providerIdentity>;+})[] =>+ sets.flatMap((set) =>+ set.groups.flatMap((group) =>+ group.operations.map((operation) => ({+ ...providerCapability.parse({+ operation,+ available: group.available,+ reason: group.reason,+ availability_code: group.availability_code,+ effects: Object.fromEntries(+ PROVIDER_EFFECT_NAMES.map((name) => [+ name,+ group.effects.includes(name),+ ]),+ ),+ limitations: [...set.shared_limitations, ...group.limitations],+ }),+ provider: set.provider,+ })),+ ),+ );+const processCoordinates = {launcher_pid: z.number().int().min(1),process_group_id: z.number().int().min(1),@@ -334,9 +395,77 @@ export type ToolUnavailabilityReason = z.output<typeof toolUnavailabilityReason>;+export const TOOL_EFFECT_NAMES = Object.keys(+ toolAvailabilityFacts.effects.shape,+) as (keyof z.output<typeof toolAvailabilityFacts.effects>)[];+export const TOOL_ANNOTATION_NAMES = Object.keys(+ toolAvailabilityFacts.annotations.shape,+) as (keyof z.output<typeof toolAvailabilityFacts.annotations>)[];++const toolAvailabilityGroupFacts = {+ names: z.array(z.string().min(1)).min(1),+ surface: toolAvailabilityFacts.surface,+ default_mode_available: toolAvailabilityFacts.default_mode_available,+ modes: toolAvailabilityFacts.modes,+ client_requirements: toolAvailabilityFacts.client_requirements.optional(),+ effects: z.array(toolAvailabilityFacts.effects.keyof()),+ annotations: z.array(toolAvailabilityFacts.annotations.keyof()),+};++const toolAvailabilityGroup = z.discriminatedUnion("available", [+ z.strictObject({+ ...toolAvailabilityGroupFacts,+ available: z.literal(true),+ reason: z.literal("available"),+ remediation: z.null(),+ }),+ z.strictObject({+ ...toolAvailabilityGroupFacts,+ available: z.literal(false),+ reason: toolUnavailabilityReason,+ remediation: z.string().nullable(),+ }),+]);++/** Complete inventory with explicit inherited client requirements and enabled flags. */+export const toolAvailabilityInventory = z.strictObject({+ client_requirements: toolAvailabilityFacts.client_requirements,+ groups: z.array(toolAvailabilityGroup),+});+export type ToolAvailabilityInventory = z.output<+ typeof toolAvailabilityInventory+>;++/** Expand the wire representation once at the consuming boundary. */+export const expandToolAvailability = (+ inventory: ToolAvailabilityInventory,+): readonly ToolAvailability[] =>+ inventory.groups.flatMap((group) =>+ group.names.map((name) =>+ toolAvailability.parse({+ ...group,+ name,+ client_requirements:+ group.client_requirements ?? inventory.client_requirements,+ effects: Object.fromEntries(+ TOOL_EFFECT_NAMES.map((effect) => [+ effect,+ group.effects.includes(effect),+ ]),+ ),+ annotations: Object.fromEntries(+ TOOL_ANNOTATION_NAMES.map((annotation) => [+ annotation,+ group.annotations.includes(annotation),+ ]),+ ),+ }),+ ),+ );+export const sessionProvider = z.object({- capabilities: z.array(providerCapability),+ capabilities: z.array(providerCapabilitySet),analysis_run: analysisRun,analysis_activity: analysisActivity,provider_operation_health: providerOperationHealth,@@ -357,10 +486,10 @@ export const sessionProvider = zavailability: providerAvailability,target_support: providerTargetSupport,selected: z.boolean(),- capabilities: z.array(providerCapability),+ capabilities: z.array(providerCapabilitySet),}),),- tool_availability: z.array(toolAvailability),+ tool_availability: toolAvailabilityInventory,client_features: z.object({elicitation_form: z.boolean(),elicitation_url: z.boolean(),@@ -388,7 +517,18 @@ export const sessionProvider = znegotiated_protocol_version: z.string().nullable(),client: z.object({ name: z.string(), version: z.string() }).nullable(),skill: z.object({ name: z.string(), expected_version: z.string() }),- catalog: z.record(z.string(), jsonValueSchema),+ catalog: z.strictObject({+ counts: z.strictObject({+ cli_commands: z.number().int().min(0),+ mcp_tools: z.number().int().min(0),+ mcp_prompts: z.number().int().min(0),+ }),+ digests: z.strictObject({+ tools_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ prompts_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ combined_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ }),+ }),protocol_features: z.object({progress: z.boolean(),cancellation: z.boolean(),diff --git a/src/server/registerSessionStatusTool.ts b/src/server/registerSessionStatusTool.tsindex c20170647..563e7528b 100644--- a/src/server/registerSessionStatusTool.ts+++ b/src/server/registerSessionStatusTool.ts@@ -3,9 +3,15 @@ import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";import type { ProviderAvailability } from "../application/AnalysisProvider.js";import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";-import { buildCapabilityInventory } from "../application/CapabilityInventory.js";+import {+ buildCapabilityInventory,+ compactToolAvailability,+} from "../application/CapabilityInventory.js";import { toolContract } from "../contracts/toolContracts.js";-import type { ClientFeatureAvailability } from "../contracts/toolOutputSchemaPrimitives.js";+import type {+ ClientFeatureAvailability,+ ToolAvailability,+} from "../contracts/toolOutputSchemaPrimitives.js";import { jsonObjectSchema } from "../domain/jsonValue.js";import { createServerIdentity } from "../serverIdentity.js";import { mcpClientMetadata } from "./mcpClientMetadata.js";@@ -13,8 +19,6 @@ import type { AvailabilityPolicy } from "../application/CapabilityInventory.js";import { toolRegistrationOptions } from "./toolRegistrationOptions.js";import { err } from "../domain/result.js";-type ToolAvailability = ReturnType<typeof buildCapabilityInventory>[number];-/** Inputs required to register the binary session status tool. */export interface SessionStatusToolOptions {readonly server: EvidenceMcpServer;@@ -111,7 +115,7 @@ const projectSessionStatus = (options: {}) =>jsonObjectSchema.parse({...options.status,- tool_availability: options.toolAvailability,+ tool_availability: compactToolAvailability(options.toolAvailability),client_features: options.clientFeatures,server_identity: options.serverIdentity,});diff --git a/tests/acceptance/applications/runtime.test.ts b/tests/acceptance/applications/runtime.test.tsindex 3c454258f..cd9f2c312 100644--- a/tests/acceptance/applications/runtime.test.ts+++ b/tests/acceptance/applications/runtime.test.ts@@ -7,7 +7,11 @@ import { z } from "zod";import { CATALOG_IDENTITY } from "../../../src/catalogIdentity.js";import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js";-import { evidenceResultOf } from "../../../src/contracts/toolOutputSchemaPrimitives.js";+import {+ evidenceResultOf,+ expandToolAvailability,+ toolAvailabilityInventory,+} from "../../../src/contracts/toolOutputSchemaPrimitives.js";import { parseEvidence } from "../../../src/domain/evidence.js";const mainPath = fileURLToPath(@@ -24,15 +28,14 @@ const expectAvailableToolInventory = async (client: Client) => {arguments: {},});expect(status.isError).not.toBe(true);- const availability = z+ const inventory = z.object({result: z.object({- tool_availability: z.array(- z.object({ name: z.string(), available: z.boolean() }),- ),+ tool_availability: toolAvailabilityInventory,}),}).parse(status.structuredContent).result.tool_availability;+ const availability = expandToolAvailability(inventory);// This asserts the compiled entrypoint matches the source catalog. When it// fails, check that `dist/` is current (`npm run build:cached`) before// suspecting a registration bug -- a stale build is by far the likeliestdiff --git a/tests/boundary/mcp/browserMcp.test.ts b/tests/boundary/mcp/browserMcp.test.tsindex d97376c55..a8a780d61 100644--- a/tests/boundary/mcp/browserMcp.test.ts+++ b/tests/boundary/mcp/browserMcp.test.ts@@ -10,7 +10,11 @@ import { CdpBrowserProvider } from "../../../src/browser/CdpBrowserProvider.js";import { webPageInspectionSchema } from "../../../src/domain/browserObservationSchemas.js";import { createWebScreenshotArtifact } from "../../../src/domain/webScreenshot.js";import { JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE } from "../../../src/contracts/javascript/javascriptRuntimeReconciliationExample.js";-import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js";+import {+ TOOL_CONTRACTS,+ toolContract,+} from "../../../src/contracts/toolContracts.js";+import { expandToolAvailability } from "../../../src/contracts/toolOutputSchemaPrimitives.js";import { createServer } from "../../../src/server/createServer.js";import { observed } from "../../fixtures/analysisExecution.js";import { runCliJson } from "../../fixtures/cliJsonProcess.js";@@ -59,16 +63,18 @@ it(name: "binary_session",arguments: {},});- expect(status.structuredContent).toMatchObject({- result: {- tool_availability: expect.arrayContaining([- expect.objectContaining({- name: "inspect_web_page",- reason: expect.any(String),- }),- ]),- },- });+ const sessionStatus = toolContract("binary_session").outputSchema.parse(+ status.structuredContent,+ );+ const availability = expandToolAvailability(+ sessionStatus.result.tool_availability,+ );+ expect(availability).toContainEqual(+ expect.objectContaining({+ name: "inspect_web_page",+ reason: expect.any(String),+ }),+ );const listed = await connected.client.callTool({name: "list_browser_targets",arguments: {diff --git a/tests/boundary/mcp/clientCapabilities.test.ts b/tests/boundary/mcp/clientCapabilities.test.tsindex a8acc0048..c741045b2 100644--- a/tests/boundary/mcp/clientCapabilities.test.ts+++ b/tests/boundary/mcp/clientCapabilities.test.ts@@ -7,11 +7,25 @@ import {import { describe, expect, it } from "vitest";import { createServer } from "../../../src/server/createServer.js";+import {+ TOOL_CONTRACTS,+ toolContract,+} from "../../../src/contracts/toolContracts.js";+import { expandToolAvailability } from "../../../src/contracts/toolOutputSchemaPrimitives.js";import {createCacheProvider,createTestBinarySession,} from "../../fixtures/binarySession.js";+const assertCompleteToolAvailability = (structuredContent: unknown): void => {+ const status =+ toolContract("binary_session").outputSchema.parse(structuredContent);+ const availability = expandToolAvailability(status.result.tool_availability);+ expect(availability.map(({ name }) => name).sort()).toEqual(+ TOOL_CONTRACTS.map(({ name }) => name).sort(),+ );+};+describe("per-request client capability reporting", () => {it.each([[{ elicitation: {} }, true, false],@@ -39,6 +53,7 @@ describe("per-request client capability reporting", () => {[CLIENT_CAPABILITIES_META_KEY]: capabilities,},});+ assertCompleteToolAvailability(status.structuredContent);expect(status.structuredContent).toMatchObject({result: {client_features: { elicitation_form: form, elicitation_url: url },@@ -71,13 +86,15 @@ describe("initialize-scoped client metadata", () => {try {await server.connect(serverTransport);await client.connect(clientTransport);- return (+ const result = (await client.callTool({name: "binary_session",arguments: {},...(meta === undefined ? {} : { _meta: meta }),})).structuredContent;+ assertCompleteToolAvailability(result);+ return result;} finally {await Promise.allSettled([client.close(),diff --git a/tests/boundary/mcp/ghidraRoutingMcp.test.ts b/tests/boundary/mcp/ghidraRoutingMcp.test.tsindex f4ed96938..e9fa4d722 100644--- a/tests/boundary/mcp/ghidraRoutingMcp.test.ts+++ b/tests/boundary/mcp/ghidraRoutingMcp.test.ts@@ -1,6 +1,8 @@import { parseMcpToolError } from "../../fixtures/mcpToolError.js";import { describe, expect, it } from "vitest";import { connectGhidraMcp } from "./ghidraMcpHarness.js";+import { toolContract } from "../../../src/contracts/toolContracts.js";+import { expandToolAvailability } from "../../../src/contracts/toolOutputSchemaPrimitives.js";describe("Ghidra MCP capability routing", () => {it("routes composed and capability tools", async () => {@@ -41,44 +43,35 @@ describe("Ghidra MCP capability routing", () => {name: "binary_session",arguments: {},});- expect(status.structuredContent).toMatchObject({- result: {- open: true,- analysis_provider_binding: {- provider: { id: "ghidra", version: "12.1.4" },- },- tool_availability: expect.arrayContaining([- expect.objectContaining({- name: "binary_overview",- available: true,- }),- expect.objectContaining({- name: "get_objc_classes",- available: true,- }),- expect.objectContaining({- name: "batch_decompile",- available: true,- }),- expect.objectContaining({- name: "trace_feature",- available: true,- }),- expect.objectContaining({- name: "get_call_graph",- available: true,- }),- expect.objectContaining({- name: "find_xrefs_to_name",- available: true,- }),- expect.objectContaining({- name: "set_comment",- available: false,- }),- ]),+ const sessionStatus = toolContract("binary_session").outputSchema.parse(+ status.structuredContent,+ );+ expect(sessionStatus.result).toMatchObject({+ open: true,+ analysis_provider_binding: {+ provider: { id: "ghidra", version: "12.1.4" },},});+ const availability = expandToolAvailability(+ sessionStatus.result.tool_availability,+ );+ expect(availability).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ name: "binary_overview", available: true }),+ expect.objectContaining({+ name: "get_objc_classes",+ available: true,+ }),+ expect.objectContaining({ name: "batch_decompile", available: true }),+ expect.objectContaining({ name: "trace_feature", available: true }),+ expect.objectContaining({ name: "get_call_graph", available: true }),+ expect.objectContaining({+ name: "find_xrefs_to_name",+ available: true,+ }),+ expect.objectContaining({ name: "set_comment", available: false }),+ ]),+ );} finally {await harness.close();}diff --git a/tests/boundary/mcp/optionalProviderIsolation.test.ts b/tests/boundary/mcp/optionalProviderIsolation.test.tsindex eb8f64fd1..5986c7894 100644--- a/tests/boundary/mcp/optionalProviderIsolation.test.ts+++ b/tests/boundary/mcp/optionalProviderIsolation.test.ts@@ -14,6 +14,7 @@ import {TOOL_CONTRACTS,toolContract,} from "../../../src/contracts/toolContracts.js";+import { expandToolAvailability } from "../../../src/contracts/toolOutputSchemaPrimitives.js";import { run } from "../../../src/main.js";import { createServer } from "../../../src/server/createServer.js";import { optionalObservationFactories } from "../../fixtures/optionalObservationProviders.js";@@ -154,33 +155,37 @@ mcpTest.for(failedAdapters)(name: "binary_session",arguments: {},});- expect(status.structuredContent).toMatchObject({- result: {- tool_availability: expect.arrayContaining([- expect.objectContaining({- name: operation,- available: false,- reason: "provider_unavailable",- remediation: expect.stringContaining(failure),- }),- expect.objectContaining({- name: "analyze_javascript_application",- available: true,- }),- expect.objectContaining({- name: "reconcile_javascript_runtime",- available: true,- }),- expect.objectContaining({- name:- port === "electronActiveObservation"- ? "list_electron_targets"- : "capture_electron_scenario",- available: true,- }),- ]),- },- });+ const sessionStatus = toolContract("binary_session").outputSchema.parse(+ status.structuredContent,+ );+ const availability = expandToolAvailability(+ sessionStatus.result.tool_availability,+ );+ expect(availability).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ name: operation,+ available: false,+ reason: "provider_unavailable",+ remediation: expect.stringContaining(failure),+ }),+ expect.objectContaining({+ name: "analyze_javascript_application",+ available: true,+ }),+ expect.objectContaining({+ name: "reconcile_javascript_runtime",+ available: true,+ }),+ expect.objectContaining({+ name:+ port === "electronActiveObservation"+ ? "list_electron_targets"+ : "capture_electron_scenario",+ available: true,+ }),+ ]),+ );const healthy =port === "javascriptRuntimeObservation"? "list_browser_targets"diff --git a/tests/boundary/mcp/serverIdentity.test.ts b/tests/boundary/mcp/serverIdentity.test.tsindex 09ace062d..a570a5caf 100644--- a/tests/boundary/mcp/serverIdentity.test.ts+++ b/tests/boundary/mcp/serverIdentity.test.ts@@ -15,6 +15,10 @@ import { CLI_COMMAND_NAMES } from "../../../src/cliCommandNames.js";import { PACKAGE_METADATA } from "../../../src/generatedPackageMetadata.js";import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../../../src/identity.js";import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js";+import {+ expandToolAvailability,+ sessionProvider,+} from "../../../src/contracts/toolOutputSchemaPrimitives.js";import { PROMPT_CONTRACTS } from "../../../src/contracts/promptContracts.js";import { createServer } from "../../../src/server/createServer.js";import { createServerIdentity } from "../../../src/serverIdentity.js";@@ -70,20 +74,18 @@ const statusCapability = (readonly reason: string;} = { available: true },) => ({- operation,- effects: {- mutates_artifact: false,- launches_process: false,- may_show_ui: false,- may_access_network: false,- may_write_filesystem: false,- changes_permissions: false,- requires_root: false,- },- limitations: [],- ...(availability.available- ? { available: true as const, reason: null, availability_code: null }- : availability),+ provider: { id: "status-fixture", name: "Status fixture", version: null },+ shared_limitations: [],+ groups: [+ {+ operations: [operation],+ effects: [],+ limitations: [],+ ...(availability.available+ ? { available: true as const, reason: null, availability_code: null }+ : availability),+ },+ ],});describe("server and catalog identity", () => {@@ -326,15 +328,10 @@ const activeTargetReasons = async (name: "binary_session",arguments: {},});- const availability = z- .object({- result: z.object({- tool_availability: z.array(- z.object({ name: z.string(), reason: z.string() }).loose(),- ),- }),- })- .parse(status.structuredContent).result.tool_availability;+ const availability = expandToolAvailability(+ z.object({ result: sessionProvider }).parse(status.structuredContent).result+ .tool_availability,+ );return Object.fromEntries(["inspect_macho", "inspect_artifact", "inspect_managed_artifact"].map((name) => [name, availability.find((tool) => tool.name === name)?.reason],@@ -347,6 +344,32 @@ const assertLiveIdentity = async (client: Client): Promise<void> => {name: "binary_session",arguments: {},});+ const status = z+ .object({ result: sessionProvider })+ .parse(identity.structuredContent).result;+ expect(Object.keys(status.server_identity.catalog).sort()).toEqual([+ "counts",+ "digests",+ ]);+ const availability = expandToolAvailability(status.tool_availability);+ expect(availability.map(({ name }) => name).sort()).toEqual(+ TOOL_CONTRACTS.map(({ name }) => name).sort(),+ );+ for (const contract of TOOL_CONTRACTS) {+ expect(availability).toContainEqual(+ expect.objectContaining({+ name: contract.name,+ surface: contract.kind,+ effects: contract.effects,+ annotations: {+ read_only: contract.annotations.readOnlyHint ?? false,+ destructive: contract.annotations.destructiveHint ?? false,+ idempotent: contract.annotations.idempotentHint ?? false,+ open_world: contract.annotations.openWorldHint ?? true,+ },+ }),+ );+ }expect(identity.structuredContent).toMatchObject({result: {server_identity: {@@ -370,7 +393,17 @@ const assertSessionIdentity = async (client: Client): Promise<void> => {name: "binary_session",arguments: { expected_package_version: "1.2.0" },});- expect(status.structuredContent).toMatchObject({+ const parsed = z+ .object({ result: sessionProvider })+ .parse(status.structuredContent);+ expect({+ result: {+ ...parsed.result,+ tool_availability: expandToolAvailability(+ parsed.result.tool_availability,+ ),+ },+ }).toMatchObject({result: {server_identity: {catalog: {diff --git a/tests/boundary/mcp/serverWorkflowMcp.test.ts b/tests/boundary/mcp/serverWorkflowMcp.test.tsindex 4651de6e8..c72fca5cb 100644--- a/tests/boundary/mcp/serverWorkflowMcp.test.ts+++ b/tests/boundary/mcp/serverWorkflowMcp.test.ts@@ -3,7 +3,6 @@ import { ok as resultOk } from "../../../src/domain/result.js";import { Client, InMemoryTransport } from "@modelcontextprotocol/client";import type { CallToolResult } from "@modelcontextprotocol/server";import { afterEach, expect, it } from "vitest";-import { z } from "zod";import { createTestBinarySession } from "../../fixtures/binarySession.js";import type {@@ -12,8 +11,11 @@ import type {} from "../../../src/application/AnalysisProvider.js";import { observed as ok } from "../../fixtures/analysisExecution.js";import { createServer } from "../../../src/server/createServer.js";-import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js";-import { toolAvailability } from "../../../src/contracts/toolOutputSchemaPrimitives.js";+import {+ TOOL_CONTRACTS,+ toolContract,+} from "../../../src/contracts/toolContracts.js";+import { expandToolAvailability } from "../../../src/contracts/toolOutputSchemaPrimitives.js";const resources: Array<{ close(): Promise<void> }> = [];@@ -126,11 +128,10 @@ it("advertises the complete currently available inventory with a session", asyncarguments: {},}),);- const inventory = z- .object({- result: z.object({ tool_availability: z.array(toolAvailability) }),- })- .parse(status).result.tool_availability;+ const inventory = expandToolAvailability(+ toolContract("binary_session").outputSchema.parse(status).result+ .tool_availability,+ );for (const availability of inventory) {if (availability.available) continue;expect(availability.reason).not.toBe("available");diff --git a/tests/boundary/mcp/sessionMcp.test.ts b/tests/boundary/mcp/sessionMcp.test.tsindex 302f91ad7..42e92e501 100644--- a/tests/boundary/mcp/sessionMcp.test.ts+++ b/tests/boundary/mcp/sessionMcp.test.ts@@ -26,6 +26,8 @@ import { createAnalysisProfile } from "../../../src/domain/analysisProfile.js";import { MAX_JSON_DEPTH } from "../../../src/domain/jsonValue.js";import { parseAnalysisSnapshot } from "../../../src/domain/analysisSnapshot.js";import { INVESTIGATION_EXAMPLES } from "../../../src/contracts/investigationExamples.js";+import { expandProviderCapabilities } from "../../../src/contracts/toolOutputSchemaPrimitives.js";+import { toolContract } from "../../../src/contracts/toolContracts.js";import { ok as resultOk } from "../../../src/domain/result.js";import {createSessionMcpHarness,@@ -294,15 +296,12 @@ describe("target-free MCP workflow", () => {expect(openedStatus).toMatchObject({result: { path: await realpath(first) },});+ const sessionStatus =+ toolContract("binary_session").outputSchema.parse(openedStatus);expect(- z- .object({- result: z.object({- capabilities: z.array(z.object({ operation: z.string() })),- }),- })- .parse(openedStatus)- .result.capabilities.map(({ operation }) => operation),+ expandProviderCapabilities(sessionStatus.result.capabilities).map(+ ({ operation }) => operation,+ ),).not.toContain("inventory_artifact");expect(text(await mcp.callTool({ name: "current_document", arguments: {} })),diff --git a/tests/composition/analysis-sessions/binarySession.test.ts b/tests/composition/analysis-sessions/binarySession.test.tsindex aa809b6fb..302d51d50 100644--- a/tests/composition/analysis-sessions/binarySession.test.ts+++ b/tests/composition/analysis-sessions/binarySession.test.ts@@ -597,10 +597,19 @@ describe("provider health and availability", () => {expect(session.status()).toMatchObject({capabilities: expect.arrayContaining([expect.objectContaining({- operation: "address_name",- available: false,- reason:- "ProviderAdapterError: Provider fixture adapter failed during address_name",+ provider: {+ id: "fixture",+ name: "Fixture analysis provider",+ version: "1",+ },+ groups: expect.arrayContaining([+ expect.objectContaining({+ operations: expect.arrayContaining(["address_name"]),+ available: false,+ reason:+ "ProviderAdapterError: Provider fixture adapter failed during address_name",+ }),+ ]),}),]),});@@ -609,9 +618,18 @@ describe("provider health and availability", () => {expect(session.status()).toMatchObject({capabilities: expect.arrayContaining([expect.objectContaining({- operation: "address_name",- available: true,- reason: null,+ provider: {+ id: "fixture",+ name: "Fixture analysis provider",+ version: "1",+ },+ groups: expect.arrayContaining([+ expect.objectContaining({+ operations: expect.arrayContaining(["address_name"]),+ available: true,+ reason: null,+ }),+ ]),}),]),});@@ -657,9 +675,18 @@ describe("provider health and availability", () => {expect(session.status()).toMatchObject({capabilities: expect.arrayContaining([expect.objectContaining({- operation: "address_name",- available: true,- reason: null,+ provider: {+ id: "fixture",+ name: "Fixture analysis provider",+ version: "1",+ },+ groups: expect.arrayContaining([+ expect.objectContaining({+ operations: expect.arrayContaining(["address_name"]),+ available: true,+ reason: null,+ }),+ ]),}),]),});