rea-agents 3.0.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

@@ -71,89 +71,90 @@ export const processTreeReconstructionSchema = z.strictObject({
     /** 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;
-    let eventsUnmatched = 0;
-    let hasReExec = false;
-    let hasReparenting = false;
-    let shortLivedDescendants = 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++;
-        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;
-        }
+        applyProcessTreeEvent(event, state);
     }
     // Attach children to nodes
     for (const [pid, childPids] of children) {
@@ -165,10 +166,10 @@ export function reconstructProcessTree(events, rootPid) {
         root_pid: rootPid,
         processes: [...nodes.values()],
         events_consumed: eventsConsumed,
-        events_unmatched: eventsUnmatched,
-        short_lived_descendants: shortLivedDescendants,
-        has_re_exec: hasReExec,
-        has_reparenting: hasReparenting,
+        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. */
@@ -179,6 +180,8 @@ export function getDescendants(processes, rootPid) {
     const queue = [rootPid];
     while (queue.length > 0) {
         const pid = queue.shift();
+        if (pid === undefined)
+            break;
         if (visited.has(pid))
             continue;
         visited.add(pid);

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"