@apifuse/provider-sdk 2.2.0-beta.27 → 2.2.0-beta.29

package/dist/stateful/errors.d.ts

@@ -1,4 +1,9 @@
 export type StatefulControlPlaneOperation = "resolve" | "acquire" | "renew" | "release";
+export declare class StatefulRoutingDeadlineError extends Error {
+    readonly requestId: string;
+    readonly deadlineAt: string;
+    constructor(requestId: string, deadlineAt: string);
+}
 export declare class StatefulControlPlaneError extends Error {
     readonly code: string;
     readonly operation: StatefulControlPlaneOperation;

package/dist/stateful/errors.js

@@ -1,3 +1,13 @@
+export class StatefulRoutingDeadlineError extends Error {
+    requestId;
+    deadlineAt;
+    constructor(requestId, deadlineAt) {
+        super(`Stateful operation request ${requestId} deadline has expired.`);
+        this.name = "StatefulRoutingDeadlineError";
+        this.requestId = requestId;
+        this.deadlineAt = deadlineAt;
+    }
+}
 export class StatefulControlPlaneError extends Error {
     code;
     operation;

package/dist/stateful/stateful-provider-session-routing.d.ts

@@ -40,11 +40,7 @@ export interface StatefulSessionRouterOptions {
     readonly clock?: () => Date;
     readonly metricEmitter?: StatefulProviderMetricEmitter;
 }
-export declare class StatefulRoutingDeadlineError extends Error {
-    readonly requestId: string;
-    readonly deadlineAt: string;
-    constructor(requestId: string, deadlineAt: string);
-}
+export { StatefulRoutingDeadlineError } from "./errors.js";
 export declare class StatefulRoutingOwnershipError extends Error {
     readonly requestId: string;
     readonly sessionKey: SessionKey;

package/dist/stateful/stateful-provider-session-routing.js

@@ -1,15 +1,7 @@
+import { StatefulRoutingDeadlineError } from "./errors.js";
 import { NOOP_STATEFUL_PROVIDER_METRIC_EMITTER, } from "./stateful-provider-observability.js";
 export { forwardingContextFromStatefulRuntimeContext, isStatefulOperationRuntimeContext, providerContextFromStatefulRuntimeContext, statefulForwardingContextFromProviderRequest, withStatefulLocalProviderContext, } from "./stateful-provider-runtime-context.js";
-export class StatefulRoutingDeadlineError extends Error {
-    requestId;
-    deadlineAt;
-    constructor(requestId, deadlineAt) {
-        super(`Stateful operation request ${requestId} deadline has expired.`);
-        this.name = "StatefulRoutingDeadlineError";
-        this.requestId = requestId;
-        this.deadlineAt = deadlineAt;
-    }
-}
+export { StatefulRoutingDeadlineError } from "./errors.js";
 export class StatefulRoutingOwnershipError extends Error {
     requestId;
     sessionKey;

package/dist/stream.js

@@ -41,16 +41,22 @@ function sseFieldValue(value, field) {
 }
 export async function* readableBytes(body) {
     const reader = body.getReader();
+    let completed = false;
     try {
         for (;;) {
             const { value, done } = await reader.read();
-            if (done)
+            if (done) {
+                completed = true;
                 return;
+            }
             if (value)
                 yield value;
         }
     }
     finally {
+        if (!completed) {
+            await reader.cancel().catch(() => undefined);
+        }
         reader.releaseLock();
     }
 }

package/dist/testing/index.d.ts

@@ -1,2 +1,3 @@
 export { describeTransform, snapshotTransform, toMatchShape } from "./helpers.js";
+export { resetProviderCacheForTests } from "../runtime/cache.js";
 export { runStandardTests, type StandardTestsManifest, type StandardTestsOptions, type StandardTestsResult, type StandardTestsUpstreamCall, type StandardTestsUpstreamResponse, type StandardTestsUpstreamStub, } from "./run.js";

package/dist/testing/index.js

@@ -1,2 +1,3 @@
 export { describeTransform, snapshotTransform, toMatchShape } from "./helpers.js";
+export { resetProviderCacheForTests } from "../runtime/cache.js";
 export { runStandardTests, } from "./run.js";

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.27",
+	"version": "2.2.0-beta.29",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -61,6 +61,31 @@
 			"import": "./dist/server/index.js",
 			"default": "./dist/server/index.js"
 		},
+		"./runtime/browser": {
+			"types": "./dist/runtime/browser.d.ts",
+			"import": "./dist/runtime/browser.js",
+			"default": "./dist/runtime/browser.js"
+		},
+		"./runtime/native-network": {
+			"types": "./dist/runtime/native-network.d.ts",
+			"import": "./dist/runtime/native-network.js",
+			"default": "./dist/runtime/native-network.js"
+		},
+		"./runtime/prevalidate": {
+			"types": "./dist/runtime/prevalidate.d.ts",
+			"import": "./dist/runtime/prevalidate.js",
+			"default": "./dist/runtime/prevalidate.js"
+		},
+		"./runtime/resolver": {
+			"types": "./dist/runtime/resolver-public.d.ts",
+			"import": "./dist/runtime/resolver-public.js",
+			"default": "./dist/runtime/resolver-public.js"
+		},
+		"./runtime/stealth": {
+			"types": "./dist/runtime/stealth.d.ts",
+			"import": "./dist/runtime/stealth.js",
+			"default": "./dist/runtime/stealth.js"
+		},
 		"./stateful": {
 			"types": "./dist/stateful/index.d.ts",
 			"import": "./dist/stateful/index.js",
@@ -97,6 +122,7 @@
 		"@biomejs/biome": "^2.5.0",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
+		"ajv": "^8.17",
 		"typescript": "6.0.3"
 	},
 	"dependencies": {
@@ -104,7 +130,6 @@
 		"@rgrove/parse-xml": "4.2.2",
 		"@types/ms": "^2.1.0",
 		"acorn": "^8.17.0",
-		"ajv": "^8.17",
 		"hono": "^4.12.25",
 		"ioredis": "^5.11.1",
 		"ms": "^2.1.3",

package/src/auth-turn/index.ts

@@ -24,7 +24,7 @@ export const AUTH_TURN_SCHEMA_ARTIFACT_PATH = "dist/auth-turn/auth-turn.v1.schem
  *
  * This is the exact codification of the runtime validation the SDK applies to
  * ceremony outputs (see `validateCeremonyOutput` in `src/ceremonies`), which
- * compiles this same document. `kind` is an OPEN string on the wire: the known
+ * evaluates this same document. `kind` is an OPEN string on the wire: the known
  * kinds in {@link TURN_KINDS} are tooling metadata, never a wire constraint.
  *
  * The committed artifact at `src/auth-turn/auth-turn.v1.schema.json` (shipped

package/src/auth.ts

@@ -296,6 +296,25 @@ export interface DefineCredentialsAuthOptions<
 	):
 		| CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>
 		| Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
+	/**
+	 * Optional re-mint of an expired session from the stored credential, wired
+	 * to `auth.flow.refresh`.
+	 *
+	 * Credential-auth upstreams routinely invalidate a session well before the
+	 * `expiresAt` the provider advertised, which leaves every operation failing
+	 * with a reauth error until a human repeats the whole interactive login.
+	 * Implement this to re-establish the session from what is already stored on
+	 * the connection; the result is resolved exactly like `login`, so it may
+	 * also raise a challenge when the upstream demands one. Omit it when the
+	 * upstream has no non-interactive path and re-authentication genuinely
+	 * requires the user.
+	 */
+	refresh?(
+		ctx: FlowContext,
+		input: Partial<CredentialsAuthInput<TFields>>,
+	):
+		| CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>
+		| Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
 }
 
 export interface DefinedCredentialsAuth {
@@ -376,6 +395,27 @@ function normalizeInput<TFields extends CredentialsAuthFields>(
 	return result as CredentialsAuthInput<TFields>;
 }
 
+/**
+ * Refresh variant of {@link normalizeInput}. `login` coerces every declared
+ * field to a string because the interactive turn has already enforced that they
+ * are present; refresh runs with no user present, so an absent field is omitted
+ * rather than turned into an empty string. That keeps "the user did not supply
+ * this" distinguishable from "the user supplied an empty value".
+ */
+function normalizePartialInput<TFields extends CredentialsAuthFields>(
+	fields: TFields,
+	input: Record<string, unknown> | undefined,
+): Partial<CredentialsAuthInput<TFields>> {
+	const result: Record<string, string> = {};
+	for (const name of Object.keys(fields)) {
+		const value = input?.[name];
+		if (typeof value === "string") {
+			result[name] = value;
+		}
+	}
+	return result as Partial<CredentialsAuthInput<TFields>>;
+}
+
 function assertCredentialKeys<TCredentialKeys extends readonly string[]>(
 	credentialKeys: TCredentialKeys,
 	credential: Record<string, unknown>,
@@ -716,6 +756,44 @@ export function defineCredentialsAuth<
 						completeTurnId,
 					);
 				},
+				// Only advertise refresh when the provider implements it: the
+				// protocol treats the hook's presence as "this connection can be
+				// re-established without the user", and exposing a stub that
+				// cannot actually re-mint would turn a recoverable expiry into a
+				// silent failure.
+				...(options.refresh
+					? {
+							refresh: async (ctx: FlowContext, rawInput?: Record<string, unknown>) => {
+								// A pending challenge belongs to the interactive flow that
+								// raised it; finish it there rather than restarting.
+								const pending = getPendingChallenge(ctx);
+								if (pending) {
+									return await continuePendingChallenge(
+										ctx,
+										options.credentialKeys,
+										challenges,
+										pending,
+										rawInput,
+										completeTurnId,
+									);
+								}
+
+								// Refresh runs without user input, so fields are optional
+								// here — unlike `continue`, missing ones are not a retry.
+								const result = await options.refresh!(
+									ctx,
+									normalizePartialInput(options.fields, rawInput),
+								);
+								return await resolveAuthResult(
+									ctx,
+									options.credentialKeys,
+									challenges,
+									result,
+									completeTurnId,
+								);
+							},
+						}
+					: {}),
 			},
 		},
 		credential: {

package/src/ceremonies/index.ts

@@ -1,7 +1,5 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 
-import Ajv2020 from "ajv/dist/2020.js";
-
 import { AUTH_TURN_SCHEMA, type KnownAuthTurnKind } from "../auth-turn/index.js";
 import {
 	FlowExpiredError,
@@ -16,13 +14,14 @@ type TurnKind = KnownAuthTurnKind;
 type CeremonyHandler = AuthFlowInputHandler;
 
 type JsonObject = Record<string, unknown>;
-
-const ajv = new Ajv2020({ allErrors: true, strict: true, strictSchema: true });
-
-// Runtime ceremony-output validation derives from the exported versioned
-// contract: it compiles the exact AUTH_TURN_SCHEMA document shipped at
-// dist/auth-turn/auth-turn.v1.schema.json, so the two cannot drift.
-const validateAuthTurn = ajv.compile(AUTH_TURN_SCHEMA);
+type JsonSchemaNode = {
+	readonly additionalProperties?: boolean;
+	readonly minimum?: number;
+	readonly minLength?: number;
+	readonly properties?: Readonly<Record<string, JsonSchemaNode>>;
+	readonly required?: readonly string[];
+	readonly type?: "number" | "object" | "string";
+};
 
 const OAUTH2_STATE_KEY = "__oauth2_state";
 const OAUTH2_PKCE_VERIFIER_KEY = "__oauth2_pkce_verifier";
@@ -45,6 +44,56 @@ function isRecord(value: unknown): value is JsonObject {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+function validateSchemaNode(
+	value: unknown,
+	schema: JsonSchemaNode,
+	path: string,
+	errors: string[],
+): void {
+	if (schema.type === "object") {
+		if (!isRecord(value)) {
+			errors.push(`${path} must be object`);
+			return;
+		}
+		const properties = schema.properties ?? {};
+		for (const required of schema.required ?? []) {
+			if (!Object.hasOwn(value, required) || value[required] === undefined) {
+				errors.push(`${path} must have required property '${required}'`);
+			}
+		}
+		if (schema.additionalProperties === false) {
+			for (const key of Object.keys(value)) {
+				if (!Object.hasOwn(properties, key)) {
+					errors.push(`${path} must NOT have additional property '${key}'`);
+				}
+			}
+		}
+		for (const [key, childSchema] of Object.entries(properties)) {
+			if (Object.hasOwn(value, key) && value[key] !== undefined) {
+				validateSchemaNode(value[key], childSchema, `${path}/${key}`, errors);
+			}
+		}
+		return;
+	}
+
+	if (schema.type === "string") {
+		if (typeof value !== "string") {
+			errors.push(`${path} must be string`);
+		} else if (schema.minLength !== undefined && value.length < schema.minLength) {
+			errors.push(`${path} must NOT have fewer than ${schema.minLength} characters`);
+		}
+		return;
+	}
+
+	if (schema.type === "number") {
+		if (typeof value !== "number" || !Number.isFinite(value)) {
+			errors.push(`${path} must be number`);
+		} else if (schema.minimum !== undefined && value < schema.minimum) {
+			errors.push(`${path} must be >= ${schema.minimum}`);
+		}
+	}
+}
+
 function ensureRecord(value: unknown): JsonObject {
 	return isRecord(value) ? value : {};
 }
@@ -162,14 +211,17 @@ function withDeclaredFormFieldOrder(expectedInput: JsonObject): JsonObject {
 }
 
 export function validateCeremonyOutput(turn: unknown): AuthTurn {
-	if (!validateAuthTurn(turn)) {
-		const detail = validateAuthTurn.errors
-			?.map((error) => `${error.instancePath || "$"} ${error.message ?? "invalid"}`)
-			.join("; ");
-		throw new TurnValidationError(detail || "Invalid AuthTurn output");
+	// Evaluate the exact exported versioned schema without eagerly initializing
+	// a general-purpose JSON Schema compiler in every provider process. Contract
+	// parity tests compare this focused evaluator with AJV over all fixtures and
+	// edge probes, so the runtime and shipped document remain locked together.
+	const errors: string[] = [];
+	validateSchemaNode(turn, AUTH_TURN_SCHEMA, "", errors);
+	if (errors.length > 0) {
+		throw new TurnValidationError(errors.join("; "));
 	}
 
-	return turn;
+	return turn as AuthTurn;
 }
 
 export function createOAuth2Ceremony(options: {
@@ -285,9 +337,7 @@ export function createOAuth2ProxiedStart(
 				}
 				const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
 				if (!ctx.flowId) {
-					throw new ValidationError(
-						"OAuth2 proxied start requires the gateway flow id.",
-					);
+					throw new ValidationError("OAuth2 proxied start requires the gateway flow id.");
 				}
 
 				const authorizePath = new URL(options.authorizeUrl).pathname;

package/src/config/loader.ts

@@ -1,8 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 
-import { Redis } from "ioredis";
+import type { Redis } from "ioredis";
 
 import type { ProviderProxyPolicy, ProviderProxyProvider, TraceConfig } from "../types.js";
 import {
@@ -102,8 +103,11 @@ export type SmartproxyAllocatorBodyClass =
 	| "text_without_proxies"
 	| "usable_proxy_endpoints";
 
+export type ProxyUserAgentSource = "declared" | "defaulted";
+
 export type ProxyResolutionTelemetryEvent = {
 	provider: ProxyVendorName;
+	userAgentSource?: ProxyUserAgentSource;
 	protocol?: ProxyProtocol;
 	cacheStatus: ProxyCacheStatus;
 	cacheHit: boolean;
@@ -217,6 +221,7 @@ type ProxyRedisClient = Pick<
 >;
 
 const proxyCache = new Map<string, CachedProxyPool>();
+const require = createRequire(import.meta.url);
 const proxyInflight = new Map<string, Promise<SmartproxyAllocationResult>>();
 const invalidatedProxyKeys = new Map<string, number>();
 const redisClients = new Map<string, ProxyRedisClient>();
@@ -276,7 +281,8 @@ function getProxyRedis(): ProxyRedisClient | undefined {
 	const existing = redisClients.get(redisUrl);
 	if (existing) return existing;
 
-	const redis = new Redis(redisUrl, {
+	const { Redis: RedisClient } = require("ioredis") as typeof import("ioredis");
+	const redis = new RedisClient(redisUrl, {
 		connectTimeout: REDIS_TIMEOUT_MS,
 		enableOfflineQueue: false,
 		lazyConnect: true,

package/src/index.ts

@@ -50,13 +50,11 @@ export * from "./recipes/gov-api.js";
 export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
-export { BrowserClient, createBrowserClient } from "./runtime/browser.js";
 export {
 	APIFUSE__CACHE__KEY_PEPPER_ENV,
 	createBypassProviderCache,
 	createProviderCache,
 	type ProviderCacheOptions,
-	resetProviderCacheForTests,
 } from "./runtime/cache.js";
 export {
 	type CreateProviderChoiceContextOptions,
@@ -72,25 +70,23 @@ export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
 export {
-	createNativeNetworkClient,
-	createEnvVendorCredentialResolver,
-	deriveNativeCredentialAffinityKey,
 	NativeEgressGrantExpiredError,
 	NativeEgressNotDeclaredError,
 	NativeIdleTimeoutError,
 	NativeNetworkError,
 	NativeProxyExpiredError,
-	resolveNativeGatewayProxy,
-	type NativeGatewayProxy,
-	type NativeGatewayProxyResolutionInput,
-	type NativeGatewayProxySkipReason,
-	type NativeGatewayProxySynthesizer,
-	type NativeGatewayProxySynthesisResult,
-	type NativeGatewayProxySynthesisInput,
-	type NativeNetworkClientOptions,
-	type NativeNetworkErrorCode,
-	type VendorCredentialLookup,
-	type VendorCredentialResolver,
+} from "./runtime/native-network-errors.js";
+export type {
+	NativeGatewayProxy,
+	NativeGatewayProxyResolutionInput,
+	NativeGatewayProxySkipReason,
+	NativeGatewayProxySynthesizer,
+	NativeGatewayProxySynthesisResult,
+	NativeGatewayProxySynthesisInput,
+	NativeNetworkClientOptions,
+	NativeNetworkErrorCode,
+	VendorCredentialLookup,
+	VendorCredentialResolver,
 } from "./runtime/native-network.js";
 export type { Insight, InsightSeverity } from "./runtime/insights.js";
 export { generateInsights } from "./runtime/insights.js";
@@ -99,7 +95,7 @@ export {
 	type InstrumentedProviderContext,
 	wrapWithInstrumentation,
 } from "./runtime/instrumentation.js";
-export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
+export type { PrevalidateResult } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
 export {
 	APIFUSE__CDP_POOL__URL,
@@ -107,12 +103,10 @@ export {
 	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
 	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
 	APIFUSE__RESOLVER__TIMEOUT_MS,
-	createResolverClientFromEnv,
-	createUnsupportedResolverClient,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
-	invalidateResolverSolution,
-	type ResolverRuntimeOptions,
-} from "./runtime/resolver.js";
+} from "./runtime/resolver-config.js";
+export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
+export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
 export type { ResolverVendorTransport } from "./runtime/resolver-vendors/types.js";
 export {
 	assertRequiredSecretsPresent,
@@ -123,7 +117,6 @@ export {
 	createUnsupportedProviderRuntimeState,
 	UnsupportedProviderStateError,
 } from "./runtime/state.js";
-export { createStealthClient } from "./runtime/stealth.js";
 export {
 	APIFUSE__OCR__API_KEY_ENV,
 	APIFUSE__OCR__BACKEND_ENV,
@@ -174,10 +167,11 @@ export {
 } from "./schema.js";
 export {
 	createServerApp,
+	createServerAppAsync,
 	ERROR_OBSERVABILITY_HEADER,
 	type ServeOptions,
 	serve,
-} from "./server/index.js";
+} from "./server/serve.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
 export type {

package/src/provider.ts

@@ -167,25 +167,23 @@ export type {
 	StateWriteOptions,
 } from "./types.js";
 export {
-	createNativeNetworkClient,
-	createEnvVendorCredentialResolver,
-	deriveNativeCredentialAffinityKey,
 	NativeEgressGrantExpiredError,
 	NativeEgressNotDeclaredError,
 	NativeIdleTimeoutError,
 	NativeNetworkError,
 	NativeProxyExpiredError,
-	resolveNativeGatewayProxy,
-	type NativeGatewayProxy,
-	type NativeGatewayProxyResolutionInput,
-	type NativeGatewayProxySkipReason,
-	type NativeGatewayProxySynthesizer,
-	type NativeGatewayProxySynthesisResult,
-	type NativeGatewayProxySynthesisInput,
-	type NativeNetworkClientOptions,
-	type NativeNetworkErrorCode,
-	type VendorCredentialLookup,
-	type VendorCredentialResolver,
+} from "./runtime/native-network-errors.js";
+export type {
+	NativeGatewayProxy,
+	NativeGatewayProxyResolutionInput,
+	NativeGatewayProxySkipReason,
+	NativeGatewayProxySynthesizer,
+	NativeGatewayProxySynthesisResult,
+	NativeGatewayProxySynthesisInput,
+	NativeNetworkClientOptions,
+	NativeNetworkErrorCode,
+	VendorCredentialLookup,
+	VendorCredentialResolver,
 } from "./runtime/native-network.js";
 export {
 	HttpRetryAfterPolicy,

package/src/runtime/auth-flow.ts

@@ -10,7 +10,7 @@ import type {
 	SttContext,
 } from "../types.js";
 import { createUnsupportedOcrClient } from "./ocr.js";
-import { createUnsupportedResolverClient } from "./resolver.js";
+import { createUnsupportedResolverClient } from "./resolver-shared.js";
 import { createUnsupportedSttClient } from "./stt.js";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {

package/src/runtime/browser.ts

@@ -290,7 +290,13 @@ function formatExpression<T>(fn: string | (() => T)): string {
 
 function toLaunchOptions(options: BrowserClientOptions): 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,
@@ -975,6 +981,20 @@ 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: {
@@ -1120,7 +1140,20 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 	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(
@@ -1384,6 +1417,21 @@ 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();
+		});
 		await this.pageClient.send("Page.enable");
 		await this.pageClient.send("Runtime.enable");
 		this.initialized = true;