@apifuse/provider-sdk 2.2.0-beta.36 → 2.2.0-beta.37

package/src/define.ts

@@ -31,6 +31,8 @@ import type {
 	ProviderAccessConfig,
 	ProviderChallengeKind,
 	ProviderDefinition,
+	ProviderContext,
+	ProviderContextFor,
 	ProviderOcrConfig,
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
@@ -197,54 +199,65 @@ function parsePositiveMsDuration(value: string): number | undefined {
 	return parsed;
 }
 
-type ProviderOperation = OperationDefinition<SchemaLike, SchemaLike>;
-type OperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationDefinition<TInput, TOutput>,
-	"handler"
-> & {
+type ProviderOperation = OperationDefinition<any, any, any>;
+type OperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationDefinition<TInput, TOutput, TContext>, "handler"> & {
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	):
 		| OperationHandlerResult<InferSchemaOutput<TOutput>>
 		| Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
 };
-type OperationMapConfig<TOperations extends Record<string, ProviderOperation>> = {
+type OperationMapConfig<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext = ProviderContext,
+> = {
 	[K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer TInput, infer TOutput>
-		? OperationConfig<TInput, TOutput> | OperationDefinition<TInput, TOutput>
+		? OperationConfig<TInput, TOutput, TContext> | OperationDefinition<TInput, TOutput, TContext>
 		: never;
 };
-type StreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> =
-	| SseOperationConfig<TInput, TOutput>
-	| HttpStreamOperationConfig<TInput, TOutput>
-	| WebSocketOperationConfig<TInput, TOutput>;
-type SseOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type StreamOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> =
+	| SseOperationConfig<TInput, TOutput, TContext>
+	| HttpStreamOperationConfig<TInput, TOutput, TContext>
+	| WebSocketOperationConfig<TInput, TOutput, TContext>;
+type SseOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationSseTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): AsyncIterable<ProviderStreamEvent> | Promise<AsyncIterable<ProviderStreamEvent>>;
 };
-type HttpStreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type HttpStreamOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationHttpStreamTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
-type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type WebSocketOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationWebSocketTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
@@ -562,7 +575,7 @@ function authStartHasHiddenInput(start: unknown): boolean {
 	return /\s=\s/.test(second);
 }
 
-export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
+export interface ProviderDeclaration {
 	id: string;
 	version: string;
 	runtime: "standard" | "shared" | "browser";
@@ -573,6 +586,8 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 	 * resolves omitted fields against the runtime deployment profiles.
 	 */
 	deployment?: ProviderDeploymentOverrides;
+	/** Declares that provider operations use the SDK HTTP client. */
+	http?: true;
 	allowedHosts?: string[];
 	native?: NativeProviderConfig;
 	stealth?: {
@@ -585,11 +600,21 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 	resolver?: ProviderResolverConfig;
 	browser?: { engine: BrowserEngine };
 	auth?: AuthConfig;
+	/** Declares that provider operations issue and consume SDK choice tokens. */
+	choice?: true;
 	reviewed?: ProviderReviewed;
 	access?: ProviderAccessConfig;
 	secrets?: ProviderSecretDeclaration[];
+	/** Declares that provider operations read SDK-managed environment values. */
+	env?: true;
 	credential?: CredentialDeclaration;
 	context?: ContextDeclaration;
+	/** Declares that provider operations use SDK-managed persistent state. */
+	state?: true;
+	/** Declares that provider operations use the SDK provider cache. */
+	cache?: true;
+	/** Declares that provider operations access runtime-resolvable files. */
+	files?: true;
 	meta: {
 		displayName: string;
 		displayNameKey?: string;
@@ -611,25 +636,35 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 			publicSchemaFieldNames?: "normalized";
 		};
 	};
-	operations: OperationMapConfig<TOperations>;
 	healthMonitor?: ProviderHealthMonitorConfig;
 	/** New name for `healthMonitor` (transitional alias); declaring both is a ValidationError. */
 	healthProbe?: ProviderHealthMonitorConfig;
 	healthJourneys?: readonly HealthJourneyDefinition[];
 }
 
-/** Define one provider operation with schema-driven handler inference. */
-export function defineOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
-	operation: OperationConfig<TInput, TOutput>,
-): OperationDefinition<TInput, TOutput> {
-	return operation;
+interface ProviderConfig<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext = ProviderContext,
+> extends ProviderDeclaration {
+	operations: OperationMapConfig<TOperations, TContext>;
+}
+
+/** Define one factored provider operation with schema-driven handler inference. */
+export function defineOperation<TContext>() {
+	return function operation<TInput extends SchemaLike, TOutput extends SchemaLike>(
+		config: OperationConfig<TInput, TOutput, TContext>,
+	): OperationDefinition<TInput, TOutput, TContext> {
+		return config;
+	};
 }
 
-/** Define a non-JSON provider operation with explicit transport metadata. */
-export function defineStreamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
-	operation: StreamOperationConfig<TInput, TOutput>,
-): OperationDefinition<TInput, TOutput> {
-	return operation;
+/** Define a factored non-JSON operation with explicit transport metadata. */
+export function defineStreamOperation<TContext>() {
+	return function streamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
+		config: StreamOperationConfig<TInput, TOutput, TContext>,
+	): OperationDefinition<TInput, TOutput, TContext> {
+		return config;
+	};
 }
 
 function assertObjectConfig(value: unknown): asserts value is Record<string, unknown> {
@@ -780,6 +815,14 @@ function validateProviderShape(config: unknown): void {
 	assertRequiredField(config, "operations", String(config.id));
 	if (typeof config.runtime === "string")
 		assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
+	if (config.native !== undefined && config.runtime === "browser") {
+		throw new ValidationError(
+			`Provider "${String(config.id)}" cannot declare capability "native" with runtime "browser"`,
+			{
+				fix: 'Use runtime: "standard" or runtime: "shared", or remove the native declaration.',
+			},
+		);
+	}
 	const auth = config.auth;
 	if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
 		assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
@@ -1087,12 +1130,14 @@ function validateProviderResolver(config: { id: string; resolver?: ProviderResol
 		"resolver",
 		config.id,
 	);
-	validateResolverLiteralArray(
-		resolver.vendors,
-		"resolver.vendors",
-		VALID_PROVIDER_RESOLVER_VENDORS,
-		config.id,
-	);
+	if (resolver.vendors !== undefined) {
+		validateResolverLiteralArray(
+			resolver.vendors,
+			"resolver.vendors",
+			VALID_PROVIDER_RESOLVER_VENDORS,
+			config.id,
+		);
+	}
 	validateResolverLiteralArray(
 		resolver.kinds,
 		"resolver.kinds",
@@ -2783,12 +2828,48 @@ function validateProviderDeployment(providerId: string, deployment: unknown): vo
 		});
 }
 
-export function defineProvider<
+/** The second authoring phase for a declaration established by defineProvider. */
+export type ProviderBuilder<TDeclaration extends ProviderDeclaration> = <
+	TOperations extends Record<string, ProviderOperation>,
+>(
+	implementation: {
+		operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+	},
+) => ProviderDefinition & {
+	operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+};
+
+/** Extract the declaration-derived operation context from a provider builder. */
+export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TDeclaration>
+	? ProviderContextFor<TDeclaration>
+	: never;
+
+/** Establish a provider declaration before its operations are contextually typed. */
+export function defineProvider<const TDeclaration extends ProviderDeclaration>(
+	declaration: TDeclaration &
+		Record<Exclude<keyof TDeclaration, keyof ProviderDeclaration>, never> &
+		AuthStartNoInputGuard<TDeclaration>,
+): ProviderBuilder<TDeclaration> {
+	const buildProvider = <TOperations extends Record<string, ProviderOperation>>(
+		implementation: {
+			operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+		},
+	) =>
+		finalizeProvider({
+			...declaration,
+			...implementation,
+		} as ProviderConfig<TOperations, ProviderContextFor<TDeclaration>>);
+	return buildProvider as ProviderBuilder<TDeclaration>;
+}
+
+function finalizeProvider<
 	TOperations extends Record<string, ProviderOperation>,
-	TConfig extends ProviderConfig<TOperations>,
+	TContext,
 >(
-	config: TConfig & AuthStartNoInputGuard<TConfig>,
-): ProviderDefinition & { operations: OperationMapConfig<TOperations> } {
+	config: ProviderConfig<TOperations, TContext>,
+): ProviderDefinition & {
+	operations: OperationMapConfig<TOperations, TContext>;
+} {
 	validateProviderShape(config);
 	const operations = resolveOperationFixtureRequests(config.operations);
 	if (!CONNECTOR_ID_REGEX.test(config.id))
@@ -2849,7 +2930,9 @@ export function defineProvider<
 			`Provider "${config.id}" cannot define browser config unless runtime is "browser"`,
 			{ fix: 'Set runtime: "browser" or remove the browser config' },
 		);
-	const provider: ProviderDefinition & { operations: OperationMapConfig<TOperations> } = {
+	const provider: ProviderDefinition & {
+		operations: OperationMapConfig<TOperations, TContext>;
+	} = {
 		id: config.id,
 		version: config.version,
 		runtime: config.runtime,
@@ -2871,7 +2954,8 @@ export function defineProvider<
 		credential: config.credential,
 		context: config.context,
 		meta: config.meta,
-		operations,
+		operations: operations as ProviderDefinition["operations"] &
+			OperationMapConfig<TOperations, TContext>,
 		// Transitional healthMonitor → healthProbe alias: mirror whichever field
 		// was declared onto both so old and new consumers keep working.
 		healthMonitor: config.healthMonitor ?? config.healthProbe,

package/src/index.ts

@@ -34,7 +34,9 @@ export {
 	defineStreamOperation,
 	every,
 	type AuthStartNoInputGuard,
-	type ProviderConfig,
+	type ProviderBuilder,
+	type ProviderContextOf,
+	type ProviderDeclaration,
 } from "./define.js";
 export type { DevServerOptions } from "./dev.js";
 export { createDevServer, startDevServer } from "./dev.js";
@@ -244,7 +246,6 @@ export type {
 	NativeNetworkDynamicGrantOptions,
 	NativeNetworkEgressGrant,
 	NativeProviderConfig,
-	NativeProviderContext,
 	NativeProxyDrainHandler,
 	NativeProxyEgressInfo,
 	NativeProxyExpiringEvent,
@@ -301,6 +302,7 @@ export type {
 	ProviderChallenge,
 	ProviderChallengeKind,
 	ProviderContext,
+	ProviderContextFor,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
 	ProviderFileRef,

package/src/provider.ts

@@ -35,6 +35,11 @@ export {
 	defineSmsOtpMatcher,
 	every,
 } from "./define.js";
+export type {
+	ProviderBuilder,
+	ProviderContextOf,
+	ProviderDeclaration,
+} from "./define.js";
 export {
 	AuthError,
 	HttpRedirectError,
@@ -107,7 +112,6 @@ export type {
 	NativeNetworkDynamicGrantOptions,
 	NativeNetworkEgressGrant,
 	NativeProviderConfig,
-	NativeProviderContext,
 	NativeProxyDrainHandler,
 	NativeProxyEgressInfo,
 	NativeProxyExpiringEvent,
@@ -142,6 +146,7 @@ export type {
 	ProviderChoiceIssueOptions,
 	ProviderChoiceParseOptions,
 	ProviderContext,
+	ProviderContextFor,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
 	ProviderFileRef,

package/src/runtime/browser.ts

@@ -804,8 +804,11 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 		private readonly proxy: LaunchOptions["proxy"] = undefined,
 	) {}
 
-	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> {
+		await this.page.goto(url, options);
 	}
 
 	async evaluate<T>(fn: string | (() => T)): Promise<T> {
@@ -1492,17 +1495,33 @@ 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();
 		}
@@ -1866,12 +1885,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;
 				}
 			}

package/src/runtime/resolver-public.ts

@@ -8,10 +8,12 @@ export {
 	createResolverClient,
 	createResolverClientFromEnv,
 	createUnsupportedResolverClient,
+	DEFAULT_RESOLVER_VENDOR_PREFERENCE,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
 	invalidateResolverSolution,
 	RESOLVER_ADAPTER_REGISTRY,
 	RESOLVER_INSTRUMENTATION_METADATA,
+	resolveProviderResolverVendors,
 	type ResolverAdapterFactory,
 	type ResolverInstrumentationMetadata,
 	type ResolverRuntimeOptions,

package/src/runtime/resolver-vendors/browser.ts

@@ -18,6 +18,7 @@ import {
 
 const BROWSER_VENDOR_ID = "browser" as const;
 const DEFAULT_COOKIE_POLL_INTERVAL_MS = 100;
+const NAVIGATION_BLOCKED_ERROR_TEXT = "net::ERR_BLOCKED_BY_CLIENT";
 const AWS_WAF_CHALLENGE_INFRASTRUCTURE_HOST_SUFFIX = ".awswaf.com";
 const RESOLVER_DOCUMENT_CONTENT_SECURITY_POLICY = "connect-src http: https:; worker-src 'none'";
 
@@ -65,12 +66,41 @@ export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
 }
 
 class BrowserSolveTimeoutError extends Error {
-	constructor() {
-		super("Browser resolver solve budget elapsed");
+	constructor(blockedRequests: readonly string[]) {
+		super(
+			`Browser resolver solve budget elapsed${formatBlockedRequests(blockedRequests)}`,
+		);
 		this.name = "BrowserSolveTimeoutError";
 	}
 }
 
+class BrowserNavigationBlockedError extends Error {
+	readonly code = "RESOLVER_BROWSER_NAVIGATION_BLOCKED";
+
+	constructor(
+		readonly navigationUrl: string,
+		readonly blockedUrls: readonly string[],
+		options: ErrorOptions,
+	) {
+		super(
+			`Browser resolver navigation was blocked for ${navigationUrl}${formatBlockedRequests(blockedUrls)}`,
+			options,
+		);
+		this.name = "BrowserNavigationBlockedError";
+	}
+}
+
+function formatBlockedRequests(blockedRequests: readonly string[]): string {
+	if (blockedRequests.length === 0) return "";
+	const displayed = blockedRequests.slice(0, 5);
+	const remainder = blockedRequests.length - displayed.length;
+	return `; blocked ${blockedRequests.length} requests: [${displayed.join(", ")}]${remainder > 0 ? ` (+${remainder} more)` : ""}`;
+}
+
+function isNavigationBlockedError(error: unknown): error is Error {
+	return error instanceof Error && error.message.includes(NAVIGATION_BLOCKED_ERROR_TEXT);
+}
+
 class BrowserCleanupTimeoutError extends Error {
 	constructor(timeoutMs: number) {
 		super(`Browser resolver cleanup exceeded ${timeoutMs}ms`);
@@ -223,6 +253,8 @@ async function solveInPage(
 	allowedHosts: readonly string[],
 	successCookieName: string,
 	pollIntervalMs: number,
+	gotoTimeoutMs: number,
+	blockedRequests: Set<string>,
 	signal: AbortSignal,
 ): Promise<Extract<ChallengeSolution, { readonly form: "cookies" }>> {
 	return await page.withResourcePolicy(
@@ -232,11 +264,13 @@ async function solveInPage(
 			routes: [
 				{
 					match: () => true,
-					handle: (request) => ({
-						action: isResolverBrowserRequestAllowed(request.url, challengeKind, allowedHosts)
-							? "continue"
-							: "block",
-					}),
+					handle: (request) => {
+						if (isResolverBrowserRequestAllowed(request.url, challengeKind, allowedHosts)) {
+							return { action: "continue" };
+						}
+						blockedRequests.add(request.url);
+						return { action: "block" };
+					},
 				},
 			],
 		},
@@ -245,7 +279,19 @@ async function solveInPage(
 				() => page.userAgent(),
 				signal,
 			);
-			await raceWithAbort(() => page.goto(pageUrl), signal);
+			try {
+				await raceWithAbort(
+					() =>
+						page.goto(pageUrl, {
+							timeout: gotoTimeoutMs,
+							waitUntil: "domcontentloaded",
+						}),
+					signal,
+				);
+			} catch (error) {
+				if (!isNavigationBlockedError(error)) throw error;
+				throw new BrowserNavigationBlockedError(pageUrl, [...blockedRequests], { cause: error });
+			}
 
 			while (true) {
 				const cookies = await raceWithAbort(() => page.cookies(), signal);
@@ -304,6 +350,7 @@ function poolErrorCode(error: Error): number | undefined {
 
 function knownUnavailableReason(
 	error: unknown,
+	beforePageSolve = false,
 ): "allocation_exhausted" | "missing_credentials" | "transport_failure" | undefined {
 	// Source-grounded mappings:
 	// - apps/cdp-pool/src/index.ts: the JSON-RPC codes and messages below.
@@ -338,7 +385,10 @@ function knownUnavailableReason(
 		return "transport_failure";
 	}
 
-	return undefined;
+	// Browser creation, Playwright launch, and CDP connection all happen before the
+	// isolated-page handler is entered. Errors after that boundary belong to the
+	// challenge solve and must retain their existing classification.
+	return beforePageSolve ? "transport_failure" : undefined;
 }
 
 async function closeBrowserClient(
@@ -400,11 +450,12 @@ export function createBrowserResolverVendorAdapter(
 				throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "not_implemented");
 			}
 
+			const blockedRequests = new Set<string>();
 			const solveController = new AbortController();
 			const onCallerAbort = () => solveController.abort(abortReason(callerSignal));
 			callerSignal.addEventListener("abort", onCallerAbort, { once: true });
 			const timeout = setTimeout(
-				() => solveController.abort(new BrowserSolveTimeoutError()),
+				() => solveController.abort(new BrowserSolveTimeoutError([...blockedRequests])),
 				options.timeoutMs,
 			);
 
@@ -427,6 +478,8 @@ export function createBrowserResolverVendorAdapter(
 						options.allowedHosts,
 						SUCCESS_COOKIE_NAMES[challengeKind],
 						pollIntervalMs,
+						options.timeoutMs,
+						blockedRequests,
 						solveController.signal,
 					);
 				});
@@ -457,10 +510,15 @@ export function createBrowserResolverVendorAdapter(
 						cause: error,
 					});
 				}
+				if (error instanceof BrowserNavigationBlockedError) {
+					throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "transport_failure", {
+						cause: error,
+					});
+				}
 				if (error instanceof ResolverVendorUnavailableError) {
 					throw error;
 				}
-				const reason = knownUnavailableReason(error);
+				const reason = knownUnavailableReason(error, !handlerEntered);
 				if (reason) {
 					throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, reason, { cause: error });
 				}

package/src/runtime/resolver-vendors/types.ts

@@ -2,6 +2,7 @@ import type {
 	ChallengeSolution,
 	ProviderChallenge,
 	ProviderChallengeKind,
+	ProviderResolverConfig,
 	ProviderResolverVendor,
 } from "../../types.js";
 import type { TraceRecorder } from "../trace.js";
@@ -42,6 +43,16 @@ export const RESOLVER_VENDOR_CAPABILITIES = {
 	],
 } as const satisfies Readonly<Record<ProviderResolverVendor, readonly ProviderChallengeKind[]>>;
 
+/**
+ * SDK-owned fallback policy for hosted resolver vendors. Capability support is
+ * applied separately, so each provider receives only vendors that support one
+ * or more of its declared challenge kinds.
+ */
+export const DEFAULT_RESOLVER_VENDOR_PREFERENCE = [
+	"capsolver",
+	"2captcha",
+] as const satisfies readonly ProviderResolverVendor[];
+
 export function resolverVendorSupports(
 	vendor: ProviderResolverVendor,
 	kind: ProviderChallengeKind,
@@ -49,6 +60,16 @@ export function resolverVendorSupports(
 	return (RESOLVER_VENDOR_CAPABILITIES[vendor] as readonly ProviderChallengeKind[]).includes(kind);
 }
 
+/** Resolves an explicit provider override or the SDK-owned default vendor chain. */
+export function resolveProviderResolverVendors(
+	config: ProviderResolverConfig,
+): readonly ProviderResolverVendor[] {
+	if (config.vendors !== undefined) return config.vendors;
+	return DEFAULT_RESOLVER_VENDOR_PREFERENCE.filter((vendor) =>
+		config.kinds.some((kind) => resolverVendorSupports(vendor, kind)),
+	);
+}
+
 export interface ResolverIdentity {
 	readonly proxyUrl: string;
 	readonly userAgent: string;