rea-agents 0.3.0 → 0.4.0

package/dist/domain/hopperValues.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AnalysisProtocolError, HopperProtocolError } from "./errors.js";
+import { AnalysisOutputError, HopperProtocolError } from "./errors.js";
 import { err, ok } from "./result.js";
 const procedureMapSchema = z.record(z.string(), z.string());
 const addressedNamesSchema = z.array(z.object({ address: z.string(), name: z.string() }));
@@ -8,6 +8,9 @@ const segmentSchema = z.object({
     name: z.string().default(""),
     start: z.string().default(""),
     end: z.string().default(""),
+    readable: z.boolean().nullable().default(null),
+    writable: z.boolean().nullable().default(null),
+    executable: z.boolean().nullable().default(null),
 });
 const addressedPageSchema = z.object({
     items: z.array(z.object({ address: z.string(), value: z.string() })),
@@ -20,6 +23,12 @@ const unavailableSchema = z
 const procedureIdentitySchema = z
     .object({ address: z.string(), name: z.string() })
     .strict();
+const localVariableSchema = z
+    .object({
+    description: z.string(),
+    provenance: z.literal("hopper-public-python-api"),
+})
+    .strict();
 const boundedSchema = (item) => z
     .object({
     items: z.array(item),
@@ -61,14 +70,14 @@ const referenceEdgeSchema = z
     kind: unavailableSchema,
 })
     .strict();
-const functionDossierSchema = z
+export const functionDossierSchema = z
     .object({
     procedure: z
         .object({
         address: z.string(),
         name: z.string(),
         signature: z.string().nullable(),
-        locals: z.array(z.json()),
+        locals: z.array(localVariableSchema),
     })
         .strict(),
     pseudocode: z
@@ -81,7 +90,7 @@ const functionDossierSchema = z
     })
         .strict()
         .superRefine((value, context) => {
-        if (value.returned_chars !== value.text.length) {
+        if (value.returned_chars !== [...value.text].length) {
             context.addIssue({
                 code: "custom",
                 message: "returned_chars must equal the text length",
@@ -146,9 +155,7 @@ export const parseFunctionDossier = (value) => {
     const parsed = functionDossierSchema.safeParse(value);
     return parsed.success
         ? ok(parsed.data)
-        : err(new AnalysisProtocolError("Invalid analyze_function provider output", {
-            cause: parsed.error,
-        }));
+        : err(new AnalysisOutputError("analyze_function", "provider output did not match the dossier contract", { cause: parsed.error }));
 };
 /** Parse page entries and continuation metadata returned by list operations. */
 export const parseAddressedPage = (value) => {

package/dist/domain/nativeInspection.js

@@ -0,0 +1,142 @@
+import { z } from "zod";
+const hexAddress = z.string().regex(/^0x[a-fA-F0-9]+$/u);
+const coverage = (item) => z.object({
+    items: z.array(item),
+    total: z.number().int().min(0).nullable(),
+    exhaustive: z.boolean(),
+    limitations: z.array(z.string()),
+});
+const nativeCommandInvocationSchema = z.object({
+    tool: z.string().min(1),
+    command: z.array(z.string()),
+    tool_version: z.string().nullable(),
+    version_reason: z.string().nullable(),
+    executable_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    exit: z.object({
+        code: z.number().int().nullable(),
+        signal: z.string().nullable(),
+    }),
+    stdout_bytes: z.number().int().min(0),
+    stderr_bytes: z.number().int().min(0),
+    stdout_truncated: z.boolean(),
+    stderr_truncated: z.boolean(),
+});
+const architectureSchema = z.object({
+    name: z.string(),
+    cpu_type: z.string().nullable(),
+    cpu_subtype: z.string().nullable(),
+    file_offset: z.number().int().min(0).nullable(),
+    size: z.number().int().min(0).nullable(),
+    alignment: z.number().int().min(0).nullable(),
+});
+const permissionSchema = z.object({
+    read: z.boolean().nullable(),
+    write: z.boolean().nullable(),
+    execute: z.boolean().nullable(),
+    raw: z.string().nullable(),
+});
+const sectionSchema = z.object({
+    segment: z.string(),
+    name: z.string(),
+    address: hexAddress.nullable(),
+    size: z.number().int().min(0).nullable(),
+    file_offset: z.number().int().min(0).nullable(),
+    alignment: z.number().int().min(0).nullable(),
+    flags: z.array(z.string()),
+});
+const segmentSchema = z.object({
+    name: z.string(),
+    vm_address: hexAddress.nullable(),
+    vm_size: z.number().int().min(0).nullable(),
+    file_offset: z.number().int().min(0).nullable(),
+    file_size: z.number().int().min(0).nullable(),
+    maximum_permissions: permissionSchema,
+    initial_permissions: permissionSchema,
+    sections: coverage(sectionSchema),
+});
+const symbolSchema = z.object({
+    name: z.string(),
+    address: hexAddress.nullable(),
+    weak: z.boolean().nullable(),
+    reexport: z.boolean().nullable(),
+    source: z.string().nullable(),
+});
+const dependencySchema = z.object({
+    path: z.string(),
+    kind: z.string(),
+    current_version: z.string().nullable(),
+    compatibility_version: z.string().nullable(),
+});
+const loadCommandSchema = z.object({
+    index: z.number().int().min(0),
+    kind: z.string(),
+    file_offset: z.number().int().min(0).nullable(),
+    fields: z.record(z.string(), z.union([z.string(), z.number(), z.null()])),
+});
+const buildMetadataSchema = z.object({
+    platform: z.string().nullable(),
+    minimum_os: z.string().nullable(),
+    sdk: z.string().nullable(),
+    tools: z.array(z.object({ name: z.string(), version: z.string() })),
+});
+export const inspectMachoSchema = z.object({
+    format: z.literal("mach-o"),
+    endian: z.enum(["little", "big"]).nullable(),
+    word_size: z.union([z.literal(32), z.literal(64)]).nullable(),
+    file_type: z.string().nullable(),
+    flags: z.array(z.string()),
+    uuid: z.string().nullable(),
+    entrypoints: coverage(z.object({ file_offset: z.number().int().min(0) })),
+    architectures: coverage(architectureSchema),
+    build_metadata: coverage(buildMetadataSchema),
+    load_commands: coverage(loadCommandSchema),
+    dependencies: coverage(dependencySchema),
+    imports: coverage(symbolSchema),
+    exports: coverage(symbolSchema),
+    segments: coverage(segmentSchema),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});
+export const inspectSignatureSchema = z.object({
+    signed: z.boolean(),
+    identifier: z.string().nullable(),
+    team_identifier: z.string().nullable(),
+    format: z.string().nullable(),
+    cdhashes: z.array(z.string()),
+    hash_algorithms: z.array(z.string()),
+    authorities: z.array(z.string()),
+    designated_requirement: z.string().nullable(),
+    entitlements: z.unknown().nullable(),
+    timestamp: z.string().nullable(),
+    hardened_runtime: z.boolean().nullable(),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});
+export const inspectPlistSchema = z.object({
+    format: z.enum(["xml", "binary", "json", "unknown"]),
+    value: z.unknown(),
+    bundle: z.object({
+        identifier: z.string().nullable(),
+        executable: z.string().nullable(),
+        name: z.string().nullable(),
+        version: z.string().nullable(),
+        short_version: z.string().nullable(),
+    }),
+    source_path: z.string(),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});
+export const listArchitecturesSchema = z.object({
+    architectures: coverage(architectureSchema),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});
+export const demangleSwiftSchema = z.object({
+    symbols: z.array(z.object({
+        input: z.string(),
+        output: z.string(),
+        status: z.enum(["demangled", "unchanged", "invalid"]),
+    })),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});

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."]),
+        ],
+    };
+};