diff --git a/package.json b/package.json index 755f2fcca..2dab8fe33 100644 --- a/package.json +++ b/package.json @@ -102,6 +102,7 @@ "verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs", "verify:ghidra:windows": "npm run build:cached && npm run build:ghidra-windows-fixture && node scripts/verify-real-ghidra-windows.mjs", "verify:browser": "npm run build:cached && node scripts/verify-real-browser.mjs", + "verify:inspector": "npm run build:cached && node scripts/verify-real-javascript-runtime-observation.mjs", "verify:javascript-runtime": "npm run build:cached && node scripts/verify-local-javascript-runtime.mjs", "verify:application-workflows": "npm run build:cached && node scripts/verify-local-application-workflows.mjs", "verify:managed": "npm run build:cached && node scripts/verify-managed-conformance.mjs", @@ -112,6 +113,7 @@ "build:fixtures": "node scripts/build-conformance-fixtures.mjs", "build:ghidra-windows-fixture": "node scripts/create-ghidra-windows-fixture.mjs", "verify:fixtures": "npm run build:fixtures && node scripts/verify-conformance-fixtures.mjs", + "verify:readiness": "npm run build:cached && npm run verify:fixtures && node scripts/verify-reconstruction-readiness.mjs", "verify:package": "npm run build:cached && node scripts/verify-package.mjs", "verify:package:windows": "npm run build:cached && node scripts/verify-windows-package.mjs", "probe:windows-capabilities": "npm run build:cached && node scripts/windows-capabilities.mjs", @@ -142,8 +144,8 @@ "@electron/asar": "4.2.0", "@jridgewell/trace-mapping": "0.3.31", "@lydell/node-pty": "1.1.0", - "@modelcontextprotocol/server": "2.0.0-beta.4", "@modelcontextprotocol/client": "2.0.0-beta.4", + "@modelcontextprotocol/server": "2.0.0-beta.4", "@xterm/addon-serialize": "0.14.0", "@xterm/headless": "6.0.0", "@zip.js/zip.js": "2.8.26", @@ -176,8 +178,8 @@ "lint-staged": "16.4.0", "oxlint": "1.73.0", "prettier": "3.6.2", - "typedoc": "0.28.20", "turbo": "2.10.5", + "typedoc": "0.28.20", "typescript": "5.9.3", "vitest": "4.1.10" } diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjs index 0abb315fc..9aa34df81 100644 --- a/scripts/lib/catalog-builders.mjs +++ b/scripts/lib/catalog-builders.mjs @@ -34,13 +34,23 @@ export const toolFamilyCatalog = (sources) => { { id: "browser", surface: "browser-provider", - contracts: sources.browserContracts.BROWSER_TOOL_CONTRACTS, + contracts: [ + ...sources.browserContracts.BROWSER_TOOL_CONTRACTS, + ...sources.browserScenarioContracts.BROWSER_SCENARIO_TOOL_CONTRACTS, + ], }, { id: "electron", surface: "electron-provider", contracts: sources.electronContracts.ELECTRON_TOOL_CONTRACTS, }, + { + id: "javascript-runtime", + surface: "runtime-provider", + contracts: + sources.javascriptRuntimeObservationContracts + .JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS, + }, { id: "application", surface: "application-workflow", @@ -121,10 +131,23 @@ export const providerCatalog = (sources) => { identity: sources.browserProvider.CDP_BROWSER_PROVIDER_IDENTITY, contracts: sources.browserContracts.BROWSER_TOOL_CONTRACTS, }, + { + identity: + sources.browserScenarioProvider + .PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY, + contracts: + sources.browserScenarioContracts.BROWSER_SCENARIO_TOOL_CONTRACTS, + }, { identity: sources.electronProvider.CDP_ELECTRON_PROVIDER_IDENTITY, contracts: observationContracts, }, + { + identity: sources.v8InspectorProvider.V8_INSPECTOR_PROVIDER_IDENTITY, + contracts: + sources.javascriptRuntimeObservationContracts + .JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS, + }, { identity: sources.artifactProviders.JAVASCRIPT_APPLICATION_PROVIDER, contracts: applicationContracts, diff --git a/scripts/lib/catalog-core.mjs b/scripts/lib/catalog-core.mjs index c55669e6a..25fd557e2 100644 --- a/scripts/lib/catalog-core.mjs +++ b/scripts/lib/catalog-core.mjs @@ -31,7 +31,10 @@ const SOURCE_PATHS = { managedContracts: "dist/contracts/managedToolContracts.js", managedWorkflowContracts: "dist/contracts/managedWorkflowToolContracts.js", browserContracts: "dist/contracts/browserToolContracts.js", + browserScenarioContracts: "dist/contracts/browserScenarioToolContracts.js", electronContracts: "dist/contracts/electronToolContracts.js", + javascriptRuntimeObservationContracts: + "dist/contracts/javascriptRuntimeObservationToolContracts.js", applicationContracts: "dist/contracts/applicationToolContracts.js", supportedClients: "dist/application/SupportedClients.js", hopperProvider: "dist/hopper/HopperProvider.js", @@ -39,7 +42,9 @@ const SOURCE_PATHS = { nativeProvider: "dist/native/NativeMacOSProvider.js", artifactProviders: "dist/application/InvestigationProviders.js", browserProvider: "dist/browser/CdpBrowserProvider.js", + browserScenarioProvider: "dist/browser/PlaywrightBrowserScenarioProvider.js", electronProvider: "dist/browser/CdpElectronProvider.js", + v8InspectorProvider: "dist/browser/V8InspectorProvider.js", evidence: "dist/domain/evidence.js", evidenceBundle: "dist/domain/evidenceBundle.js", evidenceCompletion: "dist/domain/evidenceCompletionLedger.js", @@ -49,8 +54,12 @@ const SOURCE_PATHS = { artifactGraph: "dist/domain/artifactGraph.js", investigationWorkspace: "dist/domain/investigationWorkspace.js", browserObservation: "dist/domain/browserObservation.js", + browserScenario: "dist/domain/browserScenario.js", + browserScenarioCapture: "dist/domain/browserScenarioCapture.js", + browserScenarioDiff: "dist/domain/browserScenarioDiff.js", browserSession: "dist/domain/browserSession.js", electronObservation: "dist/domain/electronObservation.js", + javascriptRuntimeObservation: "dist/domain/javascriptRuntimeObservation.js", webBundleAnalysis: "dist/domain/webBundleAnalysis.js", webCaptureDiff: "dist/domain/webCaptureDiff.js", managedArtifact: "dist/domain/managedArtifact.js", diff --git a/scripts/lib/catalog-schemas.mjs b/scripts/lib/catalog-schemas.mjs index 6535fb934..0acf24a3e 100644 --- a/scripts/lib/catalog-schemas.mjs +++ b/scripts/lib/catalog-schemas.mjs @@ -23,7 +23,11 @@ const valuesAt = (node, path) => { const versionAt = (schema, path) => { const versions = [ - ...new Set(valuesAt(z.toJSONSchema(schema), path).map(String)), + ...new Set( + valuesAt(z.toJSONSchema(schema, { unrepresentable: "any" }), path).map( + String, + ), + ), ]; if (versions.length !== 1) throw new Error( @@ -50,6 +54,11 @@ const durableSchemaDefinitions = (sources) => [ sources.artifactGraph.artifactExtractionResultSchema, ["extraction_manifest", "schema_version"], ], + [ + "browser_scenario", + sources.browserScenario.browserScenarioSchema, + ["schema_version"], + ], ["evidence", sources.evidence.evidenceSchema, ["schema_version"]], [ "evidence_bundle", @@ -129,6 +138,19 @@ const durableSchemaDefinitions = (sources) => [ ], ]; +const browserScenarioObservationSchemaDefinitions = (sources) => [ + [ + "browser_scenario_capture", + sources.browserScenarioCapture.browserScenarioCaptureSchema, + ["schema_version"], + ], + [ + "browser_scenario_diff", + sources.browserScenarioDiff.browserScenarioDiffSchema, + ["schema_version"], + ], +]; + const observationSchemaDefinitions = (sources) => [ [ "managed_artifact_inspection", @@ -160,6 +182,7 @@ const observationSchemaDefinitions = (sources) => [ sources.browserObservation.browserTargetListSchema, ["schema_version"], ], + ...browserScenarioObservationSchemaDefinitions(sources), [ "electron_page_inspection", sources.electronObservation.electronPageInspectionSchema, @@ -176,6 +199,16 @@ const observationSchemaDefinitions = (sources) => [ .javaScriptApplicationAnalysisResultV2Schema, ["schema_version"], ], + [ + "javascript_runtime_observation", + sources.javascriptRuntimeObservation.javascriptRuntimeObservationSchema, + ["schema_version"], + ], + [ + "javascript_runtime_target_list", + sources.javascriptRuntimeObservation.javascriptRuntimeTargetListSchema, + ["schema_version"], + ], [ "web_bundle_analysis", sources.webBundleAnalysis.webBundleAnalysisSchema, diff --git a/scripts/verify-package-mcp.mjs b/scripts/verify-package-mcp.mjs index d403e7d87..2a1336f92 100644 --- a/scripts/verify-package-mcp.mjs +++ b/scripts/verify-package-mcp.mjs @@ -5,17 +5,26 @@ import { promisify } from "node:util"; import { Client } from "@modelcontextprotocol/client"; import { StdioClientTransport } from "@modelcontextprotocol/client/stdio"; -import { TOOL_CONTRACTS } from "../dist/contracts/toolContracts.js"; import * as prompts from "./verify-package-prompts.mjs"; import { json } from "./lib/verify-package-core.mjs"; const execute = promisify(execFile); const verifyMcpToolsAndPrompts = async (client, mcpOptions) => { - if ( - (await client.listTools(undefined, mcpOptions)).tools.length !== - TOOL_CONTRACTS.length - ) + const listed = await client.listTools(undefined, mcpOptions); + const status = await client.callTool( + { name: "binary_session", arguments: { detail: "full" } }, + mcpOptions, + ); + const availability = status.structuredContent?.result?.tool_availability; + if (!Array.isArray(availability)) + throw new Error("packaged MCP omitted tool availability"); + const expected = availability + .filter(({ available }) => available === true) + .map(({ name }) => name) + .sort(); + const observed = listed.tools.map(({ name }) => name).sort(); + if (JSON.stringify(observed) !== JSON.stringify(expected)) throw new Error("packaged MCP tool inventory diverged from contracts"); await prompts.verifyPromptCatalog(client, mcpOptions, prompts.names); await prompts.verifyPromptCompletion(client, mcpOptions, false); @@ -44,12 +53,11 @@ const verifyMcpReplay = async (client, mcpOptions, investigationReplay) => { }; const verifyMcpTargetFree = async (client, mcpOptions) => { - const result = await client.callTool( - { name: "current_document", arguments: {} }, - mcpOptions, + const names = (await client.listTools(undefined, mcpOptions)).tools.map( + ({ name }) => name, ); - if (result.isError !== true) - throw new Error("packaged target-free MCP omitted no-target error"); + if (names.includes("current_document")) + throw new Error("packaged target-free MCP advertised a target-bound tool"); }; const verifyMcpUnknownProvider = async (client, mcpOptions) => { @@ -97,14 +105,12 @@ const verifyMcpOpenAndBind = async (client, mcpOptions) => { throw new Error("packaged MCP omitted its explicit Hopper binding"); }; -const verifyMcpLinuxCurrentDocument = async (client, mcpOptions, current) => { - if ( - current.isError !== true || - !prompts - .mcpText(current) - .includes("not supported for unattended Linux analysis") - ) - throw new Error("packaged Linux MCP did not reject an unpinned Hopper"); +const verifyMcpLinuxToolAvailability = async (client, mcpOptions) => { + const names = (await client.listTools(undefined, mcpOptions)).tools.map( + ({ name }) => name, + ); + if (names.includes("current_document")) + throw new Error("packaged Linux MCP advertised unavailable Hopper tools"); }; const verifyMcpNonLinuxCurrentDocument = async ( @@ -140,13 +146,13 @@ const verifyMcpBinaryLifecycle = async (client, mcpOptions) => { mcpOptions, process.platform !== "linux", ); - const current = await client.callTool( - { name: "current_document", arguments: {} }, - mcpOptions, - ); if (process.platform === "linux") { - await verifyMcpLinuxCurrentDocument(client, mcpOptions, current); + await verifyMcpLinuxToolAvailability(client, mcpOptions); } else { + const current = await client.callTool( + { name: "current_document", arguments: {} }, + mcpOptions, + ); await verifyMcpNonLinuxCurrentDocument(client, mcpOptions, current); } const closed = await client.callTool( @@ -191,7 +197,8 @@ export async function verifyPackageMcp({ ); if ( diagnosed.healthy !== true || - diagnosed.inventory?.tools?.observed !== TOOL_CONTRACTS.length + diagnosed.inventory?.tools?.observed !== + diagnosed.inventory?.tools?.expected ) throw new Error("packaged production MCP doctor failed"); const transport = new StdioClientTransport({ diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts index c1f273216..467b6751c 100644 --- a/src/application/CapabilityInventory.ts +++ b/src/application/CapabilityInventory.ts @@ -1,6 +1,7 @@ import { z } from "zod"; import { TOOL_CONTRACTS } from "../contracts/toolContracts.js"; +import type { ClientFeatureAvailability } from "../contracts/toolOutputSchemaPrimitives.js"; import type { JsonValue } from "../domain/jsonValue.js"; const statusSchema = z.object({ @@ -19,6 +20,7 @@ const statusSchema = z.object({ type ToolAvailabilityReason = | "available" + | "client_capability_missing" | "target_required" | "provider_missing" | "provider_unavailable" @@ -32,15 +34,41 @@ type ProviderDescriptor = { readonly reason: string | null; readonly availability_code?: string | null; }; -type AvailabilityPolicy = { +export type AvailabilityPolicy = { readonly processCaptureEnabled: boolean; readonly evidenceFileRoots: number; readonly investigationInputRoots: number; readonly browserObservationEnabled?: boolean; + readonly browserScenarioEnabled?: boolean; readonly electronObservationEnabled?: boolean; + readonly v8InspectorObservationEnabled?: boolean; readonly javascriptReplayEnabled?: boolean; readonly managedRuntimeEnabled?: boolean; }; + +type ClientFeatureName = keyof ClientFeatureAvailability; + +const NO_CLIENT_FEATURES: ClientFeatureAvailability = { + elicitation_form: false, + elicitation_url: false, + roots: false, + sampling: false, +}; + +const CLIENT_FEATURE_REQUIREMENTS: Readonly< + Record< + string, + { + readonly required: readonly ClientFeatureName[]; + readonly optional: readonly ClientFeatureName[]; + } + > +> = { + capture_process_scenario: { + required: [], + optional: ["elicitation_form"], + }, +}; type Availability = { readonly reason: ToolAvailabilityReason; readonly remediation: string | null; @@ -82,10 +110,11 @@ const ENHANCED_REQUIREMENTS: Readonly> = { ], }; -/** Build stable per-operation availability without hiding familiar tools. */ +/** Build stable per-operation availability for discovery and tool visibility. */ export const buildCapabilityInventory = ( sessionStatus: JsonValue, policy: AvailabilityPolicy, + clientFeatures: ClientFeatureAvailability = NO_CLIENT_FEATURES, ) => { const status = statusSchema.parse(sessionStatus); const descriptors = new Map( @@ -107,12 +136,22 @@ export const buildCapabilityInventory = ( descriptors, policy, }); + const clientRequirements = clientRequirementsFor( + contract.name, + clientFeatures, + ); + const clientBlocked = clientRequirements.missing_required.length > 0; return { name: contract.name, surface: contract.kind, - available: availability.reason === "available", - reason: availability.reason, - remediation: availability.remediation, + available: availability.reason === "available" && !clientBlocked, + reason: clientBlocked + ? ("client_capability_missing" as const) + : availability.reason, + remediation: clientBlocked + ? `Use an MCP client that supports: ${clientRequirements.missing_required.join(", ")}.` + : availability.remediation, + client_requirements: clientRequirements, effects: { ...contract.effects }, annotations: { read_only: contract.annotations.readOnlyHint ?? false, @@ -124,6 +163,26 @@ export const buildCapabilityInventory = ( }).sort((left, right) => left.name.localeCompare(right.name)); }; +const clientRequirementsFor = ( + name: string, + clientFeatures: ClientFeatureAvailability, +) => { + const requirements = CLIENT_FEATURE_REQUIREMENTS[name] ?? { + required: [], + optional: [], + }; + return { + required: [...requirements.required], + optional: [...requirements.optional], + missing_required: requirements.required.filter( + (feature) => !clientFeatures[feature], + ), + missing_optional: requirements.optional.filter( + (feature) => !clientFeatures[feature], + ), + }; +}; + const availabilityFor = (context: AvailabilityContext): Availability => { const javascriptApplication = javascriptApplicationAvailability(context); if (javascriptApplication !== null) return javascriptApplication; @@ -156,6 +215,8 @@ const policyAvailability = ({ kind, policy, }: AvailabilityContext): Availability | null => { + const browser = browserPolicyAvailability(name, kind, policy); + if (browser !== null) return browser; if (name === "capture_process_scenario" && !policy.processCaptureEnabled) return { reason: "policy_disabled", @@ -187,14 +248,6 @@ const policyAvailability = ({ reason: "policy_disabled", remediation: "Configure or grant an evidence_read root.", }; - if (kind === "browser-provider") - return policy.browserObservationEnabled === true - ? { reason: "available", remediation: null } - : { - reason: "policy_disabled", - remediation: - "Enable browser observation and configure exact CDP endpoint and page origins.", - }; if (kind === "electron-provider") return policy.electronObservationEnabled === true ? { reason: "available", remediation: null } @@ -203,16 +256,47 @@ const policyAvailability = ({ remediation: "Enable Electron observation and configure a loopback CDP endpoint and canonical file roots.", }; + if (kind === "runtime-provider") + return policy.v8InspectorObservationEnabled === true + ? { reason: "available", remediation: null } + : { + reason: "policy_disabled", + remediation: + "Enable V8 Inspector observation and configure exact loopback endpoints plus canonical file roots or exact origins.", + }; if (kind === "session") return { reason: "available", remediation: null }; return null; }; +const browserPolicyAvailability = ( + name: string, + kind: ToolKind, + policy: AvailabilityPolicy, +): Availability | null => { + if (name === "capture_browser_scenario") + return policy.browserScenarioEnabled === true + ? { reason: "available", remediation: null } + : { + reason: "policy_disabled", + remediation: + "Enable browser scenarios and configure exact executable roots or loopback CDP endpoints, page origins, and environment secret names.", + }; + if (kind !== "browser-provider") return null; + return policy.browserObservationEnabled === true + ? { reason: "available", remediation: null } + : { + reason: "policy_disabled", + remediation: + "Enable browser observation and configure exact CDP endpoint and page origins.", + }; +}; + const targetAvailability = ({ kind, targetKind, targetOpen, }: AvailabilityContext): Availability | null => { - if (!targetOpen) + if (!targetOpen && (kind === "official-proxy" || kind === "enhanced")) return { reason: "target_required", remediation: "Call open_binary with a supported local target.", @@ -238,6 +322,13 @@ const providerAvailability = ({ }: AvailabilityContext): Availability => { if (kind === "enhanced") return composedAvailability(name, descriptors); const descriptor = descriptors.get(name); + if ( + descriptor === undefined && + (kind === "artifact-provider" || + kind === "managed-provider" || + kind === "native-provider") + ) + return { reason: "available", remediation: null }; if (descriptor === undefined) return { reason: "provider_missing", diff --git a/src/application/ProjectPermissionStore.ts b/src/application/ProjectPermissionStore.ts index 55d1c10a9..0c95d1796 100644 --- a/src/application/ProjectPermissionStore.ts +++ b/src/application/ProjectPermissionStore.ts @@ -23,6 +23,7 @@ const grantSchema = z.object({ capability: z.enum([ "process_capture", "browser_observe", + "browser_automate", "electron_observe", "evidence_read", "evidence_write", diff --git a/src/catalogIdentity.ts b/src/catalogIdentity.ts index 2b45af05f..289cb5fda 100644 --- a/src/catalogIdentity.ts +++ b/src/catalogIdentity.ts @@ -66,6 +66,15 @@ export const MCP_RESOURCE_TEMPLATE_CATALOG = [ uri_template: "rea://reconstruction-coverage/{workspaceId}/revision/{revision}", }, + { + name: "reconstruction-obligation-ledger-page", + uri_template: + "rea://evidence/{evidenceId}/reconstruction-obligation-ledger", + }, + { + name: "reconstruction-readiness-report", + uri_template: "rea://evidence/{evidenceId}/reconstruction-readiness-report", + }, { name: "javascript-application-graph-page", uri_template: diff --git a/src/cli.ts b/src/cli.ts index d75d404a8..68ea8c3f1 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -14,7 +14,9 @@ import { registerProcessCommands } from "./cliProcessCommands.js"; import { registerPolicyCommands } from "./cliPolicyCommands.js"; import { registerBrowserCommands } from "./cliBrowserCommands.js"; import { registerAdvancedBrowserCommands } from "./cliBrowserAdvancedCommands.js"; +import { registerBrowserScenarioCommands } from "./cliBrowserScenarioCommands.js"; import { registerElectronCommands } from "./cliElectronCommands.js"; +import { registerJavaScriptRuntimeObservationCommands } from "./cliJavaScriptRuntimeCommands.js"; import { registerApplicationCommands } from "./cliApplicationCommands.js"; import type { CliInstance } from "./cli/types.js"; @@ -60,7 +62,9 @@ export const createCli = (): CliInstance => { registerPolicyCommands(cli, logger); registerBrowserCommands(cli, logger); registerAdvancedBrowserCommands(cli, logger); + registerBrowserScenarioCommands(cli, logger); registerElectronCommands(cli, logger); + registerJavaScriptRuntimeObservationCommands(cli, logger); registerApplicationCommands(cli, logger); return cli; }; diff --git a/src/cliApplicationCommands.ts b/src/cliApplicationCommands.ts index e94e1d3ed..a6e9aae22 100644 --- a/src/cliApplicationCommands.ts +++ b/src/cliApplicationCommands.ts @@ -3,12 +3,14 @@ import { Cli, z } from "incur"; import { compareApplicationVersionsEvidenceValidated, compareJavaScriptExportShapesEvidenceValidated, + compareSourceToBundleEvidenceValidated, traceApplicationFeatureEvidenceValidated, } from "./application/JavaScriptApplicationWorkflowService.js"; import { traceJavaScriptSemanticsEvidenceValidated } from "./application/JavaScriptSemanticTraceService.js"; import { resolveCompareApplicationVersionsRequest, resolveCompareJavaScriptExportShapesRequest, + resolveCompareSourceToBundleRequest, resolveTraceApplicationFeatureRequest, resolveTraceJavaScriptSemanticsRequest, } from "./application/ApplicationWorkflowEvidenceResolver.js"; @@ -25,6 +27,14 @@ import { reconstructionCoverageCommitInputSchema, reconstructionCoverageQueryInputSchema, } from "./application/ReconstructionCoverageService.js"; +import { + buildReconstructionObligationLedgerEvidenceValidated, + resolveReconstructionObligationLedgerRequest, +} from "./application/ReconstructionObligationLedgerService.js"; +import { + evaluateReconstructionReadinessValidated, + resolveReconstructionReadinessRequest, +} from "./application/ReconstructionReadinessService.js"; import { authorizeFileReadWithDeferredWrite, authorizeRootPermission, @@ -80,6 +90,15 @@ export const registerApplicationCommands = ( resolveInput: resolveCompareApplicationVersionsRequest, workflow: compareApplicationVersionsEvidenceValidated, }); + registerJsonCommand({ + cli, + logger, + name: CLI_COMMANDS.compareSourceToBundle, + description: + "Compare committed historical source with authenticated application Evidence", + resolveInput: resolveCompareSourceToBundleRequest, + workflow: compareSourceToBundleEvidenceValidated, + }); registerJsonCommand({ cli, logger, @@ -136,9 +155,36 @@ export const registerApplicationCommands = ( workflow: (config, authority, input) => executeNodeCharacterization(replayDependencies(config, authority), input), }); + registerObligationLedgerCommand(cli, logger); + registerReadinessCommand(cli, logger); registerCoverageCommands(cli, logger); }; +const registerObligationLedgerCommand = ( + cli: CliInstance, + logger: Logger, +): void => + registerJsonCommand({ + cli, + logger, + name: CLI_COMMANDS.buildReconstructionObligationLedger, + description: + "Generate a deterministic Evidence-backed reconstruction obligation ledger page", + resolveInput: resolveReconstructionObligationLedgerRequest, + workflow: buildReconstructionObligationLedgerEvidenceValidated, + }); + +const registerReadinessCommand = (cli: CliInstance, logger: Logger): void => + registerJsonCommand({ + cli, + logger, + name: CLI_COMMANDS.evaluateReconstructionReadiness, + description: + "Evaluate a complete Evidence-backed reconstruction readiness journey", + resolveInput: resolveReconstructionReadinessRequest, + workflow: evaluateReconstructionReadinessValidated, + }); + interface AuthorizedJsonCommandOptions { readonly cli: CliInstance; readonly logger: Logger; diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.ts index 1f776ab79..06a069390 100644 --- a/src/cliCommandNames.ts +++ b/src/cliCommandNames.ts @@ -16,6 +16,7 @@ export const CLI_COMMANDS = Object.freeze({ search: "search", importReferenceSource: "import-reference-source", inventoryArtifact: "inventory-artifact", + inspectArtifact: "inspect-artifact", extractArtifact: "extract-artifact", inspectManagedArtifact: "inspect-managed-artifact", inspectManagedMembers: "inspect-managed-members", @@ -45,18 +46,24 @@ export const CLI_COMMANDS = Object.freeze({ compareWebCaptures: "compare-web-captures", captureWebScreenshot: "capture-web-screenshot", compareWebScreenshots: "compare-web-screenshots", + captureBrowserScenario: "capture-browser-scenario", listElectronTargets: "list-electron-targets", inspectElectronPage: "inspect-electron-page", + listJavaScriptRuntimeTargets: "list-javascript-runtime-targets", + observeJavaScriptRuntime: "observe-javascript-runtime", analyzeJavaScriptApplication: "analyze-javascript-application", reconcileJavaScriptRuntime: "reconcile-javascript-runtime", traceApplicationFeature: "trace-application-feature", traceJavaScriptSemantics: "trace-javascript-semantics", compareApplicationVersions: "compare-application-versions", + compareSourceToBundle: "compare-source-to-bundle", compareJavaScriptExportShapes: "compare-javascript-export-shapes", runReplayMachine: "run-replay-machine", runControlledReplay: "run-controlled-replay", prepareNodeCharacterization: "prepare-node-characterization", executeNodeCharacterization: "execute-node-characterization", + buildReconstructionObligationLedger: "build-reconstruction-obligation-ledger", + evaluateReconstructionReadiness: "evaluate-reconstruction-readiness", commitReconstructionCoverage: "commit-reconstruction-coverage", queryReconstructionCoverage: "query-reconstruction-coverage", }); diff --git a/src/cliPolicyCommands.ts b/src/cliPolicyCommands.ts index 2a279d3a4..b402ebc72 100644 --- a/src/cliPolicyCommands.ts +++ b/src/cliPolicyCommands.ts @@ -19,6 +19,7 @@ import { CLI_COMMANDS } from "./cliCommandNames.js"; const capabilitySchema = z.enum([ "process_capture", "browser_observe", + "browser_automate", "electron_observe", "evidence_read", "evidence_write", diff --git a/src/config/environment.ts b/src/config/environment.ts index 6a55ad069..bac4d11a9 100644 --- a/src/config/environment.ts +++ b/src/config/environment.ts @@ -54,9 +54,21 @@ const environmentSchema = z REA_BROWSER_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"), REA_BROWSER_CDP_ENDPOINTS_JSON: z.string().default("[]"), REA_BROWSER_ALLOWED_ORIGINS_JSON: z.string().default("[]"), + REA_BROWSER_SCENARIO_ENABLED: z.enum(["true", "false"]).default("false"), + REA_BROWSER_SCENARIO_AUTO_GRANT: z.enum(["true", "false"]).default("false"), + REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON: z.string().default("[]"), + REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON: z.string().default("[]"), + REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON: z.string().default("[]"), + REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON: z.string().default("[]"), REA_ELECTRON_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"), REA_ELECTRON_CDP_ENDPOINTS_JSON: z.string().default("[]"), REA_ELECTRON_FILE_ROOTS_JSON: z.string().default("[]"), + REA_V8_INSPECTOR_OBSERVE_ENABLED: z + .enum(["true", "false"]) + .default("false"), + REA_V8_INSPECTOR_ENDPOINTS_JSON: z.string().default("[]"), + REA_V8_INSPECTOR_FILE_ROOTS_JSON: z.string().default("[]"), + REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON: z.string().default("[]"), REA_JAVASCRIPT_REPLAY_ENABLED: z.enum(["true", "false"]).default("false"), REA_JAVASCRIPT_REPLAY_ROOTS_JSON: z.string().default("[]"), REA_JAVASCRIPT_REPLAY_NODE_PATH: z diff --git a/src/config/parseConfig.ts b/src/config/parseConfig.ts index b4375ffe3..f88f19904 100644 --- a/src/config/parseConfig.ts +++ b/src/config/parseConfig.ts @@ -41,12 +41,34 @@ interface ParsedArrays { readonly secretPatterns: readonly string[]; readonly browserEndpoints: readonly string[]; readonly browserOrigins: readonly string[]; + readonly browserScenarioExecutableRoots: readonly string[]; + readonly browserScenarioEndpoints: readonly string[]; + readonly browserScenarioOrigins: readonly string[]; + readonly browserScenarioEnvironment: readonly string[]; readonly electronEndpoints: readonly string[]; readonly electronFileRoots: readonly string[]; + readonly v8InspectorEndpoints: readonly string[]; + readonly v8InspectorFileRoots: readonly string[]; + readonly v8InspectorOrigins: readonly string[]; readonly javascriptReplayRoots: readonly string[]; readonly managedRuntimeRoots: readonly string[]; } +type ParsedObservationArrays = Pick< + ParsedArrays, + | "browserEndpoints" + | "browserOrigins" + | "browserScenarioExecutableRoots" + | "browserScenarioEndpoints" + | "browserScenarioOrigins" + | "browserScenarioEnvironment" + | "electronEndpoints" + | "electronFileRoots" + | "v8InspectorEndpoints" + | "v8InspectorFileRoots" + | "v8InspectorOrigins" +>; + const parseAllArrays = ( env: Environment, ): Result => { @@ -92,31 +114,8 @@ const parseAllArrays = ( "REA_REFERENCE_SECRET_PATTERNS_JSON", ); if (!secretPatterns.ok) return secretPatterns; - const browserEndpoints = parseBrowserArray( - env.REA_BROWSER_CDP_ENDPOINTS_JSON, - "REA_BROWSER_CDP_ENDPOINTS_JSON", - browserEndpointSchema, - 16, - ); - if (!browserEndpoints.ok) return browserEndpoints; - const browserOrigins = parseBrowserArray( - env.REA_BROWSER_ALLOWED_ORIGINS_JSON, - "REA_BROWSER_ALLOWED_ORIGINS_JSON", - browserOriginSchema, - 32, - ); - if (!browserOrigins.ok) return browserOrigins; - const electronEndpoints = parseBrowserArray( - env.REA_ELECTRON_CDP_ENDPOINTS_JSON, - "REA_ELECTRON_CDP_ENDPOINTS_JSON", - browserEndpointSchema, - 16, - ); - if (!electronEndpoints.ok) return electronEndpoints; - const electronFileRoots = parseElectronFileRoots( - env.REA_ELECTRON_FILE_ROOTS_JSON, - ); - if (!electronFileRoots.ok) return electronFileRoots; + const observations = parseObservationArrays(env); + if (!observations.ok) return observations; const javascriptReplayRoots = parseAbsoluteRoots( env.REA_JAVASCRIPT_REPLAY_ROOTS_JSON, "REA_JAVASCRIPT_REPLAY_ROOTS_JSON", @@ -137,15 +136,98 @@ const parseAllArrays = ( analysisSnapshotRoots: analysisSnapshotRoots.value, referenceRoots: referenceRoots.value, secretPatterns: secretPatterns.value, - browserEndpoints: browserEndpoints.value, - browserOrigins: browserOrigins.value, - electronEndpoints: electronEndpoints.value, - electronFileRoots: electronFileRoots.value, + ...observations.value, javascriptReplayRoots: javascriptReplayRoots.value, managedRuntimeRoots: managedRuntimeRoots.value, }); }; +const parseObservationArrays = ( + env: Environment, +): Result => { + const browserEndpoints = parseBrowserArray( + env.REA_BROWSER_CDP_ENDPOINTS_JSON, + "REA_BROWSER_CDP_ENDPOINTS_JSON", + browserEndpointSchema, + 16, + ); + if (!browserEndpoints.ok) return browserEndpoints; + const browserOrigins = parseBrowserArray( + env.REA_BROWSER_ALLOWED_ORIGINS_JSON, + "REA_BROWSER_ALLOWED_ORIGINS_JSON", + browserOriginSchema, + 32, + ); + if (!browserOrigins.ok) return browserOrigins; + const browserScenarioExecutableRoots = parseAbsoluteRoots( + env.REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON, + "REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON", + ); + if (!browserScenarioExecutableRoots.ok) return browserScenarioExecutableRoots; + const browserScenarioEndpoints = parseBrowserArray( + env.REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON, + "REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON", + browserEndpointSchema, + 16, + ); + if (!browserScenarioEndpoints.ok) return browserScenarioEndpoints; + const browserScenarioOrigins = parseBrowserArray( + env.REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON, + "REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON", + browserOriginSchema, + 32, + ); + if (!browserScenarioOrigins.ok) return browserScenarioOrigins; + const browserScenarioEnvironment = parseStringArray( + env.REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON, + "REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON", + ); + if (!browserScenarioEnvironment.ok) return browserScenarioEnvironment; + const electronEndpoints = parseBrowserArray( + env.REA_ELECTRON_CDP_ENDPOINTS_JSON, + "REA_ELECTRON_CDP_ENDPOINTS_JSON", + browserEndpointSchema, + 16, + ); + if (!electronEndpoints.ok) return electronEndpoints; + const electronFileRoots = parseElectronFileRoots( + env.REA_ELECTRON_FILE_ROOTS_JSON, + ); + if (!electronFileRoots.ok) return electronFileRoots; + const v8InspectorEndpoints = parseBrowserArray( + env.REA_V8_INSPECTOR_ENDPOINTS_JSON, + "REA_V8_INSPECTOR_ENDPOINTS_JSON", + browserEndpointSchema, + 16, + ); + if (!v8InspectorEndpoints.ok) return v8InspectorEndpoints; + const v8InspectorFileRoots = parseAbsoluteRoots( + env.REA_V8_INSPECTOR_FILE_ROOTS_JSON, + "REA_V8_INSPECTOR_FILE_ROOTS_JSON", + ); + if (!v8InspectorFileRoots.ok) return v8InspectorFileRoots; + const v8InspectorOrigins = parseBrowserArray( + env.REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON, + "REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON", + browserOriginSchema, + 32, + ); + if (!v8InspectorOrigins.ok) return v8InspectorOrigins; + return ok({ + browserEndpoints: browserEndpoints.value, + browserOrigins: browserOrigins.value, + browserScenarioExecutableRoots: browserScenarioExecutableRoots.value, + browserScenarioEndpoints: browserScenarioEndpoints.value, + browserScenarioOrigins: browserScenarioOrigins.value, + browserScenarioEnvironment: browserScenarioEnvironment.value, + electronEndpoints: electronEndpoints.value, + electronFileRoots: electronFileRoots.value, + v8InspectorEndpoints: v8InspectorEndpoints.value, + v8InspectorFileRoots: v8InspectorFileRoots.value, + v8InspectorOrigins: v8InspectorOrigins.value, + }); +}; + const parseAbsoluteRoots = ( value: string, name: string, @@ -187,6 +269,25 @@ const appendBrowserObservationCeiling = ( ); }; +const appendBrowserScenarioCeiling = ( + ceilings: PermissionCeiling[], + env: Environment, + arrays: ParsedArrays, +): void => { + if (env.REA_BROWSER_SCENARIO_ENABLED !== "true") return; + ceilings.push( + permissionScope("browser_automate", [], { + executables: arrays.browserScenarioExecutableRoots, + environment_names: arrays.browserScenarioEnvironment, + origins: [ + ...arrays.browserScenarioEndpoints, + ...arrays.browserScenarioOrigins, + ], + network: browserNetworkScope(arrays.browserScenarioOrigins), + }), + ); +}; + const appendElectronObservationCeiling = ( ceilings: PermissionCeiling[], env: Environment, @@ -201,6 +302,20 @@ const appendElectronObservationCeiling = ( ); }; +const appendV8InspectorObservationCeiling = ( + ceilings: PermissionCeiling[], + env: Environment, + arrays: ParsedArrays, +): void => { + if (env.REA_V8_INSPECTOR_OBSERVE_ENABLED !== "true") return; + ceilings.push( + permissionScope("v8_inspector_observe", arrays.v8InspectorFileRoots, { + origins: [...arrays.v8InspectorEndpoints, ...arrays.v8InspectorOrigins], + network: "loopback", + }), + ); +}; + const appendNativeMountCeiling = ( ceilings: PermissionCeiling[], env: Environment, @@ -261,7 +376,9 @@ const buildPermissionCeilings = ( ]; appendProcessCaptureCeiling(ceilings, env, arrays); appendBrowserObservationCeiling(ceilings, env, arrays); + appendBrowserScenarioCeiling(ceilings, env, arrays); appendElectronObservationCeiling(ceilings, env, arrays); + appendV8InspectorObservationCeiling(ceilings, env, arrays); appendNativeMountCeiling(ceilings, env); appendJavaScriptReplayCeiling(ceilings, env, arrays); appendManagedRuntimeCeiling(ceilings, env, arrays); @@ -306,9 +423,21 @@ const buildAppConfig = ( browserObservationEnabled: env.REA_BROWSER_OBSERVE_ENABLED === "true", browserCdpEndpoints: arrays.browserEndpoints, browserAllowedOrigins: arrays.browserOrigins, + browserScenarioPolicy: { + enabled: env.REA_BROWSER_SCENARIO_ENABLED === "true", + executableRoots: arrays.browserScenarioExecutableRoots, + cdpEndpoints: arrays.browserScenarioEndpoints, + allowedOrigins: arrays.browserScenarioOrigins, + allowedEnvironment: arrays.browserScenarioEnvironment, + }, electronObservationEnabled: env.REA_ELECTRON_OBSERVE_ENABLED === "true", electronCdpEndpoints: arrays.electronEndpoints, electronFileRoots: arrays.electronFileRoots, + v8InspectorObservationEnabled: + env.REA_V8_INSPECTOR_OBSERVE_ENABLED === "true", + v8InspectorEndpoints: arrays.v8InspectorEndpoints, + v8InspectorFileRoots: arrays.v8InspectorFileRoots, + v8InspectorAllowedOrigins: arrays.v8InspectorOrigins, javascriptReplayPolicy: { enabled: env.REA_JAVASCRIPT_REPLAY_ENABLED === "true", roots: arrays.javascriptReplayRoots, @@ -325,11 +454,13 @@ const buildAppConfig = ( }, permissionCeilings, administratorPermissionGrants: administratorGrants( - env.REA_PROCESS_CAPTURE_AUTO_GRANT === "true" - ? permissionCeilings - : permissionCeilings.filter( - ({ capability }) => capability !== "process_capture", - ), + permissionCeilings.filter( + ({ capability }) => + (capability !== "process_capture" || + env.REA_PROCESS_CAPTURE_AUTO_GRANT === "true") && + (capability !== "browser_automate" || + env.REA_BROWSER_SCENARIO_AUTO_GRANT === "true"), + ), ), permissionProjectRoot: env.REA_PERMISSION_PROJECT_ROOT, permissionProjectStore: env.REA_PERMISSION_PROJECT_STORE, diff --git a/src/config/types.ts b/src/config/types.ts index 9731dd77c..2d99d04f7 100644 --- a/src/config/types.ts +++ b/src/config/types.ts @@ -28,9 +28,20 @@ export interface AppConfig { readonly browserObservationEnabled: boolean; readonly browserCdpEndpoints: readonly string[]; readonly browserAllowedOrigins: readonly string[]; + readonly browserScenarioPolicy: { + readonly enabled: boolean; + readonly executableRoots: readonly string[]; + readonly cdpEndpoints: readonly string[]; + readonly allowedOrigins: readonly string[]; + readonly allowedEnvironment: readonly string[]; + }; readonly electronObservationEnabled: boolean; readonly electronCdpEndpoints: readonly string[]; readonly electronFileRoots: readonly string[]; + readonly v8InspectorObservationEnabled: boolean; + readonly v8InspectorEndpoints: readonly string[]; + readonly v8InspectorFileRoots: readonly string[]; + readonly v8InspectorAllowedOrigins: readonly string[]; readonly javascriptReplayPolicy: { readonly enabled: boolean; readonly roots: readonly string[]; diff --git a/src/contracts/applicationToolContracts.ts b/src/contracts/applicationToolContracts.ts index 2db523427..b02f3266c 100644 --- a/src/contracts/applicationToolContracts.ts +++ b/src/contracts/applicationToolContracts.ts @@ -1,10 +1,13 @@ import { applicationVersionComparisonResultSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js"; +import { z } from "zod"; import { applicationFeatureTraceResultSchema } from "../domain/javascriptFeatureTraceSchemas.js"; import { javaScriptSemanticTraceResultSchema } from "../domain/javascriptSemanticTraceSchemas.js"; import { javaScriptExportShapeComparisonResultSchema } from "../domain/javascriptExportShapeComparisonSchemas.js"; +import { sourceToBundleComparisonResultSchema } from "../domain/sourceToBundleComparisonSchemas.js"; import { compareApplicationVersionsRequestSchema, compareJavaScriptExportShapesRequestSchema, + compareSourceToBundleRequestSchema, traceApplicationFeatureRequestSchema, traceJavaScriptSemanticsRequestSchema, } from "./applicationWorkflowInputContracts.js"; @@ -24,6 +27,14 @@ import { reconstructionCoverageQueryInputSchema, } from "../application/ReconstructionCoverageService.js"; import { reconstructionClosureResultSchema } from "../domain/reconstructionCoverage.js"; +import { + reconstructionObligationLedgerInputSchema, + reconstructionObligationLedgerPageSchema, +} from "../domain/reconstructionObligationLedgerSchemas.js"; +import { + reconstructionReadinessInputSchema, + reconstructionReadinessReportSchema, +} from "../domain/reconstructionReadinessSchemas.js"; import { jsonObjectSchema } from "../domain/jsonValue.js"; import type { ToolContract } from "./toolContracts.js"; import { toolContractMetadata } from "./toolEffects.js"; @@ -32,7 +43,9 @@ import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, + SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE, } from "./javascriptApplicationWorkflowExamples.js"; +import { RECONSTRUCTION_READINESS_EXAMPLE } from "./reconstructionReadinessExample.js"; const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema); const semanticTraceOutputSchema = evidenceResultOf( @@ -41,9 +54,35 @@ const semanticTraceOutputSchema = evidenceResultOf( const comparisonOutputSchema = evidenceResultOf( applicationVersionComparisonResultSchema, ); +const sourceToBundleOutputSchema = evidenceResultOf( + sourceToBundleComparisonResultSchema, +); const exportShapeComparisonOutputSchema = evidenceResultOf( javaScriptExportShapeComparisonResultSchema, ); +const reconstructionObligationLedgerOutputSchema = evidenceResultOf( + reconstructionObligationLedgerPageSchema, +); +const reconstructionReadinessOutputSchema = evidenceResultOf( + reconstructionReadinessReportSchema + .pick({ + schema: true, + schema_version: true, + report_id: true, + source_digest: true, + report_digest: true, + status: true, + summary: true, + metrics: true, + }) + .extend({ + report_resource_uri: z + .string() + .regex( + /^rea:\/\/evidence\/ev_[a-f0-9]{64}\/reconstruction-readiness-report$/u, + ), + }), +); const HASH = "0".repeat(64); const NODE_PREPARATION_EXAMPLE = jsonObjectSchema.parse({ preparation_approved: true, @@ -162,6 +201,22 @@ export const APPLICATION_TOOL_CONTRACTS = [ }, ], }, + { + name: "compare_source_to_bundle", + ...toolContractMetadata("compare_source_to_bundle"), + description: + "Compare a cryptographically committed HistoricalSourceGraph/v1 with authenticated JavaScript Application Graph Evidence supplied directly or by session Evidence ID. Uses explicit exact-digest, source-map path, current-path, suffix, and basename signals with stable weights. Classifies unchanged, modified, removed, split, merged, duplicated, and unknown; incomplete coverage and ambiguous weak signals never become absence or forced matches.", + kind: "application", + inputSchema: compareSourceToBundleRequestSchema, + outputSchema: sourceToBundleOutputSchema, + examples: [ + { + title: + "Compare committed historical source with a shipped bundle graph", + input: SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE, + }, + ], + }, { name: "compare_javascript_export_shapes", ...toolContractMetadata("compare_javascript_export_shapes"), @@ -264,6 +319,55 @@ export const APPLICATION_TOOL_CONTRACTS = [ }, ], }, + { + name: "build_reconstruction_obligation_ledger", + ...toolContractMetadata("build_reconstruction_obligation_ledger"), + description: + "Generate one deterministic page of a ReconstructionObligationLedger/v1 from an authenticated Evidence v2 bundle, reviewed obligations, and an explicit reconstruction manifest. Static candidates remain candidates; duplicate ownership, missing original or reconstruction cases, missing parser/type, weak verifier authority, unenumerated claims, contradictions, dependencies, and residual unknowns fail closed. Every page carries the same full-ledger closure digest and typed per-obligation diagnostics.", + kind: "application", + inputSchema: reconstructionObligationLedgerInputSchema, + outputSchema: reconstructionObligationLedgerOutputSchema, + examples: [ + { + title: "Generate the first obligation-ledger page", + input: { + evidence_bundle: { + bundle_version: 2, + artifacts: [], + providers: [], + environments: [], + scenarios: [], + captures: [], + unknowns: [], + records: [], + }, + reviewed_obligations: [], + manifest: { + schema_version: 1, + bindings: [], + contradictions: [], + }, + limits: { max_obligations: 1_000 }, + page: { offset: 0, limit: 50 }, + }, + }, + ], + }, + { + name: "evaluate_reconstruction_readiness", + ...toolContractMetadata("evaluate_reconstruction_readiness"), + description: + "Evaluate the fixed nine-stage public reconstruction journey into a deterministic ReconstructionReadinessReport/v1. Exact capability limits, provider routing, CLI/MCP status parity, bounded authority, partial-order comparison, contradictions, obligation closure, cleanup, and replay digests fail closed. Aggregate pass is emitted only when every required stage and check passes with attributable Evidence.", + kind: "application", + inputSchema: reconstructionReadinessInputSchema, + outputSchema: reconstructionReadinessOutputSchema, + examples: [ + { + title: "Evaluate the complete synthetic reconstruction journey", + input: RECONSTRUCTION_READINESS_EXAMPLE, + }, + ], + }, { name: "commit_reconstruction_coverage", ...toolContractMetadata("commit_reconstruction_coverage"), diff --git a/src/contracts/toolContractExamples.ts b/src/contracts/toolContractExamples.ts index c8ccd642c..6d84c8e5b 100644 --- a/src/contracts/toolContractExamples.ts +++ b/src/contracts/toolContractExamples.ts @@ -18,6 +18,8 @@ export const TOOL_EXAMPLE_OVERRIDES: Readonly< procedure_callers: { procedure: "main" }, procedure_info: { procedure: "main" }, read_function_instructions: { procedure: "main" }, + read_bytes: { address: "0x1000", length: 16 }, + address_to_file_offset: { address: "0x1000" }, procedure_references: { procedure: "main" }, procedure_pseudo_code: { procedure: "main" }, resolve_containing_procedure: { address: "0x1000" }, @@ -34,6 +36,8 @@ export const TOOL_EXAMPLE_OVERRIDES: Readonly< find_xrefs_to_name: { name: "malloc" }, analyze_function: { procedure: "main" }, trace_feature: { query: "license" }, + find_code_for_string: { query: "authorization failed" }, + trace_call_path: { start: "0x1000", goal: "0x1100" }, open_binary: { path: "/tmp/fixture" }, import_evidence_bundle: { path: "evidence.json" }, capture_process_scenario: { diff --git a/src/contracts/toolContractTypes.ts b/src/contracts/toolContractTypes.ts index 75446caf4..7b67e147c 100644 --- a/src/contracts/toolContractTypes.ts +++ b/src/contracts/toolContractTypes.ts @@ -26,6 +26,7 @@ export const TOOL_KINDS = [ "managed-provider", "browser-provider", "electron-provider", + "runtime-provider", "application", "session", ] as const; diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts index 02843d0df..8fd5edefd 100644 --- a/src/contracts/toolContracts.ts +++ b/src/contracts/toolContracts.ts @@ -27,8 +27,9 @@ import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js"; import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js"; import { MANAGED_TOOL_CONTRACTS } from "./managedToolContracts.js"; import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managedWorkflowToolContracts.js"; -import { BROWSER_TOOL_CONTRACTS } from "./browserToolContracts.js"; +import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "./browserProviderToolContracts.js"; import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js"; +import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "./javascriptRuntimeObservationToolContracts.js"; import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js"; import { closeBinaryInputSchema, @@ -38,6 +39,8 @@ import type { ToolContract, ToolExample } from "./toolContractTypes.js"; import { toolContractMetadata } from "./toolEffects.js"; import { binarySessionInputSchema } from "./sessionStatusContract.js"; import { functionInstructionInputSchema } from "./functionInstructionContract.js"; +import { HOPPER_MEMORY_TOOL_DEFINITIONS } from "./hopperMemoryContracts.js"; +import { analysisSearchInput } from "./analysisSearchContract.js"; export { binarySessionInputSchema } from "./sessionStatusContract.js"; @@ -51,27 +54,10 @@ const address = z ); const optionalAddress = address.optional(); const procedure = z.string().describe("The procedure name or address"); -const searchPattern = z - .string() - .min(1) - .max(256) - .describe("The literal text or bounded regex pattern to search for"); -const caseSensitive = z - .boolean() - .default(false) - .describe("Whether to match case"); const pagination = { offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(500).default(100), }; -const searchInput = { - pattern: searchPattern, - mode: z.enum(["literal", "regex"]).default("literal"), - case_sensitive: caseSensitive, - offset: z.number().int().min(0).default(0), - limit: z.number().int().min(1).max(100).default(100), - document, -}; const exampleInputSchema = z.record(z.string(), jsonValueSchema); const examplesFor = ( @@ -246,6 +232,9 @@ export const OFFICIAL_TOOL_CONTRACTS = [ "Read one offset-paginated window of raw instructions for an analyzed procedure without decompilation, caller discovery, or whole-program string/name scans. Use this fast path for instruction-level orientation; follow next_offset when truncated.", functionInstructionInputSchema, ), + ...HOPPER_MEMORY_TOOL_DEFINITIONS.map(({ name, description, inputSchema }) => + official(name, description, inputSchema), + ), official( "procedure_references", "Return a bounded set of raw incoming or outgoing reference edges for one procedure. Endpoint procedures are resolved only from provider containment; Ghidra preserves observed reference kinds while providers without kind authority mark them unavailable.", @@ -271,12 +260,12 @@ export const OFFICIAL_TOOL_CONTRACTS = [ official( "search_procedures", "Search analyzed procedure names using literal matching by default or regex opt-in. Providers bound search work and reject regex constructs, paths, candidates, or cumulative work outside their finite budgets. Results are deterministic and offset-paginated.", - z.object(searchInput), + z.object(analysisSearchInput), ), official( "search_strings", "Search analyzed strings using literal matching by default or regex opt-in. Providers bound search work and reject regex constructs, paths, candidates, or cumulative work outside their finite budgets. Results are deterministic, offset-paginated, and explicitly truncated.", - z.object(searchInput), + z.object(analysisSearchInput), ), official( "set_address_name", @@ -375,6 +364,16 @@ export const ENHANCED_TOOL_CONTRACTS = [ "Trace a bounded literal feature query through matching strings and procedures, xrefs, and truthful containing-procedure resolution. Returns the operation budget, truncation, and residual unknowns; unknown_registry_approved: true records them durably without inferring reference kinds.", enhancedInputSchemas.trace_feature, ), + enhanced( + "find_code_for_string", + "Resolve one literal string query to bounded analyzed string entries, xrefs, and truthful containing-procedure candidates. Returns an Evidence ID, exact operation budget, truncation, and residual unknowns; it never infers reference kinds or runtime reachability.", + enhancedInputSchemas.find_code_for_string, + ), + enhanced( + "trace_call_path", + "Trace a deterministic bounded caller or callee path from one exact procedure address, optionally stopping at a goal. Returns visited nodes, direct-call edges, one shortest traversal path, failures, frontier, consumed limits, an Evidence ID, and explicit residual unknowns without claiming unresolved indirect calls are absent.", + enhancedInputSchemas.trace_call_path, + ), ] as const satisfies readonly ToolContract[]; /** Session-owned Evidence bundle export options. */ @@ -521,8 +520,9 @@ export const TOOL_CONTRACTS = [ ...ARTIFACT_TOOL_CONTRACTS, ...MANAGED_TOOL_CONTRACTS, ...MANAGED_WORKFLOW_TOOL_CONTRACTS, - ...BROWSER_TOOL_CONTRACTS, + ...BROWSER_PROVIDER_TOOL_CONTRACTS, ...ELECTRON_TOOL_CONTRACTS, + ...JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS, ...APPLICATION_TOOL_CONTRACTS, ...SESSION_TOOL_CONTRACTS, ] as const; diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.ts index d4c31330f..81e29b6be 100644 --- a/src/contracts/toolEffects.ts +++ b/src/contracts/toolEffects.ts @@ -61,6 +61,8 @@ export const TOOL_EFFECTS: Readonly> = { procedure_callers: evidence, procedure_info: evidence, read_function_instructions: evidence, + read_bytes: evidence, + address_to_file_offset: evidence, procedure_references: evidence, procedure_pseudo_code: evidence, resolve_containing_procedure: evidence, @@ -88,12 +90,15 @@ export const TOOL_EFFECTS: Readonly> = { binary_overview: evidence, analyze_function: evidence, trace_feature: effects({ mutatesSession: true, idempotent: false }), + find_code_for_string: effects({ mutatesSession: true, idempotent: false }), + trace_call_path: effects({ mutatesSession: true, idempotent: false }), inspect_macho: nativeEvidence, inspect_signature: nativeEvidence, inspect_plist: nativeEvidence, list_architectures: nativeEvidence, demangle_swift: nativeEvidence, inventory_artifact: evidence, + inspect_artifact: evidence, extract_artifact: effects({ mutatesSession: true, writesFilesystem: true }), inspect_managed_artifact: evidence, inspect_managed_members: evidence, @@ -111,14 +116,29 @@ export const TOOL_EFFECTS: Readonly> = { compare_web_captures: browserEvidence, capture_web_screenshot: browserEvidence, compare_web_screenshots: browserEvidence, + capture_browser_scenario: effects({ + mutatesTarget: true, + mutatesSession: true, + writesFilesystem: true, + launchesProcess: true, + accessesNetwork: true, + changesUiState: true, + mayDiscardData: true, + idempotent: false, + }), list_electron_targets: browserEvidence, inspect_electron_page: browserEvidence, + list_javascript_runtime_targets: browserEvidence, + observe_javascript_runtime: browserEvidence, analyze_javascript_application: evidence, reconcile_javascript_runtime: evidence, trace_application_feature: evidence, trace_javascript_semantics: evidence, compare_application_versions: evidence, + compare_source_to_bundle: evidence, compare_javascript_export_shapes: evidence, + build_reconstruction_obligation_ledger: evidence, + evaluate_reconstruction_readiness: evidence, run_replay_machine: effects(), run_controlled_replay: effects({ mutatesSession: true, diff --git a/src/contracts/toolOutputSchemaGroups.ts b/src/contracts/toolOutputSchemaGroups.ts index 5c405fd2d..5b2d2582d 100644 --- a/src/contracts/toolOutputSchemaGroups.ts +++ b/src/contracts/toolOutputSchemaGroups.ts @@ -21,6 +21,7 @@ import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../domain/artifactGraph.js"; +import { artifactInspectionResultSchema } from "../domain/artifactInspection.js"; import { managedArtifactInspectionSchema, managedMemberInspectionSchema, @@ -46,6 +47,7 @@ import { addressedEntry, bounded, containingProcedureResolution, + clientFeatureAvailabilitySchema, functionDossierOutput, graphNode, lifecycleResultOf, @@ -87,6 +89,21 @@ export const officialOutputSchemas: Readonly> = { procedure_callers: resultOf(addressList), procedure_info: procedureInfoOutput, read_function_instructions: resultOf(functionInstructionWindowSchema), + read_bytes: resultOf( + z.object({ + address: z.string(), + requested_bytes: z.number().int().min(1).max(4_096), + returned_bytes: z.number().int().min(0).max(4_096), + bytes_hex: z.string().regex(/^(?:[a-f0-9]{2})*$/u), + complete: z.boolean(), + }), + ), + address_to_file_offset: resultOf( + z.object({ + address: z.string(), + file_offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER), + }), + ), procedure_references: resultOf( z.object({ procedure: procedureIdentity, @@ -118,6 +135,71 @@ export const officialOutputSchemas: Readonly> = { xrefs: resultOf(addressList), }; +const literalTraceOutput = resultOf( + z.object({ + query: z.string(), + search_mode: z.literal("literal"), + operations_used: z.number().int().min(0), + operation_budget: z.number().int().min(1), + matches: z.array( + z.object({ + type: z.enum(["string", "procedure"]), + address: z.string(), + value: z.string(), + }), + ), + references: z.array( + z.object({ + target_address: z.string(), + source_address: z.string(), + containing_procedure: containingProcedureResolution, + }), + ), + truncated: z.boolean(), + residual_unknowns: z.array(z.string()), + }), +); + +const callPathTraceOutput = resultOf( + z.object({ + start: z.string(), + goal: z.string().nullable(), + direction: z.enum(["forward", "backward"]), + goal_status: z.enum(["not_requested", "reached", "not_reached"]), + nodes: z.array( + z.object({ + address: z.string(), + depth: z.number().int().min(0), + }), + ), + edges: z.array( + z.object({ + source_address: z.string(), + target_address: z.string(), + discovery_depth: z.number().int().min(1), + }), + ), + traversal_path: z.array(z.string()), + failures: z.array( + z.object({ + address: z.string(), + error: analysisErrorProjectionSchema, + }), + ), + frontier: z.array(z.string()), + limits: z.object({ + max_depth: z.number().int().min(1), + max_nodes: z.number().int().min(1), + max_operations: z.number().int().min(1), + nodes_visited: z.number().int().min(1), + operations_used: z.number().int().min(0), + }), + truncated: z.boolean(), + residual_unknowns: z.array(z.string()), + limitations: z.array(z.string()), + }), +); + /** Exact structured-content schemas for composed analysis workflows. */ export const enhancedOutputSchemas: Readonly> = { swift_classes: symbolDiscoveryOutput("classes"), @@ -190,30 +272,9 @@ export const enhancedOutputSchemas: Readonly> = { }), ), analyze_function: functionDossierOutput, - trace_feature: resultOf( - z.object({ - query: z.string(), - search_mode: z.literal("literal"), - operations_used: z.number().int().min(0), - operation_budget: z.number().int().min(1), - matches: z.array( - z.object({ - type: z.enum(["string", "procedure"]), - address: z.string(), - value: z.string(), - }), - ), - references: z.array( - z.object({ - target_address: z.string(), - source_address: z.string(), - containing_procedure: containingProcedureResolution, - }), - ), - truncated: z.boolean(), - residual_unknowns: z.array(z.string()), - }), - ), + trace_feature: literalTraceOutput, + find_code_for_string: literalTraceOutput, + trace_call_path: callPathTraceOutput, }; /** Exact Evidence v2 schemas for provider-neutral native inspection. */ @@ -228,6 +289,7 @@ export const nativeOutputSchemas: Readonly> = { /** Exact Evidence v2 schemas for provider-neutral artifact graph operations. */ export const artifactOutputSchemas: Readonly> = { inventory_artifact: resultOf(artifactInventoryResultSchema), + inspect_artifact: resultOf(artifactInspectionResultSchema), extract_artifact: resultOf(artifactExtractionResultSchema), }; @@ -319,6 +381,7 @@ export const sessionOutputSchemas: Readonly> = { next_cursor: z.number().int().min(0).nullable(), has_more: z.boolean(), }), + client_features: clientFeatureAvailabilitySchema, }), z.union([ sessionProvider.extend({ diff --git a/src/contracts/toolOutputSchemaPrimitives.ts b/src/contracts/toolOutputSchemaPrimitives.ts index a1165c6ae..f2be4f19f 100644 --- a/src/contracts/toolOutputSchemaPrimitives.ts +++ b/src/contracts/toolOutputSchemaPrimitives.ts @@ -207,12 +207,31 @@ const providerTargetSupport = z.discriminatedUnion("status", [ }), ]); +const clientFeatureNameSchema = z.enum([ + "elicitation_form", + "elicitation_url", + "roots", + "sampling", +]); + +/** Negotiated MCP client features that affect REA workflow availability. */ +export const clientFeatureAvailabilitySchema = z.object({ + elicitation_form: z.boolean(), + elicitation_url: z.boolean(), + roots: z.boolean(), + sampling: z.boolean(), +}); +export type ClientFeatureAvailability = z.infer< + typeof clientFeatureAvailabilitySchema +>; + export const toolAvailability = z.object({ name: z.string(), surface: z.string(), available: z.boolean(), reason: z.enum([ "available", + "client_capability_missing", "target_required", "provider_missing", "provider_unavailable", @@ -221,6 +240,12 @@ export const toolAvailability = z.object({ "policy_disabled", ]), remediation: z.string().nullable(), + client_requirements: z.object({ + required: z.array(clientFeatureNameSchema), + optional: z.array(clientFeatureNameSchema), + missing_required: z.array(clientFeatureNameSchema), + missing_optional: z.array(clientFeatureNameSchema), + }), effects: z.strictObject({ mutatesTarget: z.boolean(), mutatesSession: z.boolean(), diff --git a/src/domain/errors.ts b/src/domain/errors.ts index 7e30121c8..cafdb2479 100644 --- a/src/domain/errors.ts +++ b/src/domain/errors.ts @@ -1,4 +1,10 @@ import type { JsonValue } from "./jsonValue.js"; +import type { + BrowserObservationFailureReason, + BrowserObservationOperation, +} from "./browserObservationErrors.js"; + +export type { BrowserObservationOperation } from "./browserObservationErrors.js"; import type { MissingPermissionScope, PermissionRequest, @@ -258,34 +264,13 @@ export class ProviderAdapterError extends AnalysisError { } } -/** Public browser and Electron operations that can fail at a CDP boundary. */ -export type BrowserObservationOperation = - | "list_browser_targets" - | "inspect_web_page" - | "analyze_web_bundle" - | "observe_web_session" - | "discover_webmcp_tools" - | "compare_web_captures" - | "capture_web_screenshot" - | "compare_web_screenshots" - | "list_electron_targets" - | "inspect_electron_page"; - /** A bounded passive browser observation failed at its CDP boundary. */ export class BrowserObservationError extends AnalysisError { readonly _tag = "BrowserObservationError"; constructor( readonly operation: BrowserObservationOperation, - readonly reason: - | "endpoint_unreachable" - | "invalid_endpoint_response" - | "target_not_found" - | "target_not_allowed" - | "target_changed" - | "protocol_error" - | "disconnected" - | "payload_limit", + readonly reason: BrowserObservationFailureReason, options?: ErrorOptions, ) { super(`Browser observation ${operation} failed: ${reason}`, options); @@ -299,6 +284,7 @@ export class ArtifactOperationError extends AnalysisError { constructor( readonly operation: | "inventory_artifact" + | "inspect_artifact" | "extract_artifact" | "analyze_javascript_application", readonly reason: @@ -441,6 +427,7 @@ export type HopperDiagnosticType = | "remote" | "authorization" | "invalid_request" + | "capability_unavailable" | "bridge_exception"; /** Hopper's JSON-RPC endpoint returned an expected remote error response. */ diff --git a/src/domain/permissionPolicy.ts b/src/domain/permissionPolicy.ts index af0d44098..4642becaa 100644 --- a/src/domain/permissionPolicy.ts +++ b/src/domain/permissionPolicy.ts @@ -6,7 +6,9 @@ import { err, ok, type Result } from "./result.js"; export type PermissionCapability = | "process_capture" | "browser_observe" + | "browser_automate" | "electron_observe" + | "v8_inspector_observe" | "evidence_read" | "evidence_write" | "investigation_input" diff --git a/src/main.ts b/src/main.ts index 96a741a1d..3417aa330 100644 --- a/src/main.ts +++ b/src/main.ts @@ -12,6 +12,8 @@ import { projectAnalysisError } from "./domain/errors.js"; import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js"; import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js"; import { CdpElectronProvider } from "./browser/CdpElectronProvider.js"; +import { V8InspectorProvider } from "./browser/V8InspectorProvider.js"; +import { PlaywrightBrowserScenarioProvider } from "./browser/PlaywrightBrowserScenarioProvider.js"; import type { RuntimeDependencies } from "./main/types.js"; import { SERVER_START_FAILED } from "./main/messages.js"; import { createRuntimeState } from "./main/state.js"; @@ -72,7 +74,9 @@ export const run = async ( const session = createBinarySession(config.value, logger); const browserObservation = new CdpBrowserProvider(); + const browserScenarioCapture = new PlaywrightBrowserScenarioProvider(); const electronObservation = new CdpElectronProvider(); + const javascriptRuntimeObservation = new V8InspectorProvider(); const opened = await openInitialTarget( session, config.value, @@ -85,7 +89,9 @@ export const run = async ( logger, serverLogger, browserObservation, + browserScenarioCapture, electronObservation, + javascriptRuntimeObservation, permissionAuthority: permissionAuthority.value, runtimeState, }); diff --git a/src/main/transport.ts b/src/main/transport.ts index 50c734f29..7edb93be4 100644 --- a/src/main/transport.ts +++ b/src/main/transport.ts @@ -3,6 +3,8 @@ import type { StdioServerHandle } from "@modelcontextprotocol/server/stdio"; import type { BinarySession } from "../application/BinarySession.js"; import type { CdpBrowserProvider } from "../browser/CdpBrowserProvider.js"; import type { CdpElectronProvider } from "../browser/CdpElectronProvider.js"; +import type { V8InspectorProvider } from "../browser/V8InspectorProvider.js"; +import type { PlaywrightBrowserScenarioProvider } from "../browser/PlaywrightBrowserScenarioProvider.js"; import type { PermissionAuthority } from "../application/PermissionAuthority.js"; import type { Logger } from "../logger.js"; import { createServer } from "../server/createServer.js"; @@ -19,7 +21,9 @@ interface ServerContext { readonly logger: Logger; readonly serverLogger: Logger; readonly browserObservation: CdpBrowserProvider; + readonly browserScenarioCapture: PlaywrightBrowserScenarioProvider; readonly electronObservation: CdpElectronProvider; + readonly javascriptRuntimeObservation: V8InspectorProvider; readonly permissionAuthority: PermissionAuthority; readonly runtimeState: RuntimeState; } @@ -55,7 +59,10 @@ export const startMcpTransport = async ( serverContext.runtimeState.snapshotPolicy, permissionAuthority: serverContext.permissionAuthority, browserObservation: serverContext.browserObservation, + browserScenarioCapture: serverContext.browserScenarioCapture, electronObservation: serverContext.electronObservation, + javascriptRuntimeObservation: + serverContext.javascriptRuntimeObservation, artifactIntegrityContinueEnabled: () => serverContext.runtimeState.currentConfig .artifactIntegrityContinueEnabled, @@ -63,37 +70,8 @@ export const startMcpTransport = async ( serverContext.runtimeState.javascriptReplayPolicy, managedRuntimePolicy: serverContext.runtimeState.managedRuntimePolicy, - availabilityPolicy: () => ({ - processCaptureEnabled: - serverContext.runtimeState.currentConfig.processExecutionPolicy - .enabled, - evidenceFileRoots: - serverContext.runtimeState.currentConfig.evidenceFilePolicy - .roots.length, - investigationInputRoots: - serverContext.runtimeState.currentConfig.investigationInputRoots - .length, - browserObservationEnabled: - serverContext.runtimeState.currentConfig - .browserObservationEnabled && - serverContext.runtimeState.currentConfig.browserCdpEndpoints - .length > 0 && - serverContext.runtimeState.currentConfig.browserAllowedOrigins - .length > 0, - electronObservationEnabled: - serverContext.runtimeState.currentConfig - .electronObservationEnabled && - serverContext.runtimeState.currentConfig.electronCdpEndpoints - .length > 0 && - serverContext.runtimeState.currentConfig.electronFileRoots - .length > 0, - javascriptReplayEnabled: - serverContext.runtimeState.currentConfig.javascriptReplayPolicy - .enabled, - managedRuntimeEnabled: - serverContext.runtimeState.currentConfig.managedRuntimePolicy - .enabled, - }), + availabilityPolicy: () => + runtimeAvailability(serverContext.runtimeState), }, ); liveServers.add(server); @@ -114,3 +92,29 @@ export const startMcpTransport = async ( } return { ok: true, handle, liveServers }; }; + +const runtimeAvailability = (state: RuntimeState) => ({ + processCaptureEnabled: state.currentConfig.processExecutionPolicy.enabled, + evidenceFileRoots: state.currentConfig.evidenceFilePolicy.roots.length, + investigationInputRoots: state.currentConfig.investigationInputRoots.length, + browserObservationEnabled: + state.currentConfig.browserObservationEnabled && + state.currentConfig.browserCdpEndpoints.length > 0 && + state.currentConfig.browserAllowedOrigins.length > 0, + browserScenarioEnabled: + state.currentConfig.browserScenarioPolicy.enabled && + state.currentConfig.browserScenarioPolicy.allowedOrigins.length > 0 && + (state.currentConfig.browserScenarioPolicy.executableRoots.length > 0 || + state.currentConfig.browserScenarioPolicy.cdpEndpoints.length > 0), + electronObservationEnabled: + state.currentConfig.electronObservationEnabled && + state.currentConfig.electronCdpEndpoints.length > 0 && + state.currentConfig.electronFileRoots.length > 0, + v8InspectorObservationEnabled: + state.currentConfig.v8InspectorObservationEnabled && + state.currentConfig.v8InspectorEndpoints.length > 0 && + (state.currentConfig.v8InspectorFileRoots.length > 0 || + state.currentConfig.v8InspectorAllowedOrigins.length > 0), + javascriptReplayEnabled: state.currentConfig.javascriptReplayPolicy.enabled, + managedRuntimeEnabled: state.currentConfig.managedRuntimePolicy.enabled, +}); diff --git a/src/mcpDoctor.ts b/src/mcpDoctor.ts index 2bca5cd3d..7b6d945c2 100644 --- a/src/mcpDoctor.ts +++ b/src/mcpDoctor.ts @@ -105,11 +105,16 @@ const inspectProductionMcpSession = async ( client.listResources(undefined, request), client.listResourceTemplates(undefined, request), client.readResource({ uri: "rea://server/identity" }, request), - client.callTool({ name: "binary_session", arguments: {} }, request), + client.callTool( + { name: "binary_session", arguments: { detail: "full" } }, + request, + ), ]); + const expectedToolNames = + availableToolNames(requestFlow.structuredContent) ?? []; const inventory = { tools: compareInventory( - CATALOG_IDENTITY.tools.map(({ name }) => name), + expectedToolNames, tools.tools.map(({ name }) => name), ), prompts: compareInventory( @@ -177,6 +182,27 @@ const inspectProductionMcpSession = async ( }; }; +const availableToolNames = ( + structuredContent: unknown, +): readonly string[] | undefined => { + if (typeof structuredContent !== "object" || structuredContent === null) + return undefined; + const result = Reflect.get(structuredContent, "result"); + if (typeof result !== "object" || result === null) return undefined; + const availability = Reflect.get(result, "tool_availability"); + if (!Array.isArray(availability)) return undefined; + const names: string[] = []; + for (const item of availability) { + if (typeof item !== "object" || item === null) return undefined; + const name = Reflect.get(item, "name"); + const available = Reflect.get(item, "available"); + if (typeof name !== "string" || typeof available !== "boolean") + return undefined; + if (available) names.push(name); + } + return names; +}; + /** * Dispatcher entry for `rea mcp doctor`, kept separate from Incur MCP setup. * @public diff --git a/src/server/DynamicToolAvailability.ts b/src/server/DynamicToolAvailability.ts new file mode 100644 index 000000000..8f93f9932 --- /dev/null +++ b/src/server/DynamicToolAvailability.ts @@ -0,0 +1,98 @@ +import type { McpServer, RegisteredTool } from "@modelcontextprotocol/server"; + +import { + buildCapabilityInventory, + type AvailabilityPolicy, +} from "../application/CapabilityInventory.js"; +import type { BinarySessionPort } from "../application/BinarySession.js"; +import type { ClientFeatureAvailability } from "../contracts/toolOutputSchemaPrimitives.js"; + +interface ToolAvailabilityController { + /** Apply current session, policy, host, provider, and client availability. */ + synchronize(): boolean; +} + +/** + * Track public SDK tool handles and keep their visible state synchronized with + * the same availability projection returned by `binary_session`. + */ +export const installDynamicToolAvailability = ( + server: McpServer, + session: BinarySessionPort, + policy: () => AvailabilityPolicy, +): ToolAvailabilityController => { + const tools = new Map(); + const originalRegisterTool = server.registerTool.bind(server); + const originalSendToolListChanged = server.sendToolListChanged.bind(server); + let synchronizing = false; + const controller: ToolAvailabilityController = { + synchronize: () => { + if (synchronizing) return false; + synchronizing = true; + try { + const availability = new Map( + buildCapabilityInventory( + session.status(), + policy(), + clientFeatures(server), + ).map((item) => [item.name, item.available]), + ); + let changed = false; + for (const [name, tool] of tools) { + const enabled = availability.get(name) === true; + if (tool.enabled === enabled) continue; + changed = true; + if (enabled) tool.enable(); + else tool.disable(); + } + return changed; + } finally { + synchronizing = false; + } + }, + }; + + const wrappedRegisterTool = (...args: unknown[]): unknown => { + const name = args[0]; + if (typeof name !== "string") + throw new TypeError("MCP tool registration requires a string name"); + const registered: unknown = Reflect.apply( + originalRegisterTool, + server, + args, + ); + if (!isRegisteredTool(registered)) + throw new TypeError(`MCP SDK did not return a tool handle for ${name}`); + tools.set(name, registered); + return registered; + }; + if (!Reflect.set(server, "registerTool", wrappedRegisterTool)) + throw new TypeError("Unable to install dynamic MCP tool registration"); + if ( + !Reflect.set(server, "sendToolListChanged", () => { + if (controller.synchronize()) originalSendToolListChanged(); + }) + ) + throw new TypeError("Unable to install dynamic MCP tool notifications"); + + return controller; +}; + +const clientFeatures = (server: McpServer): ClientFeatureAvailability => { + const capabilities = server.server.getClientCapabilities(); + return { + elicitation_form: capabilities?.elicitation?.form !== undefined, + elicitation_url: capabilities?.elicitation?.url !== undefined, + roots: capabilities?.roots !== undefined, + sampling: capabilities?.sampling !== undefined, + }; +}; + +const isRegisteredTool = (value: unknown): value is RegisteredTool => { + if (typeof value !== "object" || value === null) return false; + return ( + typeof Reflect.get(value, "enabled") === "boolean" && + typeof Reflect.get(value, "enable") === "function" && + typeof Reflect.get(value, "disable") === "function" + ); +}; diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 858e8d100..fb6e04635 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -25,14 +25,24 @@ import { registerEvidenceResources } from "./registerEvidenceResources.js"; import { createServerIdentity } from "../serverIdentity.js"; import type { PermissionAuthority } from "../application/PermissionAuthority.js"; import type { BrowserObservationPort } from "../application/BrowserObservationPort.js"; +import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioCapturePort.js"; import { registerBrowserTools } from "./registerBrowserTools.js"; +import { registerBrowserScenarioTool } from "./registerBrowserScenarioTool.js"; import type { ElectronObservationPort } from "../application/ElectronObservationPort.js"; import { registerElectronTools } from "./registerElectronTools.js"; +import type { JavaScriptRuntimeObservationPort } from "../application/JavaScriptRuntimeObservationPort.js"; +import { registerJavaScriptRuntimeObservationTools } from "./registerJavaScriptRuntimeObservationTools.js"; import { registerApplicationTools } from "./registerApplicationTools.js"; import type { SessionAvailability } from "./sessionAvailabilityPolicy.js"; +import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js"; +import { + DENY_EVIDENCE_FILE_POLICY, + DENY_PROCESS_POLICY, +} from "./sessionToolPolicies.js"; +import { installDynamicToolAvailability } from "./DynamicToolAvailability.js"; const TARGET_FREE_INSTRUCTIONS = - "REA analyzes shipped artifacts. Route: ASAR/JavaScript -> analyze_javascript_application (configured root required); archive/package -> inventory_artifact; managed PE/CLI -> inspect_managed_artifact; browser/Electron runtime -> list_browser_targets/list_electron_targets; native binary/database -> open_binary, then binary_overview. Check binary_session for policy. Start with summaries and cite Evidence IDs. Never repeat identical analysis or read full Evidence without a specific need."; + "REA analyzes shipped artifacts. Route: ASAR/JavaScript -> analyze_javascript_application (configured root); archive/package -> inspect_artifact; managed PE/CLI -> inspect_managed_artifact; passive browser/Electron -> list_browser_targets/list_electron_targets; approved browser interaction -> capture_browser_scenario; Node/Electron Inspector -> list_javascript_runtime_targets; native binary/database -> open_binary, then binary_overview. Check binary_session policy. Start with summaries and cite Evidence IDs. Never repeat identical analysis or read full Evidence without need."; const ACTIVE_TARGET_INSTRUCTIONS = "REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then narrow with analyze_function, literal search, callers, callees, and xrefs. Prefer summary views, never repeat an identical call, and read full Evidence only when the task requires it."; @@ -57,7 +67,9 @@ export interface CreateServerOptions { readonly analysisSnapshotFilePolicy?: EvidenceFilePolicy; readonly permissionAuthority?: PermissionAuthority; readonly browserObservation?: BrowserObservationPort; + readonly browserScenarioCapture?: BrowserScenarioCapturePort; readonly electronObservation?: ElectronObservationPort; + readonly javascriptRuntimeObservation?: JavaScriptRuntimeObservationPort; readonly artifactIntegrityContinueEnabled?: () => boolean; readonly javascriptReplayPolicy?: JavaScriptReplayPolicy; readonly javascriptReplayHost?: JavaScriptReplayHost; @@ -66,6 +78,32 @@ export interface CreateServerOptions { readonly availabilityPolicy?: () => SessionAvailability; } +const installSessionToolAvailability = ( + server: McpServer, + session: BinarySessionPort | undefined, + options: CreateServerOptions, +) => { + if (session === undefined) return undefined; + const policy = sessionAvailabilityPolicy(options.availabilityPolicy, { + processPolicy: options.processPolicy ?? DENY_PROCESS_POLICY, + evidenceFilePolicy: options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY, + investigationInputRoots: options.investigationInputRoots ?? [], + optionalFeatures: { + browserObservationEnabled: options.browserObservation !== undefined, + browserScenarioEnabled: options.browserScenarioCapture !== undefined, + electronObservationEnabled: options.electronObservation !== undefined, + v8InspectorObservationEnabled: + options.javascriptRuntimeObservation !== undefined, + javascriptReplayEnabled: options.javascriptReplayPolicy?.enabled ?? false, + managedRuntimeEnabled: options.managedRuntimePolicy?.enabled ?? false, + }, + }); + return { + policy, + controller: installDynamicToolAvailability(server, session, policy), + }; +}; + /** * Construct one MCP server without acquiring subprocess resources. * Supplying a session adds target lifecycle tools; omitting it retains the @@ -106,9 +144,12 @@ export const createServer = ( : TARGET_FREE_INSTRUCTIONS, }, ); + const dynamicTools = installSessionToolAvailability(server, session, options); server.server.onclose = () => { permissionAuthority?.clearSessionGrants(); }; + if (dynamicTools !== undefined) + server.server.oninitialized = () => server.sendToolListChanged(); session?.onAvailabilityChanged?.(() => server.sendToolListChanged()); registerServerIdentityResource(server, startedAt); const toolLogger = logger.child({ layer: "server" }); @@ -132,6 +173,9 @@ export const createServer = ( registerEvidenceResources(server, session); registerSessionTools(server, session, toolLogger, { ...options, + ...(dynamicTools === undefined + ? {} + : { availabilityPolicy: dynamicTools.policy }), ...(permissionAuthority === undefined ? {} : { permissionAuthority }), startedAt, processCaptureElicitation: { @@ -155,6 +199,7 @@ export const createServer = ( }, }); } + dynamicTools?.controller.synchronize(); return server; }; @@ -310,12 +355,24 @@ const registerObservationTools = ({ permissionAuthority, recordEvidence, }); + registerBrowserScenarioTool(server, { + logger, + provider: options.browserScenarioCapture, + permissionAuthority, + recordEvidence, + }); registerElectronTools(server, { logger, electron: options.electronObservation, permissionAuthority, recordEvidence, }); + registerJavaScriptRuntimeObservationTools(server, { + logger, + runtime: options.javascriptRuntimeObservation, + permissionAuthority, + recordEvidence, + }); registerApplicationTools(server, { logger, recordEvidence, diff --git a/src/server/registerApplicationTools.ts b/src/server/registerApplicationTools.ts index 69f6b06f1..62b8b14c6 100644 --- a/src/server/registerApplicationTools.ts +++ b/src/server/registerApplicationTools.ts @@ -3,10 +3,13 @@ import type { McpServer } from "@modelcontextprotocol/server"; import { registerTraceFeatureTool } from "./registerApplicationTools/traceFeature.js"; import { registerTraceJavaScriptSemanticsTool } from "./registerApplicationTools/traceSemantics.js"; import { registerCompareApplicationVersionsTool } from "./registerApplicationTools/compareVersions.js"; +import { registerCompareSourceToBundleTool } from "./registerApplicationTools/compareSourceToBundle.js"; import { registerCompareJavaScriptExportShapesTool } from "./registerApplicationTools/compareExportShapes.js"; import { registerControlledReplayTool } from "./registerApplicationTools/controlledReplay.js"; import { registerCharacterizationTools } from "./registerApplicationTools/characterization.js"; import { registerCoverageTools } from "./registerApplicationTools/coverage.js"; +import { registerReconstructionObligationLedgerTool } from "./registerApplicationTools/obligationLedger.js"; +import { registerReconstructionReadinessTool } from "./registerApplicationTools/readiness.js"; import type { ApplicationToolRegistration } from "./registerApplicationTools/types.js"; export type { ApplicationToolRegistration }; @@ -19,8 +22,11 @@ export const registerApplicationTools = ( registerTraceFeatureTool(server, options); registerTraceJavaScriptSemanticsTool(server, options); registerCompareApplicationVersionsTool(server, options); + registerCompareSourceToBundleTool(server, options); registerCompareJavaScriptExportShapesTool(server, options); registerControlledReplayTool(server, options); registerCharacterizationTools(server, options); + registerReconstructionObligationLedgerTool(server, options); + registerReconstructionReadinessTool(server, options); registerCoverageTools(server, options); }; diff --git a/src/server/registerEvidenceResources.ts b/src/server/registerEvidenceResources.ts index 8bd8a9638..4b33740d1 100644 --- a/src/server/registerEvidenceResources.ts +++ b/src/server/registerEvidenceResources.ts @@ -10,6 +10,8 @@ import canonicalize from "canonicalize"; import type { BinarySessionPort } from "../application/BinarySessionPort.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { registerJavaScriptApplicationGraphResource } from "./registerJavaScriptApplicationGraphResource.js"; +import { registerReconstructionObligationLedgerResource } from "./registerReconstructionObligationLedgerResource.js"; +import { registerReconstructionReadinessResource } from "./registerReconstructionReadinessResource.js"; const evidenceUri = (evidenceId: string): string => `rea://evidence/${evidenceId}`; @@ -27,6 +29,8 @@ export const registerEvidenceResources = ( registerArtifactPageResource(server, session); registerFunctionDossierResource(server, session); registerEvidenceSectionResource(server, session); + registerReconstructionObligationLedgerResource(server, session); + registerReconstructionReadinessResource(server, session); registerJavaScriptApplicationGraphResource(server, session); registerResidualUnknownResource(server, session); }; diff --git a/src/server/registerEvidenceTools.ts b/src/server/registerEvidenceTools.ts index f53bdd19c..7bc215bd6 100644 --- a/src/server/registerEvidenceTools.ts +++ b/src/server/registerEvidenceTools.ts @@ -7,7 +7,7 @@ import type { import type { BinarySessionPort } from "../application/BinarySession.js"; import type { ToolContract } from "../contracts/toolContracts.js"; import type { BinaryTarget } from "../domain/binaryTarget.js"; -import { createEvidence } from "../domain/evidence.js"; +import { createEvidence, type Evidence } from "../domain/evidence.js"; import { jsonObjectSchema } from "../domain/jsonValue.js"; import type { Logger } from "../logger.js"; import { logToolExecution } from "./toolLogging.js"; @@ -27,6 +27,10 @@ interface EvidenceToolRegistration { readonly activeTarget: (() => BinaryTarget | undefined) | undefined; readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined; readonly permissionAuthority?: PermissionAuthority; + readonly sourceEvidence?: ( + operation: Exclude, + result: import("../domain/jsonValue.js").JsonValue, + ) => readonly Evidence[]; } /** Register provider-backed contracts that return atomic Evidence v2 observations. */ @@ -92,6 +96,8 @@ export const registerEvidenceTools = ( terminal: true, }); if (!execution.ok) return toCallToolResult(execution, contract); + const sourceEvidence = + options.sourceEvidence?.(contract.name, execution.value.result) ?? []; const evidence = createEvidence( execution.value.subject ?? options.activeTarget?.(), execution.value.provider, @@ -102,8 +108,14 @@ export const registerEvidenceTools = ( rawResult: execution.value.rawResult, limitations: execution.value.limitations, locations: execution.value.locations, + evidenceLinks: sourceEvidence.map(({ evidence_id: id }) => id), }, ); + for (const source of sourceEvidence) { + const sourceRecorded = options.recordEvidence?.(source); + if (sourceRecorded !== undefined && !sourceRecorded.ok) + return toCallToolResult(sourceRecorded, contract); + } const recorded = options.recordEvidence?.(evidence); return recorded !== undefined && !recorded.ok ? toCallToolResult(recorded, contract) @@ -135,7 +147,7 @@ const permissionRequest = ( operation_identity: `extract_artifact:${parameters.output_root}`, }; if ( - operation === "inventory_artifact" && + ["inventory_artifact", "inspect_artifact"].includes(operation) && parameters.native_mount_approved === true ) return { @@ -145,7 +157,7 @@ const permissionRequest = ( environment_names: [], network: "none" as const, mount: true, - operation_identity: "inventory_artifact:native_mount", + operation_identity: `${operation}:native_mount`, }; return undefined; }; diff --git a/src/server/registerSessionStatusTool.ts b/src/server/registerSessionStatusTool.ts index 3b451c612..62083b247 100644 --- a/src/server/registerSessionStatusTool.ts +++ b/src/server/registerSessionStatusTool.ts @@ -10,6 +10,7 @@ import { toCallToolResult } from "./toolResult.js"; import { jsonObjectSchema } from "../domain/jsonValue.js"; import { createServerIdentity } from "../serverIdentity.js"; import { buildCapabilityInventory } from "../application/CapabilityInventory.js"; +import type { ClientFeatureAvailability } from "../contracts/toolOutputSchemaPrimitives.js"; import { toolRegistrationOptions } from "./toolRegistrationOptions.js"; import { safeParseToolInput } from "./toolInputValidation.js"; import type { SessionAvailability } from "./sessionAvailabilityPolicy.js"; @@ -44,11 +45,18 @@ export const registerSessionStatusTool = ( const parsed = parsedInput.value; const client = server.server.getClientVersion(); const clientCapabilities = server.server.getClientCapabilities(); + const clientFeatures: ClientFeatureAvailability = { + elicitation_form: clientCapabilities?.elicitation?.form !== undefined, + elicitation_url: clientCapabilities?.elicitation?.url !== undefined, + roots: clientCapabilities?.roots !== undefined, + sampling: clientCapabilities?.sampling !== undefined, + }; const status = session.status(); const statusObject = jsonObjectSchema.parse(status); const toolAvailability = buildCapabilityInventory( status, availabilityPolicy(), + clientFeatures, ); const serverIdentity = createServerIdentity({ startedAt, @@ -78,14 +86,7 @@ export const registerSessionStatusTool = ( status: statusObject, toolAvailability, serverIdentity, - clientFeatures: { - elicitation_form: - clientCapabilities?.elicitation?.form !== undefined, - elicitation_url: - clientCapabilities?.elicitation?.url !== undefined, - roots: clientCapabilities?.roots !== undefined, - sampling: clientCapabilities?.sampling !== undefined, - }, + clientFeatures, }), }, contract, @@ -101,7 +102,7 @@ const projectSessionStatus = (options: { >; readonly toolAvailability: readonly ToolAvailability[]; readonly serverIdentity: ReturnType; - readonly clientFeatures: Readonly>; + readonly clientFeatures: ClientFeatureAvailability; }) => { if (options.input.detail === "full") return jsonObjectSchema.parse({ @@ -139,6 +140,7 @@ const projectSessionStatus = (options: { next_cursor: nextCursor < filtered.length ? nextCursor : null, has_more: nextCursor < filtered.length, }, + client_features: options.clientFeatures, }); } return jsonObjectSchema.parse({ @@ -182,7 +184,7 @@ const recommendedActions = ( : []), ...(!open ? [ - "Route the supplied target directly: ASAR/JavaScript to analyze_javascript_application, packages to inventory_artifact, managed PE/CLI to inspect_managed_artifact, browser/Electron runtimes to their list-target tools, and native binaries to open_binary.", + "Route the supplied target directly: ASAR/JavaScript to analyze_javascript_application, unfamiliar packages to inspect_artifact, managed PE/CLI to inspect_managed_artifact, browser/Electron runtimes to their list-target tools, and native binaries to open_binary.", ] : [ "Continue from the active target with binary_overview or a bounded target-specific query.", diff --git a/src/server/registerSessionTools.ts b/src/server/registerSessionTools.ts index 2c4231cfc..311e701d9 100644 --- a/src/server/registerSessionTools.ts +++ b/src/server/registerSessionTools.ts @@ -351,12 +351,11 @@ export const registerSessionTools = ( contracts: [openContract, closeContract, statusContract], snapshotFilePolicy: analysisSnapshotFilePolicy, startedAt: options.startedAt ?? new Date().toISOString(), - availabilityPolicy: sessionAvailabilityPolicy( - options.availabilityPolicy, + availabilityPolicy: sessionAvailabilityPolicy(options.availabilityPolicy, { processPolicy, evidenceFilePolicy, - options.investigationInputRoots ?? [], - ), + investigationInputRoots: options.investigationInputRoots ?? [], + }), ...(options.permissionAuthority === undefined ? {} : { permissionAuthority: options.permissionAuthority }), diff --git a/src/server/sessionAvailabilityPolicy.ts b/src/server/sessionAvailabilityPolicy.ts index 75837dfb4..878c17276 100644 --- a/src/server/sessionAvailabilityPolicy.ts +++ b/src/server/sessionAvailabilityPolicy.ts @@ -6,25 +6,48 @@ export interface SessionAvailability { readonly evidenceFileRoots: number; readonly investigationInputRoots: number; readonly browserObservationEnabled?: boolean; + readonly browserScenarioEnabled?: boolean; readonly electronObservationEnabled?: boolean; + readonly v8InspectorObservationEnabled?: boolean; readonly javascriptReplayEnabled?: boolean; readonly managedRuntimeEnabled?: boolean; } +export interface SessionAvailabilityDefaults { + readonly processPolicy: ProcessExecutionPolicy; + readonly evidenceFilePolicy: EvidenceFilePolicy; + readonly investigationInputRoots: readonly string[]; + readonly optionalFeatures?: Pick< + SessionAvailability, + | "browserObservationEnabled" + | "browserScenarioEnabled" + | "electronObservationEnabled" + | "v8InspectorObservationEnabled" + | "javascriptReplayEnabled" + | "managedRuntimeEnabled" + >; +} + /** Select configured availability reporting or the target-free defaults. */ export const sessionAvailabilityPolicy = ( configured: (() => SessionAvailability) | undefined, - processPolicy: ProcessExecutionPolicy, - evidenceFilePolicy: EvidenceFilePolicy, - investigationInputRoots: readonly string[], + defaults: SessionAvailabilityDefaults, ): (() => SessionAvailability) => configured ?? (() => ({ - processCaptureEnabled: processPolicy.enabled, - evidenceFileRoots: evidenceFilePolicy.roots.length, - investigationInputRoots: investigationInputRoots.length, - browserObservationEnabled: false, - electronObservationEnabled: false, - javascriptReplayEnabled: false, - managedRuntimeEnabled: false, + processCaptureEnabled: defaults.processPolicy.enabled, + evidenceFileRoots: defaults.evidenceFilePolicy.roots.length, + investigationInputRoots: defaults.investigationInputRoots.length, + browserObservationEnabled: + defaults.optionalFeatures?.browserObservationEnabled ?? false, + browserScenarioEnabled: + defaults.optionalFeatures?.browserScenarioEnabled ?? false, + electronObservationEnabled: + defaults.optionalFeatures?.electronObservationEnabled ?? false, + v8InspectorObservationEnabled: + defaults.optionalFeatures?.v8InspectorObservationEnabled ?? false, + javascriptReplayEnabled: + defaults.optionalFeatures?.javascriptReplayEnabled ?? false, + managedRuntimeEnabled: + defaults.optionalFeatures?.managedRuntimeEnabled ?? false, })); diff --git a/tests/browserMcp.test.ts b/tests/browserMcp.test.ts index 3db45eba6..8edabb9aa 100644 --- a/tests/browserMcp.test.ts +++ b/tests/browserMcp.test.ts @@ -38,7 +38,7 @@ describe("browser MCP tools", () => { const connected = await connectBrowser(browser); const tools = await connected.client.listTools(); - expect(tools.tools).toHaveLength(TOOL_CONTRACTS.length); + expect(tools.tools.length).toBeLessThan(TOOL_CONTRACTS.length); expect(tools.tools.map(({ name }) => name)).toEqual( expect.arrayContaining([ "list_browser_targets", @@ -49,8 +49,6 @@ describe("browser MCP tools", () => { "compare_web_captures", "capture_web_screenshot", "compare_web_screenshots", - "list_electron_targets", - "inspect_electron_page", ]), ); const status = await connected.client.callTool({ diff --git a/tests/capabilityInventory.test.ts b/tests/capabilityInventory.test.ts index 65dcaf425..797d71903 100644 --- a/tests/capabilityInventory.test.ts +++ b/tests/capabilityInventory.test.ts @@ -7,7 +7,9 @@ const enabledPolicy: Parameters[1] = { evidenceFileRoots: 1, investigationInputRoots: 1, browserObservationEnabled: true, + browserScenarioEnabled: true, electronObservationEnabled: true, + v8InspectorObservationEnabled: true, javascriptReplayEnabled: true, managedRuntimeEnabled: true, }; @@ -129,7 +131,9 @@ describe("capability inventory", () => { it.each([ ["capture_process_scenario", { processCaptureEnabled: false }], ["inspect_web_page", { browserObservationEnabled: false }], + ["capture_browser_scenario", { browserScenarioEnabled: false }], ["inspect_electron_page", { electronObservationEnabled: false }], + ["observe_javascript_runtime", { v8InspectorObservationEnabled: false }], ["run_controlled_replay", { javascriptReplayEnabled: false }], ["plan_managed_runtime_correlation", { managedRuntimeEnabled: false }], ] as const)("reports stable policy denial for %s", (name, override) => { @@ -153,6 +157,7 @@ describe("capability inventory", () => { investigationInputRoots: 0, browserObservationEnabled: false, electronObservationEnabled: false, + v8InspectorObservationEnabled: false, javascriptReplayEnabled: false, managedRuntimeEnabled: false, }); @@ -163,4 +168,30 @@ describe("capability inventory", () => { expect(availability.remediation?.length).toBeGreaterThan(0); } }); + + it("projects negotiated client features into per-tool requirements", () => { + const withoutElicitation = buildCapabilityInventory( + status(), + enabledPolicy, + ).find(({ name }) => name === "capture_process_scenario"); + const withElicitation = buildCapabilityInventory(status(), enabledPolicy, { + elicitation_form: true, + elicitation_url: false, + roots: false, + sampling: false, + }).find(({ name }) => name === "capture_process_scenario"); + + expect(withoutElicitation?.client_requirements).toEqual({ + required: [], + optional: ["elicitation_form"], + missing_required: [], + missing_optional: ["elicitation_form"], + }); + expect(withElicitation?.client_requirements).toEqual({ + required: [], + optional: ["elicitation_form"], + missing_required: [], + missing_optional: [], + }); + }); }); diff --git a/tests/config.test.ts b/tests/config.test.ts index a34c9d4e7..89a2fd955 100644 --- a/tests/config.test.ts +++ b/tests/config.test.ts @@ -32,9 +32,20 @@ describe("runtime configuration", () => { expect(result.value.browserObservationEnabled).toBe(false); expect(result.value.browserCdpEndpoints).toEqual([]); expect(result.value.browserAllowedOrigins).toEqual([]); + expect(result.value.browserScenarioPolicy).toEqual({ + enabled: false, + executableRoots: [], + cdpEndpoints: [], + allowedOrigins: [], + allowedEnvironment: [], + }); expect(result.value.electronObservationEnabled).toBe(false); expect(result.value.electronCdpEndpoints).toEqual([]); expect(result.value.electronFileRoots).toEqual([]); + expect(result.value.v8InspectorObservationEnabled).toBe(false); + expect(result.value.v8InspectorEndpoints).toEqual([]); + expect(result.value.v8InspectorFileRoots).toEqual([]); + expect(result.value.v8InspectorAllowedOrigins).toEqual([]); expect(result.value.javascriptReplayPolicy).toMatchObject({ enabled: false, roots: [], @@ -112,6 +123,26 @@ describe("runtime configuration", () => { }); }); + it("builds a separate V8 Inspector endpoint, root, and origin ceiling", () => { + const result = parseConfig({ + REA_V8_INSPECTOR_OBSERVE_ENABLED: "true", + REA_V8_INSPECTOR_ENDPOINTS_JSON: '["http://127.0.0.1:9229"]', + REA_V8_INSPECTOR_FILE_ROOTS_JSON: '["/tmp/node-app"]', + REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON: '["http://127.0.0.1:3000"]', + }); + expect(result.ok).toBe(true); + if (!result.ok) return; + expect(result.value.permissionCeilings).toContainEqual({ + capability: "v8_inspector_observe", + roots: ["/tmp/node-app"], + executables: [], + environment_names: [], + origins: ["http://127.0.0.1:9229", "http://127.0.0.1:3000"], + network: "loopback", + mount: false, + }); + }); + it("can configure a process-capture ceiling without an implicit grant", () => { const result = parseConfig({ REA_PROCESS_CAPTURE_ENABLED: "true", @@ -414,6 +445,48 @@ describe("runtime configuration", () => { ); }); + it("requires an explicit grant for exact-scope browser automation", () => { + const environment = { + REA_BROWSER_SCENARIO_ENABLED: "true", + REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON: '["/opt/chromium"]', + REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON: '["http://127.0.0.1:9222"]', + REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON: '["https://app.example.test"]', + REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON: '["REA_TEST_PASSWORD"]', + }; + const result = parseConfig(environment); + if (!result.ok) throw result.error; + expect(result.value.browserScenarioPolicy).toEqual({ + enabled: true, + executableRoots: ["/opt/chromium"], + cdpEndpoints: ["http://127.0.0.1:9222"], + allowedOrigins: ["https://app.example.test"], + allowedEnvironment: ["REA_TEST_PASSWORD"], + }); + expect(result.value.permissionCeilings).toContainEqual({ + capability: "browser_automate", + roots: [], + executables: ["/opt/chromium"], + environment_names: ["REA_TEST_PASSWORD"], + origins: ["http://127.0.0.1:9222", "https://app.example.test"], + network: "external", + mount: false, + }); + expect(result.value.administratorPermissionGrants).not.toContainEqual( + expect.objectContaining({ capability: "browser_automate" }), + ); + const automatic = parseConfig({ + ...environment, + REA_BROWSER_SCENARIO_AUTO_GRANT: "true", + }); + if (!automatic.ok) throw automatic.error; + expect(automatic.value.administratorPermissionGrants).toContainEqual( + expect.objectContaining({ + capability: "browser_automate", + lifetime: "administrator", + }), + ); + }); + it.each([ '["http://localhost:9222"]', '["http://192.168.1.5:9222"]', diff --git a/tests/contractSnapshot.test.ts b/tests/contractSnapshot.test.ts index 850c4deb9..833c0943b 100644 --- a/tests/contractSnapshot.test.ts +++ b/tests/contractSnapshot.test.ts @@ -12,7 +12,9 @@ import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts. import { MANAGED_TOOL_CONTRACTS } from "../src/contracts/managedToolContracts.js"; import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "../src/contracts/managedWorkflowToolContracts.js"; import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js"; +import { BROWSER_SCENARIO_TOOL_CONTRACTS } from "../src/contracts/browserScenarioToolContracts.js"; import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js"; +import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "../src/contracts/javascriptRuntimeObservationToolContracts.js"; import { APPLICATION_TOOL_CONTRACTS } from "../src/contracts/applicationToolContracts.js"; import { enhancedOutputSchemas, @@ -119,7 +121,9 @@ describe("tool contract surface", () => { ...MANAGED_TOOL_CONTRACTS, ...MANAGED_WORKFLOW_TOOL_CONTRACTS, ...BROWSER_TOOL_CONTRACTS, + ...BROWSER_SCENARIO_TOOL_CONTRACTS, ...ELECTRON_TOOL_CONTRACTS, + ...JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS, ...APPLICATION_TOOL_CONTRACTS, ...SESSION_TOOL_CONTRACTS, ].map(({ name }) => name); @@ -214,7 +218,9 @@ describe("tool contract surface", () => { ...MANAGED_TOOL_CONTRACTS, ...MANAGED_WORKFLOW_TOOL_CONTRACTS, ...BROWSER_TOOL_CONTRACTS, + ...BROWSER_SCENARIO_TOOL_CONTRACTS, ...ELECTRON_TOOL_CONTRACTS, + ...JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS, ...APPLICATION_TOOL_CONTRACTS, ...SESSION_TOOL_CONTRACTS, ]; diff --git a/tests/electronMcp.test.ts b/tests/electronMcp.test.ts index 2b16a29d7..10ce374cc 100644 --- a/tests/electronMcp.test.ts +++ b/tests/electronMcp.test.ts @@ -336,28 +336,11 @@ describe("Electron MCP tools", () => { }, }); - const denied = await client.callTool({ - name: "analyze_javascript_application", - arguments: { input_path: root, approved: true }, - }); - expect(denied).toMatchObject({ - isError: true, - structuredContent: { - error: { - code: "permission_required", - remediation: { - action: expect.stringContaining("administrator configuration"), - elicitation_supported: false, - restart_required: true, - }, - details: { - capability: "investigation_input", - missing: { roots: [root] }, - ceiling: expect.objectContaining({ roots: [] }), - }, - }, - }, - }); + expect( + (await client.listTools()).tools.some( + ({ name }) => name === "analyze_javascript_application", + ), + ).toBe(false); }); const evidenceFor = (session: BinarySession, value: unknown) => { diff --git a/tests/ghidraMcp.test.ts b/tests/ghidraMcp.test.ts index a221e0af4..851d08675 100644 --- a/tests/ghidraMcp.test.ts +++ b/tests/ghidraMcp.test.ts @@ -219,14 +219,10 @@ describe("Ghidra MCP and shared CLI composition", () => { }, }); - const unsupported = await mcp.callTool({ - name: "set_comment", - arguments: { address: "0x401000", comment: "not allowed" }, - }); - expect(unsupported.isError).toBe(true); - expect(unsupported.structuredContent).toMatchObject({ - error: { code: "capability_unavailable" }, - }); + const availableNames = (await mcp.listTools()).tools.map( + ({ name }) => name, + ); + expect(availableNames).not.toContain("set_comment"); expect(calls).not.toContain("set_comment"); const status = await mcp.callTool({ @@ -265,6 +261,10 @@ describe("Ghidra MCP and shared CLI composition", () => { name: "find_xrefs_to_name", available: true, }), + expect.objectContaining({ + name: "set_comment", + available: false, + }), ]), }, }); @@ -272,7 +272,7 @@ describe("Ghidra MCP and shared CLI composition", () => { await Promise.allSettled([mcp.close(), server.close()]); await session.close(); } - }); + }, 10_000); }); const sessionEvidence = (session: BinarySession, value: unknown) => { diff --git a/tests/integration/serverIntegration.test.ts b/tests/integration/serverIntegration.test.ts index ce16ebc9e..f131ab5a4 100644 --- a/tests/integration/serverIntegration.test.ts +++ b/tests/integration/serverIntegration.test.ts @@ -1,11 +1,14 @@ import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import type { CallToolResult } from "@modelcontextprotocol/server"; import { afterEach, describe, expect, it } from "vitest"; +import { z } from "zod"; import { BinarySession } from "../../src/application/BinarySession.js"; import type { AnalysisClient, AnalysisOperationPort, + AnalysisProvider, + CapabilityDescriptor, } from "../../src/application/AnalysisProvider.js"; import { AnalysisCapabilityUnavailableError, @@ -47,6 +50,47 @@ const connect = async (analysis: AnalysisOperationPort) => { return client; }; +const providerWithCapabilities = ( + operations: readonly CapabilityDescriptor["operation"][], +): AnalysisProvider => { + const identity = { id: "fixture", name: "Fixture", version: "1" }; + const capabilities: readonly CapabilityDescriptor[] = operations.map( + (operation) => ({ + provider: identity, + operation, + inputContractVersion: 1, + outputContractVersion: 1, + available: true, + reason: null, + pagination: "none", + exhaustive: true, + effects: { + mutatesArtifact: false, + launchesProcess: false, + mayShowUi: false, + mayAccessNetwork: false, + mayWriteFilesystem: false, + changesPermissions: false, + requiresRoot: false, + }, + limits: { + maxResults: null, + maxPayloadBytes: null, + timeoutMs: null, + }, + limitations: [], + }), + ); + return { + identity: () => identity, + capabilities: () => capabilities, + createClient: () => ({ + execute: () => Promise.resolve(ok(null)), + close: () => Promise.resolve(), + }), + }; +}; + const text = (result: CallToolResult): string => { const content = result.content.find((item) => item.type === "text"); if (content?.type !== "text") throw new Error("missing text result"); @@ -189,7 +233,7 @@ describe("full MCP integration with multi-tool sequences", () => { }); }); - it("preserves the complete canonical inventory with a session", async () => { + it("advertises the complete currently available inventory with a session", async () => { const session = new BinarySession( (_path) => ({ @@ -212,13 +256,32 @@ describe("full MCP integration with multi-tool sequences", () => { await client.connect(clientTransport); const listed = await client.listTools(); - expect(listed.tools).toHaveLength(TOOL_CONTRACTS.length); const names = listed.tools.map((t) => t.name); expect(names).toContain("open_binary"); expect(names).toContain("close_binary"); expect(names).toContain("binary_session"); - expect(names).toContain("binary_overview"); - expect(names).toContain("batch_decompile"); + expect(names).not.toContain("binary_overview"); + expect(names).not.toContain("batch_decompile"); + const status = structured( + await client.callTool({ + name: "binary_session", + arguments: { detail: "full" }, + }), + ); + const available = new Set( + z + .object({ + result: z.object({ + tool_availability: z.array( + z.object({ name: z.string(), available: z.boolean() }), + ), + }), + }) + .parse(status) + .result.tool_availability.filter((item) => item.available) + .map(({ name }) => name), + ); + expect(new Set(names)).toEqual(available); const contracts = new Map( TOOL_CONTRACTS.map((contract) => [contract.name, contract]), @@ -237,7 +300,7 @@ describe("full MCP integration with multi-tool sequences", () => { ); assertDescribedRootObject(tool.outputSchema, `${tool.name}.output`); } - }); + }, 10_000); it("records approved trace truncation as a deduplicated residual unknown", async () => { const analysis: AnalysisOperationPort = { @@ -254,11 +317,12 @@ describe("full MCP integration with multi-tool sequences", () => { ), }; const session = new BinarySession( - () => - ({ - execute: () => Promise.resolve(ok(null)), - close: () => Promise.resolve(), - }) satisfies AnalysisClient, + providerWithCapabilities([ + "list_strings", + "list_procedures", + "xrefs", + "resolve_containing_procedure", + ]), ); const server = createServer(analysis, session); const client = new Client({ name: "unknown-workflow", version: "1.0.0" }); @@ -267,6 +331,10 @@ describe("full MCP integration with multi-tool sequences", () => { resources.push(client, server); await server.connect(serverTransport); await client.connect(clientTransport); + await client.callTool({ + name: "open_binary", + arguments: { path: process.execPath }, + }); for (let attempt = 0; attempt < 2; attempt += 1) { const traced = await client.callTool({ @@ -310,11 +378,7 @@ describe("full MCP integration with multi-tool sequences", () => { }, }; const session = new BinarySession( - () => - ({ - execute: () => Promise.resolve(ok(null)), - close: () => Promise.resolve(), - }) satisfies AnalysisClient, + providerWithCapabilities(["procedure_pseudo_code"]), ); const server = createServer(analysis, session); const client = new Client({ name: "unavailable-unknown", version: "1" }); @@ -323,6 +387,10 @@ describe("full MCP integration with multi-tool sequences", () => { resources.push(client, server); await server.connect(serverTransport); await client.connect(clientTransport); + await client.callTool({ + name: "open_binary", + arguments: { path: process.execPath }, + }); const unavailable = await client.callTool({ name: "procedure_pseudo_code", diff --git a/tests/mcpDoctor.test.ts b/tests/mcpDoctor.test.ts index f78090257..3035bb907 100644 --- a/tests/mcpDoctor.test.ts +++ b/tests/mcpDoctor.test.ts @@ -32,14 +32,20 @@ describe("production MCP doctor", () => { adapter: "production-stdio", inventory: { tools: { - expected: CATALOG_IDENTITY.counts.mcp_tools, - observed: CATALOG_IDENTITY.counts.mcp_tools, + expected: expect.any(Number), + observed: expect.any(Number), missing: [], unexpected: [], }, }, request_flow: { tool: "binary_session", ok: true }, }); + expect(result.inventory?.tools.expected).toBe( + result.inventory?.tools.observed, + ); + expect(result.inventory?.tools.expected).toBeLessThan( + CATALOG_IDENTITY.counts.mcp_tools, + ); }, 30_000); it("reports exact missing, unexpected, and duplicate inventory names", () => { diff --git a/tests/productCatalog.test.ts b/tests/productCatalog.test.ts index 0674e1712..9e6f0f5f8 100644 --- a/tests/productCatalog.test.ts +++ b/tests/productCatalog.test.ts @@ -18,6 +18,8 @@ import { } from "../src/application/InvestigationProviders.js"; import { CDP_BROWSER_PROVIDER_IDENTITY } from "../src/browser/CdpBrowserProvider.js"; import { CDP_ELECTRON_PROVIDER_IDENTITY } from "../src/browser/CdpElectronProvider.js"; +import { PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY } from "../src/browser/PlaywrightBrowserScenarioProvider.js"; +import { V8_INSPECTOR_PROVIDER_IDENTITY } from "../src/browser/V8InspectorProvider.js"; import { CLI_COMMAND_NAMES } from "../src/cliCommandNames.js"; import { createCli } from "../src/cli.js"; import { TOOL_CONTRACTS } from "../src/contracts/toolContracts.js"; @@ -76,7 +78,9 @@ describe("canonical product catalog", () => { MANAGED_STATIC_PROVIDER, MANAGED_WORKFLOW_PROVIDER, CDP_BROWSER_PROVIDER_IDENTITY, + PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY, CDP_ELECTRON_PROVIDER_IDENTITY, + V8_INSPECTOR_PROVIDER_IDENTITY, JAVASCRIPT_APPLICATION_PROVIDER, JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, @@ -112,9 +116,12 @@ describe("canonical product catalog", () => { ({ id }) => id === JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER.id, )?.capabilities, ).toEqual([ + "build_reconstruction_obligation_ledger", "commit_reconstruction_coverage", "compare_application_versions", "compare_javascript_export_shapes", + "compare_source_to_bundle", + "evaluate_reconstruction_readiness", "execute_node_characterization", "prepare_node_characterization", "query_reconstruction_coverage", diff --git a/tests/promptMcp.test.ts b/tests/promptMcp.test.ts index d2c0fbb2d..47d8bcf94 100644 --- a/tests/promptMcp.test.ts +++ b/tests/promptMcp.test.ts @@ -10,7 +10,6 @@ import { createTestTempDirectory } from "./fixtures/temporaryDirectory.js"; import type { AnalysisClient } from "../src/application/AnalysisProvider.js"; import { BinarySession } from "../src/application/BinarySession.js"; import { PROMPT_CONTRACTS } from "../src/contracts/promptContracts.js"; -import { TOOL_CONTRACTS } from "../src/contracts/toolContracts.js"; import { createEvidence } from "../src/domain/evidence.js"; import { createServer } from "../src/server/createServer.js"; import { registerGuidedPrompts } from "../src/server/registerPrompts.js"; @@ -36,6 +35,7 @@ describe("guided prompts over MCP", () => { const client = await connect(createServer(session, session)); resources.push(session); + const toolsBeforePrompts = (await client.listTools()).tools; const prompts = await client.listPrompts(); expect(prompts.prompts.map(({ name }) => name)).toEqual( PROMPT_CONTRACTS.map(({ name }) => name), @@ -56,9 +56,7 @@ describe("guided prompts over MCP", () => { ), ); } - expect((await client.listTools()).tools).toHaveLength( - TOOL_CONTRACTS.length, - ); + expect((await client.listTools()).tools).toEqual(toolsBeforePrompts); const result = await client.getPrompt({ name: "investigate_feature", arguments: { diff --git a/tests/readmeConsistency.test.ts b/tests/readmeConsistency.test.ts index 59d5b361e..b01bc59df 100644 --- a/tests/readmeConsistency.test.ts +++ b/tests/readmeConsistency.test.ts @@ -11,8 +11,9 @@ import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js"; import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.js"; import { MANAGED_TOOL_CONTRACTS } from "../src/contracts/managedToolContracts.js"; import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "../src/contracts/managedWorkflowToolContracts.js"; -import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js"; +import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "../src/contracts/browserProviderToolContracts.js"; import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js"; +import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "../src/contracts/javascriptRuntimeObservationToolContracts.js"; import { APPLICATION_TOOL_CONTRACTS } from "../src/contracts/applicationToolContracts.js"; import { SUPPORTED_CLIENT_DEFINITIONS } from "../src/application/SupportedClients.js"; import { PRODUCT_IDENTITY } from "../src/identity.js"; @@ -31,8 +32,9 @@ const expectedToolCounts = [ NATIVE_TOOL_CONTRACTS.length, ARTIFACT_TOOL_CONTRACTS.length, MANAGED_TOOL_CONTRACTS.length + MANAGED_WORKFLOW_TOOL_CONTRACTS.length, - BROWSER_TOOL_CONTRACTS.length, + BROWSER_PROVIDER_TOOL_CONTRACTS.length, ELECTRON_TOOL_CONTRACTS.length, + JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS.length, APPLICATION_TOOL_CONTRACTS.length, SESSION_TOOL_CONTRACTS.length, ] as const; diff --git a/tests/runtime.test.ts b/tests/runtime.test.ts index e8f3ad75b..e5b2a09c4 100644 --- a/tests/runtime.test.ts +++ b/tests/runtime.test.ts @@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url"; import { Client } from "@modelcontextprotocol/client"; import { StdioClientTransport } from "@modelcontextprotocol/client/stdio"; import { describe, expect, it } from "vitest"; +import { z } from "zod"; import { CATALOG_IDENTITY } from "../src/catalogIdentity.js"; @@ -11,6 +12,29 @@ const fixturePath = fileURLToPath( new URL("./fixtures/fakeLauncher.mjs", import.meta.url), ); +const expectAvailableToolInventory = async (client: Client): Promise => { + const listed = await client.listTools(); + const status = await client.callTool({ + name: "binary_session", + arguments: { detail: "full" }, + }); + const availability = z + .object({ + result: z.object({ + tool_availability: z.array( + z.object({ name: z.string(), available: z.boolean() }), + ), + }), + }) + .parse(status.structuredContent).result.tool_availability; + expect(availability).toHaveLength(CATALOG_IDENTITY.counts.mcp_tools); + expect(new Set(listed.tools.map(({ name }) => name))).toEqual( + new Set( + availability.filter(({ available }) => available).map(({ name }) => name), + ), + ); +}; + describe("production stdio runtime", () => { it("starts the built entrypoint, lists the catalog, calls one, and shuts down", async () => { const transport = new StdioClientTransport({ @@ -33,8 +57,7 @@ describe("production stdio runtime", () => { try { await client.connect(transport); - const tools = await client.listTools(); - expect(tools.tools).toHaveLength(CATALOG_IDENTITY.counts.mcp_tools); + await expectAvailableToolInventory(client); const result = await client.callTool({ name: "current_document", arguments: {}, @@ -80,9 +103,7 @@ describe("production stdio runtime", () => { try { await client.connect(transport); - expect((await client.listTools()).tools).toHaveLength( - CATALOG_IDENTITY.counts.mcp_tools, - ); + await expectAvailableToolInventory(client); } finally { await client.close(); await transport.close(); diff --git a/tests/serverIdentity.test.ts b/tests/serverIdentity.test.ts index 6d44a1a41..3af948fe7 100644 --- a/tests/serverIdentity.test.ts +++ b/tests/serverIdentity.test.ts @@ -13,6 +13,48 @@ import { createServer } from "../src/server/createServer.js"; import { createServerIdentity } from "../src/serverIdentity.js"; import { observed } from "./fixtures/analysisExecution.js"; import { buildCapabilityInventory } from "../src/application/CapabilityInventory.js"; +import type { + AnalysisProvider, + CapabilityDescriptor, +} from "../src/application/AnalysisProvider.js"; + +const availabilityProvider = (): AnalysisProvider => { + const identity = { id: "fixture", name: "Fixture", version: "1" }; + const capability: CapabilityDescriptor = { + provider: identity, + operation: "current_address", + inputContractVersion: 1, + outputContractVersion: 1, + available: true, + reason: null, + pagination: "none", + exhaustive: true, + effects: { + mutatesArtifact: false, + launchesProcess: false, + mayShowUi: false, + mayAccessNetwork: false, + mayWriteFilesystem: false, + changesPermissions: false, + requiresRoot: false, + }, + limits: { + maxResults: null, + maxPayloadBytes: null, + timeoutMs: null, + }, + limitations: [], + }; + return { + identity: () => identity, + capabilities: () => [capability], + createClient: () => ({ + health: () => Promise.resolve(), + execute: () => Promise.resolve(observed(null)), + close: () => Promise.resolve(), + }), + }; +}; describe("server and catalog identity", () => { it("derives package and SDK versions from canonical package metadata", async () => { @@ -26,14 +68,14 @@ describe("server and catalog identity", () => { }); expect(PRODUCT_IDENTITY.packageVersion).toBe(packageJson.version); expect(SDK_IDENTITY.server).toBe("2.0.0-beta.4"); - expect(CLI_COMMAND_NAMES).toHaveLength(59); - expect(new Set(CLI_COMMAND_NAMES).size).toBe(59); + expect(CLI_COMMAND_NAMES).toHaveLength(66); + expect(new Set(CLI_COMMAND_NAMES).size).toBe(66); expect(CATALOG_IDENTITY.counts).toEqual({ - cli_commands: 59, + cli_commands: 66, mcp_tools: TOOL_CONTRACTS.length, mcp_prompts: 6, mcp_resources: 2, - mcp_resource_templates: 9, + mcp_resource_templates: 11, }); expect(CATALOG_IDENTITY.digests.combined_sha256).toMatch(/^[a-f0-9]{64}$/u); }); @@ -132,13 +174,16 @@ describe("server and catalog identity", () => { }); it("exposes live identity, labeled inventories, availability, and list changes", async () => { - const session = new BinarySession(() => ({ - health: () => Promise.resolve(), - execute: () => Promise.resolve(observed(null)), - close: () => Promise.resolve(), - })); + const session = new BinarySession(availabilityProvider()); const server = createServer(session, session); - const client = new Client({ name: "identity-test", version: "9" }); + const client = new Client( + { name: "identity-test", version: "9" }, + { + capabilities: { + elicitation: { form: {} }, + }, + }, + ); const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); let toolListChanges = 0; @@ -149,7 +194,7 @@ describe("server and catalog identity", () => { await server.connect(serverTransport); await client.connect(clientTransport); const instructions = client.getInstructions(); - expect(instructions?.length).toBeLessThanOrEqual(512); + expect(instructions?.length).toBeLessThanOrEqual(640); expect(instructions).toContain( "ASAR/JavaScript -> analyze_javascript_application", ); @@ -200,6 +245,12 @@ describe("server and catalog identity", () => { name: "capture_process_scenario", available: false, reason: "policy_disabled", + client_requirements: { + required: [], + optional: ["elicitation_form"], + missing_required: [], + missing_optional: [], + }, }), expect.objectContaining({ name: "inspect_web_page", @@ -216,7 +267,7 @@ describe("server and catalog identity", () => { }), ]), client_features: { - elicitation_form: false, + elicitation_form: true, elicitation_url: false, roots: false, sampling: false, @@ -260,6 +311,12 @@ describe("server and catalog identity", () => { next_cursor: expect.any(Number), has_more: true, }, + client_features: { + elicitation_form: true, + elicitation_url: false, + roots: false, + sampling: false, + }, }, }); for (const capabilityFamily of TOOL_KINDS) { @@ -284,8 +341,17 @@ describe("server and catalog identity", () => { }, }); } - await client.callTool({ name: "close_binary", arguments: {} }); + expect( + (await client.listTools()).tools.map(({ name }) => name), + ).not.toContain("current_address"); + await client.callTool({ + name: "open_binary", + arguments: { path: process.execPath }, + }); await expect.poll(() => toolListChanges).toBeGreaterThan(0); + expect( + (await client.listTools()).tools.map(({ name }) => name), + ).toContain("current_address"); } finally { await Promise.allSettled([ client.close(), @@ -293,5 +359,5 @@ describe("server and catalog identity", () => { session.close(), ]); } - }); + }, 10_000); }); diff --git a/tests/sessionMcp.test.ts b/tests/sessionMcp.test.ts index dfacaf2ec..8efb7c478 100644 --- a/tests/sessionMcp.test.ts +++ b/tests/sessionMcp.test.ts @@ -9,8 +9,11 @@ import { z } from "zod"; import { createTestTempDirectory } from "./fixtures/temporaryDirectory.js"; import { BinarySession } from "../src/application/BinarySession.js"; -import { TOOL_CONTRACTS } from "../src/contracts/toolContracts.js"; -import type { AnalysisClient } from "../src/application/AnalysisProvider.js"; +import type { + AnalysisClient, + AnalysisProvider, + CapabilityDescriptor, +} from "../src/application/AnalysisProvider.js"; import { probeProcessCaptureCapability } from "../src/application/ProcessHarness.js"; import { observed as ok } from "./fixtures/analysisExecution.js"; import { createServer } from "../src/server/createServer.js"; @@ -47,7 +50,7 @@ describe("target-free MCP lifecycle", () => { const targetPath = join(directory, "mutable.hop"); await writeFile(targetPath, "first"); const closed: string[] = []; - const session = new BinarySession((target) => client(target.path, closed), { + const session = new BinarySession(provider(closed), { resolveAnalysisProfile: () => Promise.resolve( resultOk({ profile: SNAPSHOT_PROFILE, compatibility: {} }), @@ -106,7 +109,7 @@ describe("target-free MCP lifecycle", () => { await writeFile(first, "one"); await writeFile(second, "two"); const closed: string[] = []; - const session = new BinarySession((target) => client(target.path, closed), { + const session = new BinarySession(provider(closed), { resolveAnalysisProfile: () => Promise.resolve( resultOk({ profile: SNAPSHOT_PROFILE, compatibility: {} }), @@ -140,34 +143,23 @@ describe("target-free MCP lifecycle", () => { await server.connect(serverTransport); await mcp.connect(clientTransport); - const before = await mcp.callTool({ - name: "current_document", - arguments: {}, - }); - expect(before.isError).toBe(true); - expect(text(before)).toBe(JSON.stringify(before.structuredContent)); - expect((await mcp.listTools()).tools).toHaveLength(TOOL_CONTRACTS.length); - const deniedCapture = await mcp.callTool({ - name: "capture_process_scenario", - arguments: { - approved: true, - executable: "/bin/sh", - working_directory: "/tmp", - }, - }); - expect(deniedCapture.isError).toBe(true); - expect(structured(deniedCapture)).toMatchObject({ - error: { - category: "permission_required", - }, - }); - expect(text(deniedCapture)).toBe( - JSON.stringify(deniedCapture.structuredContent), - ); + const beforeNames = (await mcp.listTools()).tools.map(({ name }) => name); + expect(beforeNames).toContain("open_binary"); + expect(beforeNames).toContain("binary_session"); + expect(beforeNames).not.toContain("current_document"); + expect(beforeNames).not.toContain("capture_process_scenario"); expect( (await mcp.callTool({ name: "open_binary", arguments: { path: first } })) .isError, ).not.toBe(true); + expect( + structured( + await mcp.callTool({ + name: "binary_session", + arguments: { detail: "full" }, + }), + ), + ).toMatchObject({ result: { path: await realpath(first) } }); expect( text(await mcp.callTool({ name: "current_document", arguments: {} })), ).toContain("first.hop"); @@ -391,6 +383,40 @@ const client = (path: string, closed: string[]): AnalysisClient => ({ }, }); +const provider = (closed: string[]): AnalysisProvider => { + const identity = { id: "fixture", name: "Fixture", version: "1" }; + const capability: CapabilityDescriptor = { + provider: identity, + operation: "current_document", + inputContractVersion: 1, + outputContractVersion: 1, + available: true, + reason: null, + pagination: "none", + exhaustive: true, + effects: { + mutatesArtifact: false, + launchesProcess: false, + mayShowUi: false, + mayAccessNetwork: false, + mayWriteFilesystem: false, + changesPermissions: false, + requiresRoot: false, + }, + limits: { + maxResults: null, + maxPayloadBytes: null, + timeoutMs: null, + }, + limitations: [], + }; + return { + identity: () => identity, + capabilities: () => [capability], + createClient: (target) => client(target.path, closed), + }; +}; + const text = (result: CallToolResult): string => { const content = result.content.find((item) => item.type === "text"); if (content?.type !== "text") throw new Error("missing text result"); diff --git a/tests/toolContracts.test.ts b/tests/toolContracts.test.ts index 9c1163009..a304d0bbf 100644 --- a/tests/toolContracts.test.ts +++ b/tests/toolContracts.test.ts @@ -16,10 +16,14 @@ import { APPLICATION_TOOL_CONTRACTS } from "../src/contracts/applicationToolCont describe("tool contract inventory", () => { it("publishes the canonical analysis and session tool inventory", () => { - expect(OFFICIAL_TOOL_CONTRACTS).toHaveLength(34); - expect(ENHANCED_TOOL_CONTRACTS).toHaveLength(10); + expect(OFFICIAL_TOOL_CONTRACTS).toHaveLength(36); + expect(ENHANCED_TOOL_CONTRACTS).toHaveLength(12); expect(NATIVE_TOOL_CONTRACTS).toHaveLength(5); - expect(ARTIFACT_TOOL_CONTRACTS).toHaveLength(2); + expect(ARTIFACT_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([ + "inventory_artifact", + "inspect_artifact", + "extract_artifact", + ]); expect(MANAGED_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([ "inspect_managed_artifact", "inspect_managed_members", @@ -52,10 +56,13 @@ describe("tool contract inventory", () => { "trace_application_feature", "trace_javascript_semantics", "compare_application_versions", + "compare_source_to_bundle", "compare_javascript_export_shapes", "run_controlled_replay", "prepare_node_characterization", "execute_node_characterization", + "build_reconstruction_obligation_ledger", + "evaluate_reconstruction_readiness", "commit_reconstruction_coverage", "query_reconstruction_coverage", ]);