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

package/dist/runtime/instrumentation.js

@@ -1,9 +1,19 @@
+import { runCapabilitySpan } from "./capability-telemetry.js";
 import { registerDiagnosticSensitiveValues } from "./diagnostic-redactor.js";
 import { readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { parseHttpRequestInvocation, isSensitiveKey, redactSensitiveError, redactSensitiveText, redactUrlQueryParams, requestOptionsFromHttpInvocation, serializeRequestUrl, } from "./request-options.js";
 import { createTraceContext, getTraceRecorder, } from "./trace.js";
 import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.js";
-const BROWSER_PAGE_METHODS = new Set(["goto", "fill", "click", "type", "waitForSelector"]);
+const BROWSER_PAGE_METHODS = new Set([
+    "goto",
+    "fill",
+    "click",
+    "type",
+    "waitForSelector",
+    "evaluate",
+    "content",
+    "screenshot",
+]);
 const DIAGNOSTIC_BASE_URL = "http://apifuse-instrumentation.invalid";
 function isThenable(value) {
     return ((typeof value === "object" || typeof value === "function") &&
@@ -254,9 +264,18 @@ function buildSpanAttributes(namespace, methodName, args, result, error, diagnos
     if (method) {
         attributes.method = method;
     }
-    if (status !== undefined && (namespace === "http" || namespace === "stealth")) {
+    if (status !== undefined &&
+        (namespace === "http" || namespace === "stealth" || namespace === "ocr" || namespace === "stt")) {
         attributes.status = status;
     }
+    if ((namespace === "ocr" || namespace === "stt") && result && typeof result === "object") {
+        if ("model" in result && typeof result.model === "string")
+            attributes.model = result.model;
+        if ("durationMs" in result && typeof result.durationMs === "number")
+            attributes.duration_ms = result.durationMs;
+        if ("warnings" in result && Array.isArray(result.warnings))
+            attributes.warnings = result.warnings.length;
+    }
     if (duration !== undefined) {
         attributes.duration_ms = duration;
     }
@@ -359,14 +378,30 @@ function wrapPage(page, trace) {
             const methodName = String(property);
             const wrapped = (...args) => {
                 let elapsedMs = 0;
-                return recorder.runSpan(`browser.page.${methodName}`, async () => {
+                const diagnostics = snapshotRequestDiagnostics("browser", methodName, args);
+                registerDiagnosticSensitiveValues(trace, diagnostics.sensitiveValues);
+                return recorder.runSpan(["evaluate", "content", "screenshot"].includes(methodName)
+                    ? `browser.${methodName}`
+                    : `browser.page.${methodName}`, async () => {
                     const startedAt = Date.now();
-                    const result = await Reflect.apply(value, pageTarget, args);
+                    let result;
+                    try {
+                        result = await Reflect.apply(value, pageTarget, args);
+                    }
+                    catch (error) {
+                        throw sanitizeRequestError(error, diagnostics);
+                    }
                     elapsedMs = Date.now() - startedAt;
                     return result;
                 }, {
-                    onSuccess: () => getBrowserPageAttributes(methodName, args, elapsedMs),
-                    onError: (error) => getBrowserPageAttributes(methodName, args, undefined, error),
+                    onSuccess: () => ({
+                        ...getBrowserPageAttributes(methodName, args, elapsedMs),
+                        ...(diagnostics.traceUrl ? { url: diagnostics.traceUrl } : {}),
+                    }),
+                    onError: (error) => ({
+                        ...getBrowserPageAttributes(methodName, args, undefined, error),
+                        ...(diagnostics.traceUrl ? { url: diagnostics.traceUrl } : {}),
+                    }),
                 });
             };
             wrappedMethods.set(property, wrapped);
@@ -418,10 +453,14 @@ function wrapStealthSession(session, trace) {
     });
 }
 function wrapNamespace(namespace, target, trace, shouldInstrument) {
-    const recorder = getTraceRecorder(trace);
-    if (!recorder) {
+    const baseRecorder = getTraceRecorder(trace);
+    if (!baseRecorder)
         return target;
-    }
+    const recorder = namespace === "ocr" || namespace === "stt"
+        ? {
+            runSpan: (name, fn, options) => runCapabilitySpan(target, () => baseRecorder.runSpan(name, fn, options)),
+        }
+        : baseRecorder;
     const wrappedMethods = new Map();
     const resolverMetadata = namespace === "resolver" ? { target, traceRecorder: recorder } : undefined;
     return new Proxy(target, {
@@ -488,6 +527,30 @@ function wrapNamespace(namespace, target, trace, shouldInstrument) {
                 wrappedMethods.set(property, wrapped);
                 return wrapped;
             }
+            if (namespace === "browser" && property === "rawPage") {
+                if (wrappedMethods.has(property))
+                    return wrappedMethods.get(property);
+                const wrapped = (...args) => recorder.runSpan("browser.rawPage", async () => {
+                    const page = await Reflect.apply(value, namespaceTarget, args);
+                    return wrapPage(page, trace);
+                });
+                wrappedMethods.set(property, wrapped);
+                return wrapped;
+            }
+            if (namespace === "browser" && property === "withIsolatedContext") {
+                if (wrappedMethods.has(property))
+                    return wrappedMethods.get(property);
+                const wrapped = (handler, ...args) => recorder.runSpan("browser.withIsolatedContext", async () => {
+                    if (typeof handler !== "function")
+                        return Reflect.apply(value, namespaceTarget, [handler, ...args]);
+                    return Reflect.apply(value, namespaceTarget, [
+                        (page) => Reflect.apply(handler, undefined, [wrapPage(page, trace)]),
+                        ...args,
+                    ]);
+                });
+                wrappedMethods.set(property, wrapped);
+                return wrapped;
+            }
             if (wrappedMethods.has(property)) {
                 return wrappedMethods.get(property);
             }
@@ -495,14 +558,28 @@ function wrapNamespace(namespace, target, trace, shouldInstrument) {
             if (namespace === "browser") {
                 const wrapped = (...args) => {
                     let elapsedMs = 0;
+                    const diagnostics = snapshotRequestDiagnostics("browser", methodName, args);
+                    registerDiagnosticSensitiveValues(trace, diagnostics.sensitiveValues);
                     return recorder.runSpan(`browser.${methodName}`, async () => {
                         const startedAt = Date.now();
-                        const result = await Reflect.apply(value, namespaceTarget, args);
+                        let result;
+                        try {
+                            result = await Reflect.apply(value, namespaceTarget, args);
+                        }
+                        catch (error) {
+                            throw sanitizeRequestError(error, diagnostics);
+                        }
                         elapsedMs = Date.now() - startedAt;
                         return result;
                     }, {
-                        onSuccess: () => getBrowserPageAttributes(methodName, args, elapsedMs),
-                        onError: (error) => getBrowserPageAttributes(methodName, args, undefined, error),
+                        onSuccess: () => ({
+                            ...getBrowserPageAttributes(methodName, args, elapsedMs),
+                            ...(diagnostics.traceUrl ? { url: diagnostics.traceUrl } : {}),
+                        }),
+                        onError: (error) => ({
+                            ...getBrowserPageAttributes(methodName, args, undefined, error),
+                            ...(diagnostics.traceUrl ? { url: diagnostics.traceUrl } : {}),
+                        }),
                     });
                 };
                 wrappedMethods.set(property, wrapped);
@@ -601,7 +678,9 @@ export function wrapWithInstrumentation(ctx, options = {}) {
                 property === "browser" ||
                 property === "session" ||
                 property === "state" ||
-                property === "resolver") {
+                property === "resolver" ||
+                property === "ocr" ||
+                property === "stt") {
                 const namespace = property;
                 if (wrappedTargets.has(namespace)) {
                     return wrappedTargets.get(namespace);

package/dist/runtime/ocr-telemetry.d.ts

@@ -0,0 +1,82 @@
+import type { OcrContext } from "../types.js";
+import { type ClosedEnum, type SpanIndex, type TelemetryContributor } from "./request-telemetry.js";
+export type OcrTelemetryBackend = "cloudflare-workers-ai" | "openai-compatible" | "custom" | "unavailable";
+export type OcrTelemetryEngine = "workers-ai" | "openai-compatible" | "custom";
+export type OcrTelemetryErrorCode = "OCR_UNAVAILABLE" | "UNSUPPORTED_OCR_BACKEND" | "OCR_UPSTREAM_FAILED" | "OCR_INCOMPLETE_RESPONSE" | "transport_network_error" | "transport_timeout" | "other";
+export type OcrTelemetryModel = "gemma-4-26b-a4b-it" | "glm-ocr" | "moondream3.1-9B-A2B" | "kimi-k2.7-code";
+export type OcrTelemetryFinishReason = "stop" | "length" | "content_filter" | "tool_calls" | "function_call" | "error" | "unknown";
+export type OcrTelemetryEvent = {
+    backend: OcrTelemetryBackend;
+    engine: OcrTelemetryEngine;
+    model?: string;
+    ms: number;
+    status?: number;
+    bytesIn?: number;
+    bytesOut?: number;
+    candidates?: number;
+    warnings?: number;
+    errorCode?: OcrTelemetryErrorCode;
+    diagnostics?: string;
+    finishReason?: OcrTelemetryFinishReason;
+};
+export interface OcrTelemetrySink {
+    record(event: OcrTelemetryEvent): void;
+    markTelemetryFailed?(): void;
+}
+export type OcrTelemetryLogPayload = {
+    telemetryFailed?: true;
+    diagnostics?: string[];
+    backend: OcrTelemetryBackend;
+    engine: OcrTelemetryEngine;
+    model?: string;
+    ms: number;
+    status?: number;
+    bytesIn: number;
+    bytesOut: number;
+    candidates: number;
+    warnings: number;
+    lastErrorCode?: OcrTelemetryErrorCode;
+    finishReason?: OcrTelemetryFinishReason;
+    samples?: Array<Omit<OcrTelemetryEvent, "backend" | "engine" | "model" | "diagnostics">>;
+    samplesDropped?: number;
+};
+export type OcrTelemetryHeaderPayload = {
+    backend: ClosedEnum<OcrTelemetryBackend>;
+    engine: ClosedEnum<OcrTelemetryEngine>;
+    model?: ClosedEnum<OcrTelemetryModel>;
+    ms: number;
+    status?: number;
+    bytesIn: number;
+    bytesOut: number;
+    candidates: number;
+    warnings: number;
+    lastErrorCode?: ClosedEnum<OcrTelemetryErrorCode>;
+    finishReason?: ClosedEnum<OcrTelemetryFinishReason>;
+    samples?: Array<{
+        ms: number;
+        status?: number;
+        bytesIn?: number;
+        bytesOut?: number;
+        candidates?: number;
+        warnings?: number;
+        errorCode?: ClosedEnum<OcrTelemetryErrorCode>;
+        finishReason?: ClosedEnum<OcrTelemetryFinishReason>;
+    }>;
+    samplesDropped?: number;
+};
+export declare class OcrTelemetryCollector implements OcrTelemetrySink, TelemetryContributor<OcrTelemetryLogPayload, OcrTelemetryHeaderPayload> {
+    #private;
+    readonly key: "ocr";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    markTelemetryFailed(): void;
+    record(event: OcrTelemetryEvent): void;
+    toLogPayload(_spans: SpanIndex): OcrTelemetryLogPayload | undefined;
+    toHeaderPayload(log: OcrTelemetryLogPayload): OcrTelemetryHeaderPayload;
+}
+export declare function bindOcrTelemetry(context: OcrContext, sink: OcrTelemetrySink, options?: {
+    backend?: OcrTelemetryBackend;
+    engine?: OcrTelemetryEngine;
+    model?: string;
+}): OcrContext;

package/dist/runtime/ocr-telemetry.js

@@ -0,0 +1,192 @@
+import { add, capabilityErrorText, capabilityFacts, capabilityMetadata, capabilityText, inputBytes, integer, observeCapability, registerCapabilityInput, } from "./capability-telemetry.js";
+import { closedEnum, } from "./request-telemetry.js";
+const ERROR_CODES = new Set([
+    "OCR_UNAVAILABLE",
+    "UNSUPPORTED_OCR_BACKEND",
+    "OCR_UPSTREAM_FAILED",
+    "OCR_INCOMPLETE_RESPONSE",
+    "transport_network_error",
+    "transport_timeout",
+    "other",
+]);
+const MODELS = new Map([
+    ["@cf/google/gemma-4-26b-a4b-it", "gemma-4-26b-a4b-it"],
+    ["zai-org/GLM-OCR", "glm-ocr"],
+    ["@cf/moondream/moondream3.1-9B-A2B", "moondream3.1-9B-A2B"],
+    ["@cf/moonshotai/kimi-k2.7-code", "kimi-k2.7-code"],
+]);
+function errorCode(error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    return typeof code === "string" && ERROR_CODES.has(code)
+        ? code
+        : "other";
+}
+function finishReason(value, failed) {
+    switch (value) {
+        case "stop":
+        case "length":
+        case "content_filter":
+        case "tool_calls":
+        case "function_call":
+            return value;
+        default:
+            return value === undefined ? (failed ? "error" : "stop") : "unknown";
+    }
+}
+export class OcrTelemetryCollector {
+    key = "ocr";
+    #redact;
+    #samples = [];
+    #summary;
+    #diagnostics = [];
+    #dropped = 0;
+    #failed = false;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+    }
+    markTelemetryFailed() {
+        this.#failed = true;
+        this.#summary ??= {
+            backend: "custom",
+            engine: "custom",
+            ms: 0,
+            bytesIn: 0,
+            bytesOut: 0,
+            candidates: 0,
+            warnings: 0,
+        };
+    }
+    record(event) {
+        const sample = {
+            ms: integer(event.ms),
+            ...(event.status === undefined ? {} : { status: integer(event.status) }),
+            ...(event.bytesIn === undefined ? {} : { bytesIn: integer(event.bytesIn) }),
+            ...(event.bytesOut === undefined ? {} : { bytesOut: integer(event.bytesOut) }),
+            ...(event.candidates === undefined ? {} : { candidates: integer(event.candidates) }),
+            ...(event.warnings === undefined ? {} : { warnings: integer(event.warnings) }),
+            ...(event.errorCode ? { errorCode: event.errorCode } : {}),
+            ...(event.finishReason ? { finishReason: event.finishReason } : {}),
+            ...(event.diagnostics === undefined
+                ? {}
+                : { diagnostics: capabilityText(event.diagnostics, this.#redact, true) }),
+        };
+        const prior = this.#summary;
+        this.#summary = {
+            backend: event.backend,
+            engine: event.engine,
+            ...(event.model === undefined ? {} : { model: capabilityText(event.model, this.#redact) }),
+            ms: add(prior?.ms ?? 0, sample.ms),
+            ...(sample.status === undefined ? {} : { status: sample.status }),
+            bytesIn: add(prior?.bytesIn ?? 0, sample.bytesIn ?? 0),
+            bytesOut: add(prior?.bytesOut ?? 0, sample.bytesOut ?? 0),
+            candidates: add(prior?.candidates ?? 0, sample.candidates ?? 0),
+            warnings: add(prior?.warnings ?? 0, sample.warnings ?? 0),
+            ...(event.errorCode ? { lastErrorCode: event.errorCode } : {}),
+            ...(event.finishReason ? { finishReason: event.finishReason } : {}),
+        };
+        if (this.#samples.length < 24) {
+            const { diagnostics, ...closedSample } = sample;
+            this.#samples.push(closedSample);
+            if (diagnostics !== undefined)
+                this.#diagnostics.push(diagnostics);
+        }
+        else
+            this.#dropped = add(this.#dropped, 1);
+    }
+    toLogPayload(_spans) {
+        if (!this.#summary)
+            return undefined;
+        return {
+            ...this.#summary,
+            ...(this.#diagnostics.length ? { diagnostics: [...this.#diagnostics] } : {}),
+            ...(this.#failed ? { telemetryFailed: true } : {}),
+            samples: this.#samples.map((s) => ({ ...s })),
+            ...(this.#dropped ? { samplesDropped: this.#dropped } : {}),
+        };
+    }
+    toHeaderPayload(log) {
+        return {
+            backend: closedEnum(log.backend),
+            engine: closedEnum(log.engine),
+            ...(log.model && MODELS.has(log.model) ? { model: closedEnum(MODELS.get(log.model)) } : {}),
+            ms: log.ms,
+            ...(log.status === undefined ? {} : { status: log.status }),
+            bytesIn: log.bytesIn,
+            bytesOut: log.bytesOut,
+            candidates: log.candidates,
+            warnings: log.warnings,
+            ...(log.lastErrorCode ? { lastErrorCode: closedEnum(log.lastErrorCode) } : {}),
+            ...(log.finishReason ? { finishReason: closedEnum(log.finishReason) } : {}),
+            ...(log.samples
+                ? {
+                    samples: log.samples.map((s) => ({
+                        ms: s.ms,
+                        ...(s.status === undefined ? {} : { status: s.status }),
+                        ...(s.bytesIn === undefined ? {} : { bytesIn: s.bytesIn }),
+                        ...(s.bytesOut === undefined ? {} : { bytesOut: s.bytesOut }),
+                        ...(s.candidates === undefined ? {} : { candidates: s.candidates }),
+                        ...(s.warnings === undefined ? {} : { warnings: s.warnings }),
+                        ...(s.errorCode ? { errorCode: closedEnum(s.errorCode) } : {}),
+                        ...(s.finishReason ? { finishReason: closedEnum(s.finishReason) } : {}),
+                    })),
+                }
+                : {}),
+            ...(log.samplesDropped ? { samplesDropped: log.samplesDropped } : {}),
+        };
+    }
+}
+export function bindOcrTelemetry(context, sink, options = {}) {
+    const metadata = capabilityMetadata(context);
+    const backend = options.backend ?? metadata?.backend ?? "custom";
+    const engine = options.engine ?? metadata?.engine ?? "custom";
+    const model = options.model ?? metadata?.model;
+    async function run(input, operation) {
+        const started = performance.now();
+        const facts = {};
+        observeCapability(sink, () => registerCapabilityInput(input));
+        let result;
+        try {
+            result = await capabilityFacts.run(facts, operation);
+        }
+        catch (error) {
+            observeCapability(sink, () => {
+                const status = error &&
+                    typeof error === "object" &&
+                    "status" in error &&
+                    typeof error.status === "number"
+                    ? error.status
+                    : undefined;
+                return sink.record({
+                    backend,
+                    engine,
+                    model,
+                    ms: performance.now() - started,
+                    status: facts.status ?? status,
+                    bytesIn: inputBytes(input),
+                    errorCode: errorCode(error),
+                    finishReason: finishReason(facts.finishReason, true),
+                    diagnostics: `${capabilityErrorText(error)} ${facts.diagnostics ?? ""}`,
+                });
+            });
+            throw error;
+        }
+        observeCapability(sink, () => sink.record({
+            backend,
+            engine,
+            model: result.model,
+            ms: performance.now() - started,
+            status: facts.status,
+            bytesIn: inputBytes(input),
+            bytesOut: Buffer.byteLength(result.text),
+            candidates: result.candidates?.length ?? 0,
+            finishReason: finishReason(facts.finishReason, false),
+            warnings: result.warnings?.length ?? 0,
+        }));
+        return result;
+    }
+    return {
+        ...context,
+        recognize: (request) => run(request.image, () => context.recognize(request)),
+        extractCaptchaText: (image, opts) => run(image, () => context.extractCaptchaText(image, opts)),
+    };
+}

package/dist/runtime/ocr.js

@@ -1,5 +1,7 @@
-import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { ProviderError, TransportError } from "../errors.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";
 export { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
@@ -39,14 +41,14 @@ function createErrorOcrClient(options) {
             fix: options.fix,
         });
     };
-    return {
+    return tagCapability({
         async recognize() {
             return unavailable();
         },
         async extractCaptchaText() {
             return unavailable();
         },
-    };
+    }, { backend: "unavailable", engine: "custom" });
 }
 export function createUnsupportedOcrClient(reason) {
     return createErrorOcrClient({
@@ -179,6 +181,8 @@ function responseContent(payload, cloudflare, model) {
     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);
     }
@@ -233,8 +237,12 @@ function moondreamSseContent(body, model) {
             terminalFinishReason = chunk.finish_reason;
         }
     }
-    if (finalAnswer)
+    if (finalAnswer) {
+        captureCapability({ finishReason: "stop" });
         return finalAnswer;
+    }
+    if (terminalFinishReason)
+        captureCapability({ finishReason: terminalFinishReason });
     if (terminalFinishReason)
         throw incompleteResponseError(model, terminalFinishReason);
     if (firstDecodingFailure)
@@ -285,7 +293,10 @@ function createOcrClient(model, recognize) {
 export function createCloudflareWorkersAiOcrClient(options) {
     const model = options.model ?? DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL;
     const runFetch = options.fetch ?? fetch;
-    return createOcrClient(model, async (request) => {
+    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 {
             let response;
@@ -305,7 +316,10 @@ export function createCloudflareWorkersAiOcrClient(options) {
             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,
@@ -325,12 +339,17 @@ export function createCloudflareWorkersAiOcrClient(options) {
         finally {
             timeout.clear();
         }
-    });
+    }), { backend: "cloudflare-workers-ai", engine: "workers-ai", model });
 }
 export function createOpenAiCompatibleOcrClient(options) {
     const model = options.model;
     const runFetch = options.fetch ?? fetch;
-    return createOcrClient(model, async (request) => {
+    return tagCapability(createOcrClient(model, async (request) => {
+        registerCapabilityInput(request.image);
+        if (options.apiKey) {
+            registerDiagnosticValue(options.apiKey);
+            registerDiagnosticValue(`Bearer ${options.apiKey}`);
+        }
         const headers = { "Content-Type": "application/json" };
         if (options.apiKey)
             headers.Authorization = `Bearer ${options.apiKey}`;
@@ -348,7 +367,10 @@ export function createOpenAiCompatibleOcrClient(options) {
             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,
@@ -366,7 +388,7 @@ export function createOpenAiCompatibleOcrClient(options) {
         finally {
             timeout.clear();
         }
-    });
+    }), { backend: "openai-compatible", engine: "openai-compatible", model });
 }
 function cleanCaptchaText(text) {
     const afterColon = text.slice(text.lastIndexOf(":") + 1).trim();

package/dist/runtime/request-telemetry.d.ts

@@ -45,6 +45,8 @@ export type RequestTelemetryLogPayload = {
     proxy?: ProxyTelemetryLogPayload;
     resolver?: ResolverTelemetryLogPayload;
 } & Partial<Record<Exclude<TelemetryKey, "proxy" | "resolver">, object>>;
+/** @internal */
+export declare const HEADER_PRIORITY: readonly ["proxy", "resolver", "native", "http", "stealth", "browser", "ocr", "stt", "cache", "state"];
 /**
  * Bounded structural defence in depth against casts and accidental free text.
  * Closed-enum brands are erased at runtime; the type-level guard is the contract,

package/dist/runtime/request-telemetry.js

@@ -13,7 +13,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/dist/runtime/resolver-runtime-options.d.ts

@@ -0,0 +1,14 @@
+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 declare function resolveNativeProxyPolicy(provider: ProviderDefinition): ProviderProxyPolicy | 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 declare 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;

package/dist/runtime/resolver-runtime-options.js

@@ -0,0 +1,33 @@
+/** Normalize the `proxy` declaration shorthand (`true`/`false`) into the policy object the resolver chain consumes. */
+export function resolveNativeProxyPolicy(provider) {
+    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, cache, identityScope, proxyPolicy, proxyClientOptions, stealthProfile, telemetry, browserTelemetry) {
+    return {
+        allowedHosts: provider.allowedHosts,
+        cache,
+        telemetry,
+        browserTelemetry,
+        ...(identityScope === undefined ? {} : { identityScope }),
+        ...(proxyPolicy
+            ? {
+                proxyIntent: {
+                    mode: proxyPolicy.mode,
+                    ...proxyClientOptions,
+                    ...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
+                },
+            }
+            : {}),
+    };
+}

package/dist/runtime/resolver-shared.d.ts

@@ -1,13 +1,14 @@
 import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
 import type { TraceRecorder } from "./trace.js";
 import type { ResolverTelemetrySink } from "./resolver-telemetry.js";
-type ResolverTelemetryBinding = (sink: ResolverTelemetrySink) => ResolverContext;
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
+type ResolverTelemetryBinding = (sink: ResolverTelemetrySink, browserSink?: BrowserTelemetrySink) => ResolverContext;
 /** Internal contract: reconstruct a chain with a new request sink, without mutating the host chain. */
 export declare function registerResolverTelemetryBinding(resolver: ResolverContext, bind: ResolverTelemetryBinding): void;
 /** Preserve reconstruction across SDK wrappers without capturing their current request sink. */
 export declare function inheritResolverTelemetryBinding(resolver: ResolverContext, wrapper: ResolverContext): void;
 /** SDK chains expose each vendor invocation; opaque host resolvers expose one custom invocation. */
-export declare function bindResolverTelemetry(resolver: ResolverContext, sink: ResolverTelemetrySink | undefined): ResolverContext;
+export declare function bindResolverTelemetry(resolver: ResolverContext, sink: ResolverTelemetrySink | undefined, browserSink?: BrowserTelemetrySink): ResolverContext;
 export declare const RESOLVER_INSTRUMENTATION_METADATA: unique symbol;
 /**
  * Internal solve surface. The instrumentation layer threads its recorder as a

package/dist/runtime/resolver-shared.js

@@ -11,15 +11,15 @@ export function inheritResolverTelemetryBinding(resolver, wrapper) {
         telemetryBindings.set(wrapper, bind);
 }
 /** SDK chains expose each vendor invocation; opaque host resolvers expose one custom invocation. */
-export function bindResolverTelemetry(resolver, sink) {
+export function bindResolverTelemetry(resolver, sink, browserSink) {
     if (!sink)
         return resolver;
     const metadata = resolver[RESOLVER_INSTRUMENTATION_METADATA];
     if (metadata)
-        return bindResolverTelemetry(metadata.target, sink);
+        return bindResolverTelemetry(metadata.target, sink, browserSink);
     const bind = telemetryBindings.get(resolver);
     if (bind)
-        return bind(sink);
+        return bind(sink, browserSink);
     const wrapper = {
         async solve(challenge, signal, recorder) {
             const startedAt = Date.now();
@@ -54,7 +54,7 @@ export function bindResolverTelemetry(resolver, sink) {
     return wrapper;
 }
 function createOpaqueResolverTelemetryBinding(resolver) {
-    return (sink) => bindResolverTelemetry(resolver, sink);
+    return (sink, browserSink) => bindResolverTelemetry(resolver, sink, browserSink);
 }
 export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for("@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata");
 export function createUnsupportedResolverClient(reason) {