rea-agents 6.5.0 → 6.7.0

package/dist/browser/execution/CdpWebRuntimeProvider.js

@@ -1,17 +1,23 @@
 import { z } from "zod";
-import { AnalysisError } from "../../domain/analysisErrorBase.js";
-import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { AnalysisError, } from "../../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
 import { err, ok } from "../../domain/result.js";
 import { webExecutionSchema, } from "../../domain/webExecution.js";
 import { webEventListenersSchema, } from "../../domain/webEventListeners.js";
 import { CDP_BROWSER_PROVIDER_IDENTITY } from "../providerIdentities.js";
+import { CdpTargetSessionOwner } from "../CdpTargetSessionOwner.js";
 import { CdpRuntimeSession } from "./CdpRuntimeSession.js";
 import { CdpRuntimeSources } from "./CdpRuntimeSources.js";
 import { captureWebExecution } from "./CdpExecutionCapture.js";
 import { captureWebEventListeners, eventListenerObjectGroup, } from "./CdpEventListeners.js";
 /** Native CDP integration with distinct inspection/instrumentation authority and confirmed cleanup. */
 export class CdpWebRuntimeProvider {
+    #owner = new CdpTargetSessionOwner();
+    close() {
+        return this.#owner.close();
+    }
     /** Identify this adapter independently of the captured browser version. */
     identity() {
         return CDP_BROWSER_PROVIDER_IDENTITY;
@@ -29,7 +35,7 @@ export class CdpWebRuntimeProvider {
         let session;
         let result;
         try {
-            session = await CdpRuntimeSession.open(input, operation, options);
+            session = await CdpRuntimeSession.open(input, operation, options, this.#owner);
             result = ok(schema.parse(await capture(new CdpRuntimeSources(session))));
         }
         catch (cause) {
@@ -44,8 +50,20 @@ export class CdpWebRuntimeProvider {
         if (session !== undefined) {
             const failure = await session.close(result.ok ? undefined : result.error, group);
             if (failure !== undefined)
-                return err(failure);
+                return err(result.ok
+                    ? options.signal?.aborted === true
+                        ? analysisErrorWithCleanupFailure(new AnalysisCancelledError(operation, {
+                            cause: options.signal.reason,
+                            partialObservation: result.value,
+                        }), failure, operation)
+                        : failure.retainPartialObservation(result.value)
+                    : analysisErrorWithCleanupFailure(result.error, failure, operation));
         }
+        if (result.ok && options.signal?.aborted === true)
+            return err(new AnalysisCancelledError(operation, {
+                cause: options.signal.reason,
+                partialObservation: result.value,
+            }));
         return result;
     }
 }

package/dist/browser/history/CaptureFailures.js

@@ -1,4 +1,5 @@
 import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { artifactFileCancellationCause } from "../../artifacts/ArtifactFileOperation.js";
 import { AnalysisError } from "../../domain/analysisErrorBase.js";
 import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
@@ -48,7 +49,9 @@ export const historicalCaptureFailure = (input, cause, phase, options) => {
             return captureMemoryFailure(input, `The ${input.format} decoder exhausted its fixed V8 heap`, cause);
     }
     if (options?.signal?.aborted)
-        return new AnalysisCancelledError(OPERATION);
+        return new AnalysisCancelledError(OPERATION, {
+            cause: options.signal.reason,
+        });
     if (phase === "capture-read" &&
         cause instanceof ArtifactReaderFailure &&
         cause.reason === "integrity")
@@ -56,7 +59,9 @@ export const historicalCaptureFailure = (input, cause, phase, options) => {
     if (phase === "capture-read" &&
         cause instanceof ArtifactReaderFailure &&
         cause.reason === "cancelled")
-        return new AnalysisCancelledError(OPERATION);
+        return new AnalysisCancelledError(OPERATION, {
+            cause: artifactFileCancellationCause(cause),
+        });
     if (phase === "capture-read" &&
         cause instanceof ArtifactReaderFailure &&
         (cause.reason === "limit" ||

package/dist/browser/history/HarCapture.js

@@ -64,10 +64,25 @@ export const decodeHarCapture = (text, sensitiveValues) => {
         records,
     };
 };
+/** Evidence projection when `redact` is true; the upstream schema validation copy otherwise. */
 const projectHar = (value, sensitiveValues, redact) => {
     const redactor = new CaptureRedaction(sensitiveValues);
     const numeric_literals = [];
     const binary_fields = [];
+    const projectNumber = (item, pointer) => {
+        // Evidence publishes an unsafe number as null; the schema must still judge it as a number.
+        if (!redact)
+            return validationNumber(item.value);
+        const number = redactor.number(item, pointer, redact);
+        if (number === null)
+            return null;
+        numeric_literals.push({
+            pointer,
+            producer_type: "json-number",
+            literal: number.literal,
+        });
+        return number.reported;
+    };
     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);
@@ -75,17 +90,8 @@ const projectHar = (value, sensitiveValues, redact) => {
             parent !== undefined &&
             redactor.harCredential(pointer, parent))
             return redactor.credential(pointer);
-        if (item instanceof LosslessNumber) {
-            const number = redactor.number(item, pointer, redact);
-            if (number === null)
-                return null;
-            numeric_literals.push({
-                pointer,
-                producer_type: "json-number",
-                literal: number.literal,
-            });
-            return number.reported;
-        }
+        if (item instanceof LosslessNumber)
+            return projectNumber(item, pointer);
         if (typeof item === "string") {
             if (redact &&
                 pointer === "/response/content/text" &&
@@ -162,6 +168,31 @@ const projectHar = (value, sensitiveValues, redact) => {
         redactions: redactor.redactions,
     };
 };
+/**
+ * A JSON number lexeme as the validation copy carries it: its nearest double, unless rounding or
+ * overflow erased a fractional part, so the schema's `integer` checks the lexeme, not the double.
+ */
+const validationNumber = (literal) => {
+    const nearest = Number(literal);
+    if (integerLexeme(literal))
+        return nearest;
+    if (Number.isFinite(nearest) && !Number.isInteger(nearest))
+        return nearest;
+    return literal.startsWith("-") ? -0.5 : 0.5;
+};
+/** Whether a JSON number lexeme denotes an integer, decided from its digits and exponent. */
+const integerLexeme = (literal) => {
+    const match = /^-?(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(literal);
+    if (match === null)
+        return false;
+    const [, whole = "", fraction = "", exponent = "0"] = match;
+    const digits = `${whole}${fraction}`;
+    const significant = digits.replace(/0+$/, "");
+    if (/^0*$/.test(significant))
+        return true;
+    const trailingZeros = digits.length - significant.length;
+    return Number(exponent) - fraction.length + trailingZeros >= 0;
+};
 const decodeHarBase64 = (value, pointer) => {
     const compact = value.replace(/[\t\n\r ]/g, "");
     const bytes = Buffer.from(compact, "base64");

package/dist/browser/history/SazMetadata.js

@@ -1,5 +1,4 @@
-import { DOMParser, ParseError } from "@xmldom/xmldom";
-import { SaxesParser } from "saxes";
+import { parseXmlDocument } from "../../domain/xmlDocument.js";
 import { WEB_NETWORK_CAPTURE_LIMITS } from "../../domain/webNetworkCapture.js";
 import { decodeXmlPlistText, XmlPlistTextDecodeError, } from "../../domain/propertyListXmlText.js";
 import { CaptureFormatError } from "./CaptureFormatError.js";
@@ -18,30 +17,15 @@ export const decodeSazMetadata = (bytes) => {
             throw new CaptureFormatError("format", "SAZ metadata encoding declaration disagrees with its bytes.", "", cause);
         throw new CaptureFormatError("unsupported", "SAZ metadata must use UTF-8 or BOM-marked UTF-16.", "", cause);
     }
-    validateSazXml(xml);
-    let parseFailed = false;
-    let document;
-    try {
-        document = new DOMParser({
-            normalizeLineEndings: (source) => source,
-            onError: (level, message) => {
-                // The parser warns whenever the source contains U+FFFD. It is a legal
-                // XML Char, and the fatal decoder above already rejected invalid
-                // source bytes, so only that warning is not a well-formedness failure.
-                if (level === "warning" &&
-                    message.startsWith("Unicode replacement character detected"))
-                    return;
-                parseFailed = true;
-            },
-        }).parseFromString(xml, "application/xml");
-    }
-    catch (cause) {
-        if (!(cause instanceof ParseError))
-            throw cause;
-        throw new CaptureFormatError("format", "SAZ metadata is not well-formed XML.");
-    }
-    if (parseFailed)
-        throw new CaptureFormatError("format", "SAZ metadata is not well-formed XML.");
+    const parsed = parseXmlDocument(xml, {
+        doctype: "reject",
+        lineEndings: "preserve",
+    });
+    if (!parsed.ok)
+        throw new CaptureFormatError(parsed.error.reason === "doctype" ? "unsupported" : "format", parsed.error.reason === "doctype"
+            ? "SAZ metadata DTDs are unsupported."
+            : "SAZ metadata is not well-formed XML.", "", parsed.error);
+    const document = parsed.value;
     if (document.documentElement?.tagName !== "Session")
         throw new CaptureFormatError("format", "SAZ metadata must have a Session document element.");
     const visit = (node, depth) => {
@@ -69,24 +53,3 @@ export const decodeSazMetadata = (bytes) => {
     };
     return visit(document, 0);
 };
-/** Validate well-formedness before the DOM parser projects retained evidence. */
-const validateSazXml = (xml) => {
-    const parser = new SaxesParser({
-        defaultXMLVersion: "1.0",
-        forceXMLVersion: true,
-    });
-    let hasDoctype = false;
-    parser.on("doctype", () => {
-        hasDoctype = true;
-    });
-    try {
-        parser.write(xml).close();
-    }
-    catch {
-        if (hasDoctype)
-            throw new CaptureFormatError("unsupported", "SAZ metadata DTDs are unsupported.");
-        throw new CaptureFormatError("format", "SAZ metadata is not well-formed XML.");
-    }
-    if (hasDoctype)
-        throw new CaptureFormatError("unsupported", "SAZ metadata DTDs are unsupported.");
-};

package/dist/browser/modules/NativeModuleResolver.js

@@ -7,6 +7,7 @@ import { jsonObjectSchema } from "../../domain/jsonValue.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
 import { err, ok } from "../../domain/result.js";
+import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, } from "../../artifacts/AnalysisCleanupLease.js";
 import { webModuleResolutionSchema } from "../../domain/webModuleTrace.js";
 import { ProviderStartupDeadline } from "../../process/ProviderDeadline.js";
 const OPERATION = "trace_web_module_imports";
@@ -26,7 +27,7 @@ export class NativeModuleResolver {
     #tail = Promise.resolve();
     #closing = false;
     #closePromise;
-    #pendingBrowser;
+    #pendingCleanup;
     constructor(environment, launcher = launch) {
         this.environment = environment;
         this.launcher = launcher;
@@ -40,7 +41,7 @@ export class NativeModuleResolver {
     }
     async #resolve(input, options) {
         if (options?.signal?.aborted === true)
-            return err(new AnalysisCancelledError(OPERATION));
+            return err(new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }));
         const pending = await this.#retryCleanup();
         if (pending !== undefined)
             return err(pending);
@@ -50,20 +51,47 @@ export class NativeModuleResolver {
                 userMessage: "Provide an absolute REA_BROWSER_EXECUTABLE for a caller-supplied Chromium browser supporting import.meta.resolve. REA installs no browser.",
             }));
         const deadline = new ProviderStartupDeadline(TIMEOUT_MS, options?.signal);
-        let browser;
+        let activeCall;
+        let interruption;
+        const interrupted = () => deadline.interruption === "cancelled"
+            ? new AnalysisCancelledError(OPERATION, {
+                cause: deadline.signal.reason,
+            })
+            : new AnalysisTimeoutError(OPERATION, TIMEOUT_MS);
+        const assertActive = () => {
+            if (!deadline.signal.aborted)
+                return;
+            interruption = interrupted();
+            throw interruption;
+        };
+        const observe = (call) => {
+            assertActive();
+            const observed = { settled: false };
+            activeCall = observed;
+            return call().then((value) => {
+                observed.settled = true;
+                return value;
+            }, (cause) => {
+                observed.settled = true;
+                throw observed.interruption === undefined
+                    ? cause
+                    : observed.interruption;
+            });
+        };
+        let lease;
         let cleanup;
         const close = () => {
-            if (cleanup === undefined && browser !== undefined) {
-                const owned = browser;
+            if (cleanup === undefined && lease !== undefined) {
+                const owned = lease;
                 cleanup = Promise.resolve().then(async () => {
-                    await owned.close();
-                    this.#pendingBrowser = undefined;
+                    await owned.release();
+                    this.#pendingCleanup = undefined;
                 });
             }
             return cleanup ?? Promise.resolve();
         };
         const onAbort = () => {
-            if (browser !== undefined) {
+            if (lease !== undefined) {
                 const pending = close();
                 void pending.catch(() => undefined);
             }
@@ -71,8 +99,8 @@ export class NativeModuleResolver {
         deadline.signal.addEventListener("abort", onAbort, { once: true });
         let result;
         try {
-            deadline.signal.throwIfAborted();
-            browser = await this.launcher({
+            assertActive();
+            const browser = await observe(() => this.launcher({
                 executablePath: executable,
                 headless: true,
                 timeout: Math.max(1, deadline.remainingMs()),
@@ -88,43 +116,57 @@ export class NativeModuleResolver {
                         ? ["--no-sandbox"]
                         : []),
                 ],
-            });
-            this.#pendingBrowser = browser;
-            deadline.signal.throwIfAborted();
-            result = ok(await resolveInBrowser(browser, input, deadline, executable));
+            }));
+            lease = new AnalysisCleanupLease(async () => {
+                if (deadline.signal.aborted &&
+                    activeCall !== undefined &&
+                    !activeCall.settled) {
+                    interruption = interrupted();
+                    activeCall.interruption = interruption;
+                }
+                await browser.close();
+            }, ["chromium-browser"]);
+            this.#pendingCleanup = lease;
+            assertActive();
+            result = ok(await resolveInBrowser(browser, input, deadline, executable, assertActive, observe));
         }
         catch (cause) {
-            result = err(deadline.interruption === "cancelled"
-                ? new AnalysisCancelledError(OPERATION)
-                : deadline.interruption === "timeout"
-                    ? new AnalysisTimeoutError(OPERATION, TIMEOUT_MS)
-                    : cause instanceof AnalysisOutputError ||
-                        cause instanceof AnalysisCapabilityUnavailableError ||
-                        cause instanceof BrowserObservationError
-                        ? cause
-                        : new ProviderAdapterError("native-module-resolver", OPERATION, {
-                            cause,
-                            diagnostics: {
-                                executable,
-                                error_message: cause instanceof Error ? cause.message : String(cause),
-                            },
-                        }));
+            result = err(cause === interruption && interruption !== undefined
+                ? interruption
+                : cause instanceof AnalysisOutputError ||
+                    cause instanceof AnalysisCapabilityUnavailableError ||
+                    cause instanceof BrowserObservationError
+                    ? cause
+                    : new ProviderAdapterError("native-module-resolver", OPERATION, {
+                        cause,
+                        diagnostics: {
+                            executable,
+                            error_message: cause instanceof Error ? cause.message : String(cause),
+                        },
+                    }));
         }
         finally {
             deadline.signal.removeEventListener("abort", onAbort);
             deadline.dispose();
         }
+        let cleanupError;
         try {
             await close();
         }
         catch (cause) {
-            const failure = cleanupFailure(cause, result.ok ? result.value.rawResult : undefined);
-            return err(result.ok
-                ? failure
-                : analysisErrorWithCleanupFailure(result.error, failure, OPERATION));
+            cleanupError = cleanupFailure(cause, result.ok ? completedObservation(input, result.value) : undefined);
+            if (lease !== undefined)
+                new AnalysisCleanupLeaseGroup(cleanupError, [lease]);
         }
         if (result.ok && options?.signal?.aborted)
-            return err(new AnalysisCancelledError(OPERATION));
+            result = err(new AnalysisCancelledError(OPERATION, {
+                cause: options.signal.reason,
+                partialObservation: completedObservation(input, result.value),
+            }));
+        if (cleanupError !== undefined)
+            return err(result.ok
+                ? cleanupError
+                : analysisErrorWithCleanupFailure(result.error, cleanupError, OPERATION).bindCleanupDependencies([result.error, cleanupError]));
         return result;
     }
     async close() {
@@ -147,25 +189,27 @@ export class NativeModuleResolver {
         });
     }
     async #retryCleanup() {
-        const browser = this.#pendingBrowser;
-        if (browser === undefined)
+        const lease = this.#pendingCleanup;
+        if (lease === undefined)
             return undefined;
         try {
-            await browser.close();
-            this.#pendingBrowser = undefined;
+            await lease.release();
+            this.#pendingCleanup = undefined;
             return undefined;
         }
         catch (cause) {
-            return cleanupFailure(cause);
+            const failure = cleanupFailure(cause);
+            new AnalysisCleanupLeaseGroup(failure, [lease]);
+            return failure;
         }
     }
 }
-const resolveInBrowser = async (browser, input, deadline, executable) => {
-    const context = await browser.newContext({
+const resolveInBrowser = async (browser, input, deadline, executable, assertActive, observe) => {
+    const context = await observe(() => browser.newContext({
         serviceWorkers: "block",
         acceptDownloads: false,
-    });
-    const page = await context.newPage();
+    }));
+    const page = await observe(() => context.newPage());
     const diagnostics = [];
     let diagnosticBytes = 0;
     page.on("console", (message) => {
@@ -181,7 +225,7 @@ const resolveInBrowser = async (browser, input, deadline, executable) => {
     const transportUrl = new URL(importerUrl);
     transportUrl.hash = "";
     let stubSent = false;
-    await context.route("**/*", async (route) => {
+    await observe(() => context.route("**/*", async (route) => {
         const request = route.request();
         if (request.resourceType() === "document" &&
             request.url() === documentUrl.split("#")[0]) {
@@ -220,21 +264,21 @@ const resolveInBrowser = async (browser, input, deadline, executable) => {
             });
             await route.abort();
         }
-    });
-    await page.goto(documentUrl, {
+    }));
+    await observe(() => page.goto(documentUrl, {
         timeout: Math.max(1, deadline.remainingMs()),
-    });
-    await page.evaluate(`{const script = document.createElement("script"); script.type = "module"; script.src = ${scriptJson(importerUrl)}; script.onerror = () => {globalThis.__reaModuleFailure = "Trusted resolver stub could not be loaded in the selected context.";}; document.head.append(script);}`);
-    await page.waitForFunction(() => Reflect.has(globalThis, "__reaModuleResult") ||
+    }));
+    await observe(() => page.evaluate(`{const script = document.createElement("script"); script.type = "module"; script.src = ${scriptJson(importerUrl)}; script.onerror = () => {globalThis.__reaModuleFailure = "Trusted resolver stub could not be loaded in the selected context.";}; document.head.append(script);}`));
+    await observe(() => page.waitForFunction(() => Reflect.has(globalThis, "__reaModuleResult") ||
         Reflect.has(globalThis, "__reaModuleUnsupported") ||
-        Reflect.has(globalThis, "__reaModuleFailure"), undefined, { timeout: Math.max(1, deadline.remainingMs()) });
-    const unsupported = await page.evaluate(() => Reflect.get(globalThis, "__reaModuleUnsupported"));
+        Reflect.has(globalThis, "__reaModuleFailure"), undefined, { timeout: Math.max(1, deadline.remainingMs()) }));
+    const unsupported = await observe(() => page.evaluate(() => Reflect.get(globalThis, "__reaModuleUnsupported")));
     if (unsupported === true)
         throw new AnalysisCapabilityUnavailableError("native-module-resolver", OPERATION, "native_resolution_unsupported", {
             userMessage: `Configured Chromium ${browser.version()} does not supply import.meta.resolve; use a browser supporting native module resolution.`,
         });
-    const raw = await page.evaluate(() => Reflect.get(globalThis, "__reaModuleResult"));
-    const failure = await page.evaluate(() => Reflect.get(globalThis, "__reaModuleFailure"));
+    const raw = await observe(() => page.evaluate(() => Reflect.get(globalThis, "__reaModuleResult")));
+    const failure = await observe(() => page.evaluate(() => Reflect.get(globalThis, "__reaModuleFailure")));
     if (typeof failure === "string")
         throw new AnalysisOutputError(OPERATION, `${failure} Native diagnostics: ${diagnostics.join("\n")}`);
     const parsed = reportSchema.safeParse(raw);
@@ -245,7 +289,7 @@ const resolveInBrowser = async (browser, input, deadline, executable) => {
         throw new AnalysisOutputError(OPERATION, "Native resolver report has invalid shape or does not match the selected importer/specifiers.");
     if (diagnosticBytes > 1024 * 1024)
         throw new BrowserObservationError(OPERATION, "payload_limit");
-    deadline.signal.throwIfAborted();
+    assertActive();
     const engine = {
         id: "chromium-native-module-resolver",
         version: browser.version(),
@@ -263,12 +307,18 @@ const resolveInBrowser = async (browser, input, deadline, executable) => {
         }),
     };
 };
+const completedObservation = (input, batch) => ({
+    kind: "web-module-resolution",
+    request: input,
+    batch,
+});
 const cleanupFailure = (cause, observation) => new ProviderCleanupError("native-module-resolver", ["chromium-browser"], {
     reason: cause instanceof Error ? cause.message : String(cause),
-    ...(observation === undefined
-        ? {}
-        : { partial_observation: observation }),
-}, { cause, operation: OPERATION });
+}, {
+    cause,
+    operation: OPERATION,
+    ...(observation === undefined ? {} : { partialObservation: observation }),
+});
 const scriptJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c");
 const htmlAttribute = (value) => value
     .replaceAll("&", "&amp;")

package/dist/browser/modules/WebModuleArtifacts.js

@@ -1,6 +1,7 @@
 import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
 import { jsonObjectSchema } from "../../domain/jsonValue.js";
 import { err, ok } from "../../domain/result.js";
+import { webArtifactCleanupFailures } from "../WebArtifactCleanup.js";
 import { LocalWebScriptArtifacts } from "../assets/LocalWebScriptArtifacts.js";
 import { readWebArtifactJson, webArtifactReadError, } from "../assets/WebArtifactReads.js";
 /** Add an explicitly selected import map to a verified captured-script source. */
@@ -26,9 +27,17 @@ export class LocalWebModuleArtifacts {
                 ? []
                 : [Promise.resolve().then(closeScript)]),
         ]);
-        const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
-        if (failures.length > 0)
-            throw new AggregateError(failures, "Web module artifact cleanup failed");
+        const failures = results.flatMap((result, index) => result.status === "rejected"
+            ? [
+                {
+                    cause: result.reason,
+                    resource: index === 0 ? "web module artifacts" : "web scripts",
+                },
+            ]
+            : []);
+        const error = webArtifactCleanupFailures("web-module-artifacts", "trace_web_module_imports", failures);
+        if (error !== undefined)
+            throw error;
     }
     /** Read selected source and optional map without website requests. */
     async load(input, options) {

package/dist/browser/network/PlaywrightNetworkContent.js

@@ -7,11 +7,12 @@ const credentialHeaders = new Set([
     "cookie",
     "set-cookie",
 ]);
-const errorMessage = (cause, secrets) => {
+const errorMessage = (cause, secrets, maxMetadataAllocationBytes) => {
     const message = cause instanceof Error && cause.message !== ""
         ? cause.message
         : "Network read failed";
-    return secrets.redactionAllocationCost(message.length) <= 1024 * 1024
+    return secrets.redactionAllocationCost(message.length) <=
+        maxMetadataAllocationBytes
         ? secrets.redact(message)
         : "Network read failed; diagnostic exceeds the allocation budget.";
 };
@@ -22,10 +23,10 @@ export const captureNetworkHeaders = async (source, secrets, options) => {
         let cost = 0;
         for (const { name, value } of headers) {
             cost += secrets.redactionAllocationCost(name.length + value.length) + 128;
-            if (cost > 1024 * 1024)
+            if (cost > options.maxHeaderAllocationBytes)
                 return {
                     state: "unavailable",
-                    message: "Headers exceed the 1 MiB allocation budget.",
+                    message: `Headers exceed the ${String(options.maxHeaderAllocationBytes)}-byte allocation budget.`,
                 };
         }
         return {
@@ -45,38 +46,60 @@ export const captureNetworkHeaders = async (source, secrets, options) => {
         };
     }
     catch (cause) {
-        return { state: "unavailable", message: errorMessage(cause, secrets) };
+        return {
+            state: "unavailable",
+            message: errorMessage(cause, secrets, options.maxMetadataAllocationBytes),
+        };
     }
 };
 /** Retain bytes returned by Playwright's body API, after declared-secret redaction. */
-export const captureNetworkBody = async (read, phase, source, secrets, options) => {
+export const captureNetworkBody = async (read, phase, source, secrets, options, preflight) => {
     try {
         const observed = await withPlaywrightExecutionBoundary(read, options.timeoutMs, options.signal);
         if (observed === null)
             return { state: "not_exposed" };
         // This bounds subsequent redaction, base64 and validation copies, but the
         // Playwright API itself has already materialized the body (see PR limits).
-        if (observed.length > 64 * 1024)
+        const maxBodyBytes = options.maxBodyBytes;
+        if (observed.length > maxBodyBytes)
             return {
                 state: "unavailable",
-                reason: "body-read-failed",
-                message: "Body exceeds the 64 KiB retained-content budget.",
+                reason: "body-size-limit",
+                message: `Playwright materialized the body before its ${String(maxBodyBytes)}-byte retained-body budget was checked.`,
+                limit_bytes: maxBodyBytes,
+                observed_bytes: observed.length,
             };
-        if (secrets.redactionAllocationCost(observed.length) > 1024 * 1024)
+        const bodyAllocationCost = secrets.redactionAllocationCost(observed.length);
+        const base64AllocationCost = Math.ceil(observed.length / 3) * 4 * 8 + 2;
+        const maxBodyAllocationBytes = options.maxBodyAllocationBytes;
+        const observedBodyAllocationBytes = Math.max(bodyAllocationCost, base64AllocationCost);
+        if (observedBodyAllocationBytes > maxBodyAllocationBytes)
             return {
                 state: "unavailable",
-                reason: "body-read-failed",
-                message: "Body redaction exceeds the allocation budget.",
+                reason: "body-allocation-limit",
+                message: "Body redaction exceeds the selected network body allocation budget.",
+                limit_allocation_bytes: maxBodyAllocationBytes,
+                observed_allocation_bytes: observedBodyAllocationBytes,
             };
-        const retained = secrets.redactBytes(observed);
         const contentType = source.headers()["content-type"];
         if (contentType !== undefined &&
-            secrets.redactionAllocationCost(contentType.length) > 64 * 1024)
+            secrets.redactionAllocationCost(contentType.length) >
+                options.maxHeaderAllocationBytes)
             return {
                 state: "unavailable",
-                reason: "body-read-failed",
-                message: "Content type exceeds the retained metadata budget.",
+                reason: "body-allocation-limit",
+                message: "Content type exceeds the selected network header allocation budget.",
+                limit_allocation_bytes: options.maxHeaderAllocationBytes,
+                observed_allocation_bytes: secrets.redactionAllocationCost(contentType.length),
             };
+        const admission = preflight?.({
+            observedBytes: observed.length,
+            allocationBytes: observedBodyAllocationBytes,
+            mediaType: contentType,
+        });
+        if (admission?.status === "omitted")
+            return { state: "omitted", reason: admission.reason };
+        const retained = secrets.redactBytes(observed);
         return {
             state: "captured",
             representation: phase === "request"
@@ -100,7 +123,7 @@ export const captureNetworkBody = async (read, phase, source, secrets, options)
                 : cause instanceof AnalysisTimeoutError
                     ? "body-read-timeout"
                     : "body-read-failed",
-            message: errorMessage(cause, secrets),
+            message: errorMessage(cause, secrets, options.maxMetadataAllocationBytes),
         };
     }
 };