rea-agents 2.5.0 → 3.1.0

package/dist/domain/hopperValues.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { AnalysisOutputError, HopperProtocolError } from "./errors.js";
 import { err, ok } from "./result.js";
+import { nativeApiBoundarySchema } from "./nativeApiBoundary.js";
 /** Return a bounded byte distance between canonical addresses in one space. */
 export const addressDistance = (start, end) => {
     const left = addressCoordinate(start);
@@ -33,31 +34,24 @@ const segmentSchema = z.object({
     writable: z.boolean().nullable().default(null),
     executable: z.boolean().nullable().default(null),
 });
-const addressedPageSchema = z
-    .object({
+const addressedPageFacts = {
     items: z.array(z.object({ address: z.string(), value: z.string() })),
     offset: z.number().int().min(0),
     limit: z.number().int().min(1),
     total: z.number().int().min(0),
-    next_offset: z.number().int().min(0).nullable(),
-    has_more: z.boolean(),
-})
-    .superRefine((value, context) => {
-    if (value.has_more && value.next_offset === null) {
-        context.addIssue({
-            code: "custom",
-            message: "a page with more results must provide next_offset",
-            path: ["next_offset"],
-        });
-    }
-    if (!value.has_more && value.next_offset !== null) {
-        context.addIssue({
-            code: "custom",
-            message: "a complete page must not provide next_offset",
-            path: ["next_offset"],
-        });
-    }
-});
+};
+const addressedPageSchema = z.discriminatedUnion("has_more", [
+    z.object({
+        ...addressedPageFacts,
+        has_more: z.literal(true),
+        next_offset: z.number().int().min(0),
+    }),
+    z.object({
+        ...addressedPageFacts,
+        has_more: z.literal(false),
+        next_offset: z.null(),
+    }),
+]);
 const unavailableAnalysisFactSchema = z
     .object({ available: z.literal(false), reason: z.string() })
     .strict();
@@ -82,38 +76,42 @@ export const localVariableSchema = z
     provenance: z.string().min(1),
 })
     .strict();
-const boundedSchema = (item) => z
-    .object({
-    items: z.array(item),
-    total: z.number().int().min(0).nullable(),
-    returned: z.number().int().min(0),
-    truncated: z.boolean(),
-    next_offset: z.number().int().min(0).nullable(),
-})
-    .strict()
-    .superRefine((value, context) => {
-    if (value.returned !== value.items.length) {
-        context.addIssue({
-            code: "custom",
-            message: "returned must equal the number of items",
-            path: ["returned"],
-        });
-    }
-    if (value.total !== null && value.total < value.returned) {
-        context.addIssue({
-            code: "custom",
-            message: "total cannot be smaller than returned",
-            path: ["total"],
-        });
-    }
-    if (value.next_offset !== null && !value.truncated) {
-        context.addIssue({
-            code: "custom",
-            message: "a continuation requires truncated output",
-            path: ["next_offset"],
-        });
-    }
-});
+const boundedSchema = (item) => {
+    const boundedFacts = {
+        items: z.array(item),
+        total: z.number().int().min(0).nullable(),
+        returned: z.number().int().min(0),
+    };
+    return z
+        .discriminatedUnion("truncated", [
+        z.strictObject({
+            ...boundedFacts,
+            truncated: z.literal(false),
+            next_offset: z.null(),
+        }),
+        z.strictObject({
+            ...boundedFacts,
+            truncated: z.literal(true),
+            next_offset: z.number().int().min(0).nullable(),
+        }),
+    ])
+        .superRefine((value, context) => {
+        if (value.returned !== value.items.length) {
+            context.addIssue({
+                code: "custom",
+                message: "returned must equal the number of items",
+                path: ["returned"],
+            });
+        }
+        if (value.total !== null && value.total < value.returned) {
+            context.addIssue({
+                code: "custom",
+                message: "total cannot be smaller than returned",
+                path: ["total"],
+            });
+        }
+    });
+};
 /** Provider-neutral bounded raw-instruction window for one analyzed function. */
 export const functionInstructionWindowSchema = z
     .object({
@@ -169,14 +167,22 @@ export const functionDossierSchema = z
     })
         .strict(),
     pseudocode: z
-        .object({
-        text: z.string(),
-        total_chars: z.number().int().min(0),
-        returned_chars: z.number().int().min(0),
-        truncated: z.boolean(),
-        next_offset: z.number().int().min(0).nullable(),
-    })
-        .strict()
+        .discriminatedUnion("truncated", [
+        z.strictObject({
+            text: z.string(),
+            total_chars: z.number().int().min(0),
+            returned_chars: z.number().int().min(0),
+            truncated: z.literal(false),
+            next_offset: z.null(),
+        }),
+        z.strictObject({
+            text: z.string(),
+            total_chars: z.number().int().min(0),
+            returned_chars: z.number().int().min(0),
+            truncated: z.literal(true),
+            next_offset: z.number().int().min(0).nullable(),
+        }),
+    ])
         .superRefine((value, context) => {
         if (value.returned_chars !== [...value.text].length) {
             context.addIssue({
@@ -192,13 +198,6 @@ export const functionDossierSchema = z
                 path: ["total_chars"],
             });
         }
-        if (value.next_offset !== null && !value.truncated) {
-            context.addIssue({
-                code: "custom",
-                message: "a continuation requires truncated pseudocode",
-                path: ["next_offset"],
-            });
-        }
     }),
     assembly: boundedSchema(z.string()),
     comments: boundedSchema(z
@@ -236,6 +235,7 @@ export const functionDossierSchema = z
     instruction_scan: z
         .object({ scanned: z.number().int().min(0), truncated: z.boolean() })
         .strict(),
+    native_api: nativeApiBoundarySchema.nullable().default(null),
     limitations: z.array(z.string()).default([]),
 })
     .strict();

package/dist/domain/inputIssueProjection.js

@@ -2,6 +2,8 @@
 export const projectInputIssues = (issues, input) => issues.flatMap((issue) => projectIssue(issue, input));
 const projectIssue = (issue, input) => {
     const path = issue.path.flatMap((part) => typeof part === "string" || typeof part === "number" ? [part] : []);
+    if (issue.code === "invalid_union")
+        return issue.errors.flatMap((branch) => branch.flatMap((branchIssue) => projectIssue(branchIssue, input)));
     if (issue.code === "unrecognized_keys")
         return issue.keys.map((key) => ({
             path: [...path, key],
@@ -31,14 +33,21 @@ const projectIssue = (issue, input) => {
                 expected: issue.values.filter(isSafeExpected),
             },
         ];
-    return [{ path, reason: "invalid_value" }];
+    return [
+        {
+            path,
+            reason: "invalid_value",
+            ...(issue.message.length > 0 ? { message: issue.message } : {}),
+        },
+    ];
 };
 const valueAtPath = (input, path) => {
     let current = input;
     for (const part of path) {
         if (typeof current !== "object" || current === null)
             return undefined;
-        current = current[part];
+        const next = Reflect.get(current, part);
+        current = next;
     }
     return current;
 };

package/dist/domain/investigationWorkspace.js

@@ -37,8 +37,7 @@ const DEFAULT_INVESTIGATION_RUN_OPTIONS = {
     change_limit: 500,
 };
 /** Explicit write approval and two local versions for an automatic run. */
-export const crossVersionInvestigationInputSchema = z
-    .object({
+const crossVersionInvestigationFacts = {
     approved: z.literal(true),
     workspace_path: z.string().min(1).max(4_096),
     workspace_name: z.string().trim().min(1).max(200).default("default"),
@@ -49,20 +48,22 @@ export const crossVersionInvestigationInputSchema = z
         .optional(),
     left_path: z.string().min(1).max(4_096),
     right_path: z.string().min(1).max(4_096),
-    integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"),
-    integrity_continue_approved: z.boolean().default(false),
-    max_integrity_mismatches: z.number().int().min(1).max(100).default(10),
     options: investigationRunOptionsSchema.default(DEFAULT_INVESTIGATION_RUN_OPTIONS),
-})
-    .superRefine((input, context) => {
-    if (input.integrity_policy === "record-and-continue" &&
-        input.integrity_continue_approved !== true)
-        context.addIssue({
-            code: "custom",
-            path: ["integrity_continue_approved"],
-            message: "record-and-continue requires explicit approval",
-        });
-});
+};
+export const crossVersionInvestigationInputSchema = z.union([
+    z.object({
+        ...crossVersionInvestigationFacts,
+        integrity_policy: z.literal("fail").default("fail"),
+        integrity_continue_approved: z.literal(false).default(false),
+        max_integrity_mismatches: z.number().int().min(1).max(100).default(10),
+    }),
+    z.object({
+        ...crossVersionInvestigationFacts,
+        integrity_policy: z.literal("record-and-continue"),
+        integrity_continue_approved: z.literal(true),
+        max_integrity_mismatches: z.number().int().min(1).max(100).default(10),
+    }),
+]);
 const targetSchema = z.object({
     root_sha256: digestSchema,
     graph_sha256: digestSchema,

package/dist/domain/javascriptExportShapeComparisonSchemas.js

@@ -223,7 +223,7 @@ const comparisonChangeSchema = z.strictObject({
     right: valueAvailabilitySchema,
     left_source_range: sourceRangeSchema.nullable(),
     right_source_range: sourceRangeSchema.nullable(),
-    evidence_links: z.tuple([evidenceIdSchema, evidenceIdSchema]),
+    evidence_links: z.array(evidenceIdSchema).length(2),
     limitations: z.array(boundedTextSchema).max(20),
 });
 /** Bounded static export-return comparison with explicit unknown semantics. */
@@ -267,7 +267,7 @@ export const javaScriptExportShapeComparisonResultSchema = z.strictObject({
         omitted_candidates: z.number().int().min(0),
         omitted_changes: z.number().int().min(0),
     }),
-    evidence_links: z.tuple([evidenceIdSchema, evidenceIdSchema]),
+    evidence_links: z.array(evidenceIdSchema).length(2),
     limitations: z.array(boundedTextSchema).max(1_000),
     runtime_validation: z.strictObject({
         recommended_tool: z.literal("run_controlled_replay"),

package/dist/domain/javascriptReplay.js

@@ -105,9 +105,7 @@ const determinismSchema = z
     platform: z.literal("linux").default("linux"),
 })
     .strict();
-export const controlledReplayInputSchema = z
-    .object({
-    mode: z.enum(["plan", "execute"]),
+const controlledReplayInputShape = {
     left: replaySideSchema,
     right: replaySideSchema.optional(),
     cases: z.array(explicitCaseSchema).max(128).default([]),
@@ -133,18 +131,32 @@ export const controlledReplayInputSchema = z
         result_depth: 16,
         result_nodes: 10_000,
     }),
-    approved: z.boolean().default(false),
-    plan_digest: digestSchema.optional(),
     reproducer_export: z
-        .object({
+        .strictObject({
         path: absolutePathSchema,
-        approved: z.boolean(),
+        approved: z.literal(true),
         include_sources: z.boolean().default(false),
     })
-        .strict()
         .optional(),
-})
-    .strict()
+};
+/** Parse a replay request that can only construct a plan. */
+export const controlledReplayPlanInputSchema = z.strictObject({
+    ...controlledReplayInputShape,
+    mode: z.literal("plan"),
+});
+/** Parse a replay request carrying literal approval for one exact plan. */
+export const controlledReplayExecutionInputSchema = z.strictObject({
+    ...controlledReplayInputShape,
+    mode: z.literal("execute"),
+    approved: z.literal(true),
+    plan_digest: digestSchema,
+});
+/** Parse a controlled replay request into its legal plan or execution state. */
+export const controlledReplayInputSchema = z
+    .discriminatedUnion("mode", [
+    controlledReplayPlanInputSchema,
+    controlledReplayExecutionInputSchema,
+])
     .superRefine((value, context) => {
     if (value.cases.length === 0 && value.generator === undefined)
         context.addIssue({
@@ -158,13 +170,6 @@ export const controlledReplayInputSchema = z
             path: ["generator", "count"],
             message: "Explicit and generated replay cases must total at most 128",
         });
-    if (value.mode === "execute" &&
-        (value.approved !== true || value.plan_digest === undefined))
-        context.addIssue({
-            code: "custom",
-            path: ["approved"],
-            message: "Execution requires literal approval and a plan digest",
-        });
 });
 const moduleCommitmentSchema = z
     .object({
@@ -201,7 +206,7 @@ const replayPlanSchema = z
     filesystem: z
         .object({
         host_writes: z.literal(false),
-        private_tmpfs_bytes: z.number().int(),
+        private_tmpfs_bytes: z.number().int().nonnegative(),
     })
         .strict(),
     runtime: z
@@ -255,34 +260,45 @@ const replayPlanSchema = z
         .nullable(),
 })
     .strict();
-const replayOutcomeSchema = z
-    .object({
+const replayOutcomeFacts = {
     case_id: z.string(),
-    outcome: z.enum([
-        "return",
-        "exception",
-        "serialization_error",
-        "denied",
-        "timeout",
-        "oom",
-        "crash",
-        "cancelled",
-        "protocol_error",
-    ]),
-    value: z.json().optional(),
-    exception: z
-        .object({
-        name: z.string(),
-        message: z.string(),
-        stack: z.string().nullable(),
-    })
-        .strict()
-        .optional(),
     input_sha256: digestSchema,
-    output_sha256: digestSchema.nullable(),
-    truncated: z.boolean(),
+};
+const replayExceptionSchema = z
+    .object({
+    name: z.string(),
+    message: z.string(),
+    stack: z.string().nullable(),
 })
     .strict();
+const replayOutcomeSchema = z.discriminatedUnion("outcome", [
+    z.strictObject({
+        ...replayOutcomeFacts,
+        outcome: z.literal("return"),
+        value: z.json(),
+        output_sha256: digestSchema,
+        truncated: z.literal(false),
+    }),
+    z.strictObject({
+        ...replayOutcomeFacts,
+        outcome: z.enum(["exception", "serialization_error", "denied"]),
+        exception: z.object(replayExceptionSchema.shape).strict(),
+        output_sha256: digestSchema,
+        truncated: z.literal(false),
+    }),
+    z.strictObject({
+        ...replayOutcomeFacts,
+        outcome: z.enum(["timeout", "oom", "crash", "cancelled"]),
+        output_sha256: z.null(),
+        truncated: z.literal(false),
+    }),
+    z.strictObject({
+        ...replayOutcomeFacts,
+        outcome: z.literal("protocol_error"),
+        output_sha256: z.null(),
+        truncated: z.literal(true),
+    }),
+]);
 export const replayExecutionResultSchema = z
     .object({
     schema_version: z.literal(1),
@@ -337,25 +353,25 @@ export const replayExecutionResultSchema = z
 export const replayEvidenceSchema = evidenceEnvelopeSchema
     .omit({ normalized_result: true })
     .extend({ normalized_result: replayExecutionResultSchema });
-export const controlledReplayOutputSchema = z
-    .object({
-    phase: z.enum(["plan", "execute"]),
-    plan: replayPlanSchema.nullable(),
-    source_evidence: z.array(replayEvidenceSchema),
-    evidence: replayEvidenceSchema.nullable(),
-})
-    .strict()
-    .superRefine((value, context) => {
-    if ((value.phase === "plan" &&
-        (value.plan === null ||
-            value.evidence !== null ||
-            value.source_evidence.length !== 0)) ||
-        (value.phase === "execute" &&
-            (value.plan !== null ||
-                value.evidence === null ||
-                value.source_evidence.length === 0)))
-        context.addIssue({
-            code: "custom",
-            message: "Replay output phase does not match its payload",
-        });
+/** A replay plan result with no claimed runtime observation. */
+export const controlledReplayPlanOutputSchema = z.strictObject({
+    phase: z.literal("plan"),
+    plan: replayPlanSchema,
+    source_evidence: z
+        .array(replayEvidenceSchema)
+        .length(0)
+        .brand(),
+    evidence: z.null(),
+});
+/** An executed replay result with its required source and aggregate Evidence. */
+export const controlledReplayExecutionOutputSchema = z.strictObject({
+    phase: z.literal("execute"),
+    plan: z.null(),
+    source_evidence: z.array(replayEvidenceSchema).min(1),
+    evidence: replayEvidenceSchema,
 });
+/** Parse replay output into its legal plan or execution state. */
+export const controlledReplayOutputSchema = z.discriminatedUnion("phase", [
+    controlledReplayPlanOutputSchema,
+    controlledReplayExecutionOutputSchema,
+]);

package/dist/domain/javascriptRuntimeObservation.js

@@ -83,6 +83,7 @@ export const javascriptRuntimeLocationSchema = z.discriminatedUnion("kind", [
     z.strictObject({
         kind: z.literal("file"),
         file_path: z.string().min(1).max(16_384),
+        authority: z.literal("scope-fallback").optional(),
     }),
     z.strictObject({
         kind: z.literal("url"),

package/dist/domain/javascriptRuntimeReconciliationActive.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, relative } from "node:path";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { classifyBrowserCompleteness, } from "./browserCompleteness.js";
+import { electronActiveObservationResultSchema, } from "./electronActiveObservation.js";
+/** Parse active Electron Evidence as a bounded, target-only runtime capture. */
+export const parseActiveElectronCapture = (evidence) => {
+    assertIdentity(evidence);
+    const result = electronActiveObservationResultSchema.parse(evidence.normalized_result);
+    const parameters = z
+        .object({
+        approved: z.literal(true),
+        application_path: absolutePathSchema,
+        application_root: absolutePathSchema,
+    })
+        .passthrough()
+        .parse(evidence.parameters);
+    if (result.application.application_path !== parameters.application_path ||
+        !isWithinRoot(parameters.application_root, result.application.application_path))
+        throw new TypeError("Active Electron Evidence application path disagrees with its approved root");
+    return {
+        kind: "electron-active",
+        evidence,
+        inspection: normalizeInspection(result),
+        captureSha256: digestCanonical(result),
+        scriptsCompleteWithinScope: false,
+    };
+};
+const absolutePathSchema = z.string().min(1).max(16_384).refine(isAbsolute);
+const assertIdentity = (evidence) => {
+    if (evidence.operation !== "capture_electron_scenario" ||
+        evidence.predicate_type !== "rea.electron-active-scenario/v1" ||
+        evidence.provider.id !== "rea-playwright-electron-active" ||
+        evidence.provider.name !==
+            "REA Playwright active Electron observation provider" ||
+        evidence.provider.version !== "1" ||
+        evidence.authority !== "controlled-replay" ||
+        evidence.confidence !== "observed")
+        throw new TypeError("Evidence does not match the supported capture_electron_scenario contract");
+};
+const normalizeInspection = (result) => ({
+    target: {
+        target_id: `electron-active:${digestCanonical(result.application.application_path).slice(0, 32)}`,
+        type: "electron-application",
+        title: result.application.application_path,
+        attached: true,
+        file_path: result.application.application_path,
+    },
+    frames: [],
+    scripts: { items: [] },
+    workers: [],
+    completeness: classifyBrowserCompleteness({
+        policyFilteredSections: new Set(),
+        attachLimitedSections: new Set(),
+        truncatedSections: new Set(result.windows_truncated ||
+            result.processes.truncated ||
+            result.ipc.truncated ||
+            result.timeline.truncated
+            ? ["timeline"]
+            : []),
+        unavailableSections: new Set([
+            "frames",
+            "scripts",
+            "script_sources",
+            "workers",
+        ]),
+        excluded: [],
+        droppedEvents: {
+            scripts: 0,
+            network_requests: 0,
+            console_events: 0,
+            websocket_connections: 0,
+            websocket_frames: 0,
+            webmcp_tools: 0,
+            timeline_events: result.timeline.truncated ? result.timeline.observed : 0,
+        },
+    }),
+});
+const digestCanonical = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Runtime reconciliation could not canonicalize input");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const isWithinRoot = (root, path) => {
+    const remainder = relative(root, path);
+    return (remainder === "" || (!remainder.startsWith("..") && !isAbsolute(remainder)));
+};

package/dist/domain/javascriptRuntimeReconciliationGraph.js

@@ -24,7 +24,7 @@ export const buildReconciledApplicationGraph = (input) => {
             "Runtime presence is bounded to passive capture windows and does not prove feature execution.",
             "Cross-layer observed_as edges are inferences; digest equality proves byte identity only.",
             "Source-map relationships retain their original static authority and are not promoted into runtime matches.",
-            ...(facts.inputTruncated
+            ...(facts.inputStatus === "truncated"
                 ? [
                     "One or more source graphs or passive captures were incomplete or truncated.",
                 ]
@@ -83,6 +83,8 @@ const graphCoverageFacts = (input, omittedNodeObservations) => {
     const captureHasUnknownOmissions = input.captures.some(({ inspection }) => inspection.completeness.unavailable_sections.length > 0);
     const inputTruncated = input.layers.some(({ graph }) => graph.coverage.truncated) ||
         captureTruncated;
+    const inputComplete = input.layers.every(({ graph }) => graph.coverage.status === "complete") &&
+        input.captures.every(({ inspection }) => inspection.completeness.status === "complete_within_window");
     const outputTruncated = projectionOmissions > 0;
     const sourceOmissions = input.layers.reduce((total, { graph }) => total + (graph.coverage.omitted_count ?? 0), 0);
     const omissionsKnown = !captureTruncated &&
@@ -92,24 +94,23 @@ const graphCoverageFacts = (input, omittedNodeObservations) => {
         projectionOmissions,
         knownOmissions: projectionOmissions + sourceOmissions,
         omissionsKnown,
-        inputTruncated,
+        inputStatus: inputTruncated
+            ? "truncated"
+            : inputComplete
+                ? "complete"
+                : "partial",
         outputTruncated,
-        truncated: inputTruncated || outputTruncated,
-        complete: !inputTruncated &&
-            !outputTruncated &&
-            input.layers.every(({ graph }) => graph.coverage.status === "complete") &&
-            input.captures.every(({ inspection }) => inspection.completeness.status === "complete_within_window"),
     };
 };
-const graphCoverage = (input, facts, nodeCount) => facts.complete
+const graphCoverage = (input, facts, nodeCount) => facts.inputStatus === "complete" && !facts.outputTruncated
     ? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
-    : facts.truncated
+    : facts.inputStatus === "truncated" || facts.outputTruncated
         ? {
             status: "partial",
             truncated: true,
             omitted_count: facts.omissionsKnown ? facts.knownOmissions : null,
             limits: [
-                ...(facts.inputTruncated
+                ...(facts.inputStatus === "truncated"
                     ? [
                         {
                             name: "runtime-reconciliation-input-coverage",