rea-agents 5.0.0 → 6.1.0

package/dist/domain/explicitSensitiveFailure.js

@@ -0,0 +1,108 @@
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, AnalysisCapabilityUnavailableError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
+import { redactExplicitText } from "./explicitSensitiveValues.js";
+import { ProviderAdapterError } from "./providerAdapterError.js";
+import { ProviderCleanupError } from "./providerCleanupError.js";
+/** Keep a real JSON-pointer ancestor when a property identity is explicitly excluded. */
+export const redactExplicitPointer = (pointer, values) => {
+    let parent = "";
+    for (const segment of pointer.split("/").slice(1)) {
+        const decoded = segment.replaceAll("~1", "/").replaceAll("~0", "~");
+        const child = `${parent}/${segment}`;
+        if (values.some((literal) => decoded.includes(literal) || child.includes(literal)))
+            return parent;
+        parent = child;
+    }
+    return parent;
+};
+/** Exclude explicit literals from common acquisition/decoder failures, preserving typed diagnostics. */
+export const redactExplicitFailure = (error, values) => {
+    if (values.length === 0)
+        return error;
+    const text = (value) => redactExplicitText(value, values);
+    const path = (parts, ordinaryNames) => {
+        const retained = [];
+        for (const part of parts) {
+            if (typeof part !== "string") {
+                retained.push(part);
+            }
+            else if (!ordinaryNames && part.startsWith("/")) {
+                const pointer = redactExplicitPointer(part, values);
+                retained.push(pointer);
+                if (pointer !== part)
+                    break;
+            }
+            else {
+                if (values.some((literal) => part.includes(literal)))
+                    break;
+                retained.push(part);
+            }
+        }
+        return retained;
+    };
+    const diagnostics = (value) => Object.fromEntries(Object.entries(value)
+        .filter(([key]) => !values.some((literal) => key.includes(literal)))
+        .map(([key, item]) => [key, visit(item)]));
+    const visit = (value) => {
+        if (typeof value === "string")
+            return text(value);
+        if (Array.isArray(value))
+            return value.map(visit);
+        if (typeof value === "object" && value !== null)
+            return diagnostics(value);
+        return value;
+    };
+    if (error instanceof AnalysisAccessDeniedError)
+        return new AnalysisAccessDeniedError(error.operation, text(error.path), error.systemCode, { cause: error });
+    if (error instanceof AnalysisArtifactChangedError)
+        return new AnalysisArtifactChangedError(error.operation, text(error.path), text(error.reason), { cause: error });
+    if (error instanceof AnalysisInputError)
+        return new AnalysisInputError(error.operation, { cause: error }, error.issues.map((issue) => ({
+            ...issue,
+            // Unknown-argument paths contain literal field names, including names
+            // beginning with '/'; they are not producer JSON-pointer coordinates.
+            path: path(issue.path, issue.reason === "unknown_argument"),
+            ...(issue.message === undefined
+                ? {}
+                : { message: text(issue.message) }),
+            ...(issue.expected === undefined
+                ? {}
+                : { expected: visit(issue.expected) }),
+        })));
+    if (error instanceof AnalysisOutputError)
+        return new AnalysisOutputError(error.operation, text(error.reason), {
+            cause: error,
+        });
+    if (error instanceof AnalysisCapabilityUnavailableError)
+        return new AnalysisCapabilityUnavailableError(error.providerId, error.operation, text(error.reason), {
+            cause: error,
+            ...(error.userMessage === undefined
+                ? {}
+                : { userMessage: text(error.userMessage) }),
+        });
+    if (error instanceof AnalysisResourceConstraintError)
+        return new AnalysisResourceConstraintError(error.operation, error.resource, text(error.reason), error.reportedLimits === null ? null : diagnostics(error.reportedLimits), {
+            cause: error,
+            ...(error.remediationAction === undefined
+                ? {}
+                : { remediationAction: text(error.remediationAction) }),
+            ...(error.capturedOutput === undefined
+                ? {}
+                : {
+                    capturedOutput: {
+                        stdout: text(error.capturedOutput.stdout),
+                        stderr: text(error.capturedOutput.stderr),
+                        truncated: error.capturedOutput.truncated,
+                    },
+                }),
+        });
+    if (error instanceof ProviderCleanupError)
+        return new ProviderCleanupError(error.providerId, error.cleanupResources.map(text), diagnostics(error.diagnostics ?? {}), { operation: error.operation, cause: error });
+    if (error instanceof ProviderAdapterError)
+        return new ProviderAdapterError(error.providerId, error.operation, {
+            cause: error,
+            ...(error.diagnostics === undefined
+                ? {}
+                : { diagnostics: diagnostics(error.diagnostics) }),
+        });
+    return error;
+};

package/dist/domain/explicitSensitiveValues.js

@@ -0,0 +1,10 @@
+/** Replace caller-declared literal text values without guessing sensitivity from names. */
+export const redactExplicitText = (value, sensitiveValues) => {
+    const literals = [...new Set(sensitiveValues)].filter((literal) => literal !== "");
+    const replacement = ["[REDACTED]", "…", ""].find((candidate) => literals.every((literal) => !candidate.includes(literal))) ?? "";
+    let result = value;
+    for (const literal of literals.sort((left, right) => right.length - left.length))
+        result = result.replaceAll(literal, replacement);
+    // Replacement boundaries can form another declaration; exclude that text.
+    return literals.some((literal) => result.includes(literal)) ? "" : result;
+};

package/dist/domain/firmware/firmwareAnalysis.js

@@ -1,19 +1,25 @@
 import { z } from "zod";
 import { digestSchema } from "../digests.js";
 import { jsonValueSchema } from "../jsonValue.js";
+import { isAbsoluteLocalPath, localPathStringSchema } from "../localPath.js";
 const bytes = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
 const range = z.strictObject({ offset: bytes, length: bytes.positive() });
 const target = {
-    path: z.string().min(1).describe("Local firmware file; never executed"),
+    path: localPathStringSchema
+        .refine(isAbsoluteLocalPath, {
+        message: "path must be an absolute local filesystem path (for example /tmp/firmware.bin or C:\\firmware\\firmware.bin)",
+    })
+        .describe("Absolute local firmware file; never executed. Relative paths are rejected."),
 };
 /** Explicit firmware inspection and extraction intent, independent of engines. */
 export const firmwareInputSchemas = {
     inspect_firmware_regions: z.strictObject(target),
     extract_firmware: z.strictObject({
         ...target,
-        output_directory: z
-            .string()
-            .min(1)
+        output_directory: localPathStringSchema
+            .refine(isAbsoluteLocalPath, {
+            message: "output_directory must be an absolute local filesystem path",
+        })
             .describe("Absolute, absent output directory; parent must exist"),
         range: range
             .optional()

package/dist/domain/hopperErrors.js

@@ -9,13 +9,19 @@ export class HopperTimeoutError extends HopperError {
     operation;
     requestId;
     providerState;
+    stage;
+    launcherOutcome;
     _tag = "HopperTimeoutError";
-    constructor(timeoutMs, operation, requestId, providerState = "not_started") {
+    constructor(timeoutMs, operation, requestId, providerState = "not_started", stage = operation === undefined
+        ? "launch"
+        : "analysis", launcherOutcome) {
         super(`Hopper ${operation === undefined ? "startup" : operation} timed out after ${String(timeoutMs)}ms`);
         this.timeoutMs = timeoutMs;
         this.operation = operation;
         this.requestId = requestId;
         this.providerState = providerState;
+        this.stage = stage;
+        this.launcherOutcome = launcherOutcome;
     }
 }
 /** The caller cancelled a Hopper operation before it completed. */
@@ -51,18 +57,31 @@ export class HopperProcessError extends HopperError {
     diagnostic;
     operation;
     requestId;
+    launcherFailure;
     _tag = "HopperProcessError";
     failureCode;
     userMessage;
-    constructor(exitCode, diagnostic, operation, requestId) {
+    providerState;
+    stage;
+    constructor(exitCode, diagnostic, operation, requestId, providerState, stage, launcherFailure) {
         super(`Hopper bridge stopped unexpectedly with code ${String(exitCode)}`);
         this.exitCode = exitCode;
         this.diagnostic = diagnostic;
         this.operation = operation;
         this.requestId = requestId;
+        this.launcherFailure = launcherFailure;
         const failure = hopperStartupFailure(exitCode);
+        this.stage =
+            stage ??
+                (failure === undefined
+                    ? operation === undefined
+                        ? "connection"
+                        : "analysis"
+                    : "launch");
         this.failureCode = failure?.code;
         this.userMessage = failure?.message;
+        this.providerState =
+            providerState ?? (exitCode === null ? "unknown" : "exited");
     }
 }
 /** Hopper or the repository bridge could not be started. */
@@ -70,9 +89,11 @@ export class HopperStartError extends HopperError {
     _tag = "HopperStartError";
     userMessage;
     ownerRunId;
+    launcherFailure;
     constructor(options) {
         super("Hopper application bridge could not be started", options);
         this.userMessage = options?.userMessage;
         this.ownerRunId = options?.ownerRunId;
+        this.launcherFailure = options?.launcherFailure;
     }
 }

package/dist/domain/hopperValues.js

@@ -39,6 +39,34 @@ const segmentSchema = z.object({
 const unavailableAnalysisFactSchema = z
     .object({ available: z.literal(false), reason: z.string() })
     .strict();
+/** Typed string evidence shared by inventories and referenced function literals. */
+export const analysisStringSchema = z.object({
+    address: z.string(),
+    value: z.string(),
+    provider_value: z
+        .string()
+        .exactOptional()
+        .describe("Original provider display text, which may shorten the typed object."),
+    decoding: unavailableAnalysisFactSchema
+        .exactOptional()
+        .describe("When present, value retains native display text because typed bytes could not be decoded."),
+    string: z
+        .object({
+        encoding: z.string().min(1),
+        encoding_status: z
+            .enum(["observed", "inferred"])
+            .exactOptional()
+            .describe("Whether the provider declares the encoding or REA infers it from the typed bytes and native display. This does not establish the original source's intended encoding."),
+        termination: z.enum(["missing", "present_or_not_required"]),
+        byte_length: z.number().int().min(0),
+    })
+        .exactOptional(),
+});
+/** An analyzed bookmark retains a missing provider label as null. */
+export const analysisBookmarkSchema = z.strictObject({
+    address: z.string(),
+    name: z.string().nullable(),
+});
 /** Complete observed function-body ranges; every range endpoint is inclusive. */
 export const functionBodySchema = z.discriminatedUnion("available", [
     unavailableAnalysisFactSchema,
@@ -163,6 +191,13 @@ export const localVariableSchema = z
     .object({
     description: z.string(),
     provenance: z.string().min(1),
+    name: z.string().nullable().exactOptional(),
+    stack_displacement: z
+        .string()
+        .regex(/^-?\d+$/u)
+        .nullable()
+        .exactOptional()
+        .describe("Observed signed stack byte displacement, encoded as decimal to preserve precision."),
 })
     .strict();
 /** Provider-neutral complete raw-instruction list for one analyzed function. */
@@ -197,13 +232,26 @@ export const referenceKindSchema = z.discriminatedUnion("available", [
     unavailableAnalysisFactSchema,
     availableReferenceKindSchema,
 ]);
-const referenceEdgeSchema = z
+/** Reported call sites without resolved targets; unreported dispatch stays unknown. */
+export const unresolvedCallSchema = z.strictObject({
+    address: z.string(),
+    reason: z.string(),
+});
+/** Observed endpoints with complete or partial reference classification evidence. */
+export const referenceEdgeSchema = z
     .object({
     source_address: z.string(),
     target_address: z.string(),
     source_procedure: procedureIdentitySchema.nullable(),
     target_procedure: procedureIdentitySchema.nullable(),
     kind: referenceKindSchema,
+    call: z
+        .strictObject({
+        classification: z.enum(["none", "unknown", "direct", "objective_c"]),
+        provider_type: z.number().int(),
+        provenance: z.string().min(1),
+    })
+        .exactOptional(),
 })
     .strict();
 export const functionDossierSchema = z
@@ -225,13 +273,8 @@ export const functionDossierSchema = z
     callees: z.array(procedureIdentitySchema),
     incoming_references: z.array(referenceEdgeSchema),
     outgoing_references: z.array(referenceEdgeSchema),
-    referenced_strings: z.array(z
-        .object({
-        address: z.string(),
-        value: z.string(),
-        source_address: z.string(),
-    })
-        .strict()),
+    unresolved_calls: z.array(unresolvedCallSchema).exactOptional(),
+    referenced_strings: z.array(analysisStringSchema.extend({ source_address: z.string() })),
     referenced_names: z.array(z
         .object({
         address: z.string(),

package/dist/domain/immutableJson.js

@@ -0,0 +1,114 @@
+const immutableSnapshots = new WeakSet();
+/** Recognize an owned JSON snapshot sealed by this module, or an immutable scalar. */
+export const isImmutableJsonSnapshot = (value) => value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value)) ||
+    (typeof value === "object" && immutableSnapshots.has(value));
+/** Seal an already parsed, owned JSON snapshot for immutable zero-copy reuse. */
+export const freezeJsonSnapshot = (value) => {
+    const pending = [{ value, exiting: false }];
+    // These sets exist only during traversal, while the owned root already
+    // retains every child. Strong sets avoid per-node ephemeron GC work.
+    const visited = new Set();
+    const ancestors = new Set();
+    const objects = [];
+    while (pending.length > 0) {
+        const entry = pending.pop();
+        if (entry === undefined)
+            break;
+        const item = entry.value;
+        if (entry.exiting && typeof item === "object" && item !== null) {
+            ancestors.delete(item);
+            visited.add(item);
+            objects.push(item);
+            continue;
+        }
+        if (isImmutableJsonSnapshot(item))
+            continue;
+        if (typeof item !== "object" || item === null)
+            throw new TypeError("Immutable JSON snapshots require JSON values");
+        if (ancestors.has(item))
+            throw new TypeError("Immutable JSON snapshots cannot contain circular references");
+        if (visited.has(item))
+            continue;
+        ancestors.add(item);
+        pending.push({ value: item, exiting: true });
+        pushSnapshotChildren(item, pending);
+    }
+    // Register only after every value is checked and every object is frozen.
+    // An arbitrary Object.freeze call cannot forge this snapshot identity.
+    for (const item of objects)
+        Object.freeze(item);
+    // Register the requested root, rather than retaining weak entries for every
+    // nested object. Sealing an Evidence or bundle skips previously sealed roots.
+    if (typeof value === "object" && value !== null)
+        immutableSnapshots.add(value);
+    return value;
+};
+/**
+ * Seal exclusively owned JSON in bounded steps, authenticating only completion.
+ * Abandonment or failure can leave the provisional input partly frozen.
+ */
+export function* freezeOwnedJsonSnapshotSteps(value) {
+    const pending = [{ value, exiting: false }];
+    const visited = new Set();
+    const ancestors = new Set();
+    let examined = 0;
+    try {
+        while (pending.length > 0) {
+            if (examined++ === 4096) {
+                examined = 0;
+                yield;
+            }
+            const entry = pending.pop();
+            if (entry === undefined)
+                break;
+            const item = entry.value;
+            if (entry.exiting && typeof item === "object" && item !== null) {
+                ancestors.delete(item);
+                visited.add(item);
+                continue;
+            }
+            if (isImmutableJsonSnapshot(item))
+                continue;
+            if (typeof item !== "object" || item === null)
+                throw new TypeError("Immutable JSON snapshots require JSON values");
+            if (ancestors.has(item))
+                throw new TypeError("Immutable JSON snapshots cannot contain circular references");
+            if (visited.has(item))
+                continue;
+            ancestors.add(item);
+            pending.push({ value: item, exiting: true });
+            pushSnapshotChildren(item, pending);
+            // Lock every inspected edge before the scheduler can release control.
+            Object.freeze(item);
+        }
+        if (typeof value === "object" && value !== null)
+            immutableSnapshots.add(value);
+        return value;
+    }
+    finally {
+        pending.length = 0;
+        visited.clear();
+        ancestors.clear();
+    }
+}
+const pushSnapshotChildren = (item, pending) => {
+    const prototype = Object.getPrototypeOf(item);
+    if (!Array.isArray(item) &&
+        prototype !== Object.prototype &&
+        prototype !== null)
+        throw new TypeError("Immutable JSON snapshots require ordinary objects");
+    if (Array.isArray(item))
+        for (let index = 0; index < item.length; index += 1)
+            if (!Object.hasOwn(item, index))
+                throw new TypeError("Immutable JSON snapshots cannot contain sparse arrays");
+    for (const key of Object.getOwnPropertyNames(item)) {
+        const descriptor = Object.getOwnPropertyDescriptor(item, key);
+        if (descriptor === undefined || !Object.hasOwn(descriptor, "value"))
+            throw new TypeError("Immutable JSON snapshots cannot contain accessors");
+        const child = descriptor.value;
+        pending.push({ value: child, exiting: false });
+    }
+};

package/dist/domain/inputIssueProjection.js

@@ -1,3 +1,6 @@
+import { AnalysisInputError, } from "./analysisErrorCore.js";
+/** Build the standard application input error while retaining schema causes and extra semantic issues. */
+export const analysisInputErrorFromIssues = (operation, issues, input, options = {}) => new AnalysisInputError(operation, options.cause === undefined ? undefined : { cause: options.cause }, [...projectInputIssues(issues, input), ...(options.additionalIssues ?? [])]);
 /** Project Zod failures to secret-safe caller correction metadata. */
 export const projectInputIssues = (issues, input) => issues.flatMap((issue) => projectIssue(issue, input));
 const projectIssue = (issue, input) => {

package/dist/domain/javascript/electronActiveObservation.js

@@ -1,5 +1,8 @@
 import { z } from "zod";
-const pathInputSchema = z.string().trim().min(1);
+import { isAbsoluteLocalPath, localPathStringSchema } from "../localPath.js";
+const pathInputSchema = localPathStringSchema.refine(isAbsoluteLocalPath, {
+    message: "Electron executable, application, and root paths must be absolute local filesystem paths (for example /Applications/Electron.app/Contents/MacOS/Electron)",
+});
 const absolutePathSchema = z
     .string()
     .min(1)
@@ -52,10 +55,14 @@ const actionSchema = z.discriminatedUnion("kind", [
 ]);
 /** Input for one explicit, provider-owned Electron runtime experiment. */
 export const electronActiveObservationInputSchema = z.strictObject({
-    executable_path: pathInputSchema,
-    application_path: pathInputSchema,
-    application_root: pathInputSchema.optional(),
-    args: z.array(z.string()).default([]),
+    executable_path: pathInputSchema.describe("Absolute local filesystem path for the Electron executable; relative paths are rejected."),
+    application_path: pathInputSchema.describe("Absolute local filesystem path for the Electron application; relative paths are rejected."),
+    application_root: pathInputSchema
+        .optional()
+        .describe("Absolute local filesystem root for application-relative paths; omit to derive it from the application path. Relative paths are rejected."),
+    args: z
+        .array(z.string().regex(/^[^\0]*$/u, "Electron arguments must not contain NUL"))
+        .default([]),
     actions: z.array(actionSchema).default([]),
 });
 const ipcEventSchema = z.strictObject({
@@ -230,13 +237,37 @@ export const electronActiveObservationResultSchema = z.strictObject({
     ipc: z.strictObject({
         events: z.array(ipcEventSchema),
         observed: z.number().int().min(0),
+        dropped: z.number().int().min(0).nullable().default(null),
     }),
     timeline: z
         .strictObject({
         events: z.array(timelineEventSchema),
         observed: z.number().int().min(0),
+        dropped: z.number().int().min(0).nullable().default(null),
+    })
+        .default({ events: [], observed: 0, dropped: null }),
+    retention: z
+        .strictObject({
+        budget_bytes: z.number().int().min(0),
+        estimated_retained_bytes: z.number().int().min(0),
+        event_serialized_byte_upper_bound: z.number().int().min(0),
+        retained: z.number().int().min(0),
+        dropped: z.number().int().min(0),
+        dropped_event_families: z.array(z.strictObject({
+            family: z.string().min(1),
+            count: z.number().int().min(1),
+        })),
+        dropped_event_roles: z.array(z.strictObject({
+            role: z.string().min(1),
+            count: z.number().int().min(1),
+        })),
+        observed_ipc: z.number().int().min(0),
+        dropped_ipc: z.number().int().min(0),
+        observed_runtime: z.number().int().min(0),
+        dropped_runtime: z.number().int().min(0),
     })
-        .default({ events: [], observed: 0 }),
+        .nullable()
+        .default(null),
     coverage: coverageSchema.default({
         status: "partial_attach",
         observed_event_families: [],

package/dist/domain/javascript/electronStaticAnalysisValues.js

@@ -1,6 +1,6 @@
 import * as t from "@babel/types";
 import { compareCodePoints } from "../canonicalOrdering.js";
-import { semanticStaticPropertyName } from "./javascriptAstValues.js";
+import { readExactJavaScriptLiteral, semanticStaticPropertyName, } from "./javascriptAstValues.js";
 import { sourceSlice } from "./javascriptStaticAnalysisHelpers.js";
 /** Preserve one literal value or the exact inert expression. */
 export const electronStaticValue = (source, node) => {
@@ -101,17 +101,11 @@ const collectMembersAt = (object, prefix, depth, state) => {
     }
 };
 const literalValue = (node) => {
-    if (t.isStringLiteral(node) || t.isNumericLiteral(node))
-        return { found: true, value: node.value };
-    if (t.isBooleanLiteral(node))
-        return { found: true, value: node.value };
-    if (t.isNullLiteral(node))
-        return { found: true, value: null };
-    if (t.isTemplateLiteral(node) && node.expressions.length === 0)
-        return {
-            found: true,
-            value: node.quasis[0]?.value.cooked ?? node.quasis[0]?.value.raw ?? "",
-        };
+    if (node === null || node === undefined)
+        return { found: false };
+    const literal = readExactJavaScriptLiteral(node);
+    if (literal.found)
+        return literal;
     if (t.isUnaryExpression(node, { operator: "-" }) &&
         t.isNumericLiteral(node.argument))
         return { found: true, value: -node.argument.value };

package/dist/domain/javascript/htmlArtifactReferences.js

@@ -0,0 +1,40 @@
+import { defaultTreeAdapter, parse, } from "parse5";
+/** Extract inert HTML script references and the first document base href. */
+export const htmlArtifactReferences = (text) => {
+    const pending = [
+        parse(text, { sourceCodeLocationInfo: true }),
+    ];
+    const scripts = [];
+    let baseHref = null;
+    while (pending.length > 0) {
+        const node = pending.pop();
+        if (node === undefined)
+            continue;
+        if (defaultTreeAdapter.isElementNode(node) &&
+            node.namespaceURI === "http://www.w3.org/1999/xhtml") {
+            if (node.tagName === "base" && baseHref === null) {
+                const href = node.attrs.find(({ name }) => name === "href");
+                if (href !== undefined)
+                    baseHref = href.value;
+            }
+            if (node.tagName === "script") {
+                const src = node.attrs.find(({ name }) => name === "src");
+                const location = node.sourceCodeLocation?.startTag;
+                if (src !== undefined && src.value !== "" && location !== undefined) {
+                    scripts.push({
+                        scriptPath: src.value,
+                        startOffset: location.startOffset,
+                        endOffset: location.endOffset,
+                    });
+                }
+            }
+        }
+        // Template content belongs to a separate inert document fragment. Only
+        // traverse the actual document children, without recursion on deep input.
+        if ("childNodes" in node) {
+            for (const child of node.childNodes.toReversed())
+                pending.push(child);
+        }
+    }
+    return { baseHref, scripts };
+};