@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/runtime/browser.js

@@ -1,3 +1,19 @@
+import { readDiagnosticEnv, registerDiagnosticValue } from "./diagnostic-env.js";
+import { AsyncResource } from "node:async_hooks";
+import { observeTelemetryCallback as observeBrowserTelemetry } from "./http-telemetry-guard.js";
+import { cookieValuesFromHeaders } from "./stealth-cookies.js";
+function browserTelemetryErrorCode(error) {
+    const code = error && typeof error === "object" && "code" in error
+        ? error.code
+        : undefined;
+    if (code === "BROWSER_CDP_POOL_REQUIRED" ||
+        code === "BROWSER_PROXY_INVALID" ||
+        code === "BROWSER_RUNTIME_UNSUPPORTED")
+        return code;
+    if (typeof code === "number")
+        return "BROWSER_CDP_POOL_ERROR";
+    return "other";
+}
 import { createRequire } from "node:module";
 import { ProviderError } from "../errors.js";
 const require = createRequire(import.meta.url);
@@ -15,7 +31,7 @@ function toResourceBody(body) {
     return Buffer.from(body);
 }
 function isResourceMethod(method) {
-    return method === "GET" || method === "HEAD";
+    return method === "GET" || method === "HEAD" || method === "POST";
 }
 async function toResourceRequest(request) {
     const method = request.method().toUpperCase();
@@ -59,6 +75,68 @@ function getCdpPausedRequestId(params) {
     }
     return params.requestId;
 }
+function isCdpResponseStage(params) {
+    return (isRecord(params) &&
+        (typeof params.responseStatusCode === "number" ||
+            typeof params.responseErrorReason === "string"));
+}
+function toCdpPausedDocumentResponse(params) {
+    if (!isRecord(params) ||
+        typeof params.requestId !== "string" ||
+        typeof params.responseStatusCode !== "number" ||
+        params.resourceType !== "Document" ||
+        !isRecord(params.request)) {
+        return null;
+    }
+    const responseCode = params.responseStatusCode;
+    const responseHeaders = Array.isArray(params.responseHeaders)
+        ? params.responseHeaders.flatMap((header) => {
+            if (!isRecord(header) ||
+                typeof header.name !== "string" ||
+                typeof header.value !== "string") {
+                return [];
+            }
+            return [{ name: header.name, value: header.value }];
+        })
+        : [];
+    return {
+        hasBody: String(params.request.method ?? "").toUpperCase() !== "HEAD" &&
+            responseCode >= 200 &&
+            (responseCode < 300 || responseCode >= 400) &&
+            responseCode !== 204 &&
+            responseCode !== 205 &&
+            responseCode !== 304,
+        requestId: params.requestId,
+        responseCode,
+        responseHeaders,
+    };
+}
+function toCdpDocumentFulfillParams(response, body, contentSecurityPolicy) {
+    const responseBody = typeof body.body === "string" ? body.body : "";
+    return {
+        body: body.base64Encoded ? responseBody : Buffer.from(responseBody).toString("base64"),
+        requestId: response.requestId,
+        responseCode: response.responseCode,
+        responseHeaders: [
+            ...response.responseHeaders,
+            { name: "Content-Security-Policy", value: contentSecurityPolicy },
+        ],
+    };
+}
+function resourcePolicyFetchPatterns(policy) {
+    return [
+        { requestStage: "Request", urlPattern: "*" },
+        ...(policy.documentContentSecurityPolicy
+            ? [
+                {
+                    requestStage: "Response",
+                    resourceType: "Document",
+                    urlPattern: "*",
+                },
+            ]
+            : []),
+    ];
+}
 function toCdpResourceHeaders(value) {
     if (!isRecord(value)) {
         return {};
@@ -104,8 +182,129 @@ async function fulfillResourceRoute(route, decision) {
         status: decision.status ?? 200,
     });
 }
+async function decideResourceRequest(policy, request) {
+    for (const resourceRoute of policy.routes) {
+        if (matchesResourceRoute(resourceRoute.match, request)) {
+            return await resourceRoute.handle(request);
+        }
+    }
+    return { action: "block" };
+}
+async function abortResourceRoute(route) {
+    await route.abort("blockedbyclient");
+}
+async function handleCdpResourceRequest(session, policy, allowedMethods, params) {
+    const paused = toCdpResourceRequest(params);
+    const requestId = paused?.requestId ?? getCdpPausedRequestId(params);
+    if (!requestId)
+        return;
+    try {
+        if (!paused || !allowedMethods.has(paused.request.method)) {
+            await session.send("Fetch.failRequest", { errorReason: "BlockedByClient", requestId });
+            return;
+        }
+        const decision = await decideResourceRequest(policy, paused.request);
+        switch (decision.action) {
+            case "continue":
+                await session.send("Fetch.continueRequest", { requestId });
+                return;
+            case "fulfill":
+                await session.send("Fetch.fulfillRequest", toCdpFulfillParams(requestId, decision));
+                return;
+            case "block":
+                await session.send("Fetch.failRequest", { errorReason: "BlockedByClient", requestId });
+                return;
+        }
+    }
+    catch {
+        await session
+            .send("Fetch.failRequest", { errorReason: "BlockedByClient", requestId })
+            .catch(() => undefined);
+    }
+}
+async function handleCdpDocumentResponse(session, contentSecurityPolicy, params) {
+    const requestId = getCdpPausedRequestId(params);
+    if (!requestId)
+        return;
+    try {
+        const response = toCdpPausedDocumentResponse(params);
+        if (!response)
+            throw new Error("CDP document response metadata is unavailable");
+        if (!response.hasBody) {
+            await session.send("Fetch.continueResponse", {
+                requestId,
+                responseCode: response.responseCode,
+                responseHeaders: [...response.responseHeaders],
+            });
+            return;
+        }
+        const body = await session.send("Fetch.getResponseBody", {
+            requestId: response.requestId,
+        });
+        await session.send("Fetch.fulfillRequest", toCdpDocumentFulfillParams(response, body, contentSecurityPolicy));
+    }
+    catch {
+        await session
+            .send("Fetch.failRequest", { errorReason: "BlockedByClient", requestId })
+            .catch(() => undefined);
+    }
+}
+function getCdpAuthRequiredRequestId(params) {
+    if (!isRecord(params) || typeof params.requestId !== "string") {
+        return null;
+    }
+    return params.requestId;
+}
+function isCdpProxyAuthChallenge(params) {
+    return (isRecord(params) && isRecord(params.authChallenge) && params.authChallenge.source === "Proxy");
+}
+async function handleCdpAuthRequired(session, proxy, authAttempts, params, telemetry) {
+    const requestId = getCdpAuthRequiredRequestId(params);
+    if (!requestId)
+        return;
+    // Chromium can emit another challenge after rejected credentials. Cancel a
+    // retry so incorrect credentials fail promptly instead of looping forever.
+    const response = isCdpProxyAuthChallenge(params) && !authAttempts.has(requestId)
+        ? (() => {
+            authAttempts.add(requestId);
+            observeBrowserTelemetry(telemetry, () => telemetry?.recordProxyAuthChallenge());
+            return {
+                authChallengeResponse: {
+                    password: proxy.password,
+                    response: "ProvideCredentials",
+                    username: proxy.username,
+                },
+                requestId,
+            };
+        })()
+        : {
+            authChallengeResponse: { response: "CancelAuth" },
+            requestId,
+        };
+    await session.send("Fetch.continueWithAuth", response).catch(() => undefined);
+}
+function createResourcePolicyHandler(policy, allowedMethods) {
+    return async (route) => {
+        const request = await toResourceRequest(route.request());
+        if (!request || !allowedMethods.has(request.method)) {
+            await abortResourceRoute(route);
+            return;
+        }
+        const decision = await decideResourceRequest(policy, request);
+        switch (decision.action) {
+            case "continue":
+                await route.continue();
+                return;
+            case "fulfill":
+                await fulfillResourceRoute(route, decision);
+                return;
+            case "block":
+                await abortResourceRoute(route);
+        }
+    };
+}
 function getDefaultCdpPoolUrl(env = process.env) {
-    return env.APIFUSE__CDP_POOL__URL;
+    return readDiagnosticEnv("APIFUSE__CDP_POOL__URL", env);
 }
 async function importOptionalModule(moduleName) {
     return (await import(moduleName));
@@ -139,12 +338,62 @@ function formatExpression(fn) {
     }
     return `(${fn.toString()})()`;
 }
-function toLaunchOptions(options) {
+function toLaunchOptions(options, proxy) {
     return {
-        args: options.extraArgs,
+        // `extraArgs` is optional, but playwright-extra's stealth evasions mutate
+        // `options.args` unguarded (navigator.webdriver does
+        // `options.args.findIndex(...)` in beforeLaunch). Forwarding `undefined`
+        // therefore crashes every stealth launch that omits extraArgs with
+        // "TypeError: undefined is not an object (evaluating 'options.args.findIndex')".
+        // Always hand the launcher a concrete array.
+        args: options.extraArgs ?? [],
         executablePath: options.executablePath,
         headless: options.headless ?? true,
-        proxy: options.proxy ? { server: options.proxy } : undefined,
+        proxy,
+    };
+}
+function hasProxyCredentials(proxy) {
+    return proxy?.username !== undefined && proxy.password !== undefined;
+}
+function toPlaywrightProxy(proxy) {
+    if (!proxy)
+        return undefined;
+    const schemeEnd = proxy.indexOf("://");
+    const authorityStart = schemeEnd >= 0 ? schemeEnd + 3 : 0;
+    const remainder = proxy.slice(authorityStart);
+    const authorityEnd = remainder.search(/[/?#]/);
+    const authority = remainder.slice(0, authorityEnd >= 0 ? authorityEnd : undefined);
+    if (!authority.includes("@")) {
+        return { server: proxy };
+    }
+    let parsed;
+    try {
+        parsed = new URL(proxy);
+    }
+    catch {
+        throw new ProviderError("Browser proxy URL is invalid", {
+            code: "BROWSER_PROXY_INVALID",
+            fix: "Use a valid proxy URL.",
+        });
+    }
+    let username;
+    let password;
+    try {
+        username = decodeURIComponent(parsed.username);
+        password = decodeURIComponent(parsed.password);
+    }
+    catch {
+        throw new ProviderError("Browser proxy credentials use invalid percent-encoding", {
+            code: "BROWSER_PROXY_INVALID",
+            fix: "Percent-encode the proxy username and password as URL userinfo.",
+        });
+    }
+    registerDiagnosticValue(username);
+    registerDiagnosticValue(password);
+    return {
+        server: `${parsed.protocol}//${parsed.host}`,
+        username,
+        password,
     };
 }
 class PlaywrightBrowserLocator {
@@ -309,13 +558,25 @@ async function loadSeleniumBase() {
 }
 class PlaywrightBrowserPage {
     page;
+    proxy;
+    telemetry;
     id = "main";
     pageId;
-    constructor(page) {
+    constructor(page, proxy = undefined, telemetry) {
         this.page = page;
-    }
-    async goto(url) {
-        await this.page.goto(url);
+        this.proxy = proxy;
+        this.telemetry = telemetry;
+    }
+    async goto(url, options) {
+        const response = await this.page.goto(url, options);
+        const headers = await response?.headersArray().catch(() => []);
+        for (const header of headers ?? []) {
+            if (header.name.toLowerCase() === "set-cookie") {
+                registerDiagnosticValue(header.value);
+                for (const value of cookieValuesFromHeaders(header.value))
+                    registerDiagnosticValue(value);
+            }
+        }
     }
     async evaluate(fn) {
         if (typeof fn === "string") {
@@ -323,6 +584,9 @@ class PlaywrightBrowserPage {
         }
         return await this.page.evaluate(fn);
     }
+    async userAgent() {
+        return await this.evaluate("navigator.userAgent");
+    }
     async waitForSelector(selector, options) {
         await this.page.waitForSelector(selector, options);
     }
@@ -357,42 +621,110 @@ class PlaywrightBrowserPage {
     async close() {
         await this.page.close();
     }
+    async cookies() {
+        const cookies = (await this.page.context().cookies()).map(toBrowserCookie);
+        for (const cookie of cookies)
+            registerDiagnosticValue(cookie.value);
+        return cookies;
+    }
     async withResourcePolicy(policy, run) {
         const allowedMethods = new Set(policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS);
+        const policyHandler = createResourcePolicyHandler(policy, allowedMethods);
+        const context = this.page.context();
         const handler = async (route) => {
-            const request = await toResourceRequest(route.request());
-            if (!request || !allowedMethods.has(request.method)) {
-                await route.abort("blockedbyclient");
+            try {
+                // Context routing sees a popup's first request before the late `page`
+                // event. Fail every secondary page closed so no redirect can escape
+                // the per-page CDP interception while that session is being attached.
+                if (route.request().frame().page() !== this.page) {
+                    await abortResourceRoute(route);
+                    return;
+                }
+            }
+            catch {
+                await abortResourceRoute(route);
                 return;
             }
-            for (const resourceRoute of policy.routes) {
-                if (!matchesResourceRoute(resourceRoute.match, request)) {
-                    continue;
+            await policyHandler(route);
+        };
+        const sessions = new Set();
+        const pendingAttachments = new Set();
+        const proxy = hasProxyCredentials(this.proxy) ? this.proxy : undefined;
+        let active = true;
+        const attachPage = async (page) => {
+            const session = await context.newCDPSession(page);
+            if (!active) {
+                await session.detach();
+                return;
+            }
+            const onRequestPaused = (params) => {
+                if (isCdpResponseStage(params) && policy.documentContentSecurityPolicy) {
+                    void handleCdpDocumentResponse(session, policy.documentContentSecurityPolicy, params);
+                    return;
                 }
-                const decision = await resourceRoute.handle(request);
-                switch (decision.action) {
-                    case "fulfill":
-                        await fulfillResourceRoute(route, decision);
-                        return;
-                    case "block":
-                        await route.abort("blockedbyclient");
-                        return;
+                void handleCdpResourceRequest(session, policy, allowedMethods, params);
+            };
+            const authAttempts = new Set();
+            const onAuthRequired = (params) => {
+                if (!proxy)
+                    return;
+                void handleCdpAuthRequired(session, proxy, authAttempts, params, this.telemetry);
+            };
+            session.on("Fetch.requestPaused", onRequestPaused);
+            if (proxy) {
+                session.on("Fetch.authRequired", onAuthRequired);
+            }
+            try {
+                await session.send("Fetch.enable", {
+                    ...(proxy ? { handleAuthRequests: true } : {}),
+                    patterns: resourcePolicyFetchPatterns(policy),
+                });
+                sessions.add(session);
+            }
+            catch (error) {
+                session.off("Fetch.requestPaused", onRequestPaused);
+                if (proxy) {
+                    session.off("Fetch.authRequired", onAuthRequired);
                 }
+                await session.detach().catch(() => undefined);
+                throw error;
             }
-            await route.abort("blockedbyclient");
         };
-        await this.page.route(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+        const onPage = (page) => {
+            const attachment = attachPage(page)
+                .catch(async () => {
+                await page.close().catch(() => undefined);
+            })
+                .finally(() => pendingAttachments.delete(attachment));
+            pendingAttachments.add(attachment);
+        };
+        await context.route(RESOURCE_POLICY_ROUTE_PATTERN, handler);
         try {
-            return await run();
+            context.on("page", onPage);
+            try {
+                await attachPage(this.page);
+                return await run();
+            }
+            finally {
+                context.off("page", onPage);
+            }
         }
         finally {
-            await this.page.unroute(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+            active = false;
+            await context.unroute(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+            await Promise.allSettled(pendingAttachments);
+            await Promise.all([...sessions].map(async (session) => {
+                await session.send("Fetch.disable").catch(() => undefined);
+                await session.detach().catch(() => undefined);
+            }));
         }
     }
 }
 class PlaywrightBrowserClient {
     options;
     browser = null;
+    parsedProxy;
+    proxyParsed = false;
     engine = "playwright-stealth";
     constructor(options = {}) {
         this.options = options;
@@ -402,13 +734,19 @@ class PlaywrightBrowserClient {
             return this.browser;
         }
         const chromium = await loadChromiumLauncher(this.options);
-        this.browser = await chromium.launch(toLaunchOptions(this.options));
+        if (!this.proxyParsed) {
+            this.parsedProxy = toPlaywrightProxy(this.options.proxy);
+            this.proxyParsed = true;
+        }
+        this.browser = await chromium.launch(toLaunchOptions(this.options, this.parsedProxy));
         return this.browser;
     }
     async newPage() {
+        if (!this.options.cdpUrl)
+            observeBrowserTelemetry(this.options.telemetry, () => this.options.telemetry?.recordPoolAcquire("not_configured"));
         const browser = await this.ensureBrowser();
         const page = await browser.newPage();
-        return new PlaywrightBrowserPage(page);
+        return new PlaywrightBrowserPage(page, this.parsedProxy, this.options.telemetry);
     }
     async rawPage() {
         throw new ProviderError("ctx.browser.rawPage() requires a CDP pool", {
@@ -417,10 +755,12 @@ class PlaywrightBrowserClient {
         });
     }
     async withIsolatedContext(handler) {
+        if (!this.options.cdpUrl)
+            observeBrowserTelemetry(this.options.telemetry, () => this.options.telemetry?.recordPoolAcquire("not_configured"));
         const browser = await this.ensureBrowser();
-        const context = await browser.newContext();
+        const context = await browser.newContext({ serviceWorkers: this.options.serviceWorkers });
         const page = await context.newPage();
-        const browserPage = new PlaywrightBrowserPage(page);
+        const browserPage = new PlaywrightBrowserPage(page, this.parsedProxy, this.options.telemetry);
         try {
             return await handler(browserPage);
         }
@@ -457,13 +797,14 @@ function normalizeWebSocketEndpoint(endpoint) {
     }
     throw new Error(`Unsupported WebSocket endpoint protocol: ${url.protocol}`);
 }
-class JsonRpcWebSocketClient {
+class WebSocketCommandClient {
     nextId = 1;
     endpoint;
     listeners = new Map();
     pending = new Map();
     socket;
     socketPromise;
+    closed = false;
     constructor(endpoint) {
         this.endpoint = normalizeWebSocketEndpoint(endpoint);
     }
@@ -480,18 +821,16 @@ class JsonRpcWebSocketClient {
     }
     async send(method, params = {}) {
         const socket = await this.getSocket();
+        if (this.closed)
+            throw new Error(`WebSocket closed: ${this.endpoint}`);
         const id = this.nextId++;
         return await new Promise((resolve, reject) => {
             this.pending.set(id, { resolve, reject });
-            socket.send(JSON.stringify({
-                id,
-                jsonrpc: "2.0",
-                method,
-                params,
-            }));
+            socket.send(JSON.stringify(this.createCommandFrame(id, method, params)));
         });
     }
     async close() {
+        this.closed = true;
         for (const pending of this.pending.values()) {
             pending.reject(new Error(`WebSocket closed: ${this.endpoint}`));
         }
@@ -502,6 +841,8 @@ class JsonRpcWebSocketClient {
         this.socketPromise = undefined;
     }
     async getSocket() {
+        if (this.closed)
+            throw new Error(`WebSocket closed: ${this.endpoint}`);
         if (this.socket?.readyState === WebSocket.OPEN) {
             return this.socket;
         }
@@ -511,6 +852,11 @@ class JsonRpcWebSocketClient {
         this.socketPromise = new Promise((resolve, reject) => {
             const socket = new WebSocket(this.endpoint);
             socket.addEventListener("open", () => {
+                if (this.closed) {
+                    socket.close();
+                    reject(new Error(`WebSocket closed: ${this.endpoint}`));
+                    return;
+                }
                 this.socket = socket;
                 resolve(socket);
             });
@@ -526,7 +872,11 @@ class JsonRpcWebSocketClient {
                     }
                     this.pending.delete(payload.id);
                     if (payload.error) {
-                        pending.reject(new Error(payload.error.message ?? "JSON-RPC command failed"));
+                        const error = new Error(payload.error.message ?? "JSON-RPC command failed");
+                        if (typeof payload.error.code === "number") {
+                            Object.assign(error, { code: payload.error.code });
+                        }
+                        pending.reject(error);
                         return;
                     }
                     pending.resolve(payload.result ?? {});
@@ -554,6 +904,26 @@ class JsonRpcWebSocketClient {
         return this.socketPromise;
     }
 }
+class CdpWebSocketClient extends WebSocketCommandClient {
+    sessionId;
+    constructor(endpoint, sessionId) {
+        super(endpoint);
+        this.sessionId = sessionId;
+    }
+    createCommandFrame(id, method, params) {
+        return {
+            id,
+            method,
+            params,
+            ...(this.sessionId === undefined ? {} : { sessionId: this.sessionId }),
+        };
+    }
+}
+class JsonRpcWebSocketClient extends WebSocketCommandClient {
+    createCommandFrame(id, method, params) {
+        return { id, jsonrpc: "2.0", method, params };
+    }
+}
 function flattenCdpFrameTree(node, out = []) {
     if (!node) {
         return out;
@@ -567,6 +937,48 @@ function flattenCdpFrameTree(node, out = []) {
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function isBrowserCookieSameSite(value) {
+    return value === "Strict" || value === "Lax" || value === "None";
+}
+function toBrowserCookie(cookie) {
+    return {
+        name: cookie.name,
+        value: cookie.value,
+        domain: cookie.domain,
+        path: cookie.path,
+        ...(cookie.expires !== undefined && cookie.expires > 0 ? { expires: cookie.expires } : {}),
+        httpOnly: cookie.httpOnly,
+        secure: cookie.secure,
+        ...(isBrowserCookieSameSite(cookie.sameSite) ? { sameSite: cookie.sameSite } : {}),
+    };
+}
+function parseCdpCookies(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("CDP Network.getCookies returned an invalid cookie list");
+    }
+    return value.map((cookie) => {
+        if (!isRecord(cookie) ||
+            typeof cookie.name !== "string" ||
+            typeof cookie.value !== "string" ||
+            typeof cookie.domain !== "string" ||
+            typeof cookie.path !== "string" ||
+            typeof cookie.expires !== "number" ||
+            typeof cookie.httpOnly !== "boolean" ||
+            typeof cookie.secure !== "boolean") {
+            throw new Error("CDP Network.getCookies returned an invalid cookie");
+        }
+        return toBrowserCookie({
+            name: cookie.name,
+            value: cookie.value,
+            domain: cookie.domain,
+            path: cookie.path,
+            expires: cookie.expires,
+            httpOnly: cookie.httpOnly,
+            secure: cookie.secure,
+            sameSite: cookie.sameSite,
+        });
+    });
+}
 function parsePoolAcquireResponse(value) {
     if (!isRecord(value) ||
         typeof value.pageId !== "string" ||
@@ -586,6 +998,33 @@ function parsePoolAcquireResponse(value) {
         wsEndpoint: value.wsEndpoint,
     };
 }
+function poolAcquireOutcome(error) {
+    const code = error instanceof Error && typeof error.code === "number"
+        ? error.code
+        : undefined;
+    switch (code) {
+        case -32001:
+            return "queue_full";
+        case -32002:
+            return "timed_out";
+        case -32003:
+            return "shutting_down";
+        case -32004:
+            return "unknown_lease";
+        case -32005:
+            return "unknown_method";
+        case -32006:
+            return "missing_allowed_hosts";
+    }
+    if (error instanceof Error && /Unable to connect|WebSocket closed/.test(error.message))
+        return "transport_failure";
+    return "other";
+}
+function poolAcquireCode(error) {
+    return error instanceof Error && typeof error.code === "number"
+        ? error.code
+        : undefined;
+}
 function parseCdpFrameTreeNode(value) {
     if (!isRecord(value) || !isRecord(value.frame)) {
         return undefined;
@@ -620,6 +1059,15 @@ function getCdpExecutionContext(params) {
         id: typeof contextId === "number" ? contextId : undefined,
     };
 }
+function getCdpDestroyedExecutionContextId(params) {
+    if (!isRecord(params)) {
+        return undefined;
+    }
+    return typeof params.executionContextId === "number" ? params.executionContextId : undefined;
+}
+function isMissingExecutionContextError(error) {
+    return error instanceof Error && /\b(?:cannot|failed to) find context\b/i.test(error.message);
+}
 class CdpBrowserLocator {
     frame;
     selector;
@@ -711,7 +1159,7 @@ class CdpPoolBrowserPage {
     browserContextId;
     pageClient;
     release;
-    closed = false;
+    closePromise;
     initialized = false;
     frameExecutionContexts = new Map();
     constructor(pageId, browserContextId, pageClient, release) {
@@ -723,16 +1171,22 @@ class CdpPoolBrowserPage {
     get id() {
         return this.pageId;
     }
-    async goto(url) {
+    async goto(url, options) {
         await this.initialize();
         const startedAt = Date.now();
-        let loadEventSeen = false;
-        const unsubscribe = this.pageClient.on("Page.loadEventFired", () => {
-            loadEventSeen = true;
+        const timeout = options?.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+        const waitUntil = options?.waitUntil ?? "load";
+        let expectedEventSeen = false;
+        const eventName = waitUntil === "domcontentloaded" ? "Page.domContentEventFired" : "Page.loadEventFired";
+        const unsubscribe = this.pageClient.on(eventName, () => {
+            expectedEventSeen = true;
         });
         try {
-            await this.pageClient.send("Page.navigate", { url });
-            await this.waitForDocumentReady(startedAt + DEFAULT_WAIT_TIMEOUT_MS, () => loadEventSeen);
+            const navigation = (await this.pageClient.send("Page.navigate", { url }));
+            if (typeof navigation.errorText === "string" && navigation.errorText.length > 0) {
+                throw new Error(`Page.navigate failed: ${navigation.errorText} at ${url}`);
+            }
+            await this.waitForDocumentReady(startedAt + timeout, () => expectedEventSeen, waitUntil);
         }
         finally {
             unsubscribe();
@@ -742,10 +1196,25 @@ class CdpPoolBrowserPage {
         await this.initialize();
         return await this.evaluateWithContext(fn);
     }
+    async userAgent() {
+        return await this.evaluate("navigator.userAgent");
+    }
     async evaluateInFrame(frameId, fn) {
         await this.initialize();
         const contextId = await this.getFrameExecutionContextId(frameId);
-        return await this.evaluateWithContext(fn, contextId);
+        try {
+            return await this.evaluateWithContext(fn, contextId);
+        }
+        catch (error) {
+            if (!isMissingExecutionContextError(error)) {
+                throw error;
+            }
+            if (this.frameExecutionContexts.get(frameId) === contextId) {
+                this.frameExecutionContexts.delete(frameId);
+            }
+            const refreshedContextId = await this.getFrameExecutionContextId(frameId);
+            return await this.evaluateWithContext(fn, refreshedContextId);
+        }
     }
     async waitForSelectorInFrame(frameId, selector, options) {
         const timeout = options?.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
@@ -845,20 +1314,35 @@ class CdpPoolBrowserPage {
         });
         return Buffer.from(String(result.data ?? ""), "base64");
     }
+    async cookies() {
+        await this.initialize();
+        const result = await this.pageClient.send("Network.getCookies");
+        const cookies = parseCdpCookies(result.cookies);
+        for (const cookie of cookies)
+            registerDiagnosticValue(cookie.value);
+        return cookies;
+    }
     async close() {
-        if (this.closed) {
+        // Only the first caller observes the release outcome; repeat calls stay
+        // idempotent (as they were before the promise was memoized) instead of
+        // replaying a cached rejection, and never re-issue a release against a
+        // target the pool has already disposed.
+        if (this.closePromise) {
+            await this.closePromise.catch(() => undefined);
             return;
         }
-        this.closed = true;
-        try {
-            await this.release({
-                ...(this.browserContextId ? { browserContextId: this.browserContextId } : {}),
-                pageId: this.pageId,
-            });
-        }
-        finally {
-            await this.pageClient.close();
-        }
+        this.closePromise = (async () => {
+            try {
+                await this.release({
+                    ...(this.browserContextId ? { browserContextId: this.browserContextId } : {}),
+                    pageId: this.pageId,
+                });
+            }
+            finally {
+                await this.pageClient.close();
+            }
+        })();
+        await this.closePromise;
     }
     async withResourcePolicy(policy, run) {
         const allowedMethods = new Set(policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS);
@@ -868,7 +1352,7 @@ class CdpPoolBrowserPage {
         const unsubscribe = this.pageClient.on("Fetch.requestPaused", handlePausedRequest);
         try {
             await this.pageClient.send("Fetch.enable", {
-                patterns: [{ requestStage: "Request", urlPattern: "*" }],
+                patterns: resourcePolicyFetchPatterns(policy),
             });
         }
         catch (error) {
@@ -883,8 +1367,21 @@ class CdpPoolBrowserPage {
             return await run();
         }
         finally {
-            unsubscribe();
-            await this.pageClient.send("Fetch.disable");
+            try {
+                if (this.closePromise) {
+                    // Keep interception active until release settles. The release failure
+                    // stays observable through close() itself; swallowing it here keeps
+                    // this finally from replacing run()'s own outcome, and still avoids a
+                    // reconnect or a disable against a disposed target.
+                    await this.closePromise.catch(() => undefined);
+                }
+                else {
+                    await this.pageClient.send("Fetch.disable");
+                }
+            }
+            finally {
+                unsubscribe();
+            }
         }
     }
     async handleResourcePolicyPausedRequest(params, policy, allowedMethods) {
@@ -893,6 +1390,24 @@ class CdpPoolBrowserPage {
             return;
         }
         try {
+            if (isCdpResponseStage(params) && policy.documentContentSecurityPolicy) {
+                const response = toCdpPausedDocumentResponse(params);
+                if (!response)
+                    throw new Error("CDP document response metadata is unavailable");
+                if (!response.hasBody) {
+                    await this.pageClient.send("Fetch.continueResponse", {
+                        requestId,
+                        responseCode: response.responseCode,
+                        responseHeaders: [...response.responseHeaders],
+                    });
+                    return;
+                }
+                const body = await this.pageClient.send("Fetch.getResponseBody", {
+                    requestId: response.requestId,
+                });
+                await this.pageClient.send("Fetch.fulfillRequest", toCdpDocumentFulfillParams(response, body, policy.documentContentSecurityPolicy));
+                return;
+            }
             const parsed = toCdpResourceRequest(params);
             if (!parsed || !allowedMethods.has(parsed.request.method)) {
                 await this.failCdpResourceRequest(requestId);
@@ -904,6 +1419,11 @@ class CdpPoolBrowserPage {
                 }
                 const decision = await resourceRoute.handle(parsed.request);
                 switch (decision.action) {
+                    case "continue":
+                        await this.pageClient.send("Fetch.continueRequest", {
+                            requestId: parsed.requestId,
+                        });
+                        return;
                     case "fulfill":
                         await this.pageClient.send("Fetch.fulfillRequest", toCdpFulfillParams(parsed.requestId, decision));
                         return;
@@ -941,8 +1461,45 @@ class CdpPoolBrowserPage {
                 this.frameExecutionContexts.set(context.frameId, context.id);
             }
         });
+        this.pageClient.on("Runtime.executionContextDestroyed", (params) => {
+            const destroyedContextId = getCdpDestroyedExecutionContextId(params);
+            if (destroyedContextId === undefined) {
+                return;
+            }
+            for (const [frameId, contextId] of this.frameExecutionContexts) {
+                if (contextId === destroyedContextId) {
+                    this.frameExecutionContexts.delete(frameId);
+                }
+            }
+        });
+        this.pageClient.on("Runtime.executionContextsCleared", () => {
+            this.frameExecutionContexts.clear();
+        });
+        const registerResponseCookies = (params) => {
+            if (!isRecord(params))
+                return;
+            const headers = Array.isArray(params.responseHeaders)
+                ? params.responseHeaders
+                : isRecord(params.headers)
+                    ? Object.entries(params.headers).map(([name, value]) => ({ name, value }))
+                    : [];
+            for (const header of headers) {
+                if (isRecord(header) &&
+                    typeof header.name === "string" &&
+                    header.name.toLowerCase() === "set-cookie" &&
+                    typeof header.value === "string") {
+                    registerDiagnosticValue(header.value);
+                    for (const value of cookieValuesFromHeaders(header.value))
+                        registerDiagnosticValue(value);
+                }
+            }
+        };
+        const scopedCookieRegistration = AsyncResource.bind(registerResponseCookies);
+        this.pageClient.on("Network.responseReceived", scopedCookieRegistration);
+        this.pageClient.on("Network.responseReceivedExtraInfo", scopedCookieRegistration);
         await this.pageClient.send("Page.enable");
         await this.pageClient.send("Runtime.enable");
+        await this.pageClient.send("Network.enable").catch(() => undefined);
         this.initialized = true;
     }
     async getFrameExecutionContextId(frameId) {
@@ -962,11 +1519,13 @@ class CdpPoolBrowserPage {
         this.frameExecutionContexts.set(frameId, contextId);
         return contextId;
     }
-    async waitForDocumentReady(deadline, isLoadEventSeen) {
+    async waitForDocumentReady(deadline, isExpectedEventSeen, waitUntil) {
         while (Date.now() < deadline) {
             const readyState = await this.evaluate("document.readyState");
-            if (readyState === "complete" || readyState === "interactive") {
-                if (isLoadEventSeen() || readyState === "complete") {
+            const documentReady = readyState === "complete" ||
+                (waitUntil === "domcontentloaded" && readyState === "interactive");
+            if (documentReady) {
+                if (isExpectedEventSeen() || readyState === "complete") {
                     return;
                 }
             }
@@ -978,6 +1537,7 @@ class CdpPoolBrowserPage {
 class CdpPoolBrowserClient {
     allowedHosts;
     poolClient;
+    telemetry;
     engine = "playwright-stealth";
     constructor(options) {
         if (!options.cdpUrl) {
@@ -986,17 +1546,30 @@ class CdpPoolBrowserClient {
             });
         }
         this.allowedHosts = [...new Set(options.allowedHosts ?? [])];
+        this.telemetry = options.telemetry;
         this.poolClient = new JsonRpcWebSocketClient(options.cdpUrl);
     }
     async newPage() {
         return await this.acquirePage({ isolatedContext: true });
     }
     async acquirePage(options) {
-        const acquireResult = parsePoolAcquireResponse(await this.poolClient.send("acquire", {
-            ...(this.allowedHosts.length > 0 ? { allowedHosts: this.allowedHosts } : {}),
-            ...(options?.isolatedContext ? { isolationMode: "browserContext" } : {}),
-        }));
-        const pageClient = new JsonRpcWebSocketClient(acquireResult.wsEndpoint);
+        let acquireResult;
+        try {
+            acquireResult = parsePoolAcquireResponse(await this.poolClient.send("acquire", {
+                ...(this.allowedHosts.length > 0 ? { allowedHosts: this.allowedHosts } : {}),
+                ...(options?.isolatedContext ? { isolationMode: "browserContext" } : {}),
+            }));
+            observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordPoolAcquire("ok"));
+        }
+        catch (error) {
+            observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordPoolAcquire(poolAcquireOutcome(error)));
+            observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordError("BROWSER_CDP_POOL_ERROR"));
+            const code = poolAcquireCode(error);
+            if (code !== undefined && ![-32001, -32002, -32003, -32004, -32005, -32006].includes(code))
+                observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordPoolAcquireUnknownCode?.(code));
+            throw error;
+        }
+        const pageClient = new CdpWebSocketClient(acquireResult.wsEndpoint);
         const page = new CdpPoolBrowserPage(acquireResult.pageId, acquireResult.browserContextId, pageClient, async (request) => {
             await this.poolClient.send("release", request);
         });
@@ -1068,6 +1641,7 @@ export class BrowserClient {
     activePage;
     activePages = new Set();
     _engine;
+    telemetry;
     constructor(options = {}) {
         const resolvedOptions = {
             ...options,
@@ -1075,6 +1649,7 @@ export class BrowserClient {
         };
         const engine = resolvedOptions.engine ?? "playwright-stealth";
         this._engine = engine;
+        this.telemetry = resolvedOptions.telemetry;
         this.cdpUrl = resolvedOptions.cdpUrl;
         if (resolvedOptions.requireCdpPool && !resolvedOptions.cdpUrl) {
             throw new ProviderError("Managed CDP Pool is required for browser providers in production", {
@@ -1099,20 +1674,37 @@ export class BrowserClient {
         return this._engine;
     }
     async newPage() {
-        const page = await this.client.newPage();
-        return this.activatePage(page);
+        observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordEngine(this._engine));
+        try {
+            const page = await this.client.newPage();
+            return this.activatePage(page);
+        }
+        catch (error) {
+            observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordError(browserTelemetryErrorCode(error)));
+            throw error;
+        }
     }
     async rawPage() {
+        observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordEngine(this._engine));
         if (!this.cdpUrl) {
+            observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordPoolAcquire("not_configured"));
+            observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordError("BROWSER_RUNTIME_UNSUPPORTED"));
             throw new ProviderError("ctx.browser.rawPage() requires a CDP pool", {
                 code: "BROWSER_RUNTIME_UNSUPPORTED",
                 fix: "Set APIFUSE__CDP_POOL__URL. The SDK escape hatch is CDP pool-backed only and never launches local Chromium.",
             });
         }
-        const page = await this.client.rawPage();
-        return this.activatePage(page);
+        try {
+            const page = await this.client.rawPage();
+            return this.activatePage(page);
+        }
+        catch (error) {
+            observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordError(browserTelemetryErrorCode(error)));
+            throw error;
+        }
     }
     async withIsolatedContext(handler) {
+        observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordEngine(this._engine));
         const previousActivePage = this.activePage;
         let trackedPage;
         return await this.client.withIsolatedContext(async (page) => {
@@ -1129,24 +1721,35 @@ export class BrowserClient {
         });
     }
     activatePage(page) {
-        let closed = false;
+        let closePromise;
         const originalClose = page.close.bind(page);
         const trackedPage = new Proxy(page, {
             get: (target, property, receiver) => {
                 if (property === "close") {
                     return async () => {
-                        if (closed)
+                        // Repeat calls resolve on the first outcome instead of replaying a
+                        // cached rejection, so a failed release cannot make close() — or
+                        // BrowserClient.close(), which closes every tracked page — throw
+                        // forever.
+                        if (closePromise) {
+                            await closePromise.catch(() => undefined);
                             return;
-                        closed = true;
-                        try {
-                            await originalClose();
                         }
-                        finally {
-                            this.activePages.delete(trackedPage);
-                            if (this.activePage === trackedPage) {
-                                this.activePage = undefined;
+                        closePromise = (async () => {
+                            // Bookkeeping runs even when the release fails: the page is gone
+                            // either way, so leaving it in activePages would leak it and let
+                            // solveChallenge reuse a disposed target.
+                            try {
+                                await originalClose();
                             }
-                        }
+                            finally {
+                                this.activePages.delete(trackedPage);
+                                if (this.activePage === trackedPage) {
+                                    this.activePage = undefined;
+                                }
+                            }
+                        })();
+                        await closePromise;
                     };
                 }
                 const value = Reflect.get(target, property, receiver);
@@ -1158,7 +1761,9 @@ export class BrowserClient {
         return trackedPage;
     }
     async solveChallenge(request) {
+        observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordEngine(this._engine));
         if (request.type !== "recaptcha") {
+            observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordError("BROWSER_RUNTIME_UNSUPPORTED"));
             throw new ProviderError(`Unsupported browser challenge: ${request.type}`, {
                 code: "BROWSER_RUNTIME_UNSUPPORTED",
             });