rea-agents 0.3.0 → 0.5.0

package/dist/domain/processCapture.js

@@ -2,18 +2,41 @@ import { resolve } from "node:path";
 import { z } from "zod";
 const positiveBudget = z.number().int().positive();
 const timedEventBase = { at_ms: z.number().int().nonnegative() };
+const environmentName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);
+const reservedEnvironment = new Set([
+    "HOME",
+    "TERM",
+    "REA_PROCESS_RUN_ID",
+    "REA_REPLAY_HTTP_URL",
+    "REA_REPLAY_WEBSOCKET_URL",
+]);
+const normalizationSchema = z.object({
+    paths: z.boolean(),
+    pids: z.boolean(),
+    ports: z.boolean(),
+    time_bucket_ms: positiveBudget.max(60_000),
+    patterns: z.array(z.object({
+        pattern: z.string().max(500),
+        replacement: z.string().max(100),
+    })),
+});
 /** Exact boundary schema for bounded dynamic process scenarios. */
 export const processScenarioSchema = z
     .object({
     approved: z
         .literal(true)
         .describe("Explicit per-call acknowledgement that this operation launches the target"),
+    unknown_registry_approved: z
+        .literal(true)
+        .optional()
+        .describe("Explicit approval to record capture residuals durably"),
     executable: z.string().startsWith("/"),
     arguments: z.array(z.string()).max(256).default([]),
     working_directory: z.string().startsWith("/"),
-    environment: z.record(z.string(), z.string()).default({}),
-    inherit_environment: z.array(z.string()).max(64).default([]),
-    secret_aliases: z.array(z.string()).max(64).default([]),
+    environment: z.record(environmentName, z.string()).default({}),
+    inherit_environment: z.array(environmentName).max(64).default([]),
+    secret_aliases: z.array(environmentName).max(64).default([]),
+    network_access: z.literal("host").default("host"),
     filesystem_roots: z.array(z.string().startsWith("/")).max(16).default([]),
     events: z
         .array(z.discriminatedUnion("type", [
@@ -46,6 +69,10 @@ export const processScenarioSchema = z
         files: positiveBudget.max(100_000).default(10_000),
         file_bytes: positiveBudget.max(100_000_000).default(10_000_000),
         processes: positiveBudget.max(10_000).default(1_000),
+        protocol_events: positiveBudget.max(100_000).default(10_000),
+        protocol_body_bytes: positiveBudget.max(10_000_000).default(1_000_000),
+        connections: positiveBudget.max(1_000).default(100),
+        filesystem_depth: z.number().int().min(1).max(64).default(16),
     })
         .default({
         output_bytes: 1_000_000,
@@ -53,6 +80,10 @@ export const processScenarioSchema = z
         files: 10_000,
         file_bytes: 10_000_000,
         processes: 1_000,
+        protocol_events: 10_000,
+        protocol_body_bytes: 1_000_000,
+        connections: 100,
+        filesystem_depth: 16,
     }),
     normalization: z
         .object({
@@ -83,6 +114,12 @@ export const processScenarioSchema = z
             path: z.string().startsWith("/"),
             status: z.number().int().min(100).max(599),
             body: z.string().max(1_000_000),
+            request_headers: z.record(z.string(), z.string()).default({}),
+            request_body: z.string().max(1_000_000).optional(),
+            response_headers: z.record(z.string(), z.string()).default({}),
+            delay_ms: z.number().int().nonnegative().max(30_000).default(0),
+            disconnect: z.boolean().default(false),
+            max_calls: z.number().int().min(1).max(100).default(1),
         }))
             .max(100)
             .default([]),
@@ -90,8 +127,29 @@ export const processScenarioSchema = z
             .array(z.string().max(1_000_000))
             .max(100)
             .default([]),
+        websocket_connections: z
+            .array(z.object({
+            messages: z
+                .array(z.object({
+                data: z.string().max(1_000_000),
+                delay_ms: z
+                    .number()
+                    .int()
+                    .nonnegative()
+                    .max(30_000)
+                    .default(0),
+            }))
+                .max(100),
+            disconnect_after: z.boolean().default(false),
+        }))
+            .max(100)
+            .default([]),
     })
-        .default({ http: [], websocket_messages: [] }),
+        .default({
+        http: [],
+        websocket_messages: [],
+        websocket_connections: [],
+    }),
 })
     .strict()
     .superRefine((scenario, context) => {
@@ -114,6 +172,34 @@ export const processScenarioSchema = z
             });
         }
     }
+    const explicit = new Set(Object.keys(scenario.environment));
+    for (const name of [...explicit, ...scenario.inherit_environment]) {
+        if (reservedEnvironment.has(name)) {
+            context.addIssue({
+                code: "custom",
+                message: `${name} is reserved by the process adapter`,
+                path: ["environment", name],
+            });
+        }
+    }
+    for (const name of scenario.inherit_environment) {
+        if (explicit.has(name)) {
+            context.addIssue({
+                code: "custom",
+                message: "an environment name cannot be explicit and inherited",
+                path: ["inherit_environment"],
+            });
+        }
+    }
+    for (const event of scenario.events) {
+        if (event.at_ms > scenario.timeout_ms) {
+            context.addIssue({
+                code: "custom",
+                message: "event occurs after the scenario timeout",
+                path: ["events"],
+            });
+        }
+    }
 });
 /** Parse untrusted process scenario input and apply safe default budgets. */
 export const parseProcessScenario = (input) => processScenarioSchema.parse(input);
@@ -123,6 +209,11 @@ const isWithin = (candidate, root) => resolve(candidate) === resolve(root) ||
 export const authorizeProcessScenario = (scenario, policy) => {
     if (!policy.enabled)
         return { allowed: false, reason: "process capture is disabled" };
+    if (scenario.network_access === "host" && !policy.allowExternalNetwork)
+        return {
+            allowed: false,
+            reason: "host network access is not approved by operator policy",
+        };
     if (!policy.executableRoots.some((root) => isWithin(scenario.executable, root))) {
         return { allowed: false, reason: "executable is outside approved roots" };
     }
@@ -152,7 +243,8 @@ export const authorizeProcessScenario = (scenario, policy) => {
 };
 /** Exact serialized shape of a bounded process capture. */
 export const processCaptureSchema = z.object({
-    schema_version: z.literal(1),
+    schema_version: z.literal(2),
+    normalization: normalizationSchema,
     frames: z.array(z.object({
         sequence: z.number().int().nonnegative(),
         at_ms: z.number().int().nonnegative(),
@@ -161,6 +253,7 @@ export const processCaptureSchema = z.object({
     exit: z.object({
         code: z.number().int().nullable(),
         signal: z.number().int().nullable(),
+        reason: z.enum(["exited", "timeout", "idle_timeout"]),
     }),
     process_samples: z.array(z.object({
         at_ms: z.number().int().nonnegative(),
@@ -170,11 +263,18 @@ export const processCaptureSchema = z.object({
     })),
     protocol_events: z.array(z.object({
         sequence: z.number().int().nonnegative(),
+        at_ms: z.number().int().nonnegative(),
         protocol: z.enum(["http", "websocket"]),
         direction: z.enum(["request", "response", "received", "sent"]),
         method: z.string().nullable(),
         path: z.string().nullable(),
         data: z.string(),
+        outcome: z.enum([
+            "matched",
+            "unmatched",
+            "script_exhausted",
+            "disconnected",
+        ]),
     })),
     files_before: z.array(z.object({
         path: z.string(),
@@ -198,55 +298,53 @@ export const processCaptureSchema = z.object({
             .nullable(),
         symlink_target: z.string().nullable(),
     })),
+    filesystem_effects: z.array(z.object({
+        path: z.string(),
+        status: z.enum(["created", "modified", "deleted", "unchanged"]),
+        before: z
+            .object({
+            path: z.string(),
+            type: z.enum(["file", "directory", "symlink", "other"]),
+            mode: z.number().int().nonnegative(),
+            size: z.number().int().nonnegative(),
+            sha256: z
+                .string()
+                .regex(/^[a-f0-9]{64}$/u)
+                .nullable(),
+            symlink_target: z.string().nullable(),
+        })
+            .nullable(),
+        after: z
+            .object({
+            path: z.string(),
+            type: z.enum(["file", "directory", "symlink", "other"]),
+            mode: z.number().int().nonnegative(),
+            size: z.number().int().nonnegative(),
+            sha256: z
+                .string()
+                .regex(/^[a-f0-9]{64}$/u)
+                .nullable(),
+            symlink_target: z.string().nullable(),
+        })
+            .nullable(),
+    })),
     truncated: z.boolean(),
     limitations: z.array(z.string()),
+    residual_unknowns: z.array(z.object({
+        scope: z.enum([
+            "terminal",
+            "exit",
+            "process",
+            "filesystem",
+            "protocol",
+            "cleanup",
+            "network",
+        ]),
+        reason: z.string(),
+    })),
+    cleanup: z.object({
+        owned_process_group: z.literal("verified"),
+        temporary_root: z.literal("removed"),
+    }),
 });
-const stableFiles = (files) => JSON.stringify([...files].sort((left, right) => left.path.localeCompare(right.path)));
-/** Compare bounded captures without claiming equality for incomplete observations. */
-export const compareProcessCaptures = (left, right) => {
-    if (left.truncated || right.truncated) {
-        return {
-            status: "truncated",
-            terminal: "truncated",
-            exit: "truncated",
-            filesystem: "truncated",
-            protocol: "truncated",
-            process: "truncated",
-            limitations: ["At least one capture is truncated."],
-        };
-    }
-    const terminal = left.frames.map(({ data }) => data).join("") ===
-        right.frames.map(({ data }) => data).join("")
-        ? "unchanged"
-        : "changed";
-    const exit = JSON.stringify(left.exit) === JSON.stringify(right.exit)
-        ? "unchanged"
-        : "changed";
-    const filesystem = stableFiles(left.files_after) === stableFiles(right.files_after)
-        ? "unchanged"
-        : "changed";
-    const protocol = JSON.stringify(left.protocol_events) ===
-        JSON.stringify(right.protocol_events)
-        ? "unchanged"
-        : "changed";
-    const process = JSON.stringify(left.process_samples.map(({ command }) => command)) ===
-        JSON.stringify(right.process_samples.map(({ command }) => command))
-        ? "unchanged"
-        : "changed";
-    const status = terminal === "unchanged" &&
-        exit === "unchanged" &&
-        filesystem === "unchanged" &&
-        protocol === "unchanged" &&
-        process === "unchanged"
-        ? "unchanged"
-        : "changed";
-    return {
-        status,
-        terminal,
-        exit,
-        filesystem,
-        protocol,
-        process,
-        limitations: [...left.limitations, ...right.limitations],
-    };
-};
+export { compareProcessCaptures, comparisonStatusSchema, processCaptureComparisonSchema, } from "./processComparison.js";

package/dist/domain/processComparison.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+/** Comparison classification that never equates incomplete evidence. */
+export const comparisonStatusSchema = z.enum([
+    "unchanged",
+    "added",
+    "removed",
+    "changed",
+    "truncated",
+    "unknown",
+]);
+/** Pure normalized comparison between two captures. */
+export const processCaptureComparisonSchema = z
+    .object({
+    status: comparisonStatusSchema,
+    terminal: comparisonStatusSchema,
+    exit: comparisonStatusSchema,
+    filesystem: comparisonStatusSchema,
+    protocol: comparisonStatusSchema,
+    process: comparisonStatusSchema,
+    limitations: z.array(z.string()),
+})
+    .superRefine((comparison, context) => {
+    const dimensions = [
+        comparison.terminal,
+        comparison.exit,
+        comparison.filesystem,
+        comparison.protocol,
+        comparison.process,
+    ];
+    const expected = dimensions.includes("truncated")
+        ? "truncated"
+        : dimensions.some((status) => ["added", "removed", "changed"].includes(status))
+            ? "changed"
+            : dimensions.includes("unknown")
+                ? "unknown"
+                : "unchanged";
+    if (comparison.status !== expected)
+        context.addIssue({
+            code: "custom",
+            message: "Process comparison status contradicts its dimensions",
+            path: ["status"],
+        });
+});
+const stableFiles = (capture) => JSON.stringify([...capture.files_after].sort((left, right) => left.path.localeCompare(right.path)));
+const classifyCollection = (left, right) => {
+    if (JSON.stringify(left) === JSON.stringify(right))
+        return "unchanged";
+    if (left.length === 0)
+        return "added";
+    if (right.length === 0)
+        return "removed";
+    return "changed";
+};
+const hasUnknown = (capture, scope) => capture.residual_unknowns.some((item) => item.scope === scope);
+const comparisonStatus = (dimensions) => {
+    if (dimensions.some((status) => ["changed", "added", "removed"].includes(status)))
+        return "changed";
+    return dimensions.includes("unknown") ? "unknown" : "unchanged";
+};
+/** Compare bounded captures without equating missing or incompatible evidence. */
+export const compareProcessCaptures = (left, right) => {
+    if (left.truncated || right.truncated) {
+        return {
+            status: "truncated",
+            terminal: "truncated",
+            exit: "truncated",
+            filesystem: "truncated",
+            protocol: "truncated",
+            process: "truncated",
+            limitations: ["At least one capture is truncated."],
+        };
+    }
+    const sameNormalization = JSON.stringify(left.normalization) === JSON.stringify(right.normalization);
+    const classify = (scope, leftValues, rightValues) => !sameNormalization || hasUnknown(left, scope) || hasUnknown(right, scope)
+        ? "unknown"
+        : classifyCollection(leftValues, rightValues);
+    const terminal = classify("terminal", left.frames.map(({ data }) => data), right.frames.map(({ data }) => data));
+    const exit = hasUnknown(left, "exit") || hasUnknown(right, "exit")
+        ? "unknown"
+        : JSON.stringify(left.exit) === JSON.stringify(right.exit)
+            ? "unchanged"
+            : "changed";
+    const filesystem = !hasUnknown(left, "filesystem") &&
+        !hasUnknown(right, "filesystem") &&
+        sameNormalization &&
+        stableFiles(left) === stableFiles(right)
+        ? "unchanged"
+        : classify("filesystem", left.filesystem_effects, right.filesystem_effects);
+    const protocol = classify("protocol", left.protocol_events, right.protocol_events);
+    const process = classify("process", left.process_samples, right.process_samples);
+    return {
+        status: comparisonStatus([terminal, exit, filesystem, protocol, process]),
+        terminal,
+        exit,
+        filesystem,
+        protocol,
+        process,
+        limitations: [
+            ...left.limitations,
+            ...right.limitations,
+            ...left.residual_unknowns.map(({ reason }) => reason),
+            ...right.residual_unknowns.map(({ reason }) => reason),
+            ...(sameNormalization ? [] : ["Capture normalization rules differ."]),
+        ],
+    };
+};

package/dist/domain/reconstructionUnknowns.js

@@ -0,0 +1,90 @@
+/** Select the latest revision of each residual unknown. */
+export const reconstructionUnknownHeads = (revisions) => {
+    const heads = new Map();
+    for (const item of revisions) {
+        const current = heads.get(item.unknown_id);
+        if (current === undefined || current.revision < item.revision)
+            heads.set(item.unknown_id, item);
+    }
+    return heads;
+};
+/** Find active unknowns that affect a comparison or one of its sources. */
+export const reconstructionClaimUnknowns = (heads, comparisonId, sourceIds) => {
+    const evidenceIds = new Set([comparisonId, ...sourceIds]);
+    const relevantIds = new Set([...heads.values()]
+        .filter((item) => item.status !== "resolved" &&
+        [
+            ...item.supporting_evidence_ids,
+            ...item.contradicting_evidence_ids,
+        ].some((id) => evidenceIds.has(id)))
+        .map(({ unknown_id: id }) => id));
+    const pending = [...relevantIds];
+    while (pending.length > 0) {
+        const currentId = pending.pop();
+        if (currentId === undefined)
+            continue;
+        const current = heads.get(currentId);
+        if (current === undefined)
+            continue;
+        for (const relationship of current.relationships) {
+            if (relationship.type === "related-to")
+                continue;
+            const dependency = heads.get(relationship.unknown_id);
+            if (dependency === undefined ||
+                dependency.status === "resolved" ||
+                relevantIds.has(dependency.unknown_id))
+                continue;
+            relevantIds.add(dependency.unknown_id);
+            pending.push(dependency.unknown_id);
+        }
+    }
+    return [...relevantIds]
+        .flatMap((id) => {
+        const unknown = heads.get(id);
+        return unknown === undefined ? [] : [unknown];
+    })
+        .sort((left, right) => left.unknown_id.localeCompare(right.unknown_id, "en"));
+};
+/** Aggregate and bound deterministic probes for unresolved claims. */
+export const reconstructionProbes = (results, heads) => {
+    const output = new Map();
+    for (const result of results.filter(({ status }) => status === "unknown")) {
+        const unknowns = result.unknown_ids.flatMap((id) => {
+            const item = heads.get(id);
+            return item === undefined ? [] : [item];
+        });
+        const probes = unknowns.flatMap(({ recommended_probes: items }) => items);
+        const candidates = probes.length > 0 ? probes : [defaultProbe(result.kind)];
+        for (const probe of candidates) {
+            const key = `${probe.operation}\0${probe.rationale}`;
+            const current = output.get(key) ?? {
+                ...probe,
+                claim_ids: [],
+                unknown_ids: [],
+            };
+            current.claim_ids = uniqueSorted([...current.claim_ids, result.claim_id]);
+            current.unknown_ids = uniqueSorted([
+                ...current.unknown_ids,
+                ...result.unknown_ids,
+            ]);
+            output.set(key, current);
+        }
+    }
+    const sorted = [...output.values()].sort((left, right) => `${left.operation}\0${left.rationale}`.localeCompare(`${right.operation}\0${right.rationale}`, "en"));
+    return { items: sorted.slice(0, 2_000), truncated: sorted.length > 2_000 };
+};
+const defaultProbe = (kind) => kind === "behavioral"
+    ? {
+        operation: "capture_process_scenario",
+        rationale: "Repeat both scenarios under one controlled environment.",
+    }
+    : kind === "structural-function"
+        ? {
+            operation: "analyze_function",
+            rationale: "Capture complete function dossiers under equal limits.",
+        }
+        : {
+            operation: "inventory_artifact",
+            rationale: "Capture complete artifact inventories under equal limits.",
+        };
+const uniqueSorted = (values) => [...new Set(values)].sort((left, right) => left.localeCompare(right, "en"));