rea-agents 2.4.0 → 3.0.0

package/dist/domain/customProtocolCapture.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { jsonValueSchema } from "./jsonValue.js";
+/** Supported transport types for custom protocol capture. */
+export const transportTypeSchema = z.enum([
+    "tcp",
+    "udp",
+    "ipc",
+    "unix-socket",
+    "named-pipe",
+    "xpc",
+]);
+/** Direction of a protocol frame. */
+export const frameDirectionSchema = z.enum(["sent", "received", "intercepted"]);
+/** A captured protocol frame. */
+export const protocolFrameSchema = z.strictObject({
+    /** Monotonic sequence number. */
+    sequence: z.number().int().nonnegative(),
+    /** Timestamp in milliseconds. */
+    at_ms: z.number().int().nonnegative(),
+    /** Transport type. */
+    transport: transportTypeSchema,
+    /** Direction of the frame. */
+    direction: frameDirectionSchema,
+    /** Source process identity. */
+    source_pid: z.number().int().nullable(),
+    /** Destination process identity. */
+    dest_pid: z.number().int().nullable(),
+    /** Endpoint address (IP:port, socket path, pipe name). */
+    source_endpoint: z.string().nullable(),
+    /** Destination endpoint. */
+    dest_endpoint: z.string().nullable(),
+    /** Raw frame data as base64. */
+    raw_data: z.string().nullable(),
+    /** Decoded/parsed frame content if known. */
+    decoded_content: jsonValueSchema.nullable(),
+    /** Frame size in bytes. */
+    size: z.number().int().nonnegative(),
+    /** Whether the frame was truncated. */
+    truncated: z.boolean().default(false),
+});
+/** Authentication flow stage. */
+export const authStageSchema = z.enum([
+    "init",
+    "challenge",
+    "response",
+    "token_exchange",
+    "renewal",
+    "revocation",
+    "failure",
+    "success",
+]);
+/** Token lifecycle event. */
+export const tokenLifecycleEventSchema = z.enum([
+    "issued",
+    "refreshed",
+    "expired",
+    "revoked",
+    "renewed",
+]);
+/** A captured authentication flow event. */
+export const authFlowEventSchema = z.strictObject({
+    /** Monotonic sequence number. */
+    sequence: z.number().int().nonnegative(),
+    /** Timestamp in milliseconds. */
+    at_ms: z.number().int().nonnegative(),
+    /** Authentication stage. */
+    stage: authStageSchema,
+    /** Protocol used. */
+    protocol: z.string().min(1),
+    /** Token type if applicable. */
+    token_type: z.string().nullable(),
+    /** Token lifecycle event. */
+    token_lifecycle: tokenLifecycleEventSchema.nullable(),
+    /** Correlation ID linking challenge-response pairs. */
+    correlation_id: z.string().nullable(),
+    /** Whether credentials were detected and redacted. */
+    credentials_redacted: z.boolean().default(false),
+    /** Whether the authentication succeeded. */
+    succeeded: z.boolean().default(false),
+    /** Error message if authentication failed. */
+    error: z.string().nullable(),
+});
+/** A captured protocol session. */
+export const customProtocolCaptureSchema = z.strictObject({
+    /** Transport type for this session. */
+    transport: transportTypeSchema,
+    /** Captured frames in order. */
+    frames: z.array(protocolFrameSchema).min(0).max(100_000),
+    /** Authentication flow events. */
+    auth_events: z.array(authFlowEventSchema).default([]),
+    /** Whether any frame was truncated. */
+    has_truncated: z.boolean().default(false),
+    /** Whether credentials were detected. */
+    credentials_detected: z.boolean().default(false),
+});
+/** Correlate a frame with process identity. */
+export function correlateProcessIdentity(frame, pid) {
+    return frame.source_pid === pid || frame.dest_pid === pid;
+}
+/** Check if a frame contains credential-like content. */
+export function looksLikeCredentialFrame(frame) {
+    const patterns = [
+        "password",
+        "token",
+        "secret",
+        "api_key",
+        "apikey",
+        "authorization",
+        "credential",
+    ];
+    const content = JSON.stringify(frame.decoded_content ?? "").toLowerCase();
+    return patterns.some((p) => content.includes(p));
+}
+/** Filter frames by transport type. */
+export function framesByTransport(frames, transport) {
+    return frames.filter((f) => f.transport === transport);
+}
+/** Get all authentication flow events for a specific protocol. */
+export function authEventsByProtocol(events, protocol) {
+    return events.filter((e) => e.protocol === protocol);
+}
+/** Get successful authentication events. */
+export function successfulAuthEvents(events) {
+    return events.filter((e) => e.succeeded);
+}
+/** Get failed authentication events. */
+export function failedAuthEvents(events) {
+    return events.filter((e) => !e.succeeded);
+}
+/** Compute the duration of an authentication flow in milliseconds. */
+export function authFlowDuration(events) {
+    if (events.length === 0)
+        return null;
+    const first = events[0];
+    const last = events[events.length - 1];
+    return last.at_ms - first.at_ms;
+}

package/dist/domain/eventProcessTree.js

@@ -0,0 +1,214 @@
+import { z } from "zod";
+/** Event types for event-backed process-tree capture. */
+export const processEventTypeSchema = z.enum([
+    "spawn",
+    "exit",
+    "re_exec",
+    "reparent",
+    "signal",
+    "name_change",
+    "thread_create",
+    "thread_exit",
+]);
+/** A single event-backed process-tree event. */
+export const processTreeEventSchema = z.strictObject({
+    /** Monotonic event sequence number. */
+    sequence: z.number().int().nonnegative(),
+    /** Event timestamp in milliseconds. */
+    at_ms: z.number().int().nonnegative(),
+    /** Event type. */
+    type: processEventTypeSchema,
+    /** Process ID. */
+    pid: z.number().int().positive(),
+    /** Parent process ID. */
+    ppid: z.number().int().nullable(),
+    /** Process name if known. */
+    process_name: z.string().nullable(),
+    /** Executable path if known. */
+    executable: z.string().nullable(),
+    /** Command line arguments. */
+    arguments: z.array(z.string()).default([]),
+    /** Previous PID (for reparent events). */
+    previous_pid: z.number().int().nullable(),
+    /** Previous PPID (for reparent events). */
+    previous_ppid: z.number().int().nullable(),
+    /** Exit code (for exit events). */
+    exit_code: z.number().int().nullable(),
+    /** Signal number (for signal events). */
+    signal: z.number().int().nullable(),
+    /** Thread ID (for thread events). */
+    tid: z.number().int().nullable(),
+});
+/** Process node in a reconstructed tree. */
+export const processNodeSchema = z.strictObject({
+    pid: z.number().int().positive(),
+    ppid: z.number().int().nullable(),
+    process_name: z.string().nullable(),
+    executable: z.string().nullable(),
+    arguments: z.array(z.string()).default([]),
+    children: z.array(z.number().int()).default([]),
+    spawn_time_ms: z.number().int().nullable(),
+    exit_time_ms: z.number().int().nullable(),
+    exit_code: z.number().int().nullable(),
+    is_re_exec: z.boolean().default(false),
+    is_reparented: z.boolean().default(false),
+    previous_ppid: z.number().int().nullable(),
+});
+/** Result of event-backed process-tree reconstruction. */
+export const processTreeReconstructionSchema = z.strictObject({
+    /** Root PID of the process tree. */
+    root_pid: z.number().int().positive(),
+    /** All reconstructed process nodes. */
+    processes: z.array(processNodeSchema).min(0).max(10_000),
+    /** Events that were consumed. */
+    events_consumed: z.number().int().nonnegative(),
+    /** Events that could not be matched. */
+    events_unmatched: z.number().int().nonnegative(),
+    /** Short-lived descendants that were missed by sampling. */
+    short_lived_descendants: z.number().int().nonnegative(),
+    /** Whether any re-exec was detected. */
+    has_re_exec: z.boolean().default(false),
+    /** Whether any reparenting was detected. */
+    has_reparenting: z.boolean().default(false),
+});
+/** Reconstruct a process tree from event-backed capture. */
+export function reconstructProcessTree(events, rootPid) {
+    const nodes = new Map();
+    const children = new Map();
+    let eventsConsumed = 0;
+    let eventsUnmatched = 0;
+    let hasReExec = false;
+    let hasReparenting = false;
+    let shortLivedDescendants = 0;
+    const sorted = [...events].sort((a, b) => a.at_ms - b.at_ms);
+    for (const event of sorted) {
+        eventsConsumed++;
+        let node = nodes.get(event.pid);
+        switch (event.type) {
+            case "spawn": {
+                if (!node) {
+                    node = {
+                        pid: event.pid,
+                        ppid: event.ppid,
+                        process_name: event.process_name,
+                        executable: event.executable,
+                        arguments: event.arguments,
+                        children: [],
+                        spawn_time_ms: event.at_ms,
+                        exit_time_ms: null,
+                        exit_code: null,
+                        is_re_exec: false,
+                        is_reparented: false,
+                        previous_ppid: null,
+                    };
+                    nodes.set(event.pid, node);
+                }
+                if (event.ppid !== null) {
+                    const parentChildren = children.get(event.ppid) ?? [];
+                    parentChildren.push(event.pid);
+                    children.set(event.ppid, parentChildren);
+                }
+                break;
+            }
+            case "exit": {
+                if (node) {
+                    node.exit_time_ms = event.at_ms;
+                    node.exit_code = event.exit_code;
+                    if (node.spawn_time_ms !== null &&
+                        event.at_ms - node.spawn_time_ms < 100)
+                        shortLivedDescendants++;
+                }
+                else {
+                    eventsUnmatched++;
+                }
+                break;
+            }
+            case "re_exec": {
+                if (node) {
+                    node.is_re_exec = true;
+                    node.executable = event.executable ?? node.executable;
+                    node.arguments = event.arguments;
+                    hasReExec = true;
+                }
+                else {
+                    eventsUnmatched++;
+                }
+                break;
+            }
+            case "reparent": {
+                if (node) {
+                    node.previous_ppid = node.ppid;
+                    node.ppid = event.ppid;
+                    node.is_reparented = true;
+                    hasReparenting = true;
+                }
+                else {
+                    eventsUnmatched++;
+                }
+                break;
+            }
+            case "signal":
+            case "name_change":
+            case "thread_create":
+            case "thread_exit":
+                // These events are recorded but don't modify the tree structure
+                break;
+        }
+    }
+    // Attach children to nodes
+    for (const [pid, childPids] of children) {
+        const node = nodes.get(pid);
+        if (node)
+            node.children = childPids;
+    }
+    return {
+        root_pid: rootPid,
+        processes: [...nodes.values()],
+        events_consumed: eventsConsumed,
+        events_unmatched: eventsUnmatched,
+        short_lived_descendants: shortLivedDescendants,
+        has_re_exec: hasReExec,
+        has_reparenting: hasReparenting,
+    };
+}
+/** Get all descendant PIDs of a given root PID. */
+export function getDescendants(processes, rootPid) {
+    const byPid = new Map(processes.map((p) => [p.pid, p]));
+    const visited = new Set();
+    const result = [];
+    const queue = [rootPid];
+    while (queue.length > 0) {
+        const pid = queue.shift();
+        if (visited.has(pid))
+            continue;
+        visited.add(pid);
+        const node = byPid.get(pid);
+        if (node) {
+            for (const child of node.children) {
+                if (!visited.has(child)) {
+                    result.push(child);
+                    queue.push(child);
+                }
+            }
+        }
+    }
+    return result;
+}
+/** Check if a process tree contains a specific PID. */
+export function containsProcess(processes, pid) {
+    return processes.some((p) => p.pid === pid);
+}
+/** Get the maximum tree depth from the root. */
+export function maxTreeDepth(processes, rootPid) {
+    const byPid = new Map(processes.map((p) => [p.pid, p]));
+    function depth(pid, visited) {
+        if (visited.has(pid))
+            return 0;
+        visited.add(pid);
+        const node = byPid.get(pid);
+        if (!node || node.children.length === 0)
+            return 0;
+        return 1 + Math.max(...node.children.map((c) => depth(c, visited)));
+    }
+    return depth(rootPid, new Set());
+}

package/dist/domain/evidenceBundle.js

@@ -163,6 +163,53 @@ const validateVerifiedResolution = (unknown, evidenceById) => {
     if (qualifies !== true)
         throw new TypeError(`Residual unknown ${unknown.unknown_id} has no qualifying resolution evidence`);
 };
+/**
+ * Validate one new residual-unknown revision against an already valid ledger.
+ * This keeps ordinary mutations proportional to the affected revision while
+ * full bundle imports continue to validate the complete graph.
+ */
+export const validateResidualUnknownAddition = (unknown, evidenceById, currentHeads) => {
+    const current = currentHeads.get(unknown.unknown_id);
+    if (current === undefined
+        ? unknown.revision !== 1 || unknown.previous_revision_digest !== null
+        : unknown.revision !== current.revision + 1 ||
+            unknown.previous_revision_digest !== current.revision_digest)
+        throw new TypeError(`Residual unknown ${unknown.unknown_id} revision chain is broken`);
+    for (const evidenceId of referencedEvidenceIds(unknown))
+        if (!evidenceById.has(evidenceId))
+            throw new TypeError(`Residual unknown references missing evidence ${evidenceId}`);
+    for (const relationship of unknown.relationships)
+        if (relationship.unknown_id !== unknown.unknown_id &&
+            !currentHeads.has(relationship.unknown_id))
+            throw new TypeError(`Residual unknown references missing unknown ${relationship.unknown_id}`);
+    if (unknown.resolution?.disposition === "verified")
+        validateVerifiedResolution(unknown, evidenceById);
+    for (const relationship of unknown.relationships)
+        if (relationship.type === "depends-on" &&
+            reachesUnknown(relationship.unknown_id, unknown.unknown_id, currentHeads, unknown))
+            throw new TypeError("Residual unknown dependency graph contains a cycle");
+};
+const reachesUnknown = (start, goal, currentHeads, candidate) => {
+    const pending = [start];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const id = pending.pop();
+        if (id === undefined)
+            break;
+        if (id === goal)
+            return true;
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        const unknown = id === candidate.unknown_id ? candidate : currentHeads.get(id);
+        if (unknown === undefined)
+            continue;
+        for (const relationship of unknown.relationships)
+            if (relationship.type === "depends-on")
+                pending.push(relationship.unknown_id);
+    }
+    return false;
+};
 const evidenceQualifies = (unknown, evidence) => {
     if (unknown.required_authority !== null &&
         evidence.authority !== unknown.required_authority)

package/dist/domain/hopperStartupFailure.js

@@ -27,7 +27,7 @@ const failures = [
     [
         75,
         "hopper_exited_during_startup",
-        "Hopper exited before the REA bridge was ready. Run rea doctor and retry the analysis.",
+        "Hopper exited before the REA bridge was ready. In CI, run rea doctor --provider hopper --detail full --json; if Hopper showed a UI or license prompt, complete it in the runner user session, otherwise close stale Hopper sessions and retry.",
     ],
     [
         76,

package/dist/domain/hopperValues.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
+import { jsonValueSchema } from "./jsonValue.js";
 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);
@@ -114,6 +116,16 @@ const boundedSchema = (item) => z
         });
     }
 });
+/** Provider-neutral bounded raw-instruction window for one analyzed function. */
+export const functionInstructionWindowSchema = z
+    .object({
+    procedure: procedureIdentitySchema,
+    instructions: boundedSchema(z.string()),
+    instructions_scanned: z.number().int().min(0),
+    instruction_scan_truncated: z.boolean(),
+    limitations: z.array(z.string()),
+})
+    .strict();
 const availableReferenceKindSchema = z
     .object({
     available: z.literal(true),
@@ -226,6 +238,7 @@ export const functionDossierSchema = z
     instruction_scan: z
         .object({ scanned: z.number().int().min(0), truncated: z.boolean() })
         .strict(),
+    native_api: nativeApiBoundarySchema.optional(),
     limitations: z.array(z.string()).default([]),
 })
     .strict();
@@ -233,7 +246,7 @@ export const functionDossierSchema = z
 export const parseFunctionDossier = (value) => {
     const parsed = functionDossierSchema.safeParse(value);
     return parsed.success
-        ? ok(parsed.data)
+        ? ok(jsonValueSchema.parse(parsed.data))
         : 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. */

package/dist/domain/inputIssueProjection.js

@@ -31,7 +31,13 @@ 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;

package/dist/domain/javascriptRuntimeObservation.js

@@ -0,0 +1,170 @@
+import { isAbsolute, resolve } from "node:path";
+import { z } from "zod";
+import { browserEndpointSchema, browserOriginSchema, } from "./browserObservation.js";
+const boundedTextSchema = z.string().min(1).max(4_096);
+const runtimeFileRootsSchema = z
+    .array(z
+    .string()
+    .min(1)
+    .max(16_384)
+    .refine(isAbsolute, "Runtime file roots must be absolute paths")
+    .overwrite(resolve))
+    .max(32)
+    .overwrite((roots) => [...new Set(roots)].sort())
+    .default([]);
+const runtimeOriginsSchema = z
+    .array(browserOriginSchema)
+    .max(32)
+    .overwrite((origins) => [...new Set(origins)].sort())
+    .default([]);
+const approvedRuntimeScope = {
+    inspector_endpoint: browserEndpointSchema,
+    allowed_file_roots: runtimeFileRootsSchema,
+    allowed_origins: runtimeOriginsSchema,
+    approved: z.literal(true),
+};
+const requireRuntimeScope = (input, context) => {
+    if (input.allowed_file_roots.length === 0 &&
+        input.allowed_origins.length === 0)
+        context.addIssue({
+            code: "custom",
+            path: ["allowed_file_roots"],
+            message: "At least one exact file root or HTTP(S) origin is required",
+        });
+};
+/** Input for listing approved Node/Electron V8 Inspector targets. */
+export const listJavaScriptRuntimeTargetsInputSchema = z
+    .strictObject({
+    ...approvedRuntimeScope,
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(200).default(100),
+})
+    .superRefine(requireRuntimeScope);
+export const javascriptRuntimeKindSchema = z.enum([
+    "node",
+    "electron-main",
+    "electron-preload",
+    "electron-renderer",
+]);
+export const javascriptRuntimeObservationLimitsSchema = z.strictObject({
+    max_events: z.number().int().min(1).max(50_000).default(10_000),
+    max_scripts: z.number().int().min(1).max(10_000).default(2_000),
+    max_execution_contexts: z.number().int().min(1).max(5_000).default(1_000),
+    max_location_bytes: z.number().int().min(64).max(65_536).default(16_384),
+    max_total_metadata_bytes: z
+        .number()
+        .int()
+        .min(1_024)
+        .max(32 * 1_024 * 1_024)
+        .default(4 * 1_024 * 1_024),
+});
+/** Input for one bounded, attach-only V8 Inspector observation. */
+export const observeJavaScriptRuntimeInputSchema = z
+    .strictObject({
+    ...approvedRuntimeScope,
+    target_id: z.string().trim().min(1).max(256),
+    runtime_kind: javascriptRuntimeKindSchema,
+    observation_ms: z.number().int().min(0).max(10_000).default(100),
+    limits: javascriptRuntimeObservationLimitsSchema.default({
+        max_events: 10_000,
+        max_scripts: 2_000,
+        max_execution_contexts: 1_000,
+        max_location_bytes: 16_384,
+        max_total_metadata_bytes: 4 * 1_024 * 1_024,
+    }),
+})
+    .superRefine(requireRuntimeScope);
+export const javascriptRuntimeVersionSchema = z.strictObject({
+    product: z.string().min(1).max(1_024),
+    protocol_version: z.string().min(1).max(100),
+    v8_version: z.string().max(1_024).nullable(),
+});
+export const javascriptRuntimeLocationSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("file"),
+        file_path: z.string().min(1).max(16_384),
+    }),
+    z.strictObject({
+        kind: z.literal("url"),
+        origin: z.string().min(1).max(2_048),
+        sanitized_url: z.string().min(1).max(65_536),
+    }),
+    z.strictObject({
+        kind: z.literal("builtin"),
+        specifier: z.string().min(1).max(4_096),
+    }),
+]);
+const javascriptRuntimeTargetSchema = z.strictObject({
+    target_id: z.string().min(1).max(256),
+    protocol_type: z.string().min(1).max(100),
+    attached: z.boolean(),
+    location: javascriptRuntimeLocationSchema,
+});
+/** Root/origin-filtered V8 Inspector target inventory. */
+export const javascriptRuntimeTargetListSchema = z.strictObject({
+    schema_version: z.literal(1),
+    runtime: javascriptRuntimeVersionSchema,
+    targets: z.strictObject({
+        items: z.array(javascriptRuntimeTargetSchema),
+        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(),
+    }),
+    excluded: z.strictObject({
+        outside_file_roots: z.number().int().min(0),
+        outside_origins: z.number().int().min(0),
+        unsupported_location: z.number().int().min(0),
+        unconnectable: z.number().int().min(0),
+    }),
+    limitations: z.array(boundedTextSchema).max(100),
+});
+const javascriptRuntimeScriptSchema = z.strictObject({
+    script_key: z.string().regex(/^v8_script_[a-f0-9]{64}$/u),
+    location: javascriptRuntimeLocationSchema,
+    execution_context_key: z.string().max(64).nullable(),
+    cdp_hash: z.string().max(512).nullable(),
+    length: z.number().int().min(0),
+    is_module: z.boolean(),
+    status: z.literal("observed-loaded"),
+});
+const javascriptRuntimeContextSchema = z.strictObject({
+    context_key: z.string().min(1).max(64),
+    state: z.enum(["created", "destroyed", "cleared"]),
+    name: z.string().max(1_024).nullable(),
+    origin: z.string().max(4_096).nullable(),
+});
+/** Deterministic passive script/context snapshot from one bounded window. */
+export const javascriptRuntimeObservationSchema = z.strictObject({
+    schema_version: z.literal(1),
+    runtime: javascriptRuntimeVersionSchema,
+    target: javascriptRuntimeTargetSchema.extend({
+        runtime_kind: javascriptRuntimeKindSchema,
+        runtime_kind_authority: z.literal("caller-declared-unverified"),
+    }),
+    capture: z.strictObject({
+        observation_ms: z.number().int().min(0),
+        events_observed: z.number().int().min(0),
+        events_retained: z.number().int().min(0),
+        events_dropped: z.number().int().min(0),
+        metadata_bytes_retained: z.number().int().min(0),
+        truncated: z.boolean(),
+        truncation_reasons: z.array(boundedTextSchema).max(20),
+    }),
+    scripts: z.strictObject({
+        items: z.array(javascriptRuntimeScriptSchema),
+        observed_total: z.number().int().min(0),
+        excluded: z.strictObject({
+            outside_file_roots: z.number().int().min(0),
+            outside_origins: z.number().int().min(0),
+            unsupported_location: z.number().int().min(0),
+            invalid_protocol_value: z.number().int().min(0),
+        }),
+    }),
+    execution_contexts: z.array(javascriptRuntimeContextSchema),
+    directly_observed: z.array(boundedTextSchema).max(20),
+    unavailable_without_instrumentation: z.array(boundedTextSchema).max(20),
+    unknowns: z.array(boundedTextSchema).max(100),
+    limitations: z.array(boundedTextSchema).max(100),
+});