rea-agents 6.0.0 → 6.2.0

package/dist/process/capture/ProcessFilesystemEffects.js

@@ -1,12 +1,42 @@
-/** Classify path-stable filesystem effects between two bounded states. */
+import { sep } from "node:path";
+const unobservedAbsenceReason = (path, phase, completeRoots, filesByPath) => {
+    const alias = path.slice(0, path.indexOf(":"));
+    if (!completeRoots.has(alias))
+        return `The ${phase} snapshot did not exhaust path enumeration under ${alias}; absence remains unknown.`;
+    const rootPath = `${alias}:.`;
+    if (path !== rootPath && filesByPath.get(rootPath)?.type === "symlink")
+        return `The ${phase} snapshot did not follow the symbolic link at ${rootPath}; descendant absence remains unknown.`;
+    for (let index = path.lastIndexOf(sep); index > 0; index = path.lastIndexOf(sep, index - 1)) {
+        const parent = path.slice(0, index);
+        if (filesByPath.get(parent)?.type === "symlink")
+            return `The ${phase} snapshot did not follow the symbolic link at ${parent}; descendant absence remains unknown.`;
+    }
+    return undefined;
+};
+/** Classify effects only when a snapshot establishes the missing path's absence. */
 export const classifyFilesystemEffects = (before, after) => {
-    const beforeByPath = new Map(before.map((file) => [file.path, file]));
-    const afterByPath = new Map(after.map((file) => [file.path, file]));
+    const beforeByPath = new Map(before.files.map((file) => [file.path, file]));
+    const afterByPath = new Map(after.files.map((file) => [file.path, file]));
+    const beforeCompleteRoots = new Set(before.completeRoots);
+    const afterCompleteRoots = new Set(after.completeRoots);
     return [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])]
         .sort()
         .map((path) => {
         const beforeFile = beforeByPath.get(path) ?? null;
         const afterFile = afterByPath.get(path) ?? null;
+        const reason = beforeFile === null
+            ? unobservedAbsenceReason(path, "before", beforeCompleteRoots, beforeByPath)
+            : afterFile === null
+                ? unobservedAbsenceReason(path, "after", afterCompleteRoots, afterByPath)
+                : undefined;
+        if (reason !== undefined)
+            return {
+                path,
+                status: "unknown",
+                before: beforeFile,
+                after: afterFile,
+                reason,
+            };
         if (beforeFile === null) {
             if (afterFile === null)
                 throw new TypeError(`Filesystem effect ${path} has no file state`);

package/dist/process/capture/ProcessHarness.js

@@ -1,9 +1,8 @@
-import { parseProcessCapture } from "../../domain/process/processCapture.js";
+import { parseProcessCapture } from "../../domain/process/processCaptureParsing.js";
 import { err, ok } from "../../domain/result.js";
 import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
 import {} from "../../domain/analysisErrorBase.js";
-import { describeProcessCaptureExecutionFailure, ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
-export { ProcessCaptureError } from "./ProcessCaptureError.js";
+import { describeProcessCaptureExecutionFailure, ProcessCaptureError, normalizeCaptureFailure, processCaptureCancelled, } from "./ProcessCaptureError.js";
 import { startProcessSampler } from "./ProcessSampling.js";
 import { snapshotRoots } from "./FilesystemSnapshot.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
@@ -15,14 +14,11 @@ import { createProcessCaptureJournal, scheduleScenarioInteractions, } from "./Pr
 import { makeProcessCaptureEnvironment } from "./ProcessCaptureEnvironment.js";
 import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
 import { processCaptureOwnershipUnavailableReason } from "./ProcessCaptureCapability.js";
-import { DarwinProcessOwnershipInspectionError } from "../DarwinProcessRunTokenReader.js";
-export { probeProcessCaptureCapability } from "./ProcessCaptureCapability.js";
 const cleanupFailedStartup = async (options) => {
     const sampledProcessGroupIds = options.terminal !== undefined &&
         options.observations?.process_samples.state === "available"
         ? selectCapturedProcessGroupIds(options.terminal.pid, options.observations.process_samples.value).filter((groupId) => groupId !== options.terminal?.pid)
         : undefined;
-    options.terminal?.kill("SIGKILL");
     if (options.observations !== undefined && options.renderer !== undefined) {
         try {
             options.observations.rendered_frames = {
@@ -89,7 +85,7 @@ const startCaptureRuntime = async (options) => {
             value: scenario.normalization.pids ? 1 : terminal.pid,
         };
         const executableIdentity = observeLaunchedExecutable(scenario.executable, selectedExecutable);
-        const framesTruncated = captureTerminalFrames({
+        const rawTerminalRetention = captureTerminalFrames({
             ...options,
             terminal,
             started,
@@ -117,7 +113,7 @@ const startCaptureRuntime = async (options) => {
             startedAt,
             executableIdentity,
             lastOutput: () => lastOutput,
-            framesTruncated,
+            rawTerminalRetention,
             stopSampler,
         };
     }
@@ -181,18 +177,6 @@ const finishProcessRun = async (options) => {
         : { scenario: options.scenario, rootPid };
     return resolveProcessResult(cleanupFailure === undefined ? verifiedCapture : capture, executionFailure, cleanup, options.observations, partialContext);
 };
-/** Preserve typed process-inspection preflight failures at the capture boundary. */
-export const normalizeCaptureFailure = (cause, signal) => {
-    if (cause instanceof ProcessCaptureError)
-        return cause;
-    if (cause instanceof DarwinProcessOwnershipInspectionError)
-        return new ProcessCaptureError(cause.message, { cause });
-    if (signal?.aborted === true &&
-        (cause === signal.reason ||
-            (cause instanceof Error && cause.name === "AbortError")))
-        return processCaptureCancelled();
-    return cause;
-};
 const completeCapture = async (options) => {
     const unavailableReason = (stage, cause) => `${stage} failed: ${cause instanceof Error ? cause.message : "unknown failure"}`;
     const { runtime, scenario } = options;
@@ -201,7 +185,7 @@ const completeCapture = async (options) => {
         throw processCaptureCancelled();
     let settlement;
     try {
-        settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent, options.hostPlatform);
+        settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent, options.hostPlatform, options.signal);
     }
     catch (cause) {
         options.observationBuffer.settlement = {
@@ -214,7 +198,8 @@ const completeCapture = async (options) => {
         state: "available",
         value: settlement,
     };
-    const samplingPartial = (await runtime.stopSampler()).partial;
+    const sampling = await runtime.stopSampler();
+    const samplingPartial = sampling.partial;
     await settleProcessCaptureJournal(options.eventJournal);
     assertNotCancelled(options.signal);
     let after;
@@ -266,7 +251,7 @@ const completeCapture = async (options) => {
             name: "after_settlement",
             at_ms: Math.max(0, Date.now() - runtime.started),
             files: after.files,
-            effects: classifyFilesystemEffects(options.before.files, after.files),
+            effects: classifyFilesystemEffects(options.before, after),
             truncated: after.truncated,
         },
     ];
@@ -284,7 +269,8 @@ const completeCapture = async (options) => {
     options.observationBuffer.manifest = { state: "available", value: manifest };
     const truncated = options.initiallyTruncated ||
         after.truncated ||
-        runtime.framesTruncated() ||
+        runtime.rawTerminalRetention().observed_frames >
+            runtime.rawTerminalRetention().retained_frames ||
         checkpoints.some(({ truncated: partial }) => partial) ||
         samplingPartial ||
         runtime.renderer.truncated();
@@ -295,6 +281,17 @@ const completeCapture = async (options) => {
         before: options.before,
         after,
         truncated,
+        ...(options.before.coverage === undefined || after.coverage === undefined
+            ? {}
+            : {
+                truncationDetails: {
+                    raw_terminal: runtime.rawTerminalRetention(),
+                    rendered_terminal: runtime.renderer.retention(),
+                    filesystem_before: options.before.coverage,
+                    filesystem_after: after.coverage,
+                    process: sampling.coverage,
+                },
+            }),
         scenario,
         rootPid: runtime.terminal.pid,
         samplingPartial,
@@ -389,7 +386,6 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
         });
     }
     catch (cause) {
-        runtime?.terminal.kill("SIGKILL");
         executionFailure = normalizeCaptureFailure(cause, signal);
         if (runtime !== undefined &&
             observations.rendered_frames.state === "unavailable" &&

package/dist/process/capture/ProcessNormalization.js

@@ -1,3 +1,4 @@
+import { isIP } from "node:net";
 /** Bucket one elapsed process-capture timestamp under scenario normalization. */
 export const normalizeProcessElapsedTime = (elapsedMs, timeBucketMs) => Math.floor(elapsedMs / timeBucketMs) * timeBucketMs;
 /** Normalize one terminal/protocol payload under explicitly selected scenario rules. */
@@ -10,14 +11,31 @@ export const normalizeProcessText = (value, scenario, temporaryRoot, pid) => {
         for (const [index, root] of scenario.filesystem_observation_paths.entries())
             normalized = normalized.replaceAll(root, `<filesystem-root-${String(index)}>`);
     }
+    if (scenario.normalization.ports)
+        normalized = normalizePortTokens(normalized);
     if (scenario.normalization.pids)
         normalized = normalizePidTokens(normalized, [pid]);
-    if (scenario.normalization.ports)
-        normalized = normalized.replaceAll(/(?<=[:=])\d{2,5}\b/g, "<port>");
     for (const pattern of scenario.normalization.patterns)
         normalized = normalized.replaceAll(pattern.pattern, pattern.replacement);
     return normalized;
 };
+// A port may end a sentence, but a period followed by a letter, digit, or
+// underscore in any script continues a decimal, version, or host name and is
+// not a port boundary.
+// PTY chunks are normalized independently, so a period that ends the chunk
+// stays unnormalized: its continuation may arrive in the next chunk.
+const normalizePortTokens = (value) => {
+    const endpointNormalized = value.replaceAll(/(\b[a-z][a-z0-9+.-]*:\/\/[^\s/?#"'<>]+|\blocalhost|\b(?:\d{1,3}\.){3}\d{1,3}|\[[\da-f:.%]+\]):(\d{1,5})(?![\p{L}\p{N}_@:]|\.(?:[\p{L}\p{N}_]|$))/giu, (match, endpoint, port) => {
+        if (Number(port) > 65_535)
+            return match;
+        const isEndpoint = endpoint.includes("://")
+            ? URL.canParse(`${endpoint}:${port}`)
+            : endpoint.toLowerCase() === "localhost" ||
+                isIP(endpoint.replace(/^\[|\]$/gu, "")) !== 0;
+        return isEndpoint ? `${endpoint}:<port>` : match;
+    });
+    return endpointNormalized.replaceAll(/(\b(?:port|tcp_port|udp_port|listen)\b["']?\s*[:=]\s*)(\d{1,5})(?![\p{L}\p{N}_]|\.(?:[\p{L}\p{N}_]|$))/giu, (match, prefix, port) => Number(port) <= 65_535 ? `${prefix}<port>` : match);
+};
 /** Project sampled observations under the caller-selected normalization rules. */
 export const normalizeProcessSamples = (samples, scenario, rootPid) => {
     const identifiers = [

package/dist/process/capture/ProcessSampling.js

@@ -328,6 +328,9 @@ export const startProcessSampler = (options) => {
     let stopped = false;
     let abortCurrent;
     let partial = false;
+    let limitReached = false;
+    let samplingFailures = 0;
+    let firstSamplingFailure = null;
     let rootInitialized = false;
     const sample = () => {
         if (stopped || pending !== undefined)
@@ -363,6 +366,7 @@ export const startProcessSampler = (options) => {
                     continue;
                 if (samples.length >= limit) {
                     partial = true;
+                    limitReached = true;
                     continue;
                 }
                 lastObservations.set(value.pid, observation);
@@ -372,8 +376,16 @@ export const startProcessSampler = (options) => {
             }
         })
             .catch((cause) => {
-            if (!(cause instanceof Error && cause.name === "AbortError"))
+            if (!(cause instanceof Error && cause.name === "AbortError")) {
                 partial = true;
+                samplingFailures += 1;
+                firstSamplingFailure ??=
+                    cause instanceof Error
+                        ? `${cause.name}: ${cause.message}`
+                        : typeof cause === "string"
+                            ? cause
+                            : `Unexpected sampling rejection (${typeof cause})`;
+            }
         })
             .then(() => {
             abortCurrent = undefined;
@@ -387,6 +399,17 @@ export const startProcessSampler = (options) => {
         clearInterval(timer);
         abortCurrent?.();
         await pending;
-        return { partial };
+        return {
+            partial,
+            coverage: {
+                sample_limit: limit,
+                sampling_partial: partial,
+                retained_samples: samples.length,
+                sample_limit_reached: limitReached,
+                sampling_failures: samplingFailures,
+                first_sampling_failure: firstSamplingFailure,
+                coverage: "sampled",
+            },
+        };
     };
 };

package/dist/process/capture/TerminalRenderer.js

@@ -19,6 +19,8 @@ export class TerminalRenderer {
     #frames = [];
     #pending = Promise.resolve();
     #capturedBytes = 0;
+    #observedBytes = 0;
+    #observedFrames = 0;
     #truncated = false;
     constructor(options) {
         this.options = options;
@@ -55,6 +57,16 @@ export class TerminalRenderer {
     truncated() {
         return this.#truncated;
     }
+    /** Budget accounting after awaiting queued writes with frames(). */
+    retention() {
+        return {
+            budget_bytes: this.options.maxBytes,
+            observed_bytes: this.#observedBytes,
+            retained_bytes: this.#capturedBytes,
+            observed_frames: this.#observedFrames,
+            retained_frames: this.#frames.length,
+        };
+    }
     /** Release addon and terminal resources after all writes settle. */
     async dispose() {
         await this.#pending;
@@ -71,6 +83,8 @@ export class TerminalRenderer {
         const serializedState = this.options.normalize(this.#serializeAddon.serialize());
         const bytes = Buffer.byteLength(serializedState) +
             lines.reduce((total, line) => total + Buffer.byteLength(line), 0);
+        this.#observedBytes += bytes;
+        this.#observedFrames += 1;
         if (this.#capturedBytes + bytes > this.options.maxBytes) {
             this.#truncated = true;
             return;

package/dist/process/snapshotEnvironment.js

@@ -0,0 +1,14 @@
+/** Snapshot caller-selected variables using Node child-process key semantics. */
+export const snapshotEnvironment = (environment, platform = process.platform) => {
+    if (platform !== "win32")
+        return Object.freeze({ ...environment });
+    const snapshot = {};
+    // Node sorts keys lexicographically and forwards the first case-insensitive
+    // match on Windows. Canonical keys also make subsequent lookups deterministic.
+    for (const key of Object.keys(environment).sort()) {
+        const canonicalKey = key.toUpperCase();
+        if (!Object.hasOwn(snapshot, canonicalKey))
+            snapshot[canonicalKey] = environment[key];
+    }
+    return Object.freeze(snapshot);
+};

package/dist/server/EvidenceMcpServer.js

@@ -0,0 +1,157 @@
+import { McpServer, isCallToolResult, isJSONRPCRequest, isJSONRPCNotification, isJSONRPCResultResponse, } from "@modelcontextprotocol/server";
+import { analysisErrorProjectionSchema } from "../contracts/errorSchemas.js";
+import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { encodeToolResult } from "./toolResultEncoding.js";
+/** Bind oversized MCP error recovery to this server's Evidence ledger. */
+export class EvidenceMcpServer extends McpServer {
+    recordEvidence;
+    delivery;
+    constructor(info, options, recordEvidence, delivery) {
+        super(info, options);
+        this.recordEvidence = recordEvidence;
+        this.delivery = delivery;
+    }
+    /** Preserve the SDK transport lifecycle while retaining oversized errors. */
+    connect(transport) {
+        return super.connect(new ErrorEvidenceTransport(transport, this.recordEvidence, this.delivery));
+    }
+}
+class ErrorEvidenceTransport {
+    transport;
+    recordEvidence;
+    delivery;
+    onclose;
+    onerror;
+    onmessage;
+    hasPerRequestStream;
+    pendingTools = new Map();
+    constructor(transport, recordEvidence, delivery) {
+        this.transport = transport;
+        this.recordEvidence = recordEvidence;
+        this.delivery = delivery;
+        if (transport.hasPerRequestStream !== undefined)
+            this.hasPerRequestStream = transport.hasPerRequestStream;
+        transport.onmessage = (message, extra) => {
+            if (isJSONRPCRequest(message) &&
+                message.method === "tools/call" &&
+                typeof message.params?.["name"] === "string")
+                this.pendingTools.set(message.id, message.params["name"]);
+            // The SDK suppresses replies after cancellation, so send() cannot release
+            // this bookkeeping. Keep transport authentication outside retained data.
+            if (isJSONRPCNotification(message) &&
+                message.method === "notifications/cancelled") {
+                const id = message.params?.["requestId"];
+                if (typeof id === "string" || typeof id === "number")
+                    this.pendingTools.delete(id);
+            }
+            this.onmessage?.(message, extra);
+        };
+        transport.onerror = (error) => this.onerror?.(error);
+        transport.onclose = () => {
+            this.pendingTools.clear();
+            this.onclose?.();
+        };
+    }
+    get sessionId() {
+        return this.transport.sessionId;
+    }
+    set sessionId(value) {
+        this.transport.sessionId = value;
+    }
+    start() {
+        return this.transport.start();
+    }
+    async close() {
+        try {
+            await this.transport.close();
+        }
+        finally {
+            this.pendingTools.clear();
+        }
+    }
+    setProtocolVersion(version) {
+        this.transport.setProtocolVersion?.(version);
+    }
+    setSupportedProtocolVersions(versions) {
+        this.transport.setSupportedProtocolVersions?.(versions);
+    }
+    async send(message, options) {
+        const id = "id" in message &&
+            (typeof message.id === "string" || typeof message.id === "number")
+            ? message.id
+            : undefined;
+        const tool = id === undefined ? undefined : this.pendingTools.get(id);
+        try {
+            const recovered = this.recoverError(message, tool);
+            if (isJSONRPCResultResponse(recovered) &&
+                isCallToolResult(recovered.result) &&
+                recovered.result.isError === true) {
+                // Keep the complete typed JSON in content. Error projections are not
+                // success outputSchema data; oversized recovery must consume their
+                // private structured carrier before it is removed from the wire.
+                const { structuredContent: _diagnostic, ...result } = recovered.result;
+                await this.transport.send({ ...recovered, result }, options);
+            }
+            else
+                await this.transport.send(recovered, options);
+        }
+        finally {
+            if (!isJSONRPCRequest(message) && id !== undefined)
+                this.pendingTools.delete(id);
+        }
+    }
+    recoverError(message, tool) {
+        if (!isJSONRPCResultResponse(message) ||
+            !isCallToolResult(message.result) ||
+            message.result.isError !== true ||
+            message.result.structuredContent === undefined)
+            return message;
+        const structured = jsonObjectSchema.parse(message.result.structuredContent);
+        const budget = this.delivery.resultBudgetBytes;
+        // The delivered error omits structuredContent, so only its text counts.
+        const encoded = encodeToolResult(structured, budget, "text");
+        if (encoded.ok)
+            return message;
+        const operation = tool ?? "mcp_tool_error";
+        const originalError = analysisErrorProjectionSchema.safeParse(structured["error"]);
+        // Retain the already projected diagnostic. Transport authentication and raw
+        // request arguments are deliberately excluded: the application owns their
+        // explicit sensitivity policy, and its error projection is authoritative.
+        const evidence = createEvidence(undefined, { id: "rea-mcp", name: "REA MCP delivery", version: "1" }, {
+            operation: "mcp_tool_error",
+            parameters: { tool_name: operation },
+            result: structured,
+            rawResult: jsonObjectSchema.parse(message.result),
+        });
+        const recorded = this.recordEvidence?.(evidence);
+        const retained = recorded !== undefined && recorded.ok;
+        const failure = new AnalysisResourceConstraintError(operation, "transport", "The tool failed, but its complete error response exceeds the MCP response budget.", {
+            boundary: "mcp-response",
+            ...(originalError.success
+                ? { original_error_code: originalError.data.code }
+                : {}),
+            result_budget_bytes: budget,
+            response_bytes_at_least: encoded.bytesAtLeast,
+            constraint: encoded.constraint,
+            ...(retained
+                ? {
+                    evidence_reference: {
+                        kind: "retained-evidence",
+                        evidence_id: evidence.evidence_id,
+                    },
+                }
+                : { retention: recorded === undefined ? "unavailable" : "failed" }),
+            ...(recorded !== undefined && !recorded.ok
+                ? { retention_error: projectAnalysisError(recorded.error) }
+                : {}),
+        }, {
+            remediationAction: retained
+                ? "Export the retained original error through export_evidence_bundle to a caller-selected path. The connection remains usable."
+                : "Restart REA with a larger REA_MCP_MAX_RESPONSE_BYTES and matching client receive buffer, then retry. The original error could not be retained by this server.",
+        });
+        return { ...message, result: this.delivery.toErrorToolResult(failure) };
+    }
+}