rea-agents 2.5.0 → 3.1.0

package/dist/domain/electronActiveObservation.js

@@ -0,0 +1,277 @@
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+const absolutePathSchema = z
+    .string()
+    .min(1)
+    .max(16_384)
+    .refine(isAbsolute, "path must be absolute");
+const windowIndexSchema = z.number().int().min(0).max(99);
+const deepLinkUrlSchema = z
+    .string()
+    .min(1)
+    .max(4_096)
+    .refine((value) => {
+    try {
+        return new URL(value).protocol.length > 0;
+    }
+    catch {
+        return false;
+    }
+}, "deep-link url must be an absolute URL");
+const actionSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        step_id: z.string().min(1).max(128),
+        kind: z.literal("click"),
+        selector: z.string().min(1).max(512),
+        window_index: windowIndexSchema.default(0),
+    }),
+    z.strictObject({
+        step_id: z.string().min(1).max(128),
+        kind: z.literal("wait"),
+        duration_ms: z.number().int().min(0).max(10_000),
+        window_index: windowIndexSchema.optional(),
+    }),
+    z.strictObject({
+        step_id: z.string().min(1).max(128),
+        kind: z.literal("renderer-reload"),
+        window_index: windowIndexSchema.default(0),
+    }),
+    z.strictObject({
+        step_id: z.string().min(1).max(128),
+        kind: z.literal("renderer-crash"),
+        window_index: windowIndexSchema.default(0),
+    }),
+    z.strictObject({
+        step_id: z.string().min(1).max(128),
+        kind: z.literal("deep-link"),
+        delivery: z.enum(["open-url", "second-instance"]),
+        url: deepLinkUrlSchema,
+    }),
+]);
+const limitsSchema = z.strictObject({
+    max_duration_ms: z.number().int().min(1).max(120_000).default(60_000),
+    action_timeout_ms: z.number().int().min(1).max(30_000).default(5_000),
+    max_actions: z.number().int().min(1).max(100).default(20),
+    max_ipc_events: z.number().int().min(1).max(10_000).default(2_000),
+    max_runtime_events: z.number().int().min(1).max(20_000).default(5_000),
+    max_processes: z.number().int().min(1).max(100).default(32),
+    max_windows: z.number().int().min(1).max(100).default(32),
+});
+/** Input for one explicit, provider-owned Electron runtime experiment. */
+export const electronActiveObservationInputSchema = z
+    .strictObject({
+    schema_version: z.literal(1),
+    executable_path: absolutePathSchema,
+    application_path: absolutePathSchema,
+    application_root: absolutePathSchema,
+    args: z.array(z.string().max(4_096)).max(32).default([]),
+    actions: z.array(actionSchema).max(100).default([]),
+    limits: limitsSchema.default({
+        max_duration_ms: 60_000,
+        action_timeout_ms: 5_000,
+        max_actions: 20,
+        max_ipc_events: 2_000,
+        max_runtime_events: 5_000,
+        max_processes: 32,
+        max_windows: 32,
+    }),
+    approved: z.literal(true),
+})
+    .superRefine((input, context) => {
+    if (input.actions.length > input.limits.max_actions)
+        context.addIssue({
+            code: "custom",
+            path: ["actions"],
+            message: "actions exceed the configured max_actions limit",
+        });
+});
+const ipcEventSchema = z.strictObject({
+    sequence: z.number().int().min(1),
+    correlation_id: z.string().max(256).nullable().default(null),
+    kind: z.enum([
+        "main-handler-invocation",
+        "main-event-invocation",
+        "utility-process-fork",
+        "utility-process-message",
+        "ipc-main-to-renderer",
+        "ipc-utility-to-main",
+        "ipc-renderer-send",
+        "ipc-renderer-invoke",
+        "ipc-renderer-post-message",
+    ]),
+    event: z.string().max(128).nullable().optional(),
+    phase: z
+        .enum(["attempted", "completed", "blocked", "failed", "observed"])
+        .nullable()
+        .optional(),
+    channel: z.string().max(1_024).nullable(),
+    channel_truncated: z.boolean().default(false),
+    direction: z
+        .enum([
+        "renderer-to-main",
+        "main-to-renderer",
+        "main-to-utility",
+        "utility-to-main",
+    ])
+        .nullable()
+        .optional(),
+    sender: z.string().max(256).nullable().optional(),
+    receiver: z.string().max(256).nullable().optional(),
+    frame: z.string().max(256).nullable().default(null),
+    target: z.string().max(256).nullable().optional(),
+    argument_shapes: z.array(z.string().max(64)).max(32),
+    argument_shapes_truncated: z.boolean().default(false),
+    result_shape: z.string().max(64).nullable(),
+    process_type: z.string().max(128).nullable(),
+    source: z.string().max(64).default("electron-active-hook"),
+    capture_method: z
+        .enum(["api-wrapper", "event-emitter", "process-hook"])
+        .default("api-wrapper"),
+    artifact_path: z.string().max(16_384).nullable().default(null),
+    artifact_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable()
+        .default(null),
+    error: z.boolean(),
+});
+const timelineEventSchema = z.strictObject({
+    sequence: z.number().int().min(1),
+    correlation_id: z.string().max(256).nullable().default(null),
+    kind: z.enum([
+        "main-handler-invocation",
+        "main-event-invocation",
+        "utility-process-fork",
+        "utility-process-message",
+        "ipc-main-to-renderer",
+        "ipc-utility-to-main",
+        "ipc-renderer-send",
+        "ipc-renderer-invoke",
+        "ipc-renderer-post-message",
+        "app-lifecycle",
+        "window-lifecycle",
+        "web-contents-lifecycle",
+        "navigation",
+        "shell-attempt",
+        "process-lifecycle",
+        "permission",
+        "popup-attempt",
+        "download",
+        "protocol",
+        "preload",
+        "native-addon",
+        "updater",
+        "error",
+    ]),
+    event: z.string().max(128).nullable(),
+    phase: z.enum(["attempted", "completed", "blocked", "failed", "observed"]),
+    channel: z.string().max(1_024).nullable(),
+    channel_truncated: z.boolean(),
+    direction: z
+        .enum([
+        "renderer-to-main",
+        "main-to-renderer",
+        "main-to-utility",
+        "utility-to-main",
+    ])
+        .nullable(),
+    sender: z.string().max(256).nullable(),
+    receiver: z.string().max(256).nullable(),
+    frame: z.string().max(256).nullable(),
+    target: z.string().max(256).nullable(),
+    argument_shapes: z.array(z.string().max(64)).max(32),
+    argument_shapes_truncated: z.boolean(),
+    result_shape: z.string().max(64).nullable(),
+    process_type: z.string().max(128).nullable(),
+    source: z.string().max(64),
+    capture_method: z.enum(["api-wrapper", "event-emitter", "process-hook"]),
+    artifact_path: z.string().max(16_384).nullable(),
+    artifact_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    error: z.boolean(),
+});
+const processMetricSchema = z.strictObject({
+    pid: z.number().int().min(1),
+    type: z.string().min(1).max(128),
+    name: z.string().max(256).nullable(),
+    service_name: z.string().max(256).nullable(),
+});
+const windowResultSchema = z.strictObject({
+    window_id: z.string().max(256),
+    web_contents_id: z.string().max(256),
+    url: z.string().max(65_536),
+    title: z.string().max(16_384),
+    visible: z.boolean().nullable(),
+    destroyed: z.boolean(),
+});
+const coverageSchema = z.strictObject({
+    status: z.enum([
+        "complete",
+        "partial_attach",
+        "capture_truncated",
+        "hook_conflict",
+        "target_exited",
+        "cleanup_failed",
+    ]),
+    observed_event_families: z.array(z.string().max(128)).max(32),
+    unavailable_event_families: z.array(z.string().max(128)).max(32),
+    observed_roles: z.array(z.string().max(128)).max(16),
+    pre_capture_activity: z.literal("unavailable"),
+});
+const actionResultSchema = z.strictObject({
+    step_id: z.string().min(1).max(128),
+    kind: z.enum([
+        "click",
+        "wait",
+        "renderer-reload",
+        "renderer-crash",
+        "deep-link",
+    ]),
+    window_index: windowIndexSchema.nullable(),
+    target: z.string().max(256).nullable(),
+    status: z.enum(["completed", "failed", "cancelled"]),
+    elapsed_ms: z.number().int().min(0),
+    error: z.string().nullable(),
+});
+/** Bounded result of a provider-owned Electron runtime experiment. */
+export const electronActiveObservationResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    application: z.strictObject({
+        executable_path: absolutePathSchema,
+        application_path: absolutePathSchema,
+        electron_version: z.string().min(1).max(256),
+        process_ownership: z.literal("provider-owned"),
+        cleanup: z.literal("terminated-owned-process"),
+    }),
+    actions: z.array(actionResultSchema).max(100),
+    windows: z.array(windowResultSchema).max(100),
+    windows_truncated: z.boolean(),
+    processes: z.strictObject({
+        items: z.array(processMetricSchema).max(100),
+        truncated: z.boolean(),
+    }),
+    ipc: z.strictObject({
+        events: z.array(ipcEventSchema).max(10_000),
+        observed: z.number().int().min(0),
+        retained: z.number().int().min(0),
+        truncated: z.boolean(),
+    }),
+    timeline: z
+        .strictObject({
+        events: z.array(timelineEventSchema).max(20_000),
+        observed: z.number().int().min(0),
+        retained: z.number().int().min(0),
+        truncated: z.boolean(),
+    })
+        .default({ events: [], observed: 0, retained: 0, truncated: false }),
+    coverage: coverageSchema.default({
+        status: "partial_attach",
+        observed_event_families: [],
+        unavailable_event_families: [],
+        observed_roles: [],
+        pre_capture_activity: "unavailable",
+    }),
+    limitations: z.array(z.string().max(4_096)).max(100),
+});

package/dist/domain/electronObservation.js

@@ -25,13 +25,10 @@ export const listElectronTargetsInputSchema = z.object({
     limit: z.number().int().min(1).max(200).default(100),
 });
 /** Input for passive structural inspection of one Electron file page. */
-export const inspectElectronPageInputSchema = z
-    .object({
+const inspectElectronPageFacts = {
     ...approvedElectronInput,
     target_id: z.string().trim().min(1).max(256),
     observation_ms: z.number().int().min(0).max(10_000).default(100),
-    include_script_sources: z.boolean().default(false),
-    source_capture_approved: z.boolean().default(false),
     limits: z
         .object({
         max_frames: z.number().int().min(1).max(1_000).default(200),
@@ -61,14 +58,21 @@ export const inspectElectronPageInputSchema = z
         max_script_source_bytes: 1_024 * 1_024,
         max_total_script_source_bytes: 4 * 1_024 * 1_024,
     }),
-})
+};
+export const inspectElectronPageInputSchema = z
+    .union([
+    z.object({
+        ...inspectElectronPageFacts,
+        include_script_sources: z.literal(false).default(false),
+        source_capture_approved: z.literal(false).default(false),
+    }),
+    z.object({
+        ...inspectElectronPageFacts,
+        include_script_sources: z.literal(true),
+        source_capture_approved: z.literal(true),
+    }),
+])
     .superRefine((input, context) => {
-    if (input.include_script_sources && !input.source_capture_approved)
-        context.addIssue({
-            code: "custom",
-            path: ["source_capture_approved"],
-            message: "Electron script source capture requires separate approval",
-        });
     if (input.limits.max_script_source_bytes >
         input.limits.max_total_script_source_bytes)
         context.addIssue({

package/dist/domain/electronStaticAnalysisValues.js

@@ -51,7 +51,10 @@ export const collectContextBridgeMembers = (node, maximum = 128) => {
             unknown: 1,
             omitted: 0,
         };
-    const state = { members: [], unknown: 0 };
+    const state = {
+        members: [],
+        unknown: 0,
+    };
     collectMembersAt(node, "", 0, state);
     const members = [...new Set(state.members)].sort(compareCodePoints);
     return {

package/dist/domain/eventProcessTree.js

@@ -0,0 +1,217 @@
+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),
+});
+const applyProcessTreeEvent = (event, state) => {
+    let node = state.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,
+                };
+                state.nodes.set(event.pid, node);
+            }
+            if (event.ppid !== null) {
+                const parentChildren = state.children.get(event.ppid) ?? [];
+                parentChildren.push(event.pid);
+                state.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)
+                    state.shortLivedDescendants++;
+            }
+            else
+                state.eventsUnmatched++;
+            break;
+        case "re_exec":
+            if (node) {
+                node.is_re_exec = true;
+                node.executable = event.executable ?? node.executable;
+                node.arguments = event.arguments;
+                state.hasReExec = true;
+            }
+            else
+                state.eventsUnmatched++;
+            break;
+        case "reparent":
+            if (node) {
+                node.previous_ppid = node.ppid;
+                node.ppid = event.ppid;
+                node.is_reparented = true;
+                state.hasReparenting = true;
+            }
+            else
+                state.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;
+    }
+};
+/** Reconstruct a process tree from event-backed capture. */
+export function reconstructProcessTree(events, rootPid) {
+    const nodes = new Map();
+    const children = new Map();
+    let eventsConsumed = 0;
+    const state = {
+        nodes,
+        children,
+        eventsUnmatched: 0,
+        hasReExec: false,
+        hasReparenting: false,
+        shortLivedDescendants: 0,
+    };
+    const sorted = [...events].sort((a, b) => a.at_ms - b.at_ms);
+    for (const event of sorted) {
+        eventsConsumed++;
+        applyProcessTreeEvent(event, state);
+    }
+    // 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: state.eventsUnmatched,
+        short_lived_descendants: state.shortLivedDescendants,
+        has_re_exec: state.hasReExec,
+        has_reparenting: state.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 (pid === undefined)
+            break;
+        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/functionComparisonNormalization.js

@@ -123,14 +123,21 @@ export const stringAndNameProjection = (snapshot) => {
         : sorted(values);
 };
 export const sorted = (values) => [...values].sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right)));
-export const combineCoverage = (left, right) => ({
-    items: [...left.items, ...right.items],
-    total: left.total === null || right.total === null
-        ? null
-        : left.total + right.total,
-    complete: left.complete && right.complete,
-    truncated: left.truncated || right.truncated,
-});
+export const combineCoverage = (left, right) => {
+    const base = {
+        items: [...left.items, ...right.items],
+        total: left.total === null || right.total === null
+            ? null
+            : left.total + right.total,
+    };
+    return left.complete && right.complete
+        ? { ...base, complete: true, truncated: false }
+        : {
+            ...base,
+            complete: false,
+            truncated: left.truncated || right.truncated,
+        };
+};
 export const project = (collection, mapper) => collection.items.map(mapper);
 export const isAutoName = (name) => /^(?:sub_[0-9a-f]+|fcn\.)/iu.test(name);
 const parseAddress = (value) => /^0x[0-9a-f]+$/iu.test(value) ? BigInt(value) : null;

package/dist/domain/functionDossierEvidence.js

@@ -109,8 +109,9 @@ const mergePseudocode = (pages) => {
     return {
         text: orderedValues(characters).join(""),
         total,
-        complete,
-        truncated: !complete,
+        ...(complete
+            ? { complete: true, truncated: false }
+            : { complete: false, truncated: true }),
     };
 };
 const mergeCollection = (pages, field) => {
@@ -140,8 +141,12 @@ const mergeCollection = (pages, field) => {
     return {
         items: orderedValues(items),
         total,
-        complete,
-        truncated: scanLimited || (!unavailable && !complete),
+        ...(complete
+            ? { complete: true, truncated: false }
+            : {
+                complete: false,
+                truncated: scanLimited || !unavailable,
+            }),
     };
 };
 const collectionOffset = (page, field) => field === "assembly"

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,