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

package/src/runtime/browser.ts

@@ -1,11 +1,42 @@
+import { readDiagnosticEnv, registerDiagnosticValue } from "./diagnostic-env.js";
+import { AsyncResource } from "node:async_hooks";
+import type {
+	BrowserTelemetryPoolAcquireOutcome,
+	BrowserTelemetrySink,
+} from "./browser-telemetry.js";
+import { observeTelemetryCallback as observeBrowserTelemetry } from "./http-telemetry-guard.js";
+import { cookieValuesFromHeaders } from "./stealth-cookies.js";
+
+function browserTelemetryErrorCode(
+	error: unknown,
+):
+	| "BROWSER_CDP_POOL_REQUIRED"
+	| "BROWSER_PROXY_INVALID"
+	| "BROWSER_RUNTIME_UNSUPPORTED"
+	| "BROWSER_CDP_POOL_ERROR"
+	| "other" {
+	const code =
+		error && typeof error === "object" && "code" in error
+			? (error as { code?: unknown }).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 type { Frame, LaunchOptions, Locator, Page, Request, Route } from "playwright";
+import type { CDPSession, Frame, LaunchOptions, Locator, Page, Request, Route } from "playwright";
 
 import { ProviderError } from "../errors.js";
 import type {
 	BrowserChallengeRequest,
 	BrowserChallengeResult,
 	BrowserClient as BrowserClientContract,
+	BrowserCookie,
 	BrowserEngine,
 	BrowserFrame,
 	BrowserLocator,
@@ -42,19 +73,35 @@ type PoolReleaseRequest = {
 	pageId: string;
 };
 
-type JsonRpcId = number;
+type WebSocketCommandId = number;
 
-type JsonRpcError = {
+type WebSocketCommandError = {
 	code?: number;
 	message?: string;
 };
 
-type JsonRpcMessage = {
-	error?: JsonRpcError;
-	id?: JsonRpcId;
+type WebSocketCommandMessage = {
+	error?: WebSocketCommandError;
+	id?: WebSocketCommandId;
+	jsonrpc?: "2.0";
 	method?: string;
 	params?: Record<string, unknown>;
 	result?: Record<string, unknown>;
+	sessionId?: string;
+};
+
+type CdpCommandFrame = {
+	id: WebSocketCommandId;
+	method: string;
+	params: Record<string, unknown>;
+	sessionId?: string;
+};
+
+type JsonRpcCommandFrame = {
+	id: WebSocketCommandId;
+	jsonrpc: "2.0";
+	method: string;
+	params: Record<string, unknown>;
 };
 
 type CdpFrameTreeNode = {
@@ -70,10 +117,25 @@ type CdpFrameTreeNode = {
 type CdpFetchFulfillParams = {
 	readonly requestId: string;
 	readonly responseCode: number;
-	readonly responseHeaders?: readonly {
+	readonly responseHeaders?: {
+		readonly name: string;
+		readonly value: string;
+	}[];
+	readonly body?: string;
+};
+
+type CdpPausedDocumentResponse = {
+	readonly hasBody: boolean;
+	readonly requestId: string;
+	readonly responseCode: number;
+	readonly responseHeaders: readonly {
 		readonly name: string;
 		readonly value: string;
 	}[];
+};
+
+type CdpResponseBody = {
+	readonly base64Encoded?: boolean;
 	readonly body?: string;
 };
 
@@ -92,7 +154,7 @@ function toResourceBody(body: BrowserResourceBody | undefined): Buffer | string
 }
 
 function isResourceMethod(method: string): method is BrowserResourceMethod {
-	return method === "GET" || method === "HEAD";
+	return method === "GET" || method === "HEAD" || method === "POST";
 }
 
 async function toResourceRequest(request: Request): Promise<BrowserResourceRequest | null> {
@@ -147,6 +209,85 @@ function getCdpPausedRequestId(params: unknown): string | null {
 	return params.requestId;
 }
 
+function isCdpResponseStage(params: unknown): boolean {
+	return (
+		isRecord(params) &&
+		(typeof params.responseStatusCode === "number" ||
+			typeof params.responseErrorReason === "string")
+	);
+}
+
+function toCdpPausedDocumentResponse(params: unknown): CdpPausedDocumentResponse | null {
+	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: CdpPausedDocumentResponse,
+	body: CdpResponseBody,
+	contentSecurityPolicy: string,
+): CdpFetchFulfillParams {
+	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: BrowserResourcePolicy) {
+	return [
+		{ requestStage: "Request" as const, urlPattern: "*" },
+		...(policy.documentContentSecurityPolicy
+			? [
+					{
+						requestStage: "Response" as const,
+						resourceType: "Document" as const,
+						urlPattern: "*",
+					},
+				]
+			: []),
+	];
+}
+
 function toCdpResourceHeaders(value: unknown): Record<string, string> {
 	if (!isRecord(value)) {
 		return {};
@@ -208,11 +349,172 @@ async function fulfillResourceRoute(
 	});
 }
 
+async function decideResourceRequest(
+	policy: BrowserResourcePolicy,
+	request: BrowserResourceRequest,
+): Promise<BrowserResourceDecision> {
+	for (const resourceRoute of policy.routes) {
+		if (matchesResourceRoute(resourceRoute.match, request)) {
+			return await resourceRoute.handle(request);
+		}
+	}
+
+	return { action: "block" };
+}
+
+async function abortResourceRoute(route: Route): Promise<void> {
+	await route.abort("blockedbyclient");
+}
+
+async function handleCdpResourceRequest(
+	session: CDPSession,
+	policy: BrowserResourcePolicy,
+	allowedMethods: ReadonlySet<BrowserResourceMethod>,
+	params: unknown,
+): Promise<void> {
+	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: CDPSession,
+	contentSecurityPolicy: string,
+	params: unknown,
+): Promise<void> {
+	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: unknown): string | null {
+	if (!isRecord(params) || typeof params.requestId !== "string") {
+		return null;
+	}
+
+	return params.requestId;
+}
+
+function isCdpProxyAuthChallenge(params: unknown): boolean {
+	return (
+		isRecord(params) && isRecord(params.authChallenge) && params.authChallenge.source === "Proxy"
+	);
+}
+
+async function handleCdpAuthRequired(
+	session: CDPSession,
+	proxy: PlaywrightProxy & { username: string; password: string },
+	authAttempts: Set<string>,
+	params: unknown,
+	telemetry?: BrowserTelemetrySink,
+): Promise<void> {
+	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" as const,
+							username: proxy.username,
+						},
+						requestId,
+					};
+				})()
+			: {
+					authChallengeResponse: { response: "CancelAuth" as const },
+					requestId,
+				};
+
+	await session.send("Fetch.continueWithAuth", response).catch(() => undefined);
+}
+
+function createResourcePolicyHandler(
+	policy: BrowserResourcePolicy,
+	allowedMethods: ReadonlySet<BrowserResourceMethod>,
+): (route: Route) => Promise<void> {
+	return async (route: Route): Promise<void> => {
+		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);
+		}
+	};
+}
+
 export type BrowserClientOptions = BrowserOptions & {
 	allowedHosts?: string[];
 	cdpUrl?: string;
 	executablePath?: string;
 	extraArgs?: string[];
+	serviceWorkers?: "allow" | "block";
+	telemetry?: BrowserTelemetrySink;
 };
 
 type SupportedBrowserClient = {
@@ -224,7 +526,7 @@ type SupportedBrowserClient = {
 };
 
 function getDefaultCdpPoolUrl(env = process.env): string | undefined {
-	return env.APIFUSE__CDP_POOL__URL;
+	return readDiagnosticEnv("APIFUSE__CDP_POOL__URL", env);
 }
 
 async function importOptionalModule<T extends object>(moduleName: string): Promise<T> {
@@ -271,12 +573,72 @@ function formatExpression<T>(fn: string | (() => T)): string {
 	return `(${fn.toString()})()`;
 }
 
-function toLaunchOptions(options: BrowserClientOptions): LaunchOptions {
+function toLaunchOptions(
+	options: BrowserClientOptions,
+	proxy: LaunchOptions["proxy"],
+): LaunchOptions {
 	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,
+	};
+}
+
+type PlaywrightProxy = NonNullable<LaunchOptions["proxy"]>;
+
+function hasProxyCredentials(
+	proxy: LaunchOptions["proxy"] | undefined,
+): proxy is PlaywrightProxy & { username: string; password: string } {
+	return proxy?.username !== undefined && proxy.password !== undefined;
+}
+
+function toPlaywrightProxy(proxy: string | undefined): LaunchOptions["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: URL;
+	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: string;
+	let password: string;
+	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,
 	};
 }
 
@@ -470,10 +832,24 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 	readonly id = "main";
 	readonly pageId?: string;
 
-	constructor(private readonly page: Page) {}
+	constructor(
+		private readonly page: Page,
+		private readonly proxy: LaunchOptions["proxy"] = undefined,
+		private readonly telemetry?: BrowserTelemetrySink,
+	) {}
 
-	async goto(url: string): Promise<void> {
-		await this.page.goto(url);
+	async goto(
+		url: string,
+		options?: { readonly timeout?: number; readonly waitUntil?: "load" | "domcontentloaded" },
+	): Promise<void> {
+		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<T>(fn: string | (() => T)): Promise<T> {
@@ -484,6 +860,10 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 		return await this.page.evaluate(fn);
 	}
 
+	async userAgent(): Promise<string> {
+		return await this.evaluate<string>("navigator.userAgent");
+	}
+
 	async waitForSelector(selector: string, options?: { timeout?: number }): Promise<void> {
 		await this.page.waitForSelector(selector, options);
 	}
@@ -529,45 +909,110 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 		await this.page.close();
 	}
 
+	async cookies(): Promise<readonly BrowserCookie[]> {
+		const cookies = (await this.page.context().cookies()).map(toBrowserCookie);
+		for (const cookie of cookies) registerDiagnosticValue(cookie.value);
+		return cookies;
+	}
+
 	async withResourcePolicy<T>(policy: BrowserResourcePolicy, run: () => Promise<T>): Promise<T> {
 		const allowedMethods = new Set(policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS);
+		const policyHandler = createResourcePolicyHandler(policy, allowedMethods);
+		const context = this.page.context();
 		const handler = async (route: Route): Promise<void> => {
-			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<CDPSession>();
+		const pendingAttachments = new Set<Promise<void>>();
+		const proxy = hasProxyCredentials(this.proxy) ? this.proxy : undefined;
+		let active = true;
+		const attachPage = async (page: Page): Promise<void> => {
+			const session = await context.newCDPSession(page);
+			if (!active) {
+				await session.detach();
+				return;
+			}
 
-				const decision = await resourceRoute.handle(request);
-				switch (decision.action) {
-					case "fulfill":
-						await fulfillResourceRoute(route, decision);
-						return;
-					case "block":
-						await route.abort("blockedbyclient");
-						return;
+			const onRequestPaused = (params: unknown) => {
+				if (isCdpResponseStage(params) && policy.documentContentSecurityPolicy) {
+					void handleCdpDocumentResponse(session, policy.documentContentSecurityPolicy, params);
+					return;
 				}
+				void handleCdpResourceRequest(session, policy, allowedMethods, params);
+			};
+			const authAttempts = new Set<string>();
+			const onAuthRequired = (params: unknown) => {
+				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");
+		};
+		const onPage = (page: Page) => {
+			const attachment = attachPage(page)
+				.catch(async () => {
+					await page.close().catch(() => undefined);
+				})
+				.finally(() => pendingAttachments.delete(attachment));
+			pendingAttachments.add(attachment);
 		};
 
-		await this.page.route(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+		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 implements SupportedBrowserClient {
 	private browser: import("playwright").Browser | null = null;
+	private parsedProxy: LaunchOptions["proxy"] | undefined;
+	private proxyParsed = false;
 	readonly engine = "playwright-stealth" satisfies BrowserEngine;
 
 	constructor(private readonly options: BrowserClientOptions = {}) {}
@@ -578,15 +1023,23 @@ class PlaywrightBrowserClient implements SupportedBrowserClient {
 		}
 
 		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(): Promise<BrowserPageContract> {
+		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(): Promise<BrowserPageContract> {
@@ -597,10 +1050,14 @@ class PlaywrightBrowserClient implements SupportedBrowserClient {
 	}
 
 	async withIsolatedContext<T>(handler: (page: BrowserPageContract) => Promise<T>): Promise<T> {
+		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);
@@ -641,12 +1098,12 @@ function normalizeWebSocketEndpoint(endpoint: string): string {
 	throw new Error(`Unsupported WebSocket endpoint protocol: ${url.protocol}`);
 }
 
-class JsonRpcWebSocketClient {
+abstract class WebSocketCommandClient {
 	private nextId = 1;
 	private readonly endpoint: string;
 	private readonly listeners = new Map<string, Set<(params: unknown) => void>>();
 	private readonly pending = new Map<
-		JsonRpcId,
+		WebSocketCommandId,
 		{
 			reject: (reason?: unknown) => void;
 			resolve: (value: Record<string, unknown>) => void;
@@ -654,6 +1111,7 @@ class JsonRpcWebSocketClient {
 	>();
 	private socket?: WebSocket;
 	private socketPromise?: Promise<WebSocket>;
+	private closed = false;
 
 	constructor(endpoint: string) {
 		this.endpoint = normalizeWebSocketEndpoint(endpoint);
@@ -677,23 +1135,18 @@ class JsonRpcWebSocketClient {
 		params: Record<string, unknown> = {},
 	): Promise<Record<string, unknown>> {
 		const socket = await this.getSocket();
+		if (this.closed) throw new Error(`WebSocket closed: ${this.endpoint}`);
 		const id = this.nextId++;
 
 		return await new Promise<Record<string, unknown>>((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(): Promise<void> {
+		this.closed = true;
 		for (const pending of this.pending.values()) {
 			pending.reject(new Error(`WebSocket closed: ${this.endpoint}`));
 		}
@@ -705,7 +1158,14 @@ class JsonRpcWebSocketClient {
 		this.socketPromise = undefined;
 	}
 
+	protected abstract createCommandFrame(
+		id: WebSocketCommandId,
+		method: string,
+		params: Record<string, unknown>,
+	): CdpCommandFrame | JsonRpcCommandFrame;
+
 	private async getSocket(): Promise<WebSocket> {
+		if (this.closed) throw new Error(`WebSocket closed: ${this.endpoint}`);
 		if (this.socket?.readyState === WebSocket.OPEN) {
 			return this.socket;
 		}
@@ -718,6 +1178,11 @@ class JsonRpcWebSocketClient {
 			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);
 			});
@@ -727,7 +1192,7 @@ class JsonRpcWebSocketClient {
 					typeof event.data === "string"
 						? event.data
 						: Buffer.from(event.data as ArrayBufferLike).toString("utf8");
-				const payload = JSON.parse(rawData) as JsonRpcMessage;
+				const payload = JSON.parse(rawData) as WebSocketCommandMessage;
 
 				if (typeof payload.id === "number") {
 					const pending = this.pending.get(payload.id);
@@ -738,7 +1203,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;
 					}
 
@@ -774,6 +1243,38 @@ class JsonRpcWebSocketClient {
 	}
 }
 
+class CdpWebSocketClient extends WebSocketCommandClient {
+	constructor(
+		endpoint: string,
+		private readonly sessionId?: string,
+	) {
+		super(endpoint);
+	}
+
+	protected createCommandFrame(
+		id: WebSocketCommandId,
+		method: string,
+		params: Record<string, unknown>,
+	): CdpCommandFrame {
+		return {
+			id,
+			method,
+			params,
+			...(this.sessionId === undefined ? {} : { sessionId: this.sessionId }),
+		};
+	}
+}
+
+class JsonRpcWebSocketClient extends WebSocketCommandClient {
+	protected createCommandFrame(
+		id: WebSocketCommandId,
+		method: string,
+		params: Record<string, unknown>,
+	): JsonRpcCommandFrame {
+		return { id, jsonrpc: "2.0", method, params };
+	}
+}
+
 function flattenCdpFrameTree(
 	node: CdpFrameTreeNode | undefined,
 	out: CdpFrameTreeNode["frame"][] = [],
@@ -794,6 +1295,64 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+function isBrowserCookieSameSite(value: unknown): value is BrowserCookie["sameSite"] {
+	return value === "Strict" || value === "Lax" || value === "None";
+}
+
+function toBrowserCookie(cookie: {
+	readonly name: string;
+	readonly value: string;
+	readonly domain: string;
+	readonly path: string;
+	readonly expires?: number;
+	readonly httpOnly: boolean;
+	readonly secure: boolean;
+	readonly sameSite?: unknown;
+}): BrowserCookie {
+	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: unknown): readonly BrowserCookie[] {
+	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: unknown): PoolAcquireResponse {
 	if (
 		!isRecord(value) ||
@@ -818,6 +1377,36 @@ function parsePoolAcquireResponse(value: unknown): PoolAcquireResponse {
 	};
 }
 
+function poolAcquireOutcome(error: unknown): BrowserTelemetryPoolAcquireOutcome {
+	const code =
+		error instanceof Error && typeof (error as Error & { code?: unknown }).code === "number"
+			? (error as Error & { code: number }).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: unknown): number | undefined {
+	return error instanceof Error && typeof (error as Error & { code?: unknown }).code === "number"
+		? (error as Error & { code: number }).code
+		: undefined;
+}
+
 function parseCdpFrameTreeNode(value: unknown): CdpFrameTreeNode | undefined {
 	if (!isRecord(value) || !isRecord(value.frame)) {
 		return undefined;
@@ -861,6 +1450,18 @@ function getCdpExecutionContext(params: unknown): {
 	};
 }
 
+function getCdpDestroyedExecutionContextId(params: unknown): number | undefined {
+	if (!isRecord(params)) {
+		return undefined;
+	}
+
+	return typeof params.executionContextId === "number" ? params.executionContextId : undefined;
+}
+
+function isMissingExecutionContextError(error: unknown): boolean {
+	return error instanceof Error && /\b(?:cannot|failed to) find context\b/i.test(error.message);
+}
+
 class CdpBrowserLocator implements BrowserLocator {
 	constructor(
 		private readonly frame: {
@@ -967,14 +1568,14 @@ class CdpBrowserFrame implements BrowserFrame {
 }
 
 class CdpPoolBrowserPage implements BrowserPageContract {
-	private closed = false;
+	private closePromise?: Promise<void>;
 	private initialized = false;
 	private readonly frameExecutionContexts = new Map<string, number>();
 
 	constructor(
 		readonly pageId: string,
 		private readonly browserContextId: string | undefined,
-		private readonly pageClient: JsonRpcWebSocketClient,
+		private readonly pageClient: CdpWebSocketClient,
 		private readonly release: (request: PoolReleaseRequest) => Promise<void>,
 	) {}
 
@@ -982,17 +1583,29 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		return this.pageId;
 	}
 
-	async goto(url: string): Promise<void> {
+	async goto(
+		url: string,
+		options?: { readonly timeout?: number; readonly waitUntil?: "load" | "domcontentloaded" },
+	): Promise<void> {
 		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 })) as {
+				readonly errorText?: unknown;
+			};
+			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();
 		}
@@ -1003,10 +1616,27 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		return await this.evaluateWithContext<T>(fn);
 	}
 
+	async userAgent(): Promise<string> {
+		return await this.evaluate<string>("navigator.userAgent");
+	}
+
 	async evaluateInFrame<T>(frameId: string, fn: string | (() => T)): Promise<T> {
 		await this.initialize();
 		const contextId = await this.getFrameExecutionContextId(frameId);
-		return await this.evaluateWithContext<T>(fn, contextId);
+		try {
+			return await this.evaluateWithContext<T>(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<T>(fn, refreshedContextId);
+		}
 	}
 
 	async waitForSelectorInFrame(
@@ -1149,21 +1779,34 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		return Buffer.from(String(result.data ?? ""), "base64");
 	}
 
+	async cookies(): Promise<readonly BrowserCookie[]> {
+		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(): Promise<void> {
-		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<T>(policy: BrowserResourcePolicy, run: () => Promise<T>): Promise<T> {
@@ -1176,7 +1819,7 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 
 		try {
 			await this.pageClient.send("Fetch.enable", {
-				patterns: [{ requestStage: "Request", urlPattern: "*" }],
+				patterns: resourcePolicyFetchPatterns(policy),
 			});
 		} catch (error) {
 			unsubscribe();
@@ -1193,8 +1836,19 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		try {
 			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();
+			}
 		}
 	}
 
@@ -1209,6 +1863,28 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		}
 
 		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);
@@ -1222,6 +1898,11 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 
 				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",
@@ -1264,8 +1945,46 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 				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: unknown) => {
+			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;
 	}
 
@@ -1291,12 +2010,16 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 
 	private async waitForDocumentReady(
 		deadline: number,
-		isLoadEventSeen: () => boolean,
+		isExpectedEventSeen: () => boolean,
+		waitUntil: "load" | "domcontentloaded",
 	): Promise<void> {
 		while (Date.now() < deadline) {
 			const readyState = await this.evaluate<string>("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;
 				}
 			}
@@ -1311,6 +2034,7 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 class CdpPoolBrowserClient implements SupportedBrowserClient {
 	private readonly allowedHosts: string[];
 	private readonly poolClient: JsonRpcWebSocketClient;
+	private readonly telemetry?: BrowserTelemetrySink;
 	readonly engine = "playwright-stealth" satisfies BrowserEngine;
 
 	constructor(options: BrowserClientOptions) {
@@ -1321,6 +2045,7 @@ class CdpPoolBrowserClient implements SupportedBrowserClient {
 		}
 
 		this.allowedHosts = [...new Set(options.allowedHosts ?? [])];
+		this.telemetry = options.telemetry;
 		this.poolClient = new JsonRpcWebSocketClient(options.cdpUrl);
 	}
 
@@ -1329,13 +2054,30 @@ class CdpPoolBrowserClient implements SupportedBrowserClient {
 	}
 
 	private async acquirePage(options?: { isolatedContext?: boolean }): Promise<BrowserPageContract> {
-		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: PoolAcquireResponse;
+		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,
@@ -1426,6 +2168,7 @@ export class BrowserClient implements BrowserClientContract {
 	private activePage?: BrowserPageContract;
 	private readonly activePages = new Set<BrowserPageContract>();
 	private readonly _engine: BrowserEngine;
+	private readonly telemetry?: BrowserTelemetrySink;
 
 	constructor(options: BrowserClientOptions = {}) {
 		const resolvedOptions = {
@@ -1434,6 +2177,7 @@ export class BrowserClient implements BrowserClientContract {
 		};
 		const engine = resolvedOptions.engine ?? "playwright-stealth";
 		this._engine = engine;
+		this.telemetry = resolvedOptions.telemetry;
 		this.cdpUrl = resolvedOptions.cdpUrl;
 
 		if (resolvedOptions.requireCdpPool && !resolvedOptions.cdpUrl) {
@@ -1462,23 +2206,46 @@ export class BrowserClient implements BrowserClientContract {
 	}
 
 	async newPage(): Promise<BrowserPageContract> {
-		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(): Promise<BrowserPageContract> {
+		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<T>(handler: (page: BrowserPageContract) => Promise<T>): Promise<T> {
+		observeBrowserTelemetry(this.telemetry, () => this.telemetry?.recordEngine(this._engine));
 		const previousActivePage = this.activePage;
 		let trackedPage: BrowserPageContract | undefined;
 
@@ -1496,22 +2263,34 @@ export class BrowserClient implements BrowserClientContract {
 	}
 
 	private activatePage(page: BrowserPageContract): BrowserPageContract {
-		let closed = false;
+		let closePromise: Promise<void> | undefined;
 		const originalClose = page.close.bind(page);
 		const trackedPage = new Proxy(page, {
 			get: (target, property, receiver) => {
 				if (property === "close") {
 					return async () => {
-						if (closed) return;
-						closed = true;
-						try {
-							await originalClose();
-						} finally {
-							this.activePages.delete(trackedPage);
-							if (this.activePage === trackedPage) {
-								this.activePage = undefined;
-							}
+						// 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;
 						}
+						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);
@@ -1524,7 +2303,11 @@ export class BrowserClient implements BrowserClientContract {
 	}
 
 	async solveChallenge(request: BrowserChallengeRequest): Promise<BrowserChallengeResult> {
+		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",
 			});