rea-agents 6.1.0 → 6.3.0

package/dist/server/registerWebRuntimeTools.js

@@ -2,7 +2,6 @@ import { toolContract } from "../contracts/toolContracts.js";
 import { mcpProgressReporter } from "./mcpProgress.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
-import { toCallToolResult, toEvidenceToolResult } from "./toolResult.js";
 /** Bind distinct runtime operations to named contracts and the session's Evidence owner. */
 export const registerWebRuntimeTools = (server, service, logger, recordEvidence) => {
     const execution = toolContract("observe_web_execution");
@@ -13,15 +12,15 @@ export const registerWebRuntimeTools = (server, service, logger, recordEvidence)
             progress: mcpProgressReporter(context),
         }));
         if (!result.ok)
-            return toCallToolResult(result, execution);
+            return server.delivery.toCallToolResult(result, execution);
         const recorded = recordEvidence?.(result.value);
-        return toEvidenceToolResult(result.value, execution, recorded);
+        return server.delivery.toEvidenceToolResult(result.value, execution, recorded);
     });
     server.registerTool(listeners.name, toolRegistrationOptions(listeners), async (input, context) => {
         const result = await logToolExecution(logger, listeners.name, () => service.inspect(input, { signal: context.mcpReq.signal }));
         if (!result.ok)
-            return toCallToolResult(result, listeners);
+            return server.delivery.toCallToolResult(result, listeners);
         const recorded = recordEvidence?.(result.value);
-        return toEvidenceToolResult(result.value, listeners, recorded);
+        return server.delivery.toEvidenceToolResult(result.value, listeners, recorded);
     });
 };

package/dist/server/registerWebScriptTool.js

@@ -2,15 +2,14 @@ import { exportWebScriptsValidated } from "../application/WebScriptExportService
 import { toolContract } from "../contracts/toolContracts.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
-import { toCallToolResult, toEvidenceToolResult } from "./toolResult.js";
 /** Register local script export without requiring a live browser provider. */
 export const registerWebScriptTool = (server, options) => {
     const contract = toolContract("export_web_scripts");
     server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
         const result = await logToolExecution(options.logger, contract.name, () => exportWebScriptsValidated(input, { signal: context.mcpReq.signal }));
         if (!result.ok)
-            return toCallToolResult(result, contract);
+            return server.delivery.toCallToolResult(result, contract);
         const recorded = options.recordEvidence?.(result.value);
-        return toEvidenceToolResult(result.value, contract, recorded);
+        return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
     });
 };

package/dist/server/registerWebSourceLocationTool.js

@@ -1,15 +1,14 @@
 import { toolContract } from "../contracts/toolContracts.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
-import { toCallToolResult, toEvidenceToolResult } from "./toolResult.js";
 /** Bind source point tracing to its exact named contract and session Evidence owner. */
 export const registerWebSourceLocationTool = (server, service, logger, recordEvidence) => {
     const contract = toolContract("trace_web_source_location");
     server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
         const result = await logToolExecution(logger, contract.name, () => service.trace(input, { signal: context.mcpReq.signal }));
         if (!result.ok)
-            return toCallToolResult(result, contract);
+            return server.delivery.toCallToolResult(result, contract);
         const recorded = recordEvidence?.(result.value);
-        return toEvidenceToolResult(result.value, contract, recorded);
+        return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
     });
 };

package/dist/server/toolResult.js

@@ -2,104 +2,76 @@ import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import {} from "../domain/analysisErrorBase.js";
 import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
-import { parseMcpResponseBudget } from "../config/mcpResponseBudget.js";
-import { encodeToolResult, MCP_RESULT_BUDGET_BYTES, MCP_RESULT_STRING_LIMIT, } from "./toolResultEncoding.js";
-/**
- * Serialize an application result as MCP text and structured content.
- * Shared error projection preserves actionable local diagnostics while omitting
- * raw cause objects; explicitly retained bounded command output stays visible.
- */
-export const toCallToolResult = (result, contract, context) => result.ok
-    ? successResult(result.value, contract, context)
-    : toErrorToolResult(result.error);
-/** Deliver Evidence using the producer's explicit recording acknowledgment. */
-export const toEvidenceToolResult = (evidence, contract, recorded) => recorded !== undefined && !recorded.ok
-    ? toErrorToolResult(recorded.error)
-    : toCallToolResult({ ok: true, value: evidence }, contract, recorded === undefined
-        ? undefined
-        : { retainedEvidenceId: evidence.evidence_id });
-/** Project an error without allocating oversized repeated MCP text. */
-export const toErrorToolResult = (error) => {
-    const projected = projectAnalysisError(error);
-    const structuredContent = { error: projected };
-    const configured = parseMcpResponseBudget(process.env.REA_MCP_MAX_RESPONSE_BYTES);
-    const budget = configured.ok && configured.value !== undefined
-        ? configured.value - 1024
-        : MCP_RESULT_BUDGET_BYTES;
-    const encoded = encodeToolResult(structuredContent, budget);
-    // The session-bound transport retains an oversized projected error before
-    // replacing it with a recoverable delivery constraint. Avoid allocating its
-    // repeated text representation before that boundary has acknowledged it.
-    return {
-        content: encoded.ok ? [{ type: "text", text: encoded.text }] : [],
-        structuredContent,
-        isError: true,
-    };
-};
-const successResult = (value, contract, context) => {
-    const candidate = projectEvidence(value) ??
-        (contract.kind === "session" ? { result: value } : value);
-    const configured = parseMcpResponseBudget(process.env.REA_MCP_MAX_RESPONSE_BYTES);
-    if (!configured.ok)
-        return toErrorToolResult(configured.error);
-    const budget = configured.value === undefined
-        ? MCP_RESULT_BUDGET_BYTES
-        : configured.value - 1024;
-    const encoded = encodeToolResult(candidate, budget);
-    if (!encoded.ok)
-        return toErrorToolResult(new AnalysisResourceConstraintError(contract.name, "transport", encoded.constraint === "string-length"
-            ? "The operation completed, but its complete MCP response exceeds Node's single-string representation limit. Export retained evidence to consume the complete analysis, or use complete CLI JSON output."
-            : "The operation completed, but its complete MCP response exceeds the stdio response budget. The analysis result was not truncated; export retained evidence to consume it, or use complete CLI JSON output.", {
+import { encodeToolResult, MCP_RESULT_STRING_LIMIT, } from "./toolResultEncoding.js";
+/** Create one delivery policy from the already selected, parsed response budget. */
+export const createToolResultDelivery = (maximumResponseBytes) => new ToolResultDelivery(maximumResponseBytes ?? STDIO_DEFAULT_MAX_BUFFER_SIZE);
+/** Immutable encoding and recovery policy shared by one MCP server. */
+export class ToolResultDelivery {
+    resultBudgetBytes;
+    constructor(maximumResponseBytes) {
+        this.resultBudgetBytes = maximumResponseBytes - 1024;
+        Object.freeze(this);
+    }
+    /** Serialize a plain application result or its actionable error. */
+    toCallToolResult(result, contract) {
+        return result.ok
+            ? this.successResult(contract.kind === "session" ? { result: result.value } : result.value, contract)
+            : this.toErrorToolResult(result.error);
+    }
+    /** Deliver Evidence using the producer's explicit recording acknowledgment. */
+    toEvidenceToolResult(evidence, contract, recorded) {
+        return recorded !== undefined && !recorded.ok
+            ? this.toErrorToolResult(recorded.error)
+            : this.successResult(evidence, contract, {
+                evidence_id: evidence.evidence_id,
+                ...(recorded === undefined
+                    ? {}
+                    : {
+                        evidence_reference: {
+                            kind: "retained-evidence",
+                            evidence_id: evidence.evidence_id,
+                        },
+                    }),
+            });
+    }
+    /** Project an error without allocating oversized repeated MCP text. */
+    toErrorToolResult(error) {
+        const structuredContent = { error: projectAnalysisError(error) };
+        // Errors reach the wire as text only; the structured copy is a private
+        // carrier the transport removes after its own budget check.
+        const encoded = encodeToolResult(structuredContent, this.resultBudgetBytes, "text");
+        // The transport retains an oversized projected error before replacing it
+        // with a recoverable delivery constraint, using this same budget.
+        return {
+            content: encoded.ok ? [{ type: "text", text: encoded.text }] : [],
+            structuredContent,
+            isError: true,
+        };
+    }
+    successResult(value, contract, recovery = {}) {
+        const encoded = encodeToolResult(value, this.resultBudgetBytes);
+        if (encoded.ok)
+            return {
+                content: [{ type: "text", text: encoded.text }],
+                structuredContent: value,
+            };
+        const retainedEvidence = recovery.evidence_reference !== undefined;
+        const recoveryAdvice = retainedEvidence
+            ? "Export retained evidence to consume the complete analysis, or use complete CLI JSON output."
+            : encoded.constraint === "string-length"
+                ? "Use complete CLI JSON output to consume the analysis."
+                : "Use a larger MCP response budget with a matching client receive buffer, or use complete CLI JSON output to consume the analysis.";
+        return this.toErrorToolResult(new AnalysisResourceConstraintError(contract.name, "transport", encoded.constraint === "string-length"
+            ? `The operation completed, but its complete MCP response exceeds Node's single-string representation limit. ${recoveryAdvice}`
+            : `The operation completed, but its complete MCP response exceeds the stdio response budget. The analysis result was not truncated. ${recoveryAdvice}`, {
             boundary: "mcp-response",
             default_receive_buffer_bytes: STDIO_DEFAULT_MAX_BUFFER_SIZE,
-            result_budget_bytes: budget,
+            result_budget_bytes: this.resultBudgetBytes,
             max_string_code_units: MCP_RESULT_STRING_LIMIT,
             response_bytes_at_least: encoded.bytesAtLeast,
             response_code_units_at_least: encoded.codeUnitsAtLeast,
             constraint: encoded.constraint,
-            ...evidenceRecovery(value, context?.retainedEvidenceId),
+            ...recovery,
         }));
-    return {
-        content: [
-            {
-                type: "text",
-                text: encoded.text,
-            },
-        ],
-        structuredContent: candidate,
-    };
-};
-const evidenceRecovery = (value, retainedEvidenceId) => {
-    const projected = projectEvidence(value);
-    if (projected === undefined ||
-        typeof projected !== "object" ||
-        projected === null ||
-        Array.isArray(projected))
-        return {};
-    if (projected.evidence_id !== retainedEvidenceId)
-        return { evidence_id: projected.evidence_id ?? null };
-    return {
-        evidence_reference: {
-            kind: "retained-evidence",
-            evidence_id: projected.evidence_id ?? null,
-        },
-    };
-};
-const projectEvidence = (value) => {
-    if (typeof value !== "object" ||
-        value === null ||
-        Array.isArray(value) ||
-        typeof value.evidence_id !== "string" ||
-        !/^ev_[a-f0-9]{64}$/u.test(value.evidence_id) ||
-        !("normalized_result" in value))
-        return undefined;
-    const normalizedResult = value.normalized_result;
-    const evidenceId = value.evidence_id;
-    if (normalizedResult === undefined || typeof evidenceId !== "string")
-        return undefined;
-    return {
-        result: normalizedResult,
-        evidence_id: evidenceId,
-        evidence: value,
-    };
-};
+    }
+}

package/dist/server/toolResultEncoding.js

@@ -1,23 +1,24 @@
-import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";
 import { constants as bufferConstants } from "node:buffer";
 import { bufferedJsonParts, jsonParts } from "../domain/jsonSerialization.js";
-// Leave room for the SDK's JSON-RPC envelope and protocol metadata. This budget
-// follows the pinned client's actual default framing limit, not a result-row cap.
-export const MCP_RESULT_BUDGET_BYTES = STDIO_DEFAULT_MAX_BUFFER_SIZE - 1024;
 export const MCP_RESULT_STRING_LIMIT = bufferConstants.MAX_STRING_LENGTH - 1024;
 const RESULT_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({
     content: [{ type: "text", text: "" }],
     structuredContent: null,
 })) - 4;
-/** Account for structured JSON and escaped text before allocating the complete text. */
-export const encodeToolResult = (value, budgetBytes = MCP_RESULT_BUDGET_BYTES) => {
+const TEXT_RESULT_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ content: [{ type: "text", text: "" }] }));
+/** Account for the delivered JSON representations before allocating the complete text. */
+export const encodeToolResult = (value, budgetBytes, representations = "structured-and-text") => {
+    const structured = representations === "structured-and-text";
     const parts = [];
-    let bytes = RESULT_ENVELOPE_BYTES;
-    let codeUnits = RESULT_ENVELOPE_BYTES;
+    let bytes = structured ? RESULT_ENVELOPE_BYTES : TEXT_RESULT_ENVELOPE_BYTES;
+    let codeUnits = bytes;
     for (const part of bufferedJsonParts(jsonParts(value))) {
         const escapedPart = JSON.stringify(part);
-        bytes += Buffer.byteLength(part) + Buffer.byteLength(escapedPart) - 2;
-        codeUnits += part.length + escapedPart.length - 2;
+        bytes +=
+            (structured ? Buffer.byteLength(part) : 0) +
+                Buffer.byteLength(escapedPart) -
+                2;
+        codeUnits += (structured ? part.length : 0) + escapedPart.length - 2;
         if (bytes > budgetBytes || codeUnits > MCP_RESULT_STRING_LIMIT)
             return {
                 ok: false,

package/dist/windows/WindowsNativeLoader.js

@@ -34,6 +34,7 @@ const inspectionSchema = z.strictObject({
     privateDacl: z.literal(true),
     atomicJobAssignment: z.literal(true),
     killOnOwnerClose: z.literal(true),
+    protocolStdin: z.boolean().optional(),
 });
 const bindingSchema = z.strictObject({
     call: z.custom((value) => typeof value === "function"),

package/dist/windows/WindowsOwnedProcess.js

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import { PassThrough } from "node:stream";
+import { PassThrough, Writable } from "node:stream";
 import { z } from "zod";
 import { requireWindowsNativeAuthority, windowsHandleSchema, } from "./WindowsNativeLoader.js";
 const launchSchema = z.strictObject({
@@ -26,6 +26,7 @@ export const quoteWindowsProcessArgument = (value) => {
 export class WindowsOwnedProcess extends EventEmitter {
     stdout = new PassThrough();
     stderr = new PassThrough();
+    stdin;
     signalCode = null;
     exitCode = null;
     pid;
@@ -34,13 +35,14 @@ export class WindowsOwnedProcess extends EventEmitter {
     #settled;
     #settle;
     #closed = false;
-    #verifiedSettlement = false;
     #failure;
     #timer;
     #cleanup;
-    constructor(command, arguments_, cwd, environment, verbatim) {
+    constructor(command, arguments_, cwd, environment, verbatim, protocolStdin = false) {
         super();
         this.#authority = requireWindowsNativeAuthority();
+        if (protocolStdin && this.#authority.inspection.protocolStdin !== true)
+            throw new Error("The bundled Windows native artifact does not support owned protocol stdin; use a matching current Windows x64 REA package.");
         const entries = Object.entries(environment)
             .filter((entry) => entry[1] !== undefined)
             .map(([key, value]) => `${key}=${value}`);
@@ -55,14 +57,55 @@ export class WindowsOwnedProcess extends EventEmitter {
             line,
             cwd ?? "",
             entries,
+            ...(protocolStdin ? [true] : []),
         ]));
         this.pid = launched.pid;
         this.#handle = launched.handle;
+        this.stdin = protocolStdin
+            ? new Writable({
+                write: (chunk, _encoding, callback) => {
+                    void this.#writeInput(chunk).then(() => callback(), (cause) => callback(cause instanceof Error ? cause : new Error(String(cause))));
+                },
+                final: (callback) => {
+                    try {
+                        this.#authority.call("process_stdin_close", [this.#handle]);
+                        callback();
+                    }
+                    catch (cause) {
+                        callback(cause instanceof Error ? cause : new Error(String(cause)));
+                    }
+                },
+                destroy: (cause, callback) => {
+                    try {
+                        if (!this.#closed)
+                            this.#authority.call("process_stdin_close", [this.#handle]);
+                        callback(cause);
+                    }
+                    catch (failure) {
+                        callback(failure instanceof Error ? failure : new Error(String(failure)));
+                    }
+                },
+            })
+            : null;
         this.#settled = new Promise((resolve) => {
             this.#settle = resolve;
         });
         this.#schedule();
     }
+    async #writeInput(chunk) {
+        const bytes = z.instanceof(Buffer).parse(chunk);
+        const written = z
+            .number()
+            .int()
+            .nonnegative()
+            .max(Number.MAX_SAFE_INTEGER)
+            .parse(await this.#authority.call("process_stdin_write", [
+            this.#handle,
+            bytes,
+        ]));
+        if (written !== bytes.length)
+            throw new Error("Owned Windows input write did not preserve all requested bytes");
+    }
     /** Terminate the retained job, never a PID supplied by another caller. */
     kill(signal) {
         if (signal === 0)
@@ -78,27 +121,27 @@ export class WindowsOwnedProcess extends EventEmitter {
     }
     /** Terminate and verify that the entire job has settled before releasing it. */
     cleanup() {
-        this.#cleanup ??= this.#stop();
+        this.#cleanup ??= this.#stop().then((result) => {
+            if (!result.cleaned)
+                this.#cleanup = undefined;
+            return result;
+        });
         return this.#cleanup;
     }
     async #stop() {
         if (this.#closed)
-            return this.#verifiedSettlement
-                ? { cleaned: true, signaled: false }
-                : {
-                    cleaned: false,
-                    reason: this.#failure ?? "Windows Job Object settlement was not verified",
-                };
+            return { cleaned: true, signaled: false };
         let timer;
         try {
             const signaled = this.kill();
+            this.#schedule();
             const settled = await Promise.race([
                 this.#settled.then(() => true),
                 new Promise((resolve) => {
                     timer = setTimeout(() => resolve(false), 5_000);
                 }),
             ]);
-            return settled && this.#verifiedSettlement
+            return settled
                 ? { cleaned: true, signaled }
                 : {
                     cleaned: false,
@@ -115,18 +158,20 @@ export class WindowsOwnedProcess extends EventEmitter {
         finally {
             if (timer !== undefined)
                 clearTimeout(timer);
-            if (!this.#closed)
-                this.#release();
         }
     }
     #schedule() {
+        if (this.#closed || this.#timer !== undefined)
+            return;
         this.#timer = setTimeout(() => this.#poll(), 25);
     }
     #poll() {
+        this.#timer = undefined;
         if (this.#closed)
             return;
         try {
             const state = pollSchema.parse(this.#authority.call("process_poll", [this.#handle]));
+            this.#failure = undefined;
             if (state.stdout.length > 0)
                 this.stdout.write(state.stdout);
             if (state.stderr.length > 0)
@@ -139,7 +184,6 @@ export class WindowsOwnedProcess extends EventEmitter {
                 state.stdoutEnded &&
                 state.stderrEnded &&
                 state.activeProcesses === 0) {
-                this.#verifiedSettlement = true;
                 this.#release();
             }
             else
@@ -152,7 +196,7 @@ export class WindowsOwnedProcess extends EventEmitter {
             // the captured stderr observation produced by the child itself.
             if (this.listenerCount("error") > 0)
                 this.emit("error", failure);
-            this.#release();
+            // Retain the original job so explicit cleanup can retry its observation.
         }
     }
     #release() {
@@ -162,6 +206,7 @@ export class WindowsOwnedProcess extends EventEmitter {
             clearTimeout(this.#timer);
         this.#authority.call("process_close", [this.#handle]);
         this.#closed = true;
+        this.stdin?.destroy();
         this.stdout.end();
         this.stderr.end();
         this.#settle?.();

package/dist/windows/WindowsPrivateRuntime.js

@@ -105,7 +105,10 @@ export class WindowsPrivateRuntime {
     }
     /** Remove owned objects by handle, unlinking reparse entries without traversal. */
     close() {
-        this.#closePromise ??= this.#remove();
+        this.#closePromise ??= this.#remove().catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
         return this.#closePromise;
     }
     async #remove() {
@@ -114,13 +117,9 @@ export class WindowsPrivateRuntime {
         if (this.#pending !== undefined)
             this.authority.call("runtime_snapshot_cancel", [this.observation.handle]);
         await this.#pending?.catch(() => undefined);
-        try {
-            this.authority.call("runtime_close", [this.observation.handle]);
-        }
-        finally {
-            this.#closed = true;
-            runtimes.delete(this.observation.path.toLowerCase());
-        }
+        this.authority.call("runtime_close", [this.observation.handle]);
+        this.#closed = true;
+        runtimes.delete(this.observation.path.toLowerCase());
     }
 }
 /** Select an already-owned runtime; an arbitrary pathname cannot grant authority. */

package/native/windows/README.md

@@ -57,7 +57,9 @@ without this lane reports Windows native controls as unavailable.
   deduplicated using Windows ordinal comparison, preserving their native Unicode
   semantics and caller-selected values.
 - Cleanup walks locked directory objects, removes files by handle, and unlinks
-  reparse entries without traversing their targets. Normal close, cancellation,
+  reparse entries without traversing their targets. Failed removal retains the
+  root and ancestor leases for retry; a partially removed runtime accepts only
+  cleanup, and its registry entry remains until removal succeeds. Normal close, cancellation,
   startup failure, and timeout release provider resources. Abrupt owner death
   kills the owned job; it can leave private runtime files for later operator
   cleanup and does not claim transactional deletion after a crash.

package/native/windows/build/manifest.json

@@ -1,9 +1,9 @@
 {
-  "packageVersion": "6.1.0",
+  "packageVersion": "6.3.0",
   "platform": "win32",
   "architecture": "x64",
   "abiVersion": 1,
   "nodeApiVersion": 8,
   "artifact": "rea-windows-x64.node",
-  "artifactSha256": "9914815706dcd4ef94d01543e31cb0b20035e98d5011d4b4e7f8e509823c8b1d"
+  "artifactSha256": "fedfd4ce8b3e15784d1a6ef7e9ba7eb9052e8335a1c75b6d69cd7e94f29ab1f8"
 }