rea-agents 1.7.0 → 2.1.0

package/dist/contracts/browserToolContracts.js

@@ -1,24 +1,16 @@
-import { z } from "zod";
-import { evidenceEnvelopeSchema } 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) => evidenceEnvelopeSchema
-    .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 = evidenceEnvelopeSchema
-    .omit({ normalized_result: true })
-    .extend({ normalized_result: webPageInspectionSchema });
-const bundleOutputSchema = evidenceEnvelopeSchema
-    .omit({ normalized_result: true })
-    .extend({ normalized_result: webBundleAnalysisSchema });
-const observationSessionOutputSchema = evidenceEnvelopeSchema
-    .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 { evidenceEnvelopeSchema } 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 = evidenceEnvelopeSchema
-    .omit({ normalized_result: true })
-    .extend({ normalized_result: electronTargetListSchema });
-const inspectionOutputSchema = evidenceEnvelopeSchema
-    .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/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,
+};

package/dist/contracts/javascriptRuntimeReconciliationExample.js

@@ -0,0 +1,208 @@
+import { createEvidence } from "../domain/evidence.js";
+import { createJavaScriptApplicationGraph, createJavaScriptApplicationNode, } from "../domain/javascriptApplicationGraph.js";
+import { createWebTextArtifact } from "../domain/webContentArtifact.js";
+const applicationSha256 = "1".repeat(64);
+const script = createWebTextArtifact("export const example = true;\n", "text/javascript");
+const inputPath = "/Applications/Example.app/Contents/Resources/app";
+const scriptPath = `${inputPath}/renderer.js`;
+const completeCoverage = {
+    status: "complete",
+    truncated: false,
+    omitted_count: 0,
+    limits: [],
+};
+const graphEvidence = {
+    authority: "artifact-bytes",
+    state: "observed",
+    confidence: "exact",
+    artifact: {
+        available: true,
+        artifact_id: `art_${script.sha256}`,
+        sha256: script.sha256,
+    },
+    location: {
+        available: true,
+        value: { kind: "artifact-path", path: "renderer.js" },
+    },
+    extractor: {
+        name: "rea-javascript-application",
+        version: "1",
+        operation: "inventory-relevant-file",
+        executable_sha256: null,
+    },
+    coverage: completeCoverage,
+    limitations: [],
+    evidence_ids: [],
+};
+const asset = createJavaScriptApplicationNode({
+    kind: "javascript-asset",
+    identity: {
+        strategy: "content-digest",
+        stability: "global-exact",
+        sha256: script.sha256,
+    },
+    observations: [
+        {
+            label: "renderer.js",
+            properties: { path: "renderer.js", bytes: script.bytes },
+            evidence: graphEvidence,
+        },
+    ],
+});
+const graph = createJavaScriptApplicationGraph({
+    schema: "JavaScriptApplicationGraph",
+    schema_version: 1,
+    root_node_ids: [asset.node_id],
+    nodes: [asset],
+    edges: [],
+    coverage: completeCoverage,
+    limitations: [],
+});
+const staticEvidence = createEvidence({ path: inputPath, sha256: applicationSha256, format: "directory" }, {
+    id: "rea-javascript-application",
+    name: "REA JavaScript application analyzer",
+    version: "1",
+}, {
+    predicateType: "rea.javascript-application-analysis/v1",
+    operation: "analyze_javascript_application",
+    parameters: { approved: true, source_map_read_approved: false },
+    result: {
+        schema_version: 1,
+        input_path: inputPath,
+        format: "directory",
+        root_artifact_sha256: applicationSha256,
+        inventory_manifest_id: `agm_${"2".repeat(64)}`,
+        inventory_graph_sha256: "3".repeat(64),
+        graph,
+        summary: {
+            browser_windows: 0,
+            explicit_web_preferences: 0,
+            preload_entrypoints: 0,
+            context_bridge_apis: 0,
+            exposed_api_members: 0,
+            ipc: {
+                operations: 0,
+                literal_channels: 0,
+                dynamic_channel_operations: 0,
+                renderer_transmissions: 0,
+                renderer_listeners: 0,
+                main_handlers: 0,
+                paired_renderer_transmissions: 0,
+                ambiguous_renderer_transmissions: 0,
+                unpaired_literal_renderer_transmissions: 0,
+            },
+            sender_validation_observations: 0,
+            utility_processes: 0,
+            resolved_utility_entrypoints: 0,
+            native_addon_bindings: 0,
+            resolved_native_addon_bindings: 0,
+        },
+        statistics: {
+            relevant_files: 1,
+            nested_asar_containers: 0,
+            text_files_selected: 1,
+            text_bytes_read: script.bytes,
+            omitted_text_files: 0,
+            limit_omitted_text_files: 0,
+            policy_filtered_text_files: 0,
+            invalid_utf8_files: 0,
+            parsed_javascript_files: 1,
+            visited_ast_nodes: 1,
+            findings: 0,
+            modules: 0,
+            parse_failures: 0,
+            truncated_scopes: 0,
+        },
+        limitations: [],
+    },
+    confidence: "derived",
+    authority: "shipped-artifact",
+});
+/** Minimal valid static application Evidence for graph workflow examples. */
+export const JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE = staticEvidence;
+const runtimeEvidence = createEvidence(undefined, {
+    id: "rea-cdp-electron",
+    name: "REA Electron file-page CDP observation provider",
+    version: "1",
+}, {
+    predicateType: "rea.electron-page-inspection/v1",
+    operation: "inspect_electron_page",
+    parameters: {
+        cdp_endpoint: "http://127.0.0.1:9223",
+        allowed_file_roots: [inputPath],
+        target_id: "example-target",
+        include_script_sources: true,
+        source_capture_approved: true,
+    },
+    result: {
+        schema_version: 1,
+        browser: {
+            product: "Electron/example",
+            protocol_version: "1.3",
+            revision: "example",
+            user_agent: "Electron example",
+            js_version: "1",
+        },
+        target: {
+            target_id: "example-target",
+            type: "page",
+            title: "Example",
+            file_path: `${inputPath}/index.html`,
+            attached: false,
+        },
+        capture_window: {
+            started_at: "2026-07-15T00:00:00.000Z",
+            ended_at: "2026-07-15T00:00:00.100Z",
+            observation_ms: 100,
+        },
+        completeness: browserCompleteness(),
+        frames: [],
+        dom: { total_nodes: 0, nodes: [] },
+        scripts: {
+            total: 1,
+            items: [
+                {
+                    script_key: `electron_script_${"4".repeat(64)}`,
+                    frame_id: null,
+                    file_path: scriptPath,
+                    cdp_hash: "example",
+                    length: script.bytes,
+                    is_module: true,
+                    language: "JavaScript",
+                    source: { included: true, artifact: script },
+                },
+            ],
+        },
+        resources: [],
+        workers: [],
+        limitations: ["Example passive capture."],
+    },
+    confidence: "observed",
+    authority: "external-service",
+});
+/** Compact valid Evidence pair used by the public reconciliation contract. */
+export const JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE = {
+    static_layers: [{ role: "application", analysis: staticEvidence }],
+    runtime_observations: [runtimeEvidence],
+};
+function browserCompleteness() {
+    return {
+        status: "complete_within_window",
+        conditions: ["complete_within_window"],
+        policy_filtered_sections: [],
+        attach_limited_sections: [],
+        truncated_sections: [],
+        unavailable_sections: [],
+        excluded: [],
+        dropped_events: {
+            scripts: 0,
+            network_requests: 0,
+            console_events: 0,
+            websocket_connections: 0,
+            websocket_frames: 0,
+            webmcp_tools: 0,
+            timeline_events: 0,
+            total: 0,
+        },
+    };
+}