rea-agents 1.6.0 → 2.0.0

package/dist/config.js

@@ -1,14 +1,27 @@
 import { z } from "zod";
+import { isAbsolute } from "node:path";
 import { ConfigurationError } from "./domain/errors.js";
 import { err, ok } from "./domain/result.js";
 import { browserEndpointSchema, browserOriginSchema, isLiteralLoopbackHostname, } from "./domain/browserObservation.js";
 import { electronFileRootsSchema } from "./domain/electronObservation.js";
+import { analysisProviderSelectorSchema, } from "./contracts/providerSelection.js";
 const DEFAULT_HOPPER_LAUNCHER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
 const defaultHopperLauncherPath = () => process.platform === "linux"
     ? "/opt/hopper/bin/Hopper"
     : DEFAULT_HOPPER_LAUNCHER_PATH;
 const environmentSchema = z
     .object({
+    REA_ANALYSIS_PROVIDER: analysisProviderSelectorSchema.default("auto"),
+    GHIDRA_INSTALL_DIR: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "GHIDRA_INSTALL_DIR must be absolute")
+        .optional(),
+    JAVA_HOME: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "JAVA_HOME must be absolute")
+        .optional(),
     HOPPER_LAUNCHER_PATH: z.string().min(1).optional(),
     HOPPER_TARGET_PATH: z.string().min(1).optional(),
     HOPPER_TARGET_KIND: z
@@ -42,6 +55,40 @@ const environmentSchema = z
     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_JAVASCRIPT_REPLAY_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_JAVASCRIPT_REPLAY_ROOTS_JSON: z.string().default("[]"),
+    REA_JAVASCRIPT_REPLAY_NODE_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_NODE_PATH must be absolute")
+        .default(process.execPath),
+    REA_JAVASCRIPT_REPLAY_BWRAP_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_BWRAP_PATH must be absolute")
+        .default("/usr/bin/bwrap"),
+    REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH must be absolute")
+        .default("/usr/bin/systemd-run"),
+    REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH must be absolute")
+        .default("/usr/bin/systemctl"),
+    REA_JAVASCRIPT_REPLAY_SHELL_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_SHELL_PATH must be absolute")
+        .default("/usr/bin/bash"),
+    REA_MANAGED_RUNTIME_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_MANAGED_RUNTIME_ROOTS_JSON: z.string().default("[]"),
+    REA_MANAGED_RUNTIME_EXECUTABLE_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_MANAGED_RUNTIME_EXECUTABLE_PATH must be absolute")
+        .default("/usr/bin/dotnet"),
     REA_PERMISSION_PROJECT_ROOT: z.string().min(1).optional(),
     REA_PERMISSION_PROJECT_STORE: z.string().min(1).optional(),
 })
@@ -136,7 +183,7 @@ const parseLoaderArgs = (encoded) => {
         : err(new ConfigurationError("HOPPER_LOADER_ARGS_JSON must encode an array of strings", { cause: parsed.error }));
 };
 /**
- * Parse Hopper launcher configuration once at the composition root.
+ * Parse provider and authority configuration once at the composition root.
  * Explicit loader arguments override REA's header-derived defaults for a
  * supported target, allowing callers to refine Hopper's loader behavior without
  * bypassing REA's path and executable-header checks.
@@ -144,7 +191,7 @@ const parseLoaderArgs = (encoded) => {
 export const parseConfig = (environment) => {
     const parsedEnvironment = environmentSchema.safeParse(environment);
     if (!parsedEnvironment.success) {
-        return err(new ConfigurationError("Invalid Hopper environment configuration", {
+        return err(new ConfigurationError("Invalid REA environment configuration", {
             cause: parsedEnvironment.error,
         }));
     }
@@ -187,6 +234,16 @@ export const parseConfig = (environment) => {
     const electronFileRoots = parseElectronFileRoots(parsedEnvironment.data.REA_ELECTRON_FILE_ROOTS_JSON);
     if (!electronFileRoots.ok)
         return electronFileRoots;
+    const javascriptReplayRoots = parseStringArray(parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_ROOTS_JSON, "REA_JAVASCRIPT_REPLAY_ROOTS_JSON");
+    if (!javascriptReplayRoots.ok)
+        return javascriptReplayRoots;
+    if (javascriptReplayRoots.value.some((root) => !isAbsolute(root)))
+        return err(new ConfigurationError("REA_JAVASCRIPT_REPLAY_ROOTS_JSON must encode absolute roots"));
+    const managedRuntimeRoots = parseStringArray(parsedEnvironment.data.REA_MANAGED_RUNTIME_ROOTS_JSON, "REA_MANAGED_RUNTIME_ROOTS_JSON");
+    if (!managedRuntimeRoots.ok)
+        return managedRuntimeRoots;
+    if (managedRuntimeRoots.value.some((root) => !isAbsolute(root)))
+        return err(new ConfigurationError("REA_MANAGED_RUNTIME_ROOTS_JSON must encode absolute roots"));
     const permissionCeilings = [
         ...(parsedEnvironment.data.REA_PROCESS_CAPTURE_ENABLED === "true"
             ? [
@@ -228,8 +285,36 @@ export const parseConfig = (environment) => {
         ...(parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true"
             ? [permissionScope("native_mount", [], { mount: true })]
             : []),
+        ...(parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_ENABLED === "true"
+            ? [
+                permissionScope("javascript_replay", javascriptReplayRoots.value, {
+                    executables: [
+                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_NODE_PATH,
+                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_BWRAP_PATH,
+                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH,
+                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH,
+                        parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SHELL_PATH,
+                    ],
+                    network: "none",
+                    mount: true,
+                }),
+            ]
+            : []),
+        ...(parsedEnvironment.data.REA_MANAGED_RUNTIME_ENABLED === "true"
+            ? [
+                permissionScope("managed_runtime", managedRuntimeRoots.value, {
+                    executables: [
+                        parsedEnvironment.data.REA_MANAGED_RUNTIME_EXECUTABLE_PATH,
+                    ],
+                    network: "none",
+                }),
+            ]
+            : []),
     ];
     return ok({
+        analysisProvider: parsedEnvironment.data.REA_ANALYSIS_PROVIDER,
+        ghidraInstallDir: parsedEnvironment.data.GHIDRA_INSTALL_DIR,
+        ghidraJavaHome: parsedEnvironment.data.JAVA_HOME,
         hopperLauncherPath: parsedEnvironment.data.HOPPER_LAUNCHER_PATH ??
             defaultHopperLauncherPath(),
         hopperTargetPath: parsedEnvironment.data.HOPPER_TARGET_PATH,
@@ -262,6 +347,20 @@ export const parseConfig = (environment) => {
         electronObservationEnabled: parsedEnvironment.data.REA_ELECTRON_OBSERVE_ENABLED === "true",
         electronCdpEndpoints: electronEndpoints.value,
         electronFileRoots: electronFileRoots.value,
+        javascriptReplayPolicy: {
+            enabled: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_ENABLED === "true",
+            roots: javascriptReplayRoots.value,
+            nodePath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_NODE_PATH,
+            bubblewrapPath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_BWRAP_PATH,
+            systemdRunPath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH,
+            systemctlPath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH,
+            shellPath: parsedEnvironment.data.REA_JAVASCRIPT_REPLAY_SHELL_PATH,
+        },
+        managedRuntimePolicy: {
+            enabled: parsedEnvironment.data.REA_MANAGED_RUNTIME_ENABLED === "true",
+            roots: managedRuntimeRoots.value,
+            executablePath: parsedEnvironment.data.REA_MANAGED_RUNTIME_EXECUTABLE_PATH,
+        },
         permissionCeilings,
         administratorPermissionGrants: administratorGrants(permissionCeilings),
         permissionProjectRoot: parsedEnvironment.data.REA_PERMISSION_PROJECT_ROOT,

package/dist/contracts/applicationToolContracts.js

@@ -0,0 +1,91 @@
+import { applicationVersionComparisonResultSchema, compareApplicationVersionsInputSchema, } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { applicationFeatureTraceResultSchema, traceApplicationFeatureInputSchema, } from "../domain/javascriptFeatureTraceSchemas.js";
+import { controlledReplayInputSchema, controlledReplayOutputSchema, } from "../domain/javascriptReplay.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemas.js";
+import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, } from "./javascriptApplicationWorkflowExamples.js";
+const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema);
+const comparisonOutputSchema = evidenceResultOf(applicationVersionComparisonResultSchema);
+/** Provider-neutral graph workflow contracts shared by MCP and CLI adapters. */
+export const APPLICATION_TOOL_CONTRACTS = [
+    {
+        name: "trace_application_feature",
+        ...toolContractMetadata("trace_application_feature"),
+        description: "Trace a typed literal seed through an authenticated JavaScript Application Graph with explicit direction, depth, node, edge, and path bounds. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
+        kind: "application",
+        inputSchema: traceApplicationFeatureInputSchema,
+        outputSchema: traceOutputSchema,
+        examples: [
+            {
+                title: "Trace one module seed through a retained application graph",
+                input: JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+            },
+        ],
+    },
+    {
+        name: "compare_application_versions",
+        ...toolContractMetadata("compare_application_versions"),
+        description: "Compare two authenticated JavaScript Application Graph versions using unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus a bounded changed_from graph without fuzzy or module-ordinal pairing.",
+        kind: "application",
+        inputSchema: compareApplicationVersionsInputSchema,
+        outputSchema: comparisonOutputSchema,
+        examples: [
+            {
+                title: "Compare authenticated static and reconciled application graphs",
+                input: JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
+            },
+        ],
+    },
+    {
+        name: "run_controlled_replay",
+        ...toolContractMetadata("run_controlled_replay"),
+        description: "Plan or execute a content-bound extracted-module JavaScript replay inside the Linux Bubblewrap, seccomp, and cgroup boundary. Execution requires approved: true and the exact plan digest. Supports deterministic boundary cases and optional left/right differential comparison; observations have controlled-replay authority and do not claim real application runtime behavior.",
+        kind: "application",
+        inputSchema: controlledReplayInputSchema,
+        outputSchema: controlledReplayOutputSchema,
+        examples: [
+            {
+                title: "Plan one extracted ESM parser replay",
+                input: {
+                    mode: "plan",
+                    left: {
+                        modules: [
+                            {
+                                alias: "parser",
+                                path: "/approved/parser.mjs",
+                                format: "esm",
+                                role: "module",
+                                dependencies: {},
+                            },
+                        ],
+                        entry_alias: "parser",
+                        entry_export: "default",
+                    },
+                    cases: [{ case_id: "empty", arguments: [""] }],
+                    determinism: {
+                        clock_iso: "2000-01-01T00:00:00.000Z",
+                        random_seed: 0,
+                        locale: "en-US",
+                        timezone: "UTC",
+                        platform: "linux",
+                    },
+                    limits: {
+                        wall_time_ms: 3000,
+                        memory_bytes: 134217728,
+                        tasks: 8,
+                        cpu_quota_percent: 50,
+                        tmpfs_bytes: 16777216,
+                        module_bytes: 4194304,
+                        input_bytes: 262144,
+                        protocol_bytes: 16777216,
+                        output_bytes: 524288,
+                        stderr_bytes: 32768,
+                        result_depth: 16,
+                        result_nodes: 10000,
+                    },
+                    approved: false,
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/artifactToolContracts.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { artifactOutputSchemas } from "./toolOutputSchemas.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
+import { toolContractMetadata } from "./toolEffects.js";
 const pageInput = {
     node_offset: z.number().int().min(0).default(0),
     node_limit: z.number().int().min(1).max(500).default(100),
@@ -67,22 +68,17 @@ const examples = {
         occurrence_ids: [`occ_${"0".repeat(64)}`],
     },
 };
-const artifact = (name, description, inputSchema, mutatesFilesystem) => {
+const artifact = (name, description, inputSchema) => {
     const outputSchema = artifactOutputSchemas[name];
     if (outputSchema === undefined)
         throw new Error(`Missing artifact output schema for ${name}`);
     return {
         name,
+        ...toolContractMetadata(name),
         description,
         kind: "artifact-provider",
         inputSchema,
         outputSchema,
-        annotations: {
-            readOnlyHint: !mutatesFilesystem,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
         examples: [
             {
                 title: `Example ${name.replaceAll("_", " ")} request`,
@@ -93,6 +89,6 @@ const artifact = (name, description, inputSchema, mutatesFilesystem) => {
 };
 /** Artifact-graph inventory and explicitly approved safe extraction contracts. */
 export const ARTIFACT_TOOL_CONTRACTS = [
-    artifact("inventory_artifact", "Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.", artifactInventoryInputSchema, false),
-    artifact("extract_artifact", "Extract selected graph artifacts beneath an explicit output root. Requires approval, rejects traversal and symlink escapes, never overwrites, enforces bomb limits, and verifies cleanup.", artifactExtractionInputSchema, true),
+    artifact("inventory_artifact", "Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.", artifactInventoryInputSchema),
+    artifact("extract_artifact", "Extract selected graph artifacts beneath an explicit output root. Requires approval, rejects traversal and symlink escapes, never overwrites, enforces bomb limits, and verifies cleanup.", artifactExtractionInputSchema),
 ];

package/dist/contracts/browserToolContracts.js

@@ -1,24 +1,16 @@
-import { z } from "zod";
-import { evidenceSchema } from "../domain/evidence.js";
 import { browserTargetListSchema, inspectWebPageInputSchema, listBrowserTargetsInputSchema, webPageInspectionSchema, } from "../domain/browserObservation.js";
 import { analyzeWebBundleInputSchema, webBundleAnalysisSchema, } from "../domain/webBundleAnalysis.js";
 import { observeWebSessionInputSchema, webObservationSessionSchema, } from "../domain/browserSession.js";
 import { discoverWebMcpToolsInputSchema, webMcpDiscoverySchema, } from "../domain/webMcpDiscovery.js";
 import { compareWebCapturesInputSchema, webCaptureDiffSchema, } from "../domain/webCaptureDiff.js";
 import { captureWebScreenshotInputSchema, compareWebScreenshotsInputSchema, webScreenshotDiffSchema, webScreenshotSchema, } from "../domain/webScreenshot.js";
-const evidenceResult = (schema) => evidenceSchema
-    .omit({ normalized_result: true })
-    .extend({ normalized_result: schema });
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemas.js";
+const evidenceResult = evidenceResultOf;
 const listOutputSchema = evidenceResult(browserTargetListSchema);
-const inspectionOutputSchema = evidenceSchema
-    .omit({ normalized_result: true })
-    .extend({ normalized_result: webPageInspectionSchema });
-const bundleOutputSchema = evidenceSchema
-    .omit({ normalized_result: true })
-    .extend({ normalized_result: webBundleAnalysisSchema });
-const observationSessionOutputSchema = evidenceSchema
-    .omit({ normalized_result: true })
-    .extend({ normalized_result: webObservationSessionSchema });
+const inspectionOutputSchema = evidenceResult(webPageInspectionSchema);
+const bundleOutputSchema = evidenceResult(webBundleAnalysisSchema);
+const observationSessionOutputSchema = evidenceResult(webObservationSessionSchema);
 const webMcpOutputSchema = evidenceResult(webMcpDiscoverySchema);
 const captureDiffOutputSchema = evidenceResult(webCaptureDiffSchema);
 const screenshotOutputSchema = evidenceResult(webScreenshotSchema);
@@ -29,16 +21,11 @@ const origin = "https://app.example.test";
 export const BROWSER_TOOL_CONTRACTS = [
     {
         name: "list_browser_targets",
+        ...toolContractMetadata("list_browser_targets"),
         description: "List bounded page targets from an approved user-owned loopback Chrome DevTools Protocol endpoint. Only targets whose current URL matches an approved exact origin are returned; URL credentials, query values, and fragments are redacted.",
         kind: "browser-provider",
         inputSchema: listBrowserTargetsInputSchema,
         outputSchema: listOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
         examples: [
             {
                 title: "List approved browser page targets",
@@ -54,16 +41,11 @@ export const BROWSER_TOOL_CONTRACTS = [
     },
     {
         name: "inspect_web_page",
+        ...toolContractMetadata("inspect_web_page"),
         description: "Passively inspect one approved page target through CDP without evaluating JavaScript, navigating, clicking, closing, or mutating the page. Returns bounded DOM structure, accessibility, scripts, resources, attach-window network and console metadata, workers, and redacted storage inventory as Evidence v2.",
         kind: "browser-provider",
         inputSchema: inspectWebPageInputSchema,
         outputSchema: inspectionOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
         examples: [
             {
                 title: "Inspect one approved browser page",
@@ -112,16 +94,11 @@ export const BROWSER_TOOL_CONTRACTS = [
     },
     {
         name: "analyze_web_bundle",
+        ...toolContractMetadata("analyze_web_bundle"),
         description: "Capture explicitly approved JavaScript source from one approved CDP page and statically derive a bounded chunk graph, route and endpoint candidates, vendor fingerprints, page-declared WebMCP metadata, and optional separately approved source-map evidence. JavaScript is parsed but never executed.",
         kind: "browser-provider",
         inputSchema: analyzeWebBundleInputSchema,
         outputSchema: bundleOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
         examples: [
             {
                 title: "Analyze an approved page bundle",
@@ -152,16 +129,11 @@ export const BROWSER_TOOL_CONTRACTS = [
     },
     {
         name: "observe_web_session",
+        ...toolContractMetadata("observe_web_session"),
         description: "Arm a bounded CDP observation window while the user operates the page. Allows approved same-origin reload and SPA navigation, records ordered navigation, redirect, lifecycle, and failure metadata, and stops before retaining an out-of-policy destination.",
         kind: "browser-provider",
         inputSchema: observeWebSessionInputSchema,
         outputSchema: observationSessionOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
         examples: [
             {
                 title: "Observe one external user action",
@@ -178,16 +150,11 @@ export const BROWSER_TOOL_CONTRACTS = [
     },
     {
         name: "discover_webmcp_tools",
+        ...toolContractMetadata("discover_webmcp_tools"),
         description: "Passively inventory page-registered WebMCP tools using the experimental CDP WebMCP domain. Metadata is bounded and page-declared-untrusted; REA never registers or invokes discovered tools.",
         kind: "browser-provider",
         inputSchema: discoverWebMcpToolsInputSchema,
         outputSchema: webMcpOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
         examples: [
             {
                 title: "Discover current WebMCP declarations",
@@ -207,16 +174,11 @@ export const BROWSER_TOOL_CONTRACTS = [
     },
     {
         name: "compare_web_captures",
+        ...toolContractMetadata("compare_web_captures"),
         description: "Compare two normalized web captures across DOM, scripts, resources, network, safe metadata, and optional WebMCP inventories. Stable observed changes are distinguished from unknown absence caused by incomplete capture coverage.",
         kind: "browser-provider",
         inputSchema: compareWebCapturesInputSchema,
         outputSchema: captureDiffOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
         examples: [
             {
                 title: "Compare two normalized captures",
@@ -230,16 +192,11 @@ export const BROWSER_TOOL_CONTRACTS = [
     },
     {
         name: "capture_web_screenshot",
+        ...toolContractMetadata("capture_web_screenshot"),
         description: "Capture the current visible viewport of one approved page as a bounded, content-addressed PNG artifact. Screenshot capture requires separate explicit approval and never scrolls, navigates, or evaluates page JavaScript.",
         kind: "browser-provider",
         inputSchema: captureWebScreenshotInputSchema,
         outputSchema: screenshotOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
         examples: [
             {
                 title: "Capture an approved viewport",
@@ -256,16 +213,11 @@ export const BROWSER_TOOL_CONTRACTS = [
     },
     {
         name: "compare_web_screenshots",
+        ...toolContractMetadata("compare_web_screenshots"),
         description: "Compare two self-verifying PNG screenshot artifacts with bounded local pixel metrics. Returns exact changed-pixel ratios and channel deltas without OCR or external services.",
         kind: "browser-provider",
         inputSchema: compareWebScreenshotsInputSchema,
         outputSchema: screenshotDiffOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
         examples: [
             {
                 title: "Compare two screenshot artifacts",

package/dist/contracts/electronToolContracts.js

@@ -1,27 +1,24 @@
-import { evidenceSchema } from "../domain/evidence.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemas.js";
 import { electronPageInspectionSchema, electronTargetListSchema, inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../domain/electronObservation.js";
-const listOutputSchema = evidenceSchema
-    .omit({ normalized_result: true })
-    .extend({ normalized_result: electronTargetListSchema });
-const inspectionOutputSchema = evidenceSchema
-    .omit({ normalized_result: true })
-    .extend({ normalized_result: electronPageInspectionSchema });
+import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../domain/javascriptApplicationAnalysis.js";
+import { javascriptRuntimeReconciliationResultSchema, reconcileJavaScriptRuntimeInputSchema, } from "../domain/javascriptRuntimeReconciliationSchemas.js";
+import { JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE } from "./javascriptRuntimeReconciliationExample.js";
+const listOutputSchema = evidenceResultOf(electronTargetListSchema);
+const inspectionOutputSchema = evidenceResultOf(electronPageInspectionSchema);
+const applicationOutputSchema = evidenceResultOf(javascriptApplicationAnalysisResultSchema);
+const reconciliationOutputSchema = evidenceResultOf(javascriptRuntimeReconciliationResultSchema);
 const endpoint = "http://127.0.0.1:9223";
 const root = "/Applications/Example.app/Contents/Resources";
 /** Root-confined Electron file-page discovery and inspection contracts. */
 export const ELECTRON_TOOL_CONTRACTS = [
     {
         name: "list_electron_targets",
+        ...toolContractMetadata("list_electron_targets"),
         description: "List Electron file:// page targets from an approved user-owned loopback CDP endpoint. Every path is canonicalized and must remain contained by an approved filesystem root, including after symlink resolution.",
         kind: "electron-provider",
         inputSchema: listElectronTargetsInputSchema,
         outputSchema: listOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
         examples: [
             {
                 title: "List approved Electron file pages",
@@ -37,16 +34,11 @@ export const ELECTRON_TOOL_CONTRACTS = [
     },
     {
         name: "inspect_electron_page",
+        ...toolContractMetadata("inspect_electron_page"),
         description: "Passively inspect one approved Electron file page through CDP. Returns root-confined frames, DOM structure, resource paths, and scripts without evaluating renderer JavaScript or invoking Electron APIs; script contents require separate approval.",
         kind: "electron-provider",
         inputSchema: inspectElectronPageInputSchema,
         outputSchema: inspectionOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
         examples: [
             {
                 title: "Inspect an approved Electron page",
@@ -63,6 +55,7 @@ export const ELECTRON_TOOL_CONTRACTS = [
                         max_dom_nodes: 2_000,
                         max_scripts: 500,
                         max_resources: 2_000,
+                        max_workers: 500,
                         max_script_source_bytes: 1_048_576,
                         max_total_script_source_bytes: 4_194_304,
                     },
@@ -70,4 +63,37 @@ export const ELECTRON_TOOL_CONTRACTS = [
             },
         ],
     },
+    {
+        name: "analyze_javascript_application",
+        ...toolContractMetadata("analyze_javascript_application"),
+        description: "Statically reconstruct one approved local ASAR or extracted JavaScript application as Evidence v2 and JavaScript Application Graph v1. Maps BrowserWindow preferences, preload and contextBridge APIs, literal and dynamic IPC, handler locations, sender-validation observations, utility processes, and requested native addon bindings without executing JavaScript; source-map contents require separate approval.",
+        kind: "electron-provider",
+        inputSchema: analyzeJavaScriptApplicationInputSchema,
+        outputSchema: applicationOutputSchema,
+        examples: [
+            {
+                title: "Analyze one approved local Electron application",
+                input: {
+                    input_path: "/Applications/Example.app/Contents/Resources/app.asar",
+                    format: "auto",
+                    approved: true,
+                    source_map_read_approved: false,
+                },
+            },
+        ],
+    },
+    {
+        name: "reconcile_javascript_runtime",
+        ...toolContractMetadata("reconcile_javascript_runtime"),
+        description: "Reconcile verified static JavaScript application graphs with existing passive web or Electron CDP Evidence. Exact captured-source digests take priority over caller-declared file/URL mappings; target, frame, script, and worker ambiguity remains explicit, and source-map authority stays separate.",
+        kind: "electron-provider",
+        inputSchema: reconcileJavaScriptRuntimeInputSchema,
+        outputSchema: reconciliationOutputSchema,
+        examples: [
+            {
+                title: "Reconcile one passive Electron capture",
+                input: JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE,
+            },
+        ],
+    },
 ];

package/dist/contracts/enhancedInputs.js

@@ -6,12 +6,12 @@ export const enhancedInputSchemas = {
     get_objc_protocols: z.object({}),
     batch_decompile: z.object({
         addresses: z
-            .array(z.string().describe("A Hopper address"))
+            .array(z.string().describe("A provider-normalized procedure address"))
             .max(20)
             .default([]),
     }),
     get_call_graph: z.object({
-        address: z.string().describe("A Hopper address"),
+        address: z.string().describe("A provider-normalized procedure address"),
         direction: z.enum(["forward", "backward"]).default("forward"),
         depth: z.number().int().min(1).max(5).default(2),
     }),

package/dist/contracts/errorSchemas.js

@@ -95,6 +95,7 @@ export const analysisErrorProjectionSchema = z.discriminatedUnion("code", [
     generic("configuration_invalid"),
     generic("target_unavailable"),
     generic("execution_failure"),
+    generic("plan_stale"),
 ]);
 /** JSON Schema document used by generated API documentation and clients. */
 export const analysisErrorJsonSchema = z.toJSONSchema(analysisErrorProjectionSchema);

package/dist/contracts/investigationExamples.js

@@ -1,7 +1,6 @@
 import { compareFunctions } from "../domain/functionComparison.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-import { createEvidenceBundle } from "../domain/evidenceBundle.js";
 import { compareProcessCaptures, processCaptureSchema, } from "../domain/processCapture.js";
 import { FUNCTION_COMPARISON_EXAMPLE } from "./functionComparisonExample.js";
 import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
@@ -109,10 +108,5 @@ export const INVESTIGATION_EXAMPLES = {
                 },
             ],
         },
-        evidence_bundle: createEvidenceBundle([
-            PROCESS_CAPTURE_REFERENCE,
-            PROCESS_CAPTURE_RECONSTRUCTION,
-            PROCESS_COMPARISON_EVIDENCE,
-        ]),
     },
 };

package/dist/contracts/javascriptApplicationWorkflowExamples.js

@@ -0,0 +1,46 @@
+import { createEvidence } from "../domain/evidence.js";
+import { reconcileJavaScriptRuntime } from "../domain/javascriptRuntimeReconciliation.js";
+import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE, JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE, } from "./javascriptRuntimeReconciliationExample.js";
+const reconciliation = reconcileJavaScriptRuntime(JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE);
+const reconciliationEvidence = createEvidence(undefined, {
+    id: "rea-javascript-runtime-reconciliation",
+    name: "REA JavaScript runtime reconciliation",
+    version: "1",
+}, {
+    predicateType: "rea.javascript-runtime-reconciliation/v1",
+    operation: "reconcile_javascript_runtime",
+    parameters: {
+        static_layers: JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.static_layers.map(({ role, analysis }) => ({
+            role,
+            evidence_id: analysis.evidence_id,
+            runtime_mappings: [],
+        })),
+        runtime_evidence_ids: JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.runtime_observations.map(({ evidence_id: id }) => id),
+        limits: {
+            max_runtime_entities: 10_000,
+            max_reconciliation_items: 20_000,
+            max_static_load_states: 20_000,
+        },
+    },
+    result: reconciliation,
+    confidence: "inferred",
+    authority: "analyst-inference",
+    limitations: reconciliation.limitations,
+    evidenceLinks: reconciliation.evidence_links,
+});
+/** Valid public trace request without proprietary artifacts. */
+export const JAVASCRIPT_FEATURE_TRACE_EXAMPLE = {
+    application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+    seed: {
+        kind: "module",
+        value: "renderer.js",
+        match: "exact",
+        case_sensitive: false,
+    },
+    direction: "both",
+};
+/** Valid static/runtime graph pair demonstrating comparison authority. */
+export const JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE = {
+    left: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+    right: reconciliationEvidence,
+};