@apifuse/provider-sdk 2.2.0-beta.61 → 2.2.0-beta.63

package/src/runtime/ocr.ts

@@ -1,4 +1,3 @@
-import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { ProviderError, TransportError } from "../errors.js";
 import type {
 	OcrCaptchaCandidate,
@@ -10,6 +9,13 @@ import type {
 	OcrResult,
 	ProviderOcrConfig,
 } from "../types.js";
+import { readCapabilityErrorBody } from "./capability-response.js";
+import {
+	captureCapability,
+	registerCapabilityInput,
+	tagCapability,
+} from "./capability-telemetry.js";
+import { readDiagnosticEnv, registerDiagnosticValue } from "./diagnostic-env.js";
 import { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
 import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
 
@@ -78,14 +84,17 @@ function createErrorOcrClient(options: ErrorOcrClientOptions): OcrContext {
 			fix: options.fix,
 		});
 	};
-	return {
-		async recognize() {
-			return unavailable();
-		},
-		async extractCaptchaText() {
-			return unavailable();
+	return tagCapability(
+		{
+			async recognize() {
+				return unavailable();
+			},
+			async extractCaptchaText() {
+				return unavailable();
+			},
 		},
-	};
+		{ backend: "unavailable", engine: "custom" },
+	);
 }
 
 export function createUnsupportedOcrClient(reason?: string): OcrContext {
@@ -249,6 +258,8 @@ function responseContent(payload: unknown, cloudflare: boolean, model: string):
 	const choices = root?.choices;
 	if (!Array.isArray(choices)) return undefined;
 	const choice = unknownRecord(choices[0]);
+	if (typeof choice?.finish_reason === "string")
+		captureCapability({ finishReason: choice.finish_reason });
 	if (typeof choice?.finish_reason === "string" && choice.finish_reason !== "stop") {
 		throw incompleteResponseError(model, choice.finish_reason);
 	}
@@ -305,7 +316,11 @@ function moondreamSseContent(body: string, model: string): string | undefined {
 			terminalFinishReason = chunk.finish_reason;
 		}
 	}
-	if (finalAnswer) return finalAnswer;
+	if (finalAnswer) {
+		captureCapability({ finishReason: "stop" });
+		return finalAnswer;
+	}
+	if (terminalFinishReason) captureCapability({ finishReason: terminalFinishReason });
 	if (terminalFinishReason) throw incompleteResponseError(model, terminalFinishReason);
 	if (firstDecodingFailure) throw malformedResponseError(model, firstDecodingFailure);
 	return finalAnswer;
@@ -361,48 +376,57 @@ export function createCloudflareWorkersAiOcrClient(
 ): OcrContext {
 	const model = options.model ?? DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL;
 	const runFetch = options.fetch ?? fetch;
-	return createOcrClient(model, async (request) => {
-		const timeout = createTimeoutController(request.timeoutMs ?? DEFAULT_OCR_TIMEOUT_MS);
-		try {
-			let response: Response;
+	return tagCapability(
+		createOcrClient(model, async (request) => {
+			registerCapabilityInput(request.image);
+			registerDiagnosticValue(options.apiToken);
+			registerDiagnosticValue(`Bearer ${options.apiToken}`);
+			const timeout = createTimeoutController(request.timeoutMs ?? DEFAULT_OCR_TIMEOUT_MS);
 			try {
-				response = await runFetch(
-					`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(options.accountId)}/ai/run/${model}`,
-					{
-						method: "POST",
-						headers: {
-							Authorization: `Bearer ${options.apiToken}`,
-							"Content-Type": "application/json",
+				let response: Response;
+				try {
+					response = await runFetch(
+						`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(options.accountId)}/ai/run/${model}`,
+						{
+							method: "POST",
+							headers: {
+								Authorization: `Bearer ${options.apiToken}`,
+								"Content-Type": "application/json",
+							},
+							body: JSON.stringify(
+								isMoondreamModel(model)
+									? moondreamPayload(request)
+									: cloudflareMessagesPayload(request, model),
+							),
+							signal: timeout.controller.signal,
 						},
-						body: JSON.stringify(
-							isMoondreamModel(model)
-								? moondreamPayload(request)
-								: cloudflareMessagesPayload(request, model),
-						),
-						signal: timeout.controller.signal,
-					},
-				);
+					);
+				} catch (error) {
+					throw toOcrTransportError(error);
+				}
+				captureCapability({ status: response.status });
+				if (!response.ok) {
+					const echoed = await readCapabilityErrorBody(response, timeout.controller.signal);
+					captureCapability({ diagnostics: echoed });
+					throw new TransportError("OCR upstream request failed", {
+						code: "OCR_UPSTREAM_FAILED",
+						status: response.status,
+						upstreamStatus: response.status,
+					});
+				}
+				const text = isMoondreamModel(model)
+					? moondreamSseContent(await response.text(), model)
+					: responseContent(await responseJson(response, model), true, model);
+				if (!text) throw emptyResponseError(model);
+				return { text, model };
 			} catch (error) {
 				throw toOcrTransportError(error);
+			} finally {
+				timeout.clear();
 			}
-			if (!response.ok) {
-				throw new TransportError("OCR upstream request failed", {
-					code: "OCR_UPSTREAM_FAILED",
-					status: response.status,
-					upstreamStatus: response.status,
-				});
-			}
-			const text = isMoondreamModel(model)
-				? moondreamSseContent(await response.text(), model)
-				: responseContent(await responseJson(response, model), true, model);
-			if (!text) throw emptyResponseError(model);
-			return { text, model };
-		} catch (error) {
-			throw toOcrTransportError(error);
-		} finally {
-			timeout.clear();
-		}
-	});
+		}),
+		{ backend: "cloudflare-workers-ai", engine: "workers-ai", model },
+	);
 }
 
 export function createOpenAiCompatibleOcrClient(
@@ -410,38 +434,49 @@ export function createOpenAiCompatibleOcrClient(
 ): OcrContext {
 	const model = options.model;
 	const runFetch = options.fetch ?? fetch;
-	return createOcrClient(model, async (request) => {
-		const headers: Record<string, string> = { "Content-Type": "application/json" };
-		if (options.apiKey) headers.Authorization = `Bearer ${options.apiKey}`;
-		const timeout = createTimeoutController(request.timeoutMs ?? DEFAULT_OCR_TIMEOUT_MS);
-		try {
-			let response: Response;
+	return tagCapability(
+		createOcrClient(model, async (request) => {
+			registerCapabilityInput(request.image);
+			if (options.apiKey) {
+				registerDiagnosticValue(options.apiKey);
+				registerDiagnosticValue(`Bearer ${options.apiKey}`);
+			}
+			const headers: Record<string, string> = { "Content-Type": "application/json" };
+			if (options.apiKey) headers.Authorization = `Bearer ${options.apiKey}`;
+			const timeout = createTimeoutController(request.timeoutMs ?? DEFAULT_OCR_TIMEOUT_MS);
 			try {
-				response = await runFetch(`${options.baseUrl.replace(/\/+$/u, "")}/chat/completions`, {
-					method: "POST",
-					headers,
-					body: JSON.stringify(messagesPayload(request, model)),
-					signal: timeout.controller.signal,
-				});
+				let response: Response;
+				try {
+					response = await runFetch(`${options.baseUrl.replace(/\/+$/u, "")}/chat/completions`, {
+						method: "POST",
+						headers,
+						body: JSON.stringify(messagesPayload(request, model)),
+						signal: timeout.controller.signal,
+					});
+				} catch (error) {
+					throw toOcrTransportError(error);
+				}
+				captureCapability({ status: response.status });
+				if (!response.ok) {
+					const echoed = await readCapabilityErrorBody(response, timeout.controller.signal);
+					captureCapability({ diagnostics: echoed });
+					throw new TransportError("OCR upstream request failed", {
+						code: "OCR_UPSTREAM_FAILED",
+						status: response.status,
+						upstreamStatus: response.status,
+					});
+				}
+				const text = responseContent(await responseJson(response, model), false, model);
+				if (!text) throw emptyResponseError(model);
+				return { text, model };
 			} catch (error) {
 				throw toOcrTransportError(error);
+			} finally {
+				timeout.clear();
 			}
-			if (!response.ok) {
-				throw new TransportError("OCR upstream request failed", {
-					code: "OCR_UPSTREAM_FAILED",
-					status: response.status,
-					upstreamStatus: response.status,
-				});
-			}
-			const text = responseContent(await responseJson(response, model), false, model);
-			if (!text) throw emptyResponseError(model);
-			return { text, model };
-		} catch (error) {
-			throw toOcrTransportError(error);
-		} finally {
-			timeout.clear();
-		}
-	});
+		}),
+		{ backend: "openai-compatible", engine: "openai-compatible", model },
+	);
 }
 
 function cleanCaptchaText(text: string): string {

package/src/runtime/request-telemetry.ts

@@ -140,7 +140,8 @@ const MAX_INGESTIBLE_ARRAY_LENGTH = 64;
 const MAX_INGESTIBLE_OBJECT_KEYS = 32;
 const MAX_INGESTIBLE_DEPTH = 4;
 const INGESTIBLE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
-const HEADER_PRIORITY = [
+/** @internal */
+export const HEADER_PRIORITY = [
 	"proxy",
 	"resolver",
 	"native",

package/src/runtime/resolver-runtime-options.ts

@@ -0,0 +1,50 @@
+import type { ProviderCache, ProviderDefinition, ProviderProxyPolicy } from "../types.js";
+import type { ResolverRuntimeOptions } from "./resolver.js";
+import type { ResolverTelemetrySink } from "./resolver-telemetry.js";
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
+
+/** Normalize the `proxy` declaration shorthand (`true`/`false`) into the policy object the resolver chain consumes. */
+export function resolveNativeProxyPolicy(
+	provider: ProviderDefinition,
+): ProviderProxyPolicy | undefined {
+	if (typeof provider.proxy === "object") return provider.proxy;
+	if (provider.proxy === true) return { mode: "optional" };
+	if (provider.proxy === false) return { mode: "disabled" };
+	return undefined;
+}
+
+/**
+ * One option set for every SDK-built resolver chain — the server's ctx.resolver and automatic
+ * SBSD solve, and the CLI helper contexts — so they share allowed hosts, cache, identity scope,
+ * proxy intent, and the telemetry sink. `identityScope` is server-owned; CLI contexts pass none.
+ */
+export function createResolverRuntimeOptions(
+	provider: ProviderDefinition,
+	cache: ProviderCache,
+	identityScope: string | undefined,
+	proxyPolicy: ProviderProxyPolicy | undefined,
+	proxyClientOptions: Omit<
+		NonNullable<ResolverRuntimeOptions["proxyIntent"]>,
+		"mode" | "userAgent"
+	>,
+	stealthProfile: { readonly userAgent: string } | undefined,
+	telemetry: ResolverTelemetrySink,
+	browserTelemetry?: BrowserTelemetrySink,
+): ResolverRuntimeOptions {
+	return {
+		allowedHosts: provider.allowedHosts,
+		cache,
+		telemetry,
+		browserTelemetry,
+		...(identityScope === undefined ? {} : { identityScope }),
+		...(proxyPolicy
+			? {
+					proxyIntent: {
+						mode: proxyPolicy.mode,
+						...proxyClientOptions,
+						...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
+					},
+				}
+			: {}),
+	};
+}

package/src/runtime/resolver-shared.ts

@@ -2,8 +2,12 @@ import { ProviderError } from "../errors.js";
 import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
 import type { TraceRecorder } from "./trace.js";
 import type { ResolverTelemetryOutcome, ResolverTelemetrySink } from "./resolver-telemetry.js";
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
 
-type ResolverTelemetryBinding = (sink: ResolverTelemetrySink) => ResolverContext;
+type ResolverTelemetryBinding = (
+	sink: ResolverTelemetrySink,
+	browserSink?: BrowserTelemetrySink,
+) => ResolverContext;
 const telemetryBindings = new WeakMap<ResolverContext, ResolverTelemetryBinding>();
 
 /** Internal contract: reconstruct a chain with a new request sink, without mutating the host chain. */
@@ -27,6 +31,7 @@ export function inheritResolverTelemetryBinding(
 export function bindResolverTelemetry(
 	resolver: ResolverContext,
 	sink: ResolverTelemetrySink | undefined,
+	browserSink?: BrowserTelemetrySink,
 ): ResolverContext {
 	if (!sink) return resolver;
 	const metadata = (
@@ -34,9 +39,9 @@ export function bindResolverTelemetry(
 			readonly [RESOLVER_INSTRUMENTATION_METADATA]?: { readonly target: ResolverContext };
 		}
 	)[RESOLVER_INSTRUMENTATION_METADATA];
-	if (metadata) return bindResolverTelemetry(metadata.target, sink);
+	if (metadata) return bindResolverTelemetry(metadata.target, sink, browserSink);
 	const bind = telemetryBindings.get(resolver);
-	if (bind) return bind(sink);
+	if (bind) return bind(sink, browserSink);
 	const wrapper: ResolverSolveWithRecorder = {
 		async solve(challenge, signal, recorder) {
 			const startedAt = Date.now();
@@ -74,7 +79,7 @@ export function bindResolverTelemetry(
 }
 
 function createOpaqueResolverTelemetryBinding(resolver: ResolverContext): ResolverTelemetryBinding {
-	return (sink) => bindResolverTelemetry(resolver, sink);
+	return (sink, browserSink) => bindResolverTelemetry(resolver, sink, browserSink);
 }
 
 export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for(

package/src/runtime/resolver-telemetry.ts

@@ -147,7 +147,7 @@ function boundedInteger(value: number): number {
 	return Math.max(0, Math.floor(Number.isFinite(value) ? value : 0));
 }
 
-function boundedText(value: string, redact?: (text: string) => string): string {
+export function boundedText(value: string, redact?: (text: string) => string): string {
 	let result = value;
 	try {
 		result = redact?.(value) ?? value;

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

@@ -8,6 +8,7 @@ import type {
 } from "../../types.js";
 import { type BrowserClientOptions, createBrowserClient } from "../browser.js";
 import type { TraceRecorder } from "../trace.js";
+import type { BrowserTelemetrySink } from "../browser-telemetry.js";
 import { resolverChallengeIssuingIdentity } from "./bindings.js";
 import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.js";
 import {
@@ -31,6 +32,59 @@ type SupportedBrowserChallengeKind = keyof typeof SUCCESS_COOKIE_NAMES;
 
 type BrowserClientFactory = (options: BrowserClientOptions) => BrowserClient;
 
+const RESOLVER_PAGE_METHODS = new Set([
+	"goto",
+	"evaluate",
+	"fill",
+	"click",
+	"type",
+	"waitForSelector",
+	"content",
+	"screenshot",
+	"cookies",
+	"url",
+	"title",
+	"userAgent",
+]);
+
+function instrumentResolverBrowser(client: BrowserClient, recorder: TraceRecorder): BrowserClient {
+	const wrapPage = (page: BrowserPage): BrowserPage =>
+		new Proxy(page, {
+			get(target, property, receiver) {
+				const value = Reflect.get(target, property, receiver);
+				if (
+					typeof property !== "string" ||
+					!RESOLVER_PAGE_METHODS.has(property) ||
+					typeof value !== "function"
+				)
+					return value;
+				return (...args: unknown[]) =>
+					recorder.runSpan(`browser.page.${property}`, () => Reflect.apply(value, target, args));
+			},
+		});
+	return new Proxy(client, {
+		get(target, property, receiver) {
+			const value = Reflect.get(target, property, receiver);
+			if (property === "newPage" && typeof value === "function")
+				return () =>
+					recorder.runSpan("browser.newPage", async () =>
+						wrapPage(await Reflect.apply(value, target, [])),
+					);
+			if (property === "rawPage" && typeof value === "function")
+				return () =>
+					recorder.runSpan("browser.rawPage", async () =>
+						wrapPage(await Reflect.apply(value, target, [])),
+					);
+			if (property === "withIsolatedContext" && typeof value === "function")
+				return (handler: (page: BrowserPage) => Promise<unknown>) =>
+					recorder.runSpan("browser.withIsolatedContext", () =>
+						Reflect.apply(value, target, [(page: BrowserPage) => handler(wrapPage(page))]),
+					);
+			return value;
+		},
+	});
+}
+
 let createResolverBrowserClient: BrowserClientFactory = createBrowserClient;
 
 /** Internal test seam; deliberately not re-exported from the package root. */
@@ -53,6 +107,7 @@ export interface BrowserResolverVendorOptions {
 	readonly pollIntervalMs?: number;
 	readonly allowedHosts: readonly string[];
 	readonly createClient?: BrowserClientFactory;
+	readonly telemetry?: BrowserTelemetrySink;
 }
 
 export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
@@ -67,9 +122,7 @@ export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
 
 class BrowserSolveTimeoutError extends Error {
 	constructor(blockedRequests: readonly string[]) {
-		super(
-			`Browser resolver solve budget elapsed${formatBlockedRequests(blockedRequests)}`,
-		);
+		super(`Browser resolver solve budget elapsed${formatBlockedRequests(blockedRequests)}`);
 		this.name = "BrowserSolveTimeoutError";
 	}
 }
@@ -274,10 +327,7 @@ async function solveInPage(
 			],
 		},
 		async () => {
-			const userAgent = await raceWithAbort(
-				() => page.userAgent(),
-				signal,
-			);
+			const userAgent = await raceWithAbort(() => page.userAgent(), signal);
 			try {
 				await raceWithAbort(
 					() =>
@@ -467,7 +517,15 @@ export function createBrowserResolverVendorAdapter(
 					...(proxyUrl === undefined ? {} : { proxy: proxyUrl }),
 					requireCdpPool: cdpUrl !== undefined,
 					serviceWorkers: "block",
+					telemetry: options.telemetry,
 				});
+				/**
+				 * Direct vendor callers without a telemetry sink keep the historical trace shape.
+				 * Bound server requests record browser page spans under resolver.vendor.attempt,
+				 * with resolver.vendor.cleanup as a sibling of the browser context span.
+				 */
+				if (traceRecorder && options.telemetry)
+					client = instrumentResolverBrowser(client, traceRecorder);
 				const contextOperation = client.withIsolatedContext(async (page) => {
 					handlerEntered = true;
 					return await solveInPage(

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

@@ -1,4 +1,25 @@
 import { ProviderError } from "../../errors.js";
+import type { ProviderResolverVendor } from "../../types.js";
+
+/**
+ * Exact SDK-owned service hosts each vendor's adapter may reach through its bound
+ * transport, in addition to the provider's declared `allowedHosts`. This table is
+ * the trust boundary for `ResolverVendorAdapter.transportAllowedHosts`: a
+ * declaration outside its vendor's entry is rejected, whoever supplied the adapter.
+ * Only Hyper's observed-IP reflector rides the identity-bound transport (ADR-0008
+ * v1.1 amend, PR #251); every other vendor talks to its own service directly.
+ * Frozen at runtime, not just in the type: the Hyper adapter hands its entry out by
+ * reference as `transportAllowedHosts`, so a mutable table would let any holder of a
+ * registry adapter widen the boundary for every later adapter in the process.
+ */
+export const RESOLVER_VENDOR_TRANSPORT_HOSTS = Object.freeze({
+	"2captcha": Object.freeze([] as const),
+	browser: Object.freeze([] as const),
+	capmonster: Object.freeze([] as const),
+	capsolver: Object.freeze([] as const),
+	custom: Object.freeze([] as const),
+	hypersolutions: Object.freeze(["ip.hypersolutions.co"] as const),
+}) satisfies Readonly<Record<ProviderResolverVendor, readonly string[]>>;
 
 export function normalizedResolverHostname(hostname: string): string {
 	return hostname.trim().toLowerCase().replace(/\.$/, "");
@@ -36,3 +57,25 @@ export function assertResolverHostAllowed(
 		fix: "Add the exact target hostname to the provider's allowedHosts declaration.",
 	});
 }
+
+export function assertResolverVendorTransportHosts(
+	vendor: ProviderResolverVendor,
+	declaredHosts: readonly string[],
+): void {
+	// A vendor id outside the table (only reachable from untyped callers) owns no hosts and
+	// is rejected below like any other overreach; `hasOwn` keeps prototype keys out too.
+	const ownedHosts: readonly string[] = Object.hasOwn(RESOLVER_VENDOR_TRANSPORT_HOSTS, vendor)
+		? RESOLVER_VENDOR_TRANSPORT_HOSTS[vendor]
+		: [];
+	for (const declaredHost of declaredHosts) {
+		const normalizedHost = normalizedResolverHostname(declaredHost);
+		if (ownedHosts.some((host) => normalizedResolverHostname(host) === normalizedHost)) continue;
+		throw new ProviderError(
+			`Resolver vendor "${vendor}" may not declare transport host "${normalizedHost}"`,
+			{
+				code: "RESOLVER_VENDOR_HOST_NOT_ALLOWED",
+				fix: "Remove the host from transportAllowedHosts: an adapter reaches only the provider's allowedHosts plus the SDK-owned service hosts of its vendor.",
+			},
+		);
+	}
+}

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

@@ -3,7 +3,7 @@ import { isIP } from "node:net";
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
 import { recordPaidResolverCreate } from "../resolver-usage.js";
 import type { TraceRecorder } from "../trace.js";
-import { assertResolverHostAllowed } from "./hosts.js";
+import { assertResolverHostAllowed, RESOLVER_VENDOR_TRANSPORT_HOSTS } from "./hosts.js";
 import {
 	ResolverChallengeVerdictError,
 	type ResolverIdentity,
@@ -21,7 +21,7 @@ const HYPER_IP_URL = "https://ip.hypersolutions.co/ip";
  * egress address the upstream will see. The payload-generation POST carries no
  * identity and goes direct, as in the measured zozotown source.
  */
-const HYPER_TRANSPORT_HOSTS = ["ip.hypersolutions.co"] as const;
+const HYPER_TRANSPORT_HOSTS = RESOLVER_VENDOR_TRANSPORT_HOSTS.hypersolutions;
 const IP_RESPONSE_MAX_BYTES = 4_096;
 /** Measured bound shared by the script, the Hyper envelope, and the payload submission. */
 const BODY_MAX_BYTES = 1_000_000;

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

@@ -157,10 +157,11 @@ export interface ResolverVendorAdapter {
 	readonly id: ProviderResolverVendor;
 	readonly requiresTransport?: boolean | ((kind: ProviderChallengeKind) => boolean);
 	/**
-	 * Exact SDK-owned service hosts this adapter may reach through its bound transport.
-	 * Honored for every adapter the chain runs, so whoever supplies `adapters` to
-	 * `createResolverClient` is the trust boundary; the engine path
-	 * (`createResolverClientFromEnv`) only constructs registry adapters.
+	 * Exact SDK-owned service hosts this adapter may reach through its bound transport,
+	 * in addition to the provider's `allowedHosts`. Every host must appear in the
+	 * SDK-owned `RESOLVER_VENDOR_TRANSPORT_HOSTS` entry for `id`; the chain rejects any
+	 * other declaration with `RESOLVER_VENDOR_HOST_NOT_ALLOWED`, whoever supplied the
+	 * adapter. The transport handed to `solve` is revoked once `solve` settles.
 	 */
 	readonly transportAllowedHosts?: readonly string[];
 	supports(kind: ProviderChallengeKind): boolean;