rea-agents 6.3.0 → 6.5.0

package/dist/browser/history/HarSchema.js

@@ -1,7 +1,9 @@
 import { createRequire } from "node:module";
+import { isIP } from "node:net";
 import { Ajv } from "ajv";
 import { z } from "zod";
 import { CaptureFormatError } from "./CaptureFormatError.js";
+import { captureObject } from "./CaptureRedaction.js";
 /** Validate using the unchanged, pinned upstream HAR 1.2 draft-06 schemas. */
 export const createHarValidator = () => {
     const require = createRequire(import.meta.url);
@@ -20,53 +22,51 @@ export const createHarValidator = () => {
     if (validate === undefined)
         throw new Error("Pinned HAR root schema is unavailable");
     return (value) => {
-        allowMitmproxyAbsentPostData(value);
+        const adaptedPlaywrightEntries = allowObservedProducerRepresentations(value);
         if (!validate(value)) {
             const error = validate.errors?.[0];
-            throw new CaptureFormatError("format", `HAR schema validation failed: ${error?.keyword ?? "unknown constraint"}.`, error?.instancePath ?? "");
+            // AJV messages name the violated constraint, such as the missing
+            // property, without restating any captured value.
+            throw new CaptureFormatError("format", error === undefined
+                ? "HAR schema validation failed: unknown constraint."
+                : `HAR schema validation failed: ${error.keyword} (${error.message ?? "no detail"}).`, error?.instancePath ?? "");
         }
+        return adaptedPlaywrightEntries;
     };
 };
-/** Observed SaveHar 12.2.3 compatibility: validate omitted optional text while retaining reported null. */
-const allowMitmproxyAbsentPostData = (value) => {
-    const parsed = z
-        .object({
-        log: z.object({
-            creator: z.object({
-                name: z.literal("mitmproxy"),
-                version: z.literal("12.2.3"),
-            }),
-            entries: z.array(z.unknown()),
-        }),
-    })
-        .safeParse(value);
-    if (!parsed.success ||
-        typeof value !== "object" ||
-        value === null ||
-        !("log" in value))
-        return;
+/** Adapt only observed producer representations in the disposable validation copy. */
+const allowObservedProducerRepresentations = (value) => {
+    if (!captureObject(value) || !captureObject(value.log))
+        return [];
     const log = value.log;
-    if (typeof log !== "object" ||
-        log === null ||
-        !("entries" in log) ||
-        !Array.isArray(log.entries))
-        return;
-    for (const entry of log.entries) {
+    if (!captureObject(log.creator) || !Array.isArray(log.entries))
+        return [];
+    const mitmproxy = log.creator.name === "mitmproxy" && log.creator.version === "12.2.3";
+    const playwright = log.creator.name === "Playwright" && log.creator.version === "1.58.2";
+    if (!mitmproxy && !playwright)
+        return [];
+    const adaptedPlaywrightEntries = [];
+    for (const [ordinal, entry] of log.entries.entries()) {
         const candidate = entry;
-        if (typeof candidate !== "object" ||
-            candidate === null ||
-            !("request" in candidate))
+        if (!captureObject(candidate))
+            continue;
+        const address = candidate.serverIPAddress;
+        if (playwright &&
+            typeof address === "string" &&
+            address.startsWith("[") &&
+            address.endsWith("]") &&
+            isIP(address.slice(1, -1)) === 6) {
+            candidate.serverIPAddress = address.slice(1, -1);
+            adaptedPlaywrightEntries.push(ordinal);
+        }
+        if (!mitmproxy)
             continue;
         const request = candidate.request;
-        if (typeof request !== "object" ||
-            request === null ||
-            !("postData" in request))
+        if (!captureObject(request))
             continue;
         const body = request.postData;
-        if (typeof body === "object" &&
-            body !== null &&
-            "text" in body &&
-            body.text === null)
+        if (captureObject(body) && body.text === null)
             delete body.text;
     }
+    return adaptedPlaywrightEntries;
 };

package/dist/browser/history/HistoricalCaptureDecoder.js

@@ -1,4 +1,5 @@
-import { historicalCaptureFailure, captureMemoryFailure, } from "./CaptureFailures.js";
+import { CAPTURE_PROCESS_MEMORY_LIMIT_REASON, historicalCaptureFailure, captureMemoryFailure, } from "./CaptureFailures.js";
+import { NODE_CAPTURE_HEAP_ENFORCED, NODE_CAPTURE_HEAP_LIMITS, NODE_CAPTURE_PROCESS_MEMORY_LIMIT_BYTES, } from "./CaptureRelease.js";
 import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
 import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
@@ -6,29 +7,29 @@ import { join } from "node:path";
 import { z } from "zod";
 import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
 import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
 import { AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
 import { err, ok } from "../../domain/result.js";
-import { WEB_NETWORK_CAPTURE_LIMITS, webNetworkCaptureSchema, } from "../../domain/webNetworkCapture.js";
+import { WEB_NETWORK_CAPTURE_LIMITS, webNetworkCapturePayloadSchema, } from "../../domain/webNetworkCapture.js";
 import { runOwnedCommand } from "../../process/OwnedCommand.js";
 import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
 import { redactExplicitFailure } from "../../domain/explicitSensitiveFailure.js";
 const OPERATION = "inspect_web_network_capture";
-const decodedSchema = webNetworkCaptureSchema.omit({
-    artifact: true,
-    format: true,
-    runtime_attribution: true,
-    limitations: true,
-});
 const replySchema = z.discriminatedUnion("ok", [
-    z.strictObject({ ok: z.literal(true), value: decodedSchema }),
+    z.strictObject({
+        ok: z.literal(true),
+        value: webNetworkCapturePayloadSchema,
+    }),
     z.strictObject({
         ok: z.literal(false),
         reason: z.enum([
             "format",
             "unsupported",
             "input-limit",
+            "expanded-limit",
             "resource-limit",
             "decoder",
             "limit",
@@ -42,13 +43,28 @@ export class HistoricalCaptureDecoder {
     adapters;
     environment;
     createRuntime;
-    constructor(adapters, environment, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-web-capture-" })) {
+    #resources;
+    constructor(adapters, environment, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-web-capture-" }), resources = new ArtifactResourceScope()) {
         this.adapters = adapters;
         this.environment = environment;
         this.createRuntime = createRuntime;
+        this.#resources = resources;
+    }
+    /** Retry retained readers and private roots at service shutdown. */
+    close() {
+        return this.#resources.close();
     }
     /** Snapshot the selected artifact, decode it offline, and release private credentials and processes. */
     async inspect(input, options) {
+        try {
+            return await this.#resources.run(() => this.inspectAdmitted(input, options));
+        }
+        catch (cause) {
+            const error = historicalCaptureFailure(input, cause, "capture-read", options);
+            return err(redactExplicitFailure(this.withReaderCleanup(error, cause), input.sensitive_values));
+        }
+    }
+    async inspectAdmitted(input, options) {
         let runtime;
         let result;
         let phase = "capture-read";
@@ -56,7 +72,7 @@ export class HistoricalCaptureDecoder {
             const adapter = this.adapters.find((candidate) => candidate.format === input.format);
             if (adapter === undefined)
                 throw new AnalysisCapabilityUnavailableError(input.format, OPERATION, "No adapter is configured for the selected capture format.");
-            const snapshot = await readStableArtifact(input.capture_path, WEB_NETWORK_CAPTURE_LIMITS.inputBytes, options?.signal);
+            const snapshot = await readStableArtifact(input.capture_path, WEB_NETWORK_CAPTURE_LIMITS.inputBytes, options?.signal, undefined, this.#resources);
             phase = "decoder";
             runtime = await this.createRuntime();
             const snapshotPath = join(runtime.path, "capture.snapshot");
@@ -78,7 +94,7 @@ export class HistoricalCaptureDecoder {
                 UV_THREADPOOL_SIZE: "1",
             };
             delete environment.NODE_OPTIONS;
-            await runOwnedCommand({
+            const completed = await runOwnedCommand({
                 ...command,
                 runId: `rea-web-capture-${randomUUID()}`,
                 cwd: runtime.path,
@@ -87,12 +103,19 @@ export class HistoricalCaptureDecoder {
                 timeoutMs: WEB_NETWORK_CAPTURE_LIMITS.timeoutMs,
                 diagnosticBytes: 1024 * 1024,
             }, options?.signal === undefined ? {} : { signal: options.signal });
+            // A decoder that survived a failed allocation may still reply; its
+            // reply is not trusted as complete once the limit was reached.
+            if (completed.memoryLimitReached === true)
+                throw captureMemoryFailure(input, CAPTURE_PROCESS_MEMORY_LIMIT_REASON);
             let reply;
             try {
-                const replyFile = await readStableArtifact(replyPath, WEB_NETWORK_CAPTURE_LIMITS.outputBytes, options?.signal);
+                const replyFile = await readStableArtifact(replyPath, WEB_NETWORK_CAPTURE_LIMITS.outputBytes, options?.signal, undefined, this.#resources);
                 reply = replySchema.parse(JSON.parse(replyFile.bytes.toString("utf8")));
             }
             catch (cause) {
+                if (cause instanceof ArtifactReaderFailure &&
+                    cause.cleanup !== undefined)
+                    throw cause;
                 if (options?.signal?.aborted)
                     throw new AnalysisCancelledError(OPERATION);
                 throw new AnalysisOutputError(OPERATION, `Owned capture decoder reply failed for ${input.capture_path}: ${replyFailureReason(cause)}`, { cause });
@@ -117,6 +140,17 @@ export class HistoricalCaptureDecoder {
                             },
                         },
                     ]);
+                if (reply.reason === "expanded-limit")
+                    throw new AnalysisInputError(OPERATION, undefined, [
+                        {
+                            path: ["capture_path", reply.pointer],
+                            reason: "out_of_range",
+                            message: reply.message,
+                            expected: {
+                                maximum_expanded_capture_bytes: WEB_NETWORK_CAPTURE_LIMITS.inputBytes,
+                            },
+                        },
+                    ]);
                 if (reply.reason === "resource-limit")
                     throw captureMemoryFailure(input, reply.message);
                 if (reply.reason === "decoder")
@@ -136,45 +170,79 @@ export class HistoricalCaptureDecoder {
                 reply.value.decoder.name !== adapter.identity.name ||
                 reply.value.decoder.version !== adapter.identity.version)
                 throw new AnalysisOutputError(OPERATION, "Capture decoder changed the selected upstream profile identity.");
-            result = ok({
-                ...reply.value,
+            const common = {
                 artifact: {
                     path: input.capture_path,
                     sha256: snapshot.sha256,
                     bytes: snapshot.bytes.length,
                 },
-                format: input.format,
                 runtime_attribution: "unknown",
                 limitations: [
+                    ...(adapter.limitations ?? []),
                     "This is retained producer evidence, without live browser transaction IDs, scenario provenance, execution attribution or deployment authenticity. Recorded URLs are never fetched.",
                     "Every record is decoded before selection; no partial success is returned on malformed input or a resource limit.",
                     "Known authentication headers/cookies and explicitly marked literal values are excluded. Unknown extension names do not establish sensitivity.",
-                    "A 32 MiB input, 96 MiB reply and 64-level nesting budget bound complete evidence. HAR uses a 192 MiB Node old-generation heap; native decoding uses a 768 MiB Linux address-space limit. Each owned command has a 30-second deadline with independent cleanup.",
+                    `A 32 MiB input, 96 MiB reply and 64-level nesting budget bound complete evidence. ${nodeMemoryLimitation()}; mitmproxy decoding uses a 768 MiB Linux address-space limit. Each owned command has a 30-second deadline with independent cleanup.`,
                 ],
-            });
+            };
+            if (input.format === "qlog") {
+                if (!("qlog" in reply.value))
+                    throw new AnalysisOutputError(OPERATION, "Capture decoder omitted qlog transport facts.");
+                result = ok({ ...reply.value, ...common, format: "qlog" });
+            }
+            else {
+                if ("qlog" in reply.value)
+                    throw new AnalysisOutputError(OPERATION, "Capture decoder supplied inapplicable qlog transport facts.");
+                result = ok({ ...reply.value, ...common, format: input.format });
+            }
         }
         catch (cause) {
-            result = err(redactExplicitFailure(historicalCaptureFailure(input, cause, phase, options), input.sensitive_values));
+            const error = historicalCaptureFailure(input, cause, phase, options);
+            result = err(redactExplicitFailure(this.withReaderCleanup(error, cause), input.sensitive_values));
         }
         if (runtime !== undefined) {
-            try {
-                await runtime.close();
-            }
-            catch (cause) {
+            const cleanup = await this.#resources.release({
+                kind: "private-runtime-root",
+                resource: runtime.path,
+                root: runtime,
+            });
+            if (cleanup.kind === "failed") {
                 return err(redactExplicitFailure(new ProviderCleanupError(input.format, [runtime.path], {
                     capture_path: input.capture_path,
                     previous_error: result.ok
                         ? null
                         : projectAnalysisError(result.error),
-                    reason: cause instanceof Error ? cause.message : String(cause),
-                }, { operation: OPERATION }), input.sensitive_values));
+                    reason: cleanup.cause instanceof Error
+                        ? cleanup.cause.message
+                        : String(cleanup.cause),
+                }, { operation: OPERATION, cause: cleanup.cause }), input.sensitive_values));
             }
         }
         return result.ok && options?.signal?.aborted
             ? err(new AnalysisCancelledError(OPERATION))
             : result;
     }
+    withReaderCleanup(primary, cause) {
+        if (!(cause instanceof ArtifactReaderFailure) ||
+            cause.cleanup === undefined)
+            return primary;
+        if (cause.reason === "unavailable")
+            return new ProviderCleanupError("web-network-capture", cause.cleanup.resources, { reason: cause.cleanup.reason }, { operation: OPERATION, cause });
+        const cleanup = new ProviderCleanupError("web-network-capture", cause.cleanup.resources, {
+            reason: cause.cleanup.reason,
+            previous_error: projectAnalysisError(primary),
+        }, { operation: OPERATION, cause });
+        return analysisErrorWithCleanupFailure(primary, cleanup, OPERATION);
+    }
 }
+/** The Node capture decoder runs on this executable; only Node.js enforces its V8 heap flags. */
+const nodeMemoryLimitation = () => {
+    if (NODE_CAPTURE_HEAP_ENFORCED)
+        return `HAR/SAZ/qlog use a ${String(NODE_CAPTURE_HEAP_LIMITS.oldGenerationMiB)} MiB Node old-generation heap`;
+    return NODE_CAPTURE_PROCESS_MEMORY_LIMIT_BYTES === null
+        ? "HAR/SAZ/qlog run on Bun, which does not enforce REA's V8 heap flags"
+        : `HAR/SAZ/qlog run on Bun, which does not enforce REA's V8 heap flags, under a ${String(NODE_CAPTURE_PROCESS_MEMORY_LIMIT_BYTES)}-byte Windows Job Object commit limit`;
+};
 const replyFailureReason = (cause) => {
     if (cause instanceof ArtifactReaderFailure)
         return cause.message;

package/dist/browser/history/MitmproxyCaptureAdapter.js

@@ -1,4 +1,4 @@
-import { access } from "node:fs/promises";
+import { access, stat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -22,6 +22,8 @@ export class MitmproxyCaptureAdapter {
             throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, MITMDUMP_REQUIREMENT, { userMessage: MITMDUMP_REQUIREMENT });
         try {
             await access(command, constants.R_OK | constants.X_OK);
+            if (!(await stat(command)).isFile())
+                throw new TypeError("Configured path is not a regular file");
         }
         catch (cause) {
             const reason = `Configured mitmdump executable is unavailable: ${command}.`;

package/dist/browser/history/NodeCaptureAdapter.js

@@ -0,0 +1,48 @@
+import { fileURLToPath } from "node:url";
+import { NODE_CAPTURE_HEAP_ENFORCED, HAR_CAPTURE_PROVIDER_IDENTITY, SAZ_CAPTURE_PROVIDER_IDENTITY, QLOG_CAPTURE_PROVIDER_IDENTITY, NODE_CAPTURE_HEAP_LIMITS, NODE_CAPTURE_PROCESS_MEMORY_LIMIT_BYTES, } from "./CaptureRelease.js";
+import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+/** Package-backed capture decoders share one bounded offline Node process profile. */
+export class NodeCaptureAdapter {
+    format;
+    identity;
+    limitations;
+    constructor(format) {
+        this.format = format;
+        this.identity =
+            format === "har"
+                ? HAR_CAPTURE_PROVIDER_IDENTITY
+                : format === "saz"
+                    ? SAZ_CAPTURE_PROVIDER_IDENTITY
+                    : QLOG_CAPTURE_PROVIDER_IDENTITY;
+        this.limitations =
+            format === "saz"
+                ? [
+                    "SAZ ordinals follow first session-member occurrence in ZIP directory order, not chronology or numeric session ID.",
+                    "HTTP fields use byte-preserving Latin-1 text; start-line separators and header delimiters are not projected. Bodies retain stored bytes without transfer/content decoding. Absent members are null, distinct from empty bodies.",
+                    "XML preserves node order and attribute/text values, not its original byte serialization. WebSocket and gRPC members retain opaque message-file bytes, not decoded protocol events.",
+                    "Non-session archive members are inventoried but their content is not decoded.",
+                ]
+                : [];
+    }
+    async command(requestPath) {
+        if (this.format !== "har" &&
+            !NODE_CAPTURE_HEAP_ENFORCED &&
+            NODE_CAPTURE_PROCESS_MEMORY_LIMIT_BYTES === null)
+            throw new AnalysisCapabilityUnavailableError(this.identity.id, "inspect_web_network_capture", `${this.format} decoding requires an enforced decoder memory limit. Run REA with Node.js on this host.`);
+        return {
+            command: process.execPath,
+            arguments: [
+                `--max-old-space-size=${NODE_CAPTURE_HEAP_LIMITS.oldGenerationMiB}`,
+                `--max-semi-space-size=${NODE_CAPTURE_HEAP_LIMITS.semiSpaceMiB}`,
+                "--v8-pool-size=1",
+                "--single-threaded",
+                fileURLToPath(new URL("./NodeCaptureProcess.js", import.meta.url)),
+                requestPath,
+                this.format,
+            ],
+            ...(NODE_CAPTURE_PROCESS_MEMORY_LIMIT_BYTES === null
+                ? {}
+                : { memoryLimitBytes: NODE_CAPTURE_PROCESS_MEMORY_LIMIT_BYTES }),
+        };
+    }
+}

package/dist/browser/history/{HarCaptureProcess.js → NodeCaptureProcess.js}

@@ -1,32 +1,33 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { TextDecoder } from "node:util";
 import { z } from "zod";
 import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
 import { WEB_NETWORK_CAPTURE_LIMITS } from "../../domain/webNetworkCapture.js";
 import { CaptureFormatError } from "./CaptureFormatError.js";
-import { decodeHarCapture } from "./HarCapture.js";
 const requestSchema = z.strictObject({
     snapshot_path: z.string(),
     reply_path: z.string(),
     sensitive_values: z.array(z.string().min(1)),
 });
-/** Decode untrusted HAR in an owned, bounded heap rather than the long-lived MCP process. */
+/** Parse untrusted captures in an owned heap and return one complete bounded reply. */
 const main = async () => {
+    const format = z.enum(["har", "saz", "qlog"]).parse(process.argv[3]);
     const request = requestSchema.parse(JSON.parse(await readFile(process.argv[2] ?? "", "utf8")));
     let reply;
     try {
-        const snapshot = await readStableArtifact(request.snapshot_path, WEB_NETWORK_CAPTURE_LIMITS.inputBytes);
-        let text;
-        try {
-            text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(snapshot.bytes);
+        let value;
+        if (format !== "saz") {
+            const { decodeCaptureText } = await import("./CaptureJson.js");
+            const decoder = format === "har"
+                ? (await import("./HarCapture.js")).decodeHarCapture
+                : (await import("./QlogCapture.js")).decodeQlogCapture;
+            const snapshot = await readStableArtifact(request.snapshot_path, WEB_NETWORK_CAPTURE_LIMITS.inputBytes);
+            value = decoder(decodeCaptureText(snapshot.bytes, format === "har" ? "HAR" : "qlog"), request.sensitive_values);
         }
-        catch {
-            throw new CaptureFormatError("format", "HAR is not valid UTF-8 JSON.");
+        else {
+            const { decodeSazCapture } = await import("./SazCapture.js");
+            value = await decodeSazCapture(request.snapshot_path, request.sensitive_values);
         }
-        reply = {
-            ok: true,
-            value: decodeHarCapture(text, request.sensitive_values),
-        };
+        reply = { ok: true, value };
     }
     catch (cause) {
         reply =
@@ -40,7 +41,7 @@ const main = async () => {
                 : {
                     ok: false,
                     reason: "decoder",
-                    message: `HAR decoder failed unexpectedly (${cause instanceof Error ? cause.name : "unknown exception"}).`,
+                    message: `Capture decoder failed unexpectedly (${cause instanceof Error ? cause.name : "unknown exception"}).`,
                     pointer: "",
                 };
     }
@@ -49,7 +50,7 @@ const main = async () => {
         text = JSON.stringify({
             ok: false,
             reason: "limit",
-            message: "HAR reply exceeds the complete-evidence output budget.",
+            message: "Capture reply exceeds the complete-evidence output budget.",
             pointer: "",
         });
     await writeFile(request.reply_path, text, { flag: "wx", mode: 0o600 });