rea-agents 5.0.0 → 6.0.0

package/dist/browser/PlaywrightElectronActiveProvider.js

@@ -9,7 +9,7 @@ import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
 import { cleanupOwnedProcessGroup, cleanupWindowsProcessTree, verifyNoTokenOwnedProcesses, } from "../process/ProcessOwnership.js";
-import { observeOwnedProcessLineage } from "../process/ProcessOwnershipObservation.js";
+import { observeOwnedProcessLineage, prepareProcessOwnershipInspection, systemProcessOwnershipHost, } from "../process/ProcessOwnershipObservation.js";
 import { selectCapturedProcessGroupIds } from "../process/ProcessOwnershipProcessTree.js";
 import { runElectronActions, readApplicationState, runWithExecutionLimits, } from "./PlaywrightElectronActiveActions.js";
 const OPERATION = "capture_electron_scenario";
@@ -101,8 +101,12 @@ export class PlaywrightElectronActiveProvider {
         try {
             if (options.signal?.aborted === true)
                 throw new BrowserObservationError(OPERATION, "cancelled");
+            await prepareProcessOwnershipInspection(options.signal);
             const startupDeadline = Date.now() + STARTUP_TIMEOUT_MS;
             const paths = await canonicalPaths(input);
+            const captureBaseline = await systemProcessOwnershipHost.captureBaseline?.(options.signal);
+            if (options.signal?.aborted)
+                throw new BrowserObservationError(OPERATION, "cancelled");
             application = await electron.launch({
                 executablePath: paths.executable,
                 cwd: paths.root,
@@ -122,13 +126,18 @@ export class PlaywrightElectronActiveProvider {
                 expectedParentPid: process.pid,
                 expectedCommand: paths.executable,
                 sweepTokenOwnedProcesses: true,
+                ...(captureBaseline === undefined ? {} : { captureBaseline }),
             };
             const actions = await runElectronActions(application, input, options);
             const state = await runWithExecutionLimits(readApplicationState(application), options.signal);
             outcome = ok(createResult(paths, input, actions, state));
         }
         catch (cause) {
-            outcome = err(providerError(cause));
+            outcome = err(options.signal?.aborted === true &&
+                (cause === options.signal.reason ||
+                    (cause instanceof Error && cause.name === "AbortError"))
+                ? new BrowserObservationError(OPERATION, "cancelled", { cause })
+                : providerError(cause));
         }
         if (application !== undefined) {
             if (ownership !== undefined)
@@ -200,7 +209,7 @@ const cleanupElectronProcesses = async (ownership, lineage) => {
             return result;
         signaled ||= result.signaled;
     }
-    const remaining = await verifyNoTokenOwnedProcesses(ownership.runId);
+    const remaining = await verifyNoTokenOwnedProcesses(ownership.runId, undefined, ownership.captureBaseline);
     if (!remaining.cleaned)
         return remaining;
     return { cleaned: true, signaled };

package/dist/browser/history/CaptureFailures.js

@@ -0,0 +1,101 @@
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { WEB_NETWORK_CAPTURE_LIMITS, } from "../../domain/webNetworkCapture.js";
+import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
+const OPERATION = "inspect_web_network_capture";
+/** Preserve the origin and typed cause of a historical capture failure. */
+export const historicalCaptureFailure = (input, cause, phase, options) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    if (cause instanceof OwnedCommandFailure) {
+        if (cause.cleanupFailure !== null)
+            return new ProviderCleanupError(input.format, cause.resources, {
+                reason: cause.cleanupFailure,
+                previous_error: {
+                    failure_kind: cause.reason,
+                    message: cause.message,
+                    exit_code: cause.snapshot?.exitCode ?? null,
+                    signal: cause.snapshot?.signal ?? null,
+                    stdout: cause.snapshot?.stdout.text ?? null,
+                    stderr: cause.snapshot?.stderr.text ?? null,
+                    diagnostic_truncated: cause.snapshot?.diagnosticTruncated ?? null,
+                },
+            }, { operation: OPERATION, cause });
+        if (cause.reason === "cancelled")
+            return new AnalysisCancelledError(OPERATION);
+        if (cause.reason === "timeout")
+            return new AnalysisTimeoutError(OPERATION, WEB_NETWORK_CAPTURE_LIMITS.timeoutMs);
+        if (cause.reason === "output-limit")
+            return new AnalysisOutputError(OPERATION, cause.message);
+    }
+    if (options?.signal?.aborted)
+        return new AnalysisCancelledError(OPERATION);
+    if (phase === "capture-read" &&
+        cause instanceof ArtifactReaderFailure &&
+        cause.reason === "integrity")
+        return new AnalysisArtifactChangedError(OPERATION, input.capture_path, cause.message, { cause });
+    if (phase === "capture-read" &&
+        cause instanceof ArtifactReaderFailure &&
+        cause.reason === "cancelled")
+        return new AnalysisCancelledError(OPERATION);
+    if (phase === "capture-read" &&
+        cause instanceof ArtifactReaderFailure &&
+        (cause.reason === "limit" ||
+            cause.reason === "format" ||
+            cause.reason === "path"))
+        return new AnalysisInputError(OPERATION, { cause }, [
+            {
+                path: ["capture_path"],
+                reason: cause.reason === "limit" ? "out_of_range" : "invalid_format",
+                message: cause.reason === "limit"
+                    ? `${cause.message}. Select a capture within the ${WEB_NETWORK_CAPTURE_LIMITS.inputBytes}-byte input budget.`
+                    : cause.message,
+                ...(cause.reason === "limit"
+                    ? {
+                        expected: {
+                            maximum_capture_bytes: WEB_NETWORK_CAPTURE_LIMITS.inputBytes,
+                        },
+                    }
+                    : {}),
+            },
+        ]);
+    if (phase === "capture-read" &&
+        cause instanceof Error &&
+        "code" in cause &&
+        (cause.code === "EACCES" || cause.code === "EPERM"))
+        return new AnalysisAccessDeniedError(OPERATION, input.capture_path, cause.code, { cause });
+    if (phase === "capture-read" &&
+        cause instanceof Error &&
+        "code" in cause &&
+        ["ENOENT", "ENOTDIR"].includes(String(cause.code)))
+        return new AnalysisInputError(OPERATION, { cause }, [
+            {
+                path: ["capture_path"],
+                reason: "invalid_value",
+                message: `Selected capture could not be read (${String(cause.code)}): ${input.capture_path}.`,
+            },
+        ]);
+    return new ProviderAdapterError(input.format, OPERATION, {
+        cause,
+        diagnostics: {
+            phase,
+            capture_path: input.capture_path,
+            reason: cause instanceof Error ? cause.message : String(cause),
+            ...(cause instanceof ArtifactReaderFailure
+                ? { failure_kind: cause.reason }
+                : {}),
+            ...(cause instanceof OwnedCommandFailure && cause.snapshot !== null
+                ? {
+                    exit_code: cause.snapshot.exitCode ?? null,
+                    signal: cause.snapshot.signal ?? null,
+                    stdout: cause.snapshot.stdout.text,
+                    stderr: cause.snapshot.stderr.text,
+                    diagnostic_truncated: cause.snapshot.diagnosticTruncated ?? false,
+                }
+                : {}),
+        },
+    });
+};

package/dist/browser/history/CaptureFormatError.js

@@ -0,0 +1,10 @@
+/** Expected malformed, unsupported or oversized producer data at a historical decoder boundary. */
+export class CaptureFormatError extends Error {
+    reason;
+    pointer;
+    constructor(reason, message, pointer = "") {
+        super(message);
+        this.reason = reason;
+        this.pointer = pointer;
+    }
+}

package/dist/browser/history/CaptureRedaction.js

@@ -0,0 +1,65 @@
+const CREDENTIAL_HEADERS = new Set([
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+]);
+/** Literal redaction and structural authentication exclusions preserve unrelated local evidence. */
+export class CaptureRedaction {
+    sensitiveValues;
+    redactions = [];
+    #sensitiveByteValues;
+    constructor(sensitiveValues) {
+        this.sensitiveValues = sensitiveValues;
+        // An unpaired surrogate has no UTF-8 representation. Buffer.from would
+        // invent replacement-character bytes and incorrectly discard real evidence.
+        this.#sensitiveByteValues = sensitiveValues.flatMap((value) => {
+            const encoded = Buffer.from(value, "utf8");
+            return encoded.toString("utf8") === value ? [encoded] : [];
+        });
+    }
+    /** Preserve exact text unless explicitly sensitive or known transport URL userinfo. */
+    text(value, pointer, transportUrl = false) {
+        let result = value;
+        if (transportUrl) {
+            const match = /^([\x00-\x20]*(?:[a-z][a-z0-9+.-]*:)?\/\/)([^/?#]*@)/i.exec(result);
+            if (match !== null) {
+                result = `${match[1]}${result.slice(match[0].length)}`;
+                this.redactions.push({ pointer, reason: "transport-credential" });
+            }
+        }
+        if (this.sensitiveValues.some((literal) => value.includes(literal) || result.includes(literal))) {
+            this.redactions.push({ pointer, reason: "explicit-sensitive-value" });
+            return null;
+        }
+        return result;
+    }
+    /** Remove a credential field's value without retaining its digest or encoded form. */
+    credential(pointer) {
+        this.redactions.push({ pointer, reason: "transport-credential" });
+        return null;
+    }
+    /** Known HAR credential surfaces; unknown extensions are ordinary caller-selected evidence. */
+    harCredential(pointer, parent) {
+        return ((/^\/(request|response)\/headers\/\d+\/value$/.test(pointer) &&
+            typeof parent.name === "string" &&
+            CREDENTIAL_HEADERS.has(parent.name.toLowerCase())) ||
+            /^\/(request|response)\/cookies\/\d+\/value$/.test(pointer));
+    }
+    /** Only actual request/redirect fields and known transport header URLs declare URL semantics. */
+    harTransportUrl(pointer, parent) {
+        return (pointer === "/request/url" ||
+            pointer === "/response/redirectURL" ||
+            (/^\/(request|response)\/headers\/\d+\/value$/.test(pointer) &&
+                typeof parent?.name === "string" &&
+                ["location", "referer", "origin"].includes(parent.name.toLowerCase())));
+    }
+    /** Preserve bytes unless an explicitly declared UTF-8 literal occurs in them. */
+    sensitiveBytes(bytes) {
+        return this.#sensitiveByteValues.some((value) => bytes.includes(value));
+    }
+}
+/** Escape a producer property for an RFC 6901 location. */
+export const capturePointer = (parent, key) => `${parent}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+/** Structural record guard does not duck-type number/byte sidecar markers. */
+export const captureObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/browser/history/CaptureRelease.js

@@ -0,0 +1,12 @@
+/** Exact upstream package profile for unchanged offline HAR validation and numeric parsing. */
+export const HAR_CAPTURE_PROVIDER_IDENTITY = {
+    id: "har-schema/lossless-json",
+    name: "REA HAR capture adapter",
+    version: "har-schema@2.0.0;jsonc-parser@3.3.1;lossless-json@4.3.1",
+};
+/** Native executable profile verified with unchanged mitmproxy raw-state decoding. */
+export const MITMPROXY_CAPTURE_PROVIDER_IDENTITY = {
+    id: "mitmproxy-native-tnetstring",
+    name: "REA offline native mitmproxy adapter",
+    version: "12.2.3",
+};

package/dist/browser/history/HarCapture.js

@@ -0,0 +1,165 @@
+import { createHash } from "node:crypto";
+import { isSafeNumber, LosslessNumber } from "lossless-json";
+import { parseHarJson } from "./HarJson.js";
+import { WEB_NETWORK_CAPTURE_LIMITS, } from "../../domain/webNetworkCapture.js";
+import { CaptureFormatError } from "./CaptureFormatError.js";
+import { CaptureRedaction, captureObject, capturePointer, } from "./CaptureRedaction.js";
+import { createHarValidator } from "./HarSchema.js";
+import { HAR_CAPTURE_PROVIDER_IDENTITY } from "./CaptureRelease.js";
+/** Decode a retained HAR with exact numeric lexemes and unchanged upstream schema validation. */
+export const decodeHarCapture = (text, sensitiveValues) => {
+    const raw = parseHarJson(text);
+    const validation = projectHar(raw, [], false);
+    createHarValidator()(validation.reported);
+    if (!captureObject(raw) ||
+        !captureObject(raw.log) ||
+        !Array.isArray(raw.log.entries))
+        throw new CaptureFormatError("format", "HAR must contain log.entries.");
+    if (raw.log.version !== "1.2")
+        throw new CaptureFormatError("unsupported", "Only the pinned HAR 1.2 schema profile is supported.", "/log/version");
+    const entries = raw.log.entries;
+    const recordsExcluded = ["log", "entries"].some((key) => sensitiveValues.some((literal) => key.includes(literal)));
+    const container = projectHar({ ...raw, log: { ...raw.log, entries: null } }, sensitiveValues, true);
+    const records = entries.map((entry, ordinal) => {
+        // Validate each original record even when a structural ancestor excludes it.
+        const projected = projectHar(entry, sensitiveValues, true);
+        const projection = recordsExcluded
+            ? {
+                reported: null,
+                numeric_literals: [],
+                binary_fields: [],
+                redactions: [{ pointer: "", reason: "explicit-sensitive-value" }],
+            }
+            : projected;
+        return {
+            ordinal,
+            location: recordsExcluded
+                ? { kind: "unknown", reason: "explicit-sensitive-value" }
+                : { kind: "json-pointer", pointer: `/log/entries/${ordinal}` },
+            ...projection,
+            limitations: [
+                "HAR text is producer-decoded Unicode. Original body bytes remain unknown unless content explicitly uses valid base64; declared sizes are preserved independently of retained bytes. mitmproxy 12.2.3 SaveHar may report null optional postData.text; that null is retained and omitted only from the upstream validation copy.",
+                ...(recordsExcluded
+                    ? [
+                        "This record's payload and sidecars are excluded because its structural ancestor property was explicitly marked sensitive.",
+                    ]
+                    : []),
+            ],
+        };
+    });
+    return {
+        decoder: { ...HAR_CAPTURE_PROVIDER_IDENTITY },
+        container: {
+            reported: container.reported,
+            numeric_literals: container.numeric_literals,
+            redactions: container.redactions,
+            records_pointer: recordsExcluded ? null : "/log/entries",
+        },
+        total_records: records.length,
+        records,
+    };
+};
+const projectHar = (value, sensitiveValues, redact) => {
+    const redactor = new CaptureRedaction(sensitiveValues);
+    const numeric_literals = [];
+    const binary_fields = [];
+    const visit = (item, pointer, depth, parent) => {
+        if (depth > WEB_NETWORK_CAPTURE_LIMITS.depth)
+            throw new CaptureFormatError("input-limit", "HAR exceeds the 64-level complete-evidence nesting budget.", pointer);
+        if (redact &&
+            parent !== undefined &&
+            redactor.harCredential(pointer, parent))
+            return redactor.credential(pointer);
+        if (item instanceof LosslessNumber) {
+            if (redact && redactor.text(item.value, pointer) === null)
+                return null;
+            numeric_literals.push({
+                pointer,
+                producer_type: "json-number",
+                literal: item.value,
+            });
+            return isSafeNumber(item.value) ? Number(item.value) : null;
+        }
+        if (typeof item === "string") {
+            if (redact &&
+                pointer === "/response/content/text" &&
+                parent?.encoding === "base64") {
+                const bytes = decodeHarBase64(item, pointer);
+                const contentBase64 = bytes.toString("base64");
+                const sha256 = createHash("sha256").update(bytes).digest("hex");
+                const hidden = redactor.sensitiveBytes(bytes) ||
+                    sensitiveValues.some((literal) => item.includes(literal) ||
+                        contentBase64.includes(literal) ||
+                        sha256.includes(literal));
+                binary_fields.push(hidden
+                    ? {
+                        pointer,
+                        representation: "har-base64-content",
+                        state: "redacted",
+                        content_base64: null,
+                        bytes: null,
+                        sha256: null,
+                    }
+                    : {
+                        pointer,
+                        representation: "har-base64-content",
+                        state: "retained",
+                        content_base64: contentBase64,
+                        bytes: bytes.length,
+                        sha256,
+                    });
+                if (hidden) {
+                    redactor.redactions.push({
+                        pointer,
+                        reason: "explicit-sensitive-value",
+                    });
+                    return null;
+                }
+            }
+            return redact
+                ? redactor.text(item, pointer, redactor.harTransportUrl(pointer, parent))
+                : item;
+        }
+        if (item === null || typeof item === "boolean")
+            return item;
+        if (Array.isArray(item))
+            return item.map((child, index) => visit(child, capturePointer(pointer, String(index)), depth + 1));
+        if (captureObject(item))
+            return Object.fromEntries(Object.entries(item).flatMap(([key, child]) => {
+                if (redact &&
+                    sensitiveValues.some((literal) => key.includes(literal))) {
+                    const beforeNumbers = numeric_literals.length;
+                    const beforeBinaries = binary_fields.length;
+                    const beforeRedactions = redactor.redactions.length;
+                    visit(child, capturePointer(pointer, key), depth + 1, item);
+                    numeric_literals.splice(beforeNumbers);
+                    binary_fields.splice(beforeBinaries);
+                    redactor.redactions.splice(beforeRedactions);
+                    redactor.redactions.push({
+                        pointer,
+                        reason: "explicit-sensitive-value",
+                        scope: "property-name",
+                    });
+                    return [];
+                }
+                return [
+                    [key, visit(child, capturePointer(pointer, key), depth + 1, item)],
+                ];
+            }));
+        throw new CaptureFormatError("format", "HAR parser returned a non-JSON value.", pointer);
+    };
+    return {
+        reported: visit(value, "", 0),
+        numeric_literals,
+        binary_fields,
+        redactions: redactor.redactions,
+    };
+};
+const decodeHarBase64 = (value, pointer) => {
+    const compact = value.replace(/[\t\n\r ]/g, "");
+    const bytes = Buffer.from(compact, "base64");
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(compact) ||
+        bytes.toString("base64") !== compact)
+        throw new CaptureFormatError("format", "HAR content declares base64 but its text is not valid canonical base64 (ASCII whitespace is allowed).", pointer);
+    return bytes;
+};

package/dist/browser/history/HarCaptureAdapter.js

@@ -0,0 +1,20 @@
+import { fileURLToPath } from "node:url";
+import { HAR_CAPTURE_PROVIDER_IDENTITY } from "./CaptureRelease.js";
+/** HAR's parser/schema packages run in one bounded Node heap, without network or target execution. */
+export class HarCaptureAdapter {
+    format = "har";
+    identity = HAR_CAPTURE_PROVIDER_IDENTITY;
+    async command(requestPath) {
+        return {
+            command: process.execPath,
+            arguments: [
+                "--max-old-space-size=192",
+                "--max-semi-space-size=8",
+                "--v8-pool-size=1",
+                "--single-threaded",
+                fileURLToPath(new URL("./HarCaptureProcess.js", import.meta.url)),
+                requestPath,
+            ],
+        };
+    }
+}

package/dist/browser/history/HarCaptureProcess.js

@@ -0,0 +1,57 @@
+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. */
+const main = async () => {
+    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);
+        }
+        catch {
+            throw new CaptureFormatError("format", "HAR is not valid UTF-8 JSON.");
+        }
+        reply = {
+            ok: true,
+            value: decodeHarCapture(text, request.sensitive_values),
+        };
+    }
+    catch (cause) {
+        reply =
+            cause instanceof CaptureFormatError
+                ? {
+                    ok: false,
+                    reason: cause.reason,
+                    message: cause.message,
+                    pointer: cause.pointer,
+                }
+                : {
+                    ok: false,
+                    reason: "decoder",
+                    message: `HAR decoder failed unexpectedly (${cause instanceof Error ? cause.name : "unknown exception"}).`,
+                    pointer: "",
+                };
+    }
+    let text = JSON.stringify(reply);
+    if (Buffer.byteLength(text) > WEB_NETWORK_CAPTURE_LIMITS.outputBytes)
+        text = JSON.stringify({
+            ok: false,
+            reason: "limit",
+            message: "HAR reply exceeds the complete-evidence output budget.",
+            pointer: "",
+        });
+    await writeFile(request.reply_path, text, { flag: "wx", mode: 0o600 });
+};
+await main();

package/dist/browser/history/HarJson.js

@@ -0,0 +1,91 @@
+import { visit } from "jsonc-parser";
+import { LosslessNumber } from "lossless-json";
+import { WEB_NETWORK_CAPTURE_LIMITS } from "../../domain/webNetworkCapture.js";
+import { CaptureFormatError } from "./CaptureFormatError.js";
+/** Materialize upstream JSON events without duplicate folding, prototype setters or numeric rounding. */
+export const parseHarJson = (text) => {
+    const frames = [];
+    let result;
+    const valuePointer = () => {
+        const parent = frames.at(-1);
+        if (parent === undefined)
+            return "";
+        if (parent.kind === "array")
+            return `${parent.pointer}/${parent.items.length}`;
+        return parent.pendingKey === undefined
+            ? parent.pointer
+            : `${parent.pointer}/${parent.pendingKey.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+    };
+    const checkDepth = () => {
+        if (frames.length > WEB_NETWORK_CAPTURE_LIMITS.depth)
+            throw new CaptureFormatError("input-limit", "HAR exceeds the 64-level complete-evidence nesting budget.", valuePointer());
+    };
+    const append = (value) => {
+        const parent = frames.at(-1);
+        if (parent === undefined)
+            result = value;
+        else if (parent.kind === "array")
+            parent.items.push(value);
+        else {
+            if (parent.pendingKey === undefined)
+                throw new TypeError("JSON visitor omitted an object property identity.");
+            parent.members.set(parent.pendingKey, value);
+            delete parent.pendingKey;
+        }
+    };
+    visit(text, {
+        onObjectBegin: () => {
+            checkDepth();
+            frames.push({
+                kind: "object",
+                pointer: valuePointer(),
+                members: new Map(),
+            });
+        },
+        onObjectProperty: (key) => {
+            if (key === "__proto__")
+                throw new CaptureFormatError("unsupported", "HAR object contains a __proto__ member that the current JSON schema boundary cannot preserve.");
+            const frame = frames.at(-1);
+            if (frame?.kind !== "object")
+                throw new TypeError("JSON visitor emitted a property outside an object.");
+            if (frame.members.has(key))
+                throw new CaptureFormatError("format", "HAR JSON contains duplicate object members.");
+            frame.pendingKey = key;
+        },
+        onObjectEnd: () => {
+            const frame = frames.pop();
+            if (frame?.kind !== "object")
+                throw new TypeError("JSON visitor ended an unexpected object.");
+            append(Object.fromEntries(frame.members));
+        },
+        onArrayBegin: () => {
+            checkDepth();
+            frames.push({ kind: "array", pointer: valuePointer(), items: [] });
+        },
+        onArrayEnd: () => {
+            const frame = frames.pop();
+            if (frame?.kind !== "array")
+                throw new TypeError("JSON visitor ended an unexpected array.");
+            append(frame.items);
+        },
+        onLiteralValue: (value, offset, length) => {
+            checkDepth();
+            if (typeof value === "number")
+                append(new LosslessNumber(text.slice(offset, offset + length)));
+            else if (value === null ||
+                typeof value === "boolean" ||
+                typeof value === "string")
+                append(value);
+            else
+                throw new TypeError("JSON visitor emitted an unsupported literal.");
+        },
+        onError: () => {
+            throw new CaptureFormatError("format", "HAR is malformed JSON.");
+        },
+    }, {
+        disallowComments: true,
+        allowTrailingComma: false,
+        allowEmptyContent: false,
+    });
+    return result;
+};

package/dist/browser/history/HarSchema.js

@@ -0,0 +1,72 @@
+import { createRequire } from "node:module";
+import { Ajv } from "ajv";
+import { z } from "zod";
+import { CaptureFormatError } from "./CaptureFormatError.js";
+/** Validate using the unchanged, pinned upstream HAR 1.2 draft-06 schemas. */
+export const createHarValidator = () => {
+    const require = createRequire(import.meta.url);
+    const schemas = z
+        .record(z.string(), z.record(z.string(), z.unknown()))
+        .parse(require("har-schema"));
+    const ajv = new Ajv({ strict: false, allErrors: false, ownProperties: true });
+    ajv.addMetaSchema(require("ajv/dist/refs/json-schema-draft-06.json"));
+    const plugin = require("ajv-formats");
+    if (typeof plugin !== "function")
+        throw new Error("Pinned AJV formats plugin is unavailable");
+    plugin(ajv);
+    for (const schema of Object.values(schemas))
+        ajv.addSchema(schema);
+    const validate = ajv.getSchema("har.json#");
+    if (validate === undefined)
+        throw new Error("Pinned HAR root schema is unavailable");
+    return (value) => {
+        allowMitmproxyAbsentPostData(value);
+        if (!validate(value)) {
+            const error = validate.errors?.[0];
+            throw new CaptureFormatError("format", `HAR schema validation failed: ${error?.keyword ?? "unknown constraint"}.`, error?.instancePath ?? "");
+        }
+    };
+};
+/** 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;
+    const log = value.log;
+    if (typeof log !== "object" ||
+        log === null ||
+        !("entries" in log) ||
+        !Array.isArray(log.entries))
+        return;
+    for (const entry of log.entries) {
+        const candidate = entry;
+        if (typeof candidate !== "object" ||
+            candidate === null ||
+            !("request" in candidate))
+            continue;
+        const request = candidate.request;
+        if (typeof request !== "object" ||
+            request === null ||
+            !("postData" in request))
+            continue;
+        const body = request.postData;
+        if (typeof body === "object" &&
+            body !== null &&
+            "text" in body &&
+            body.text === null)
+            delete body.text;
+    }
+};