rea-agents 6.0.0 → 6.1.0

package/dist/native/LldbRetainedObservations.js

@@ -0,0 +1,178 @@
+import { open } from "node:fs/promises";
+import { nativeCallEventSchema } from "../domain/native/nativeCallObservation.js";
+/** Maximum journal size enforced by the LLDB bridge. */
+export const LLDB_OBSERVATION_JOURNAL_MAX_BYTES = 8 * 1024 * 1024;
+const MAX_CAPTURE_BYTES = 1024 * 1024;
+/** Join safely retained journal and process evidence into its failure contract. */
+export const projectLldbPartialObservation = (input) => ({
+    kind: "native-call-observation",
+    target: input.target,
+    process: {
+        pid: input.pid ?? null,
+        stdout: input.stdout,
+        stderr: input.stderr,
+        other_stops: input.journal.otherStops,
+    },
+    debugger: { version: input.version },
+    events: input.journal.events,
+    coverage: { status: "partial", reason: input.reason },
+    limitations: [
+        "The LLDB run did not produce a complete native call observation result.",
+        "The target SHA-256 identifies the selected artifact; LLDB did not verify the bytes loaded into the process.",
+        "Captured output byte counts are observed lower bounds because LLDB did not report final stream counters.",
+        ...input.journal.limitations,
+        ...(input.journalLimitations ?? []),
+        ...(input.limitations ?? []),
+        ...(input.pid === undefined ? ["The target PID was unavailable."] : []),
+        ...(input.stdout === null
+            ? ["The target stdout capture was unavailable."]
+            : []),
+        ...(input.stderr === null
+            ? ["The target stderr capture was unavailable."]
+            : []),
+    ],
+});
+/** Parse completed JSONL records while retaining valid records around bad ones. */
+export const parseLldbObservationJournal = (bytes) => {
+    const completeText = Buffer.from(bytes).toString("utf8");
+    const newline = completeText.lastIndexOf("\n");
+    const hasTornTail = newline !== completeText.length - 1;
+    const events = [];
+    const otherStops = [];
+    const limitations = [];
+    let malformedCount = 0;
+    let firstMalformedRow;
+    let start = 0;
+    let rowNumber = 0;
+    while (start <= newline && newline >= 0) {
+        const end = completeText.indexOf("\n", start);
+        if (end < 0 || end > newline)
+            break;
+        const line = completeText.slice(start, end);
+        start = end + 1;
+        if (line.length === 0)
+            continue;
+        rowNumber += 1;
+        const markMalformed = () => {
+            malformedCount += 1;
+            firstMalformedRow ??= rowNumber;
+        };
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            markMalformed();
+            continue;
+        }
+        if (typeof row !== "object" ||
+            row === null ||
+            !("kind" in row) ||
+            typeof row.kind !== "string") {
+            markMalformed();
+            continue;
+        }
+        if (row.kind === "event" && "event" in row) {
+            const event = nativeCallEventSchema.safeParse(row.event);
+            if (event.success)
+                events.push(event.data);
+            else
+                markMalformed();
+        }
+        else if (row.kind === "other-stop" &&
+            "reason" in row &&
+            typeof row.reason === "string") {
+            otherStops.push(row.reason);
+        }
+        else {
+            markMalformed();
+        }
+    }
+    if (malformedCount > 0)
+        limitations.push(`${malformedCount} observation journal row(s) were malformed or invalid and ignored (first at row ${String(firstMalformedRow)}).`);
+    if (hasTornTail)
+        limitations.push("The final observation journal record was incomplete and was ignored.");
+    return { events, otherStops, limitations };
+};
+/** Keep reading a bounded prefix across short reads until EOF or the bound. */
+export const readBoundedPrefix = async (requestedBytes, readChunk) => {
+    const buffer = Buffer.alloc(requestedBytes);
+    let bytesRead = 0;
+    while (bytesRead < requestedBytes) {
+        const count = await readChunk(buffer, bytesRead, requestedBytes - bytesRead, bytesRead);
+        if (count === 0)
+            break;
+        if (count > requestedBytes - bytesRead)
+            throw new Error("The bounded read returned more bytes than requested");
+        bytesRead += count;
+    }
+    return { buffer, bytesRead };
+};
+const readPrefix = (handle, requestedBytes) => readBoundedPrefix(requestedBytes, async (buffer, offset, length, position) => (await handle.read(buffer, offset, length, position)).bytesRead);
+/** Read at most the bridge's journal bound, checking size before allocation. */
+export const readLldbObservationJournal = async (path) => {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        const { size } = await handle.stat();
+        const length = Math.min(size, LLDB_OBSERVATION_JOURNAL_MAX_BYTES);
+        const { buffer, bytesRead } = await readPrefix(handle, length);
+        const parsed = parseLldbObservationJournal(buffer.subarray(0, bytesRead));
+        const limitations = [
+            ...(size > LLDB_OBSERVATION_JOURNAL_MAX_BYTES
+                ? [
+                    "The observation journal exceeded 8 MiB; only its bounded prefix was read.",
+                ]
+                : []),
+            ...(bytesRead < length
+                ? [
+                    "The observation journal became shorter while being read; the available prefix was parsed.",
+                ]
+                : []),
+        ];
+        return {
+            parsed,
+            limitations,
+        };
+    }
+    catch (cause) {
+        return {
+            parsed: { events: [], otherStops: [], limitations: [] },
+            limitations: [
+                `The observation journal could not be read: ${cause instanceof Error ? cause.message : String(cause)}`,
+            ],
+        };
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+/** Retain an available output prefix without claiming an unreported total. */
+export const readPartialCapture = async (path) => {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        const { size } = await handle.stat();
+        const length = Math.min(size, MAX_CAPTURE_BYTES);
+        const { buffer, bytesRead } = await readPrefix(handle, length);
+        return {
+            capture: {
+                text: buffer.subarray(0, bytesRead).toString("utf8"),
+                bytes: Math.max(size, bytesRead),
+                truncated: true,
+                complete: false,
+            },
+            limitations: bytesRead < length
+                ? [
+                    "A target output capture became shorter while being read; its retained prefix may be incomplete.",
+                ]
+                : [],
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};

package/dist/native/NativeCallObservation.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { open } from "node:fs/promises";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
 import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { nativeCallObservationInputSchema, nativeCallObservationResultSchema, } from "../domain/native/nativeCallObservation.js";
 import { err, ok } from "../domain/result.js";
 const OPERATION = "observe_native_calls";
@@ -15,26 +16,42 @@ export const NATIVE_CALL_OBSERVATION_LIMITATIONS = [
     "The observation window is checked about once a second, and recording pauses the process at every entry, which slows it.",
 ];
 /** Launch the active Mach-O under LLDB, record requested call entries, then stop it. */
-export const observeNativeCalls = async (target, parameters, tracer, signal) => {
+export const observeNativeCalls = async (target, parameters, tracer, signal, readTargetDigest = fileSha256) => {
     if (target.kind !== "executable" || target.format !== "mach-o")
         return err(new AnalysisCapabilityUnavailableError("native-macos", OPERATION, "Native call observation launches a Mach-O executable; the active target is not one"));
     const parsed = nativeCallObservationInputSchema.safeParse(parameters);
     if (!parsed.success)
         return err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
     // Observe the bytes the session's other Evidence describes.
-    if ((await fileSha256(target.path, signal)) !== target.sha256)
+    let digest;
+    try {
+        digest = await readTargetDigest(target.path, signal);
+    }
+    catch (cause) {
+        if (signal?.aborted === true || isAbortError(cause))
+            return err(new AnalysisCancelledError(OPERATION));
+        return err(new ProviderAdapterError("native-macos", OPERATION, {
+            diagnostics: {
+                reason: "Unable to verify the selected target digest",
+                detail: cause instanceof Error ? cause.message : String(cause),
+            },
+        }));
+    }
+    if (digest !== target.sha256)
         return err(new EvidenceIntegrityError("Native call observation target digest changed after session binding"));
     if (signal?.aborted === true)
         return err(new AnalysisCancelledError(OPERATION));
     const traced = await tracer.trace({
         executable: target.path,
         architecture: target.architecture,
+        expectedSha256: target.sha256,
         input: parsed.data,
     }, signal);
     if (!traced.ok)
         return traced;
     return ok(projectNativeCalls(target, parsed.data, traced.value));
 };
+const isAbortError = (cause) => cause instanceof Error && cause.name === "AbortError";
 /** Join the request, the tracer's run and REA's own checks into the result contract. */
 export const projectNativeCalls = (target, input, trace) => {
     const { run } = trace;
@@ -42,14 +59,31 @@ export const projectNativeCalls = (target, input, trace) => {
         .filter(({ location_count: count }) => count === 0)
         .map(({ index }) => index);
     const eventLimit = run.outcome === "event-limit";
-    const partial = eventLimit || run.outcome === "stop-limit" || unresolved.length > 0;
+    const resourceLimit = run.outcome === "resource-limit";
+    const breakpointLocationLimit = run.breakpoint_locations_truncated === true;
+    const partial = eventLimit ||
+        resourceLimit ||
+        breakpointLocationLimit ||
+        run.outcome === "duration-elapsed" ||
+        run.outcome === "stop-limit" ||
+        unresolved.length > 0;
     return nativeCallObservationResultSchema.parse({
         target: {
             path: target.path,
             sha256: target.sha256,
             architecture: target.architecture,
             arguments: input.arguments,
+            environment: input.environment,
             working_directory: input.working_directory ?? null,
+            launch_identity: {
+                loaded_image_sha256: run.target_identity.loaded_image_sha256,
+                file_device: run.target_identity.file_device,
+                file_inode: run.target_identity.file_inode,
+                selected_file_sha256: run.target_identity.selected_file_sha256,
+                module_path: run.target_identity.module_path,
+                module_uuid: run.target_identity.module_uuid,
+                stable: run.target_identity.stable,
+            },
         },
         debugger: trace.debugger,
         process: {
@@ -75,20 +109,35 @@ export const projectNativeCalls = (target, input, trace) => {
         coverage: {
             status: partial ? "partial" : "complete",
             event_limit_reached: eventLimit,
+            resource_limit_reached: resourceLimit,
+            ...(breakpointLocationLimit
+                ? { breakpoint_locations_truncated: true }
+                : {}),
             unresolved_breakpoints: unresolved,
         },
         limitations: [
             ...NATIVE_CALL_OBSERVATION_LIMITATIONS,
+            "The selected pathname digest and LLDB module identity are checked around launch. No immutable executable snapshot is used; concurrent in-place mutation or replacement and restoration cannot be ruled out, so the loaded-image digest remains unknown.",
             ...(eventLimit
                 ? [
                     `Observation stopped at max_events (${input.max_events}); later calls were not recorded and the process was killed.`,
                 ]
                 : []),
+            ...(resourceLimit
+                ? [
+                    "Observation stopped before retaining the next complete event because the estimated 8 MiB trace-payload or 65,536-frame aggregate budget was reached; the process was killed.",
+                ]
+                : []),
             ...(run.outcome === "duration-elapsed"
                 ? [
                     `The process was still running after duration_ms (${input.duration_ms}) and was killed.`,
                 ]
                 : []),
+            ...(run.target_identity.stable
+                ? []
+                : [
+                    "LLDB did not provide enough module identity evidence to confirm pathname and module continuity around launch.",
+                ]),
             ...(run.outcome === "stop-limit"
                 ? [
                     "Observation stopped after repeated signal or exception stops; the process was killed.",
@@ -104,9 +153,19 @@ export const projectNativeCalls = (target, input, trace) => {
                     "Breakpoints with many matching locations list only the first 64; location_count gives the total.",
                 ]
                 : []),
+            ...(breakpointLocationLimit
+                ? [
+                    "Resolved breakpoint locations exceeded the aggregate 8 MiB metadata budget; omitted locations are counted in location_count. This metadata limit does not change the process outcome.",
+                ]
+                : []),
             ...(trace.stdout.truncated || trace.stderr.truncated
                 ? ["Target output beyond 1 MiB per stream is counted but not kept."]
                 : []),
+            ...(!trace.stdout.complete || !trace.stderr.complete
+                ? [
+                    "Target output draining did not complete; reported byte counts are observed lower bounds, not stream totals.",
+                ]
+                : []),
             ...(run.terminated && trace.terminated
                 ? []
                 : [

package/dist/native/NativeMacOSProvider.js

@@ -9,7 +9,7 @@ import { open, realpath, stat } from "node:fs/promises";
 import { z } from "zod";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { NATIVE_TOOL_CONTRACTS, } from "../contracts/native/nativeToolContracts.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
@@ -17,7 +17,8 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
 import { omittedPrototypeKeysLimitation, parseXmlPropertyList, } from "../domain/propertyListKeys.js";
 import { demangleSwiftSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/native/nativeInspection.js";
 import { err, ok } from "../domain/result.js";
-import { NativeCommandFailure, XcrunCommandRunner, } from "./CommandRunner.js";
+import { NATIVE_COMMAND_TIMEOUT_MS, NATIVE_COMMAND_OUTPUT_BUDGET_BYTES, NativeCommandFailure, XcrunCommandRunner, } from "./CommandRunner.js";
+import { withSignatureTarget, verifySignatureTarget, } from "./SignatureTargetBinding.js";
 import { parseCodeSignature } from "./parsers/codesign.js";
 import { parseDemangledSymbols } from "./parsers/demangle.js";
 import { parseLipoArchitectures } from "./parsers/lipo.js";
@@ -192,20 +193,23 @@ class NativeMacOSClient {
         });
     }
     async #inspectSignature(signal) {
-        const display = await this.#run("inspect_signature", "codesign", ["-d", "--verbose=4", this.target.path], { signal, acceptNonZero: true });
+        return withSignatureTarget(this.target, (binding) => this.#inspectBoundSignature(binding, signal), signal);
+    }
+    async #inspectBoundSignature(binding, signal) {
+        const display = await this.#captureSignature(binding, ["-d", "--verbose=4"], signal);
         if (!display.ok)
             return display;
         const unsigned = isNonzeroUnsignedObservation(display.value);
         const displayFailure = codeSignCaptureFailure(display.value);
         if (displayFailure !== null)
             return err(displayFailure);
-        const requirements = await this.#run("inspect_signature", "codesign", ["-d", "-r-", this.target.path], { signal, acceptNonZero: true });
+        const requirements = await this.#captureSignature(binding, ["-d", "-r-"], signal);
         if (!requirements.ok)
             return requirements;
         const requirementsFailure = codeSignCaptureFailure(requirements.value);
         if (requirementsFailure !== null)
             return err(requirementsFailure);
-        const entitlements = await this.#run("inspect_signature", "codesign", ["-d", "--entitlements", ":-", this.target.path], { signal, acceptNonZero: true });
+        const entitlements = await this.#captureSignature(binding, ["-d", "--entitlements", ":-"], signal);
         if (!entitlements.ok)
             return entitlements;
         const entitlementsFailure = codeSignCaptureFailure(entitlements.value);
@@ -213,8 +217,8 @@ class NativeMacOSClient {
             return err(entitlementsFailure);
         // codesign echoes the resolved executable path in its diagnostics.
         const parsed = parseCodeSignature(display.value.stderr, unsigned, [
-            this.target.path,
-            ...(await canonicalPath(this.target.path)),
+            binding.snapshotPath,
+            ...(await canonicalPath(binding.snapshotPath)),
         ]);
         // The requirement is printed to stdout; stderr echoes the path.
         const requirementText = /designated\s*=>\s*(.+)$/mu.exec(requirements.value.stdout)?.[1] ?? null;
@@ -223,6 +227,7 @@ class NativeMacOSClient {
         const captures = [display.value, requirements.value, entitlements.value];
         const limitations = [
             ...parsed.limitations,
+            "Inspected a digest-verified Mach-O byte snapshot; filesystem-bound signing context and trust validation are not examined.",
             ...(entitlementValue.omittedPrototypeKeys === 0
                 ? []
                 : [
@@ -233,13 +238,19 @@ class NativeMacOSClient {
             (isNonzeroUnsignedObservation(requirements.value) ||
                 isNonzeroUnsignedObservation(entitlements.value));
         if (mixedSigning) {
-            const slices = await this.#inspectMixedSignatureSlices(parsed.format, requirements.value.exitCode !== 0, entitlements.value.exitCode !== 0, signal);
+            const slices = await this.#inspectMixedSignatureSlices(binding, parsed.format, {
+                requirements: requirements.value.exitCode,
+                entitlements: entitlements.value.exitCode,
+            }, signal);
             if (!slices.ok)
                 return slices;
             captures.push(...slices.value.captures);
             limitations.push(...slices.value.limitations);
         }
-        const provenance = captures.map((capture) => invocation(capture, this.target.path));
+        const provenance = captures.map((capture) => invocation(capture, binding.snapshotPath));
+        const version = await verifySignatureTarget(this.target, binding, signal);
+        if (!version.ok)
+            return version;
         const result = inspectSignatureSchema.parse({
             ...parsed,
             designated_requirement: requirementText,
@@ -254,12 +265,12 @@ class NativeMacOSClient {
             locations: [],
         });
     }
-    async #inspectMixedSignatureSlices(format, requirementsUnavailable, entitlementsUnavailable, signal) {
+    async #inspectMixedSignatureSlices(binding, format, aggregateExits, signal) {
         const captures = [];
         const unsigned = [];
         const unclassified = [];
         for (const architecture of codeSignArchitectures(format, this.target)) {
-            const slice = await this.#run("inspect_signature", "codesign", ["-d", "-a", architecture, "--verbose=4", this.target.path], { signal, acceptNonZero: true });
+            const slice = await this.#captureSignature(binding, ["-d", "-a", architecture, "--verbose=4"], signal);
             if (!slice.ok)
                 return slice;
             captures.push(slice.value);
@@ -277,12 +288,38 @@ class NativeMacOSClient {
         ];
         if (unclassified.length > 0)
             limitations.push(`Signature state could not be classified for Mach-O slices: ${unclassified.join(", ")}.`);
-        if (requirementsUnavailable)
+        if (aggregateExits.requirements !== 0)
             limitations.push("The aggregate designated requirement is unavailable because Mach-O slices have mixed signing states.");
-        if (entitlementsUnavailable)
+        if (aggregateExits.entitlements !== 0)
             limitations.push("The aggregate entitlements are unavailable because Mach-O slices have mixed signing states.");
         return ok({ captures, limitations });
     }
+    async #captureSignature(binding, args, signal) {
+        const before = await verifySignatureTarget(this.target, binding, signal);
+        if (!before.ok)
+            return before;
+        let capture;
+        try {
+            capture = await this.#run("inspect_signature", "codesign", [...args, binding.snapshotPath], {
+                signal,
+                acceptNonZero: true,
+            });
+        }
+        catch (cause) {
+            capture = err(new ProviderAdapterError(IDENTITY.id, "inspect_signature", {
+                cause,
+                diagnostics: {
+                    phase: "codesign-capture",
+                    path: this.target.path,
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                },
+            }));
+        }
+        // Verify failed captures too: a disappearing target is not a codesign
+        // execution failure, and later captures must never use another version.
+        const after = await verifySignatureTarget(this.target, binding, signal);
+        return after.ok ? capture : after;
+    }
     async #inspectPlist(parameters, signal) {
         const requested = parameters.path;
         if (requested !== undefined && typeof requested !== "string")
@@ -366,13 +403,57 @@ class NativeMacOSClient {
 }
 const isNativeOperation = (operation) => NATIVE_TOOL_CONTRACTS.some(({ name }) => name === operation);
 const translateCommandFailure = (operation, failure) => {
+    const capturedOutput = failure.capture === null
+        ? undefined
+        : {
+            stdout: failure.capture.stdout,
+            stderr: failure.capture.stderr,
+            truncated: failure.capture.truncated,
+            stdout_bytes: failure.capture.stdoutBytes,
+            stderr_bytes: failure.capture.stderrBytes,
+            exit_code: failure.capture.exitCode,
+            signal: failure.capture.signal,
+        };
+    const cleanup = failure.cleanupFailure === null
+        ? undefined
+        : {
+            reason: failure.cleanupFailure,
+            resources: [...failure.cleanupResources],
+        };
+    const errorOptions = {
+        ...(capturedOutput === undefined ? {} : { capturedOutput }),
+        ...(cleanup === undefined ? {} : { cleanup }),
+    };
     if (failure.reason === "unavailable")
-        return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `${failure.tool} is unavailable through xcrun.`);
+        return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `${failure.tool} is unavailable through xcrun.`, errorOptions);
     if (failure.reason === "cancelled")
-        return new AnalysisCancelledError(operation);
-    return new ProviderAdapterError(IDENTITY.id, operation, { cause: failure });
+        return new AnalysisCancelledError(operation, errorOptions);
+    if (failure.reason === "timeout")
+        return new AnalysisTimeoutError(operation, NATIVE_COMMAND_TIMEOUT_MS, errorOptions);
+    if (failure.reason === "output-limit")
+        return new AnalysisResourceConstraintError(operation, "memory", `Native command output exceeded ${String(NATIVE_COMMAND_OUTPUT_BUDGET_BYTES)} bytes; complete output is required for analysis.`, { max_output_bytes: NATIVE_COMMAND_OUTPUT_BUDGET_BYTES }, errorOptions);
+    return new ProviderAdapterError(IDENTITY.id, operation, {
+        cause: failure,
+        ...errorOptions,
+        diagnostics: {
+            tool: failure.tool,
+            reason: failure.reason,
+            exit_code: failure.capture?.exitCode ?? failure.exitCode,
+            signal: failure.capture?.signal ?? null,
+            stdout_bytes: failure.capture?.stdoutBytes ?? 0,
+            stderr_bytes: failure.capture?.stderrBytes ?? 0,
+        },
+    });
 };
-const translateCodeSignExitFailure = (capture) => translateCommandFailure("inspect_signature", new NativeCommandFailure("codesign", "nonzero-exit", capture.exitCode));
+const translateCodeSignExitFailure = (capture) => translateCommandFailure("inspect_signature", new NativeCommandFailure("codesign", "nonzero-exit", capture.exitCode, undefined, {
+    stdout: capture.stdout,
+    stderr: capture.stderr,
+    stdoutBytes: capture.stdoutBytes,
+    stderrBytes: capture.stderrBytes,
+    exitCode: capture.exitCode,
+    signal: capture.signal,
+    truncated: false,
+}));
 const commandOutput = (capture) => `${capture.stdout}\n${capture.stderr}`;
 /**
  * A signed artifact exits zero; its diagnostics can still contain this text