rea-agents 6.5.0 → 6.7.0

package/dist/browser/PlaywrightScenarioSession.js

@@ -1,3 +1,5 @@
+import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, } from "../artifacts/AnalysisCleanupLease.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { BrowserScenarioSecrets } from "./BrowserScenarioSecrets.js";
 import { failBrowserScenarioOperation, openPlaywrightScenarioBrowser, } from "./PlaywrightScenarioBrowser.js";
@@ -6,12 +8,14 @@ import { capturePlaywrightStepArtifacts } from "./PlaywrightScenarioArtifacts.js
 import { PlaywrightScenarioEvents } from "./PlaywrightScenarioEvents.js";
 import { PlaywrightScenarioStorage } from "./PlaywrightScenarioStorage.js";
 import { PlaywrightScenarioServiceWorkers } from "./PlaywrightScenarioServiceWorkers.js";
-import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
+import { withPlaywrightExecutionBoundary, PLAYWRIGHT_CLEANUP_CONFIRMATION_TIMEOUT_MS, } from "./PlaywrightExecutionBoundary.js";
 import { browserScenarioCaptureData, browserScenarioOperationFailure, } from "./BrowserScenarioPartialObservation.js";
 const OPERATION = "capture_browser_scenario";
 const throwIfScenarioCancelled = (signal) => {
     if (signal?.aborted === true)
-        throw new BrowserObservationError(OPERATION, "cancelled");
+        throw new BrowserObservationError(OPERATION, "cancelled", {
+            cause: signal?.reason,
+        });
 };
 const throwCleanupFailures = (failures) => {
     if (failures.length === 1)
@@ -47,6 +51,9 @@ export class PlaywrightScenarioSession {
     serviceWorkers;
     signal;
     #storageReleased = false;
+    #stopLoading = false;
+    cleanupLease;
+    #policyStopsLoading = false;
     constructor(opened, options) {
         this.opened = opened;
         this.mode = options.mode;
@@ -59,6 +66,13 @@ export class PlaywrightScenarioSession {
         this.signal = options.signal;
         this.version = opened.browser.version();
         this.initialUrl = opened.page.url();
+        this.cleanupLease = new AnalysisCleanupLease(async () => {
+            await this.#closeResources();
+        }, {
+            get cleanupResources() {
+                return opened.cleanup.cleanupResources;
+            },
+        });
     }
     static async open(scenario, environment, options) {
         throwIfScenarioCancelled(options.signal);
@@ -66,23 +80,48 @@ export class PlaywrightScenarioSession {
         if (secrets === undefined)
             throw new BrowserObservationError(OPERATION, "secret_unavailable");
         const startedAt = performance.now();
+        const openingCleanup = new Set();
         const opening = openPlaywrightScenarioBrowser(scenario, environment, {
             signal: options.signal,
-            ...(options.retainCleanup === undefined
-                ? {}
-                : { retainCleanup: options.retainCleanup }),
+            retainCleanup: (lease) => {
+                openingCleanup.add(lease);
+                options.retainCleanup?.(lease);
+            },
         });
         let opened;
         try {
             opened = await withPlaywrightExecutionBoundary(() => opening, undefined, options.signal);
         }
         catch (cause) {
-            const lateCleanup = () => opening.then((lateOpened) => lateOpened.cleanup.close(), () => undefined);
-            options.retainCleanup?.(() => withPlaywrightExecutionBoundary(lateCleanup, 1_000));
-            void lateCleanup().catch((cleanupCause) => {
-                // best-effort cleanup: retainCleanup keeps the retry capability.
-                void cleanupCause;
+            let lateOpened;
+            let openingFailure;
+            const cleanup = new AnalysisCleanupLease(async () => {
+                try {
+                    lateOpened = await opening;
+                }
+                catch (cause) {
+                    openingFailure =
+                        cause instanceof AnalysisError &&
+                            !(options.signal?.aborted === true &&
+                                cause === options.signal.reason)
+                            ? cause
+                            : undefined;
+                    const results = await Promise.allSettled([...openingCleanup].map((lease) => lease.release()));
+                    const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+                    throwCleanupFailures(failures);
+                    if (openingFailure?.cleanupIncomplete === true)
+                        throw openingFailure;
+                    return;
+                }
+                await lateOpened.cleanup.release();
+            }, {
+                get cleanupResources() {
+                    return (lateOpened?.cleanup.cleanupResources ??
+                        openingFailure?.cleanupResources);
+                },
             });
+            options.retainCleanup?.(cleanup);
+            void withPlaywrightExecutionBoundary(() => cleanup.release(), 1_000).catch(() => undefined);
             throw cause;
         }
         const session = await this.initializeSession(opened, scenario, secrets, options);
@@ -104,7 +143,7 @@ export class PlaywrightScenarioSession {
             catch (failure) {
                 cleanup = "incomplete";
                 cleanupFailure = { cause: failure };
-                options.retainCleanup?.(() => session.close());
+                options.retainCleanup?.(session.cleanupLease);
             }
             throw browserScenarioOperationFailure(cause, {
                 kind: "browser-scenario-observation",
@@ -148,6 +187,7 @@ export class PlaywrightScenarioSession {
                 enabled: new Set(scenario.capture.events),
                 secrets,
                 network: scenario.capture.network,
+                limits: scenario.capture.limits,
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
             return new PlaywrightScenarioSession(opened, {
@@ -161,28 +201,36 @@ export class PlaywrightScenarioSession {
         }
         catch (cause) {
             let storageReleased = false;
+            const storageStopsLoading = storage !== undefined && options.signal?.aborted === true;
+            let policyStopsLoading = !storageStopsLoading;
             const cleanup = async () => {
                 let storageFailure;
                 let policyFailure;
                 let browserFailure;
                 if (!storageReleased) {
                     try {
-                        await storage?.close(options.signal?.aborted === true);
+                        const result = await storage?.close(storageStopsLoading);
+                        if (storageStopsLoading && result?.loadingStopped !== true)
+                            policyStopsLoading = true;
                     }
                     catch (failure) {
                         storageFailure = { cause: failure };
+                        // Ownership transfers only after the storage attempt is no longer
+                        // in flight. Its failure does not establish that navigation stop
+                        // succeeded, so the policy owner must confirm it before release.
+                        policyStopsLoading = true;
                     }
                 }
                 try {
                     if (!opened.cleanup.browserClosed)
-                        await serviceWorkers?.close(true);
+                        await serviceWorkers?.close(policyStopsLoading);
                 }
                 catch (failure) {
                     policyFailure = { cause: failure };
                 }
                 if (policyFailure === undefined) {
                     try {
-                        await opened.cleanup.close(events === undefined
+                        await opened.cleanup.release(events === undefined
                             ? undefined
                             : () => events?.finish() ?? Promise.resolve());
                     }
@@ -208,12 +256,13 @@ export class PlaywrightScenarioSession {
                     ...(browserFailure === undefined ? [] : [browserFailure.cause]),
                 ]);
             };
+            const recovery = new AnalysisCleanupLease(cleanup, opened.cleanup);
             try {
-                return await failBrowserScenarioOperation(cleanup, cause);
+                return await failBrowserScenarioOperation(recovery, cause);
             }
             catch (failure) {
                 if (failure !== cause)
-                    options.retainCleanup?.(cleanup);
+                    options.retainCleanup?.(recovery);
                 throw failure;
             }
         }
@@ -259,27 +308,54 @@ export class PlaywrightScenarioSession {
         }), undefined, signal);
     }
     async close(stopLoading = this.signal?.aborted === true) {
+        this.#stopLoading ||= stopLoading;
+        try {
+            await withPlaywrightExecutionBoundary(() => this.cleanupLease.release(), PLAYWRIGHT_CLEANUP_CONFIRMATION_TIMEOUT_MS);
+        }
+        catch (cause) {
+            const error = new BrowserObservationError(OPERATION, "cleanup_failed", {
+                cause,
+                cleanup: {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    resources: this.cleanupLease.cleanupResources ?? [],
+                },
+            });
+            new AnalysisCleanupLeaseGroup(error, [this.cleanupLease]);
+            throw error;
+        }
+        return this.mode === "launch"
+            ? "terminated-owned-process"
+            : "disconnected-external";
+    }
+    async #closeResources() {
+        const stopLoading = this.#stopLoading || this.signal?.aborted === true;
         let storageFailure;
         let policyFailure;
         let browserFailure;
+        if (stopLoading && this.storage === undefined)
+            this.#policyStopsLoading = true;
         if (!this.#storageReleased) {
             try {
-                await this.storage?.close(stopLoading);
+                const result = await this.storage?.close(stopLoading);
+                if (stopLoading && result?.loadingStopped !== true)
+                    this.#policyStopsLoading = true;
             }
             catch (failure) {
                 storageFailure = { cause: failure };
+                if (stopLoading)
+                    this.#policyStopsLoading = true;
             }
         }
         try {
             if (!this.opened.cleanup.browserClosed)
-                await this.serviceWorkers?.close(stopLoading);
+                await this.serviceWorkers?.close(this.#policyStopsLoading);
         }
         catch (failure) {
             policyFailure = { cause: failure };
         }
         if (policyFailure === undefined) {
             try {
-                await this.opened.cleanup.close(() => this.eventCapture.finish());
+                await this.opened.cleanup.release(() => this.eventCapture.finish());
             }
             catch (failure) {
                 browserFailure = { cause: failure };
@@ -302,9 +378,6 @@ export class PlaywrightScenarioSession {
                 : [storageFailure.cause]),
             ...(browserFailure === undefined ? [] : [browserFailure.cause]),
         ]);
-        return this.mode === "launch"
-            ? "terminated-owned-process"
-            : "disconnected-external";
     }
     redactError(error) {
         return this.secrets.redact(error instanceof Error ? error.message : "browser action failed");

package/dist/browser/PlaywrightScenarioStorage.js

@@ -1,3 +1,4 @@
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
@@ -72,6 +73,7 @@ export class PlaywrightScenarioStorage {
     #generation = 0;
     #closed = false;
     #cleanupCompleted = false;
+    #loadingStopped = false;
     #failure;
     #closePromise;
     #detachPromise;
@@ -109,8 +111,11 @@ export class PlaywrightScenarioStorage {
                         detached = true;
                     }
                 };
-                retainCleanup?.(lateCleanup);
-                void withPlaywrightExecutionBoundary(lateCleanup, STORAGE_CLEANUP_TIMEOUT_MS).catch(() => undefined);
+                const cleanup = new AnalysisCleanupLease(lateCleanup, [
+                    "browser_storage_transport",
+                ]);
+                retainCleanup?.(cleanup);
+                void withPlaywrightExecutionBoundary(() => cleanup.release(), STORAGE_CLEANUP_TIMEOUT_MS).catch(() => undefined);
             }
             throw cause;
         }
@@ -126,10 +131,10 @@ export class PlaywrightScenarioStorage {
     }
     async initializeRoot(page, context) {
         const rootInfo = targetInfoResponse.parse(await this.cdp.send("Target.getTargetInfo"));
-        const root = this.createTarget(undefined, rootInfo.targetInfo.targetId, (method, params) => this.cdp.send(method, params));
-        this.#targets.set("", root);
         if (this.#closed)
             return;
+        const root = this.createTarget(undefined, rootInfo.targetInfo.targetId, (method, params) => this.cdp.send(method, params));
+        this.#targets.set("", root);
         this.listen(page, context);
         const ready = this.initializeTarget(root);
         root.ready = ready;
@@ -435,7 +440,7 @@ export class PlaywrightScenarioStorage {
     }
     close(stopLoading = false) {
         if (this.#cleanupCompleted)
-            return Promise.resolve();
+            return Promise.resolve({ loadingStopped: this.#loadingStopped });
         if (this.#closePromise !== undefined)
             return this.#closePromise;
         const closing = this.closeResources(stopLoading).catch((cause) => {
@@ -457,11 +462,13 @@ export class PlaywrightScenarioStorage {
     async closeResources(stopLoading) {
         this.#closed = true;
         let stopLoadingFailure;
-        if (stopLoading) {
+        if (stopLoading && !this.#loadingStopped) {
             try {
                 const root = this.#targets.get("");
-                if (root !== undefined)
+                if (root !== undefined) {
                     await withPlaywrightExecutionBoundary(() => root.send("Page.stopLoading"), STORAGE_CLEANUP_TIMEOUT_MS);
+                    this.#loadingStopped = true;
+                }
             }
             catch (cause) {
                 stopLoadingFailure = { cause };
@@ -503,5 +510,6 @@ export class PlaywrightScenarioStorage {
         this.#cleanupCompleted = true;
         if (stopLoadingFailure !== undefined)
             throw stopLoadingFailure.cause;
+        return { loadingStopped: this.#loadingStopped };
     }
 }

package/dist/browser/StructuredFieldToken.js

@@ -0,0 +1,53 @@
+// RFC 9651 sections 4.2.3–4.2.10. Consume complete items, without retaining
+// parameter values that the response-declaration projection does not expose.
+const token = /[A-Za-z*][A-Za-z0-9!#$%&'*+.^_`|~:/\x2d]*/uy;
+const key = /[a-z*][a-z0-9_.*\x2d]*/uy;
+const bareItem = /(?:[A-Za-z*][A-Za-z0-9!#$%&'*+.^_`|~:/\x2d]*|"(?:[\x20-\x21\x23-\x5b\x5d-\x7e]|\\["\\])*"|-?[0-9]{1,12}\.[0-9]{1,3}|-?[0-9]{1,15}|\?[01]|@-?[0-9]{1,15}|:(?<bytes>[A-Za-z0-9+/]*={0,2}):|%"(?<display>(?:[\x20-\x21\x23-\x24\x26-\x7e]|%[0-9a-f]{2})*)")/uy;
+/** Return the exact declared token only if the entire Structured Field Item is valid. */
+export const structuredFieldToken = (value) => {
+    if (value === undefined)
+        return null;
+    let cursor = 0;
+    while (value[cursor] === " ")
+        cursor += 1;
+    token.lastIndex = cursor;
+    const declared = token.exec(value)?.[0];
+    if (declared === undefined)
+        return null;
+    cursor = token.lastIndex;
+    while (value[cursor] === ";") {
+        cursor += 1;
+        while (value[cursor] === " ")
+            cursor += 1;
+        key.lastIndex = cursor;
+        if (key.exec(value) === null)
+            return null;
+        cursor = key.lastIndex;
+        if (value[cursor] !== "=")
+            continue;
+        bareItem.lastIndex = cursor + 1;
+        const parameter = bareItem.exec(value);
+        if (parameter === null)
+            return null;
+        cursor = bareItem.lastIndex;
+        const bytes = parameter.groups?.bytes;
+        if (bytes !== undefined) {
+            const padded = bytes.endsWith("=");
+            if (padded ? bytes.length % 4 !== 0 : bytes.length % 4 === 1)
+                return null;
+        }
+        const display = parameter.groups?.display;
+        if (display !== undefined) {
+            try {
+                // Percent syntax was checked above; this rejects invalid UTF-8 octets.
+                decodeURIComponent(display);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    while (value[cursor] === " ")
+        cursor += 1;
+    return cursor === value.length ? declared : null;
+};

package/dist/browser/WebArtifactCleanup.js

@@ -0,0 +1,53 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+export const webArtifactCleanupFailures = (owner, operation, failures) => {
+    if (failures.length === 0)
+        return undefined;
+    const normalized = failures.map(({ resource, cause }) => {
+        if (cause instanceof AnalysisError) {
+            const projection = projectAnalysisError(cause);
+            return {
+                cause,
+                projection,
+                observation: {
+                    reason: projection.message,
+                    resources: cause.cleanupResources.length === 0
+                        ? [resource]
+                        : cause.cleanupResources,
+                },
+            };
+        }
+        return {
+            cause,
+            projection: undefined,
+            observation: ArtifactReaderFailure.cleanupObservation(cause, resource),
+        };
+    });
+    const recoveryActions = [
+        ...new Set(normalized.flatMap(({ projection }) => projection === undefined ? [] : [projection.remediation.action])),
+    ];
+    return new ProviderCleanupError(owner, [
+        ...new Set(normalized.flatMap(({ observation }) => observation.resources)),
+    ], {
+        reason: normalized
+            .map(({ observation }) => observation.reason)
+            .join("; "),
+        failures: normalized.map(({ cause, projection, observation }) => projection !== undefined
+            ? projection
+            : {
+                name: cause instanceof Error ? cause.name : "UnknownError",
+                message: cause instanceof Error ? cause.message : String(cause),
+                resource: [...observation.resources],
+            }),
+    }, {
+        cause: normalized.length === 1
+            ? normalized[0].cause
+            : new AggregateError(normalized.map(({ cause }) => cause), `${owner} cleanup failed`),
+        operation,
+        ...(recoveryActions.length === 0
+            ? {}
+            : { remediationAction: recoveryActions.join("; ") }),
+    });
+};

package/dist/browser/WebSourceMapFetcher.js

@@ -6,7 +6,7 @@ import { isUrlLikeModuleSpecifier } from "../domain/webBundleAnalyzerAst.js";
 import { analyzeParsedJavaScriptReferences } from "../domain/javascript/javascriptSemanticAnalysis.js";
 import { traverseJavaScriptAst } from "../domain/javascript/javascriptSemanticTraversal.js";
 import { parseJavaScriptSource } from "../domain/javascript/javascriptSourceParser.js";
-import { isTypeOnlyExportDeclaration, isTypeOnlyImportDeclaration, } from "../domain/javascript/javascriptModuleDeclaration.js";
+import { isTypeOnlyExportDeclaration, isTypeOnlyImportDeclaration, semanticImportEqualsSpecifier, } from "../domain/javascript/javascriptModuleDeclaration.js";
 import { stringValue } from "../domain/javascript/javascriptStaticAnalysisHelpers.js";
 import { webSourceMapsSchema } from "../domain/webBundleAnalysis.js";
 import { createWebTextArtifact } from "../domain/webContentArtifact.js";
@@ -27,6 +27,14 @@ const SOURCE_MAP_FAILURE_LIMITATION_RESERVE = 512;
 const SOURCE_MAP_COLLECTION_ENVELOPE_RESERVE = 1_024;
 /** Fetch and validate approved source maps without browser credentials. */
 export const fetchWebSourceMaps = async (requests, input, signal, host = { fetch: globalThis.fetch }) => {
+    throwIfAborted(signal);
+    if (requests.length === 0)
+        return webSourceMapsSchema.parse({
+            status: "not_requested",
+            requested: 0,
+            processed: 0,
+            items: [],
+        });
     const items = [];
     const operationController = new AbortController();
     const timeout = setTimeout(() => operationController.abort(new SourceMapDeadlineError()), host.timeoutMs ?? SOURCE_MAP_FETCH_TIMEOUT_MS);
@@ -95,6 +103,10 @@ export const fetchWebSourceMaps = async (requests, input, signal, host = { fetch
         ...(limitation === undefined ? {} : { limitation }),
     });
 };
+const throwIfAborted = (signal) => {
+    if (signal?.aborted === true)
+        throw signal.reason;
+};
 const sourceMapOutputLimitation = (unprocessed) => `source-map output budget could not retain results for ${String(unprocessed)} requested map${unprocessed === 1 ? "" : "s"}. their results are unknown.`;
 const sourceMapsStatus = (items, omitted) => {
     const retained = items.filter(({ status }) => status === "included" || status === "partial").length;
@@ -730,14 +742,11 @@ const originalDependency = (node) => {
             : { kind: "require", specifier, requireCallee: node.callee };
     }
     // `import x = require("m")` is only legal at module top level and always
-    // refers to the host loader, so it needs no unbound-`require` check. The
-    // `moduleReference` is an entity name for a local alias instead, which
-    // declares no dependency.
-    if (t.isTSImportEqualsDeclaration(node) &&
-        t.isTSExternalModuleReference(node.moduleReference))
-        return {
-            kind: "require",
-            specifier: node.moduleReference.expression.value,
-        };
+    // refers to the host loader, so it needs no unbound-`require` check. An
+    // entity-name alias or an erased `import type` declares no dependency.
+    if (t.isTSImportEqualsDeclaration(node)) {
+        const specifier = semanticImportEqualsSpecifier(node);
+        return specifier === null ? null : { kind: "require", specifier };
+    }
     return null;
 };

package/dist/browser/assets/WebArtifactReads.js

@@ -31,12 +31,16 @@ export const readWebArtifactJson = async (path, maximumBytes, signal, resourceSc
 export const webArtifactReadError = (cause, context, signal) => {
     if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) {
         const primary = signal?.aborted === true
-            ? new AnalysisCancelledError(context.operation, { cause })
+            ? new AnalysisCancelledError(context.operation, {
+                cause: signal.reason,
+            })
             : new ArtifactOperationError(context.operation, cause.reason, cause.details, cause.message, { cause });
         return analysisErrorWithCleanupFailure(primary, new ProviderCleanupError("captured-web-artifacts", cause.cleanup.resources, { reason: cause.cleanup.reason }, { cause, operation: context.operation }), context.operation);
     }
     if (signal?.aborted === true)
-        return new AnalysisCancelledError(context.operation, { cause });
+        return new AnalysisCancelledError(context.operation, {
+            cause: signal.reason,
+        });
     const selection = context.callerSelected
         ? selectedFileError(cause, context)
         : undefined;

package/dist/browser/assets/WebSourceLocationArtifacts.js

@@ -2,6 +2,7 @@ import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"
 import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
 import { WEB_SOURCE_MAP_LIMITS, } from "../../domain/webSourceLocation.js";
 import { err, ok } from "../../domain/result.js";
+import { webArtifactCleanupFailures } from "../WebArtifactCleanup.js";
 import { LocalWebScriptArtifacts } from "./LocalWebScriptArtifacts.js";
 import { decodeWebArtifact, webArtifactReadError } from "./WebArtifactReads.js";
 /** Read one verified capture source and the caller-selected map, without fetching. */
@@ -27,9 +28,17 @@ export class LocalWebSourceLocationArtifacts {
                 ? []
                 : [Promise.resolve().then(closeScript)]),
         ]);
-        const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
-        if (failures.length > 0)
-            throw new AggregateError(failures, "Web source-location artifact cleanup failed");
+        const failures = results.flatMap((result, index) => result.status === "rejected"
+            ? [
+                {
+                    cause: result.reason,
+                    resource: index === 0 ? "web source-location artifacts" : "web scripts",
+                },
+            ]
+            : []);
+        const error = webArtifactCleanupFailures("web-source-location-artifacts", "trace_web_source_location", failures);
+        if (error !== undefined)
+            throw error;
     }
     /** Preserve actual map identity separately from the selected deployment URL. */
     async load(input, options) {

package/dist/browser/execution/CdpRuntimeSession.js

@@ -2,6 +2,8 @@ import { AnalysisError } from "../../domain/analysisErrorBase.js";
 import { AnalysisTimeoutError } from "../../domain/analysisErrorCore.js";
 import { BrowserObservationError } from "../../domain/browserObservationError.js";
 import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
+import { CdpTargetSessionOwner } from "../CdpTargetSessionOwner.js";
 import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
 import { WEB_RUNTIME_LIMITS, } from "../../domain/webRuntime.js";
 import { authorizeCdpTarget } from "../CdpAuthorizedTarget.js";
@@ -17,24 +19,26 @@ export class CdpRuntimeSession {
     allowedOrigins;
     operation;
     options;
+    owner;
     enabledDomains = [];
     preciseCoverageMayBeActive = false;
     #completion;
     #completionTimer;
-    constructor(transport, discovery, target, allowedOrigins, operation, options) {
+    constructor(transport, discovery, target, allowedOrigins, operation, options, owner) {
         this.transport = transport;
         this.discovery = discovery;
         this.target = target;
         this.allowedOrigins = allowedOrigins;
         this.operation = operation;
         this.options = options;
+        this.owner = owner;
     }
     /** Acquire a validated target; failed setup releases its owned socket. */
-    static async open(input, operation, options) {
+    static async open(input, operation, options, owner) {
         return runtimeDeadline(operation, options.signal, async (signal) => {
             const discovery = await discoverCdpEndpoint(input.cdp_endpoint, operation, signal);
             const { target, allowedOrigins } = authorizeCdpTarget(discovery, input, operation);
-            const transport = await openCdpTargetSession(discovery, target, operation, signal, { maxPayloadBytes: WEB_RUNTIME_LIMITS.protocolBytes });
+            const transport = await openCdpTargetSession(discovery, target, operation, signal, { maxPayloadBytes: WEB_RUNTIME_LIMITS.protocolBytes }, owner);
             try {
                 const tree = runtimeFrameTreeSchema.parse(await authorizedMainFrame({
                     ...transport,
@@ -52,10 +56,18 @@ export class CdpRuntimeSession {
                     origin: url.origin,
                     frame_id: frame.id,
                     loader_id: frame.loaderId ?? null,
-                }, allowedOrigins, operation, options);
+                }, allowedOrigins, operation, options, owner);
             }
             catch (cause) {
-                await transport.connection.close();
+                try {
+                    await owner.finish(transport.connection);
+                }
+                catch (cleanupCause) {
+                    if (cause instanceof AnalysisError &&
+                        cleanupCause instanceof AnalysisError)
+                        throw analysisErrorWithCleanupFailure(cause, cleanupCause, operation);
+                    throw new AggregateError([cause, cleanupCause], `CDP runtime setup ${operation} failed and cleanup remains incomplete.`, { cause });
+                }
                 throw cause;
             }
         });
@@ -106,6 +118,7 @@ export class CdpRuntimeSession {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), WEB_RUNTIME_LIMITS.cleanupTimeoutMs);
         const failures = [];
+        let transportFailure;
         const send = async (method, params = {}) => {
             try {
                 await this.transport.connection.send(method, params, this.transport.sessionId, controller.signal);
@@ -132,7 +145,18 @@ export class CdpRuntimeSession {
         }
         finally {
             clearTimeout(timer);
-            await this.transport.connection.close();
+            try {
+                await this.owner.finish(this.transport.connection);
+            }
+            catch (cause) {
+                transportFailure =
+                    cause instanceof AnalysisError
+                        ? cause
+                        : new ProviderCleanupError("rea-cdp-browser", [this.target.target_id], {
+                            reason: cause instanceof Error ? cause.message : String(cause),
+                        }, { operation: this.operation, cause });
+                failures.push(`CDP WebSocket close: ${transportFailure.userMessage ?? transportFailure.message}`);
+            }
         }
         return failures.length === 0
             ? undefined
@@ -140,7 +164,12 @@ export class CdpRuntimeSession {
                 target_id: this.target.target_id,
                 cleanup_failures: failures,
                 previous_error: previousError?.userMessage ?? previousError?.message ?? null,
-            }, { operation: this.operation });
+            }, {
+                operation: this.operation,
+                ...(transportFailure === undefined
+                    ? {}
+                    : { cause: transportFailure }),
+            });
     }
 }
 /** Apply a disposable command deadline without turning timeout into caller cancellation. */