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

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

@@ -0,0 +1,77 @@
+import type { SttContext } from "../types.js";
+import { type ClosedEnum, type SpanIndex, type TelemetryContributor } from "./request-telemetry.js";
+export type SttTelemetryBackend = "cloudflare-workers-ai" | "custom" | "unavailable";
+export type SttTelemetryEngine = "workers-ai" | "custom";
+export type SttTelemetryErrorCode = "STT_UNAVAILABLE" | "UNSUPPORTED_STT_BACKEND" | "STT_UPSTREAM_FAILED" | "STT_AUDIO_TOO_LARGE" | "UNSUPPORTED_STT_OPTION" | "INVALID_STT_AUDIO" | "INVALID_STT_VERIFICATION_CODE_OPTIONS" | "NO_CODE_FOUND" | "AMBIGUOUS_CODE" | "transport_network_error" | "transport_timeout" | "other";
+export type SttTelemetryModel = "whisper-large-v3-turbo";
+export type SttTelemetryEvent = {
+    backend: SttTelemetryBackend;
+    engine: SttTelemetryEngine;
+    model?: string;
+    ms: number;
+    status?: number;
+    audioBytes?: number;
+    durationMs?: number;
+    usage?: number;
+    warnings?: number;
+    errorCode?: SttTelemetryErrorCode;
+    diagnostics?: string;
+};
+export interface SttTelemetrySink {
+    record(event: SttTelemetryEvent): void;
+    markTelemetryFailed?(): void;
+}
+export type SttTelemetryLogPayload = {
+    telemetryFailed?: true;
+    diagnostics?: string[];
+    backend: SttTelemetryBackend;
+    engine: SttTelemetryEngine;
+    model?: string;
+    ms: number;
+    status?: number;
+    audioBytes: number;
+    durationMs: number;
+    usage: number;
+    warnings: number;
+    lastErrorCode?: SttTelemetryErrorCode;
+    samples?: Array<Omit<SttTelemetryEvent, "backend" | "engine" | "model" | "diagnostics">>;
+    samplesDropped?: number;
+};
+export type SttTelemetryHeaderPayload = {
+    backend: ClosedEnum<SttTelemetryBackend>;
+    engine: ClosedEnum<SttTelemetryEngine>;
+    model?: ClosedEnum<SttTelemetryModel>;
+    ms: number;
+    status?: number;
+    audioBytes: number;
+    durationMs: number;
+    usage: number;
+    warnings: number;
+    lastErrorCode?: ClosedEnum<SttTelemetryErrorCode>;
+    samples?: Array<{
+        ms: number;
+        status?: number;
+        audioBytes?: number;
+        durationMs?: number;
+        usage?: number;
+        warnings?: number;
+        errorCode?: ClosedEnum<SttTelemetryErrorCode>;
+    }>;
+    samplesDropped?: number;
+};
+export declare class SttTelemetryCollector implements SttTelemetrySink, TelemetryContributor<SttTelemetryLogPayload, SttTelemetryHeaderPayload> {
+    #private;
+    readonly key: "stt";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    markTelemetryFailed(): void;
+    record(event: SttTelemetryEvent): void;
+    toLogPayload(_spans: SpanIndex): SttTelemetryLogPayload | undefined;
+    toHeaderPayload(log: SttTelemetryLogPayload): SttTelemetryHeaderPayload;
+}
+export declare function bindSttTelemetry(context: SttContext, sink: SttTelemetrySink, options?: {
+    backend?: SttTelemetryBackend;
+    engine?: SttTelemetryEngine;
+    model?: string;
+}): SttContext;

package/dist/runtime/stt-telemetry.js

@@ -0,0 +1,176 @@
+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([
+    "STT_UNAVAILABLE",
+    "UNSUPPORTED_STT_BACKEND",
+    "STT_UPSTREAM_FAILED",
+    "STT_AUDIO_TOO_LARGE",
+    "UNSUPPORTED_STT_OPTION",
+    "INVALID_STT_AUDIO",
+    "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+    "NO_CODE_FOUND",
+    "AMBIGUOUS_CODE",
+    "transport_network_error",
+    "transport_timeout",
+    "other",
+]);
+const MODELS = new Map([
+    ["@cf/openai/whisper-large-v3-turbo", "whisper-large-v3-turbo"],
+]);
+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";
+}
+export class SttTelemetryCollector {
+    key = "stt";
+    #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,
+            audioBytes: 0,
+            durationMs: 0,
+            usage: 0,
+            warnings: 0,
+        };
+    }
+    record(event) {
+        const sample = {
+            ms: integer(event.ms),
+            ...(event.status === undefined ? {} : { status: integer(event.status) }),
+            ...(event.audioBytes === undefined ? {} : { audioBytes: integer(event.audioBytes) }),
+            ...(event.durationMs === undefined ? {} : { durationMs: integer(event.durationMs) }),
+            ...(event.usage === undefined ? {} : { usage: integer(event.usage) }),
+            ...(event.warnings === undefined ? {} : { warnings: integer(event.warnings) }),
+            ...(event.errorCode ? { errorCode: event.errorCode } : {}),
+            ...(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 }),
+            audioBytes: add(prior?.audioBytes ?? 0, sample.audioBytes ?? 0),
+            durationMs: add(prior?.durationMs ?? 0, sample.durationMs ?? 0),
+            usage: add(prior?.usage ?? 0, sample.usage ?? 0),
+            warnings: add(prior?.warnings ?? 0, sample.warnings ?? 0),
+            ...(event.errorCode ? { lastErrorCode: event.errorCode } : {}),
+        };
+        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 }),
+            audioBytes: log.audioBytes,
+            durationMs: log.durationMs,
+            usage: log.usage,
+            warnings: log.warnings,
+            ...(log.lastErrorCode ? { lastErrorCode: closedEnum(log.lastErrorCode) } : {}),
+            ...(log.samples
+                ? {
+                    samples: log.samples.map((s) => ({
+                        ms: s.ms,
+                        ...(s.status === undefined ? {} : { status: s.status }),
+                        ...(s.audioBytes === undefined ? {} : { audioBytes: s.audioBytes }),
+                        ...(s.durationMs === undefined ? {} : { durationMs: s.durationMs }),
+                        ...(s.usage === undefined ? {} : { usage: s.usage }),
+                        ...(s.warnings === undefined ? {} : { warnings: s.warnings }),
+                        ...(s.errorCode ? { errorCode: closedEnum(s.errorCode) } : {}),
+                    })),
+                }
+                : {}),
+            ...(log.samplesDropped ? { samplesDropped: log.samplesDropped } : {}),
+        };
+    }
+}
+export function bindSttTelemetry(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,
+                    audioBytes: inputBytes(input),
+                    errorCode: errorCode(error),
+                    diagnostics: `${capabilityErrorText(error)} ${facts.diagnostics ?? ""}`,
+                });
+            });
+            throw error;
+        }
+        observeCapability(sink, () => sink.record({
+            backend,
+            engine,
+            model: model,
+            ms: performance.now() - started,
+            status: facts.status,
+            audioBytes: result.usage?.audioBytes ?? inputBytes(input),
+            durationMs: result.durationMs,
+            usage: result.usage?.audioDurationMs,
+            warnings: result.warnings?.length ?? 0,
+        }));
+        return result;
+    }
+    return {
+        ...context,
+        transcribe: (request) => run(request.audio, () => context.transcribe(request)),
+        extractVerificationCode: (text, opts) => context.extractVerificationCode(text, opts),
+    };
+}

package/dist/runtime/stt.js

@@ -1,5 +1,7 @@
-import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { ProviderError, TransportError, ValidationError } 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 { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
 export const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
 export const APIFUSE__STT__MODEL_ENV = "APIFUSE__STT__MODEL";
@@ -15,7 +17,7 @@ function providerError(message, options) {
     return new ProviderError(message, options);
 }
 function createErrorSttClient(options) {
-    return {
+    return tagCapability({
         async transcribe() {
             throw providerError(options.message, {
                 code: options.code,
@@ -23,7 +25,7 @@ function createErrorSttClient(options) {
             });
         },
         extractVerificationCode,
-    };
+    }, { backend: "unavailable", engine: "custom" });
 }
 export function createUnsupportedSttClient(reason) {
     return createErrorSttClient({
@@ -209,8 +211,11 @@ function toSttTranscript(payload, audioBytes) {
 export function createCloudflareWorkersAiSttClient(options) {
     const model = options.model ?? DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL;
     const runFetch = options.fetch ?? fetch;
-    return {
+    return tagCapability({
         async transcribe(request) {
+            registerCapabilityInput(request.audio);
+            registerDiagnosticValue(options.apiToken);
+            registerDiagnosticValue(`Bearer ${options.apiToken}`);
             const warnings = [];
             if (request.initialPrompt && effectivePromptPolicy(request) !== "custom-hint") {
                 const warning = warnOrThrowUnsupportedOption(request, "initialPrompt is honored only when promptPolicy is custom-hint");
@@ -235,16 +240,20 @@ export function createCloudflareWorkersAiSttClient(options) {
                 catch (error) {
                     throw toSttTransportError(error);
                 }
-                const payload = await response.json().catch(() => undefined);
+                captureCapability({ status: response.status });
                 if (!response.ok) {
+                    const echoed = await readCapabilityErrorBody(response, timeout.controller.signal);
+                    captureCapability({ diagnostics: echoed });
                     throw new TransportError("STT upstream request failed", {
                         code: "STT_UPSTREAM_FAILED",
                         status: response.status,
                         upstreamStatus: response.status,
                     });
                 }
+                const payload = await response.json().catch(() => undefined);
                 const envelope = unknownRecord(payload);
                 if (envelope?.success === false) {
+                    captureCapability({ diagnostics: JSON.stringify(payload) });
                     throw new TransportError("STT upstream returned an error", {
                         code: "STT_UPSTREAM_FAILED",
                         status: 502,
@@ -270,7 +279,7 @@ export function createCloudflareWorkersAiSttClient(options) {
             }
         },
         extractVerificationCode,
-    };
+    }, { backend: "cloudflare-workers-ai", engine: "workers-ai", model });
 }
 const EN_DIGITS = {
     zero: "0",

package/dist/server/error-stack-frames.d.ts

@@ -0,0 +1,35 @@
+import { type DiagnosticRedactor } from "../runtime/diagnostic-redactor.js";
+/**
+ * Bounded, whitelist-shaped stack frames for masked (>=500) provider failures.
+ *
+ * `sanitizeDiagnosticText` is a blacklist scrubber for free text: a V8/Bun
+ * frame such as `at inner (/srv/app/probe.ts:3:30)` comes out as
+ * `at inner ([REDACTED])`, and even a bare `serve-implementation.ts:2039:12`
+ * trips the opaque-token heuristics. Stack frames therefore never go through
+ * it. Instead each frame is parsed against a strict grammar and re-emitted
+ * from its parts only: an optional `async`/`new` marker, the function name
+ * (identifier characters only), the file *basename* (never a filesystem
+ * directory, URL, or drive letter) and the numeric line:column. The sole
+ * exception is an engine-internal location (`native`, or a `node:` module id
+ * of identifier-shaped segments), which is kept verbatim because it names no
+ * deployment path. Frames that do not fit the grammar (eval frames, frames
+ * without a location, oversized lines) are dropped rather than passed
+ * through.
+ */
+export declare const MAX_PROVIDER_ERROR_STACK_FRAMES = 5;
+/** Parses one `at ...` line into `[async |new ][fn ](basename:line:col)`, or undefined. */
+export declare function parseProviderErrorStackFrame(line: string): string | undefined;
+/**
+ * Up to {@link MAX_PROVIDER_ERROR_STACK_FRAMES} whitelist-shaped frames from
+ * `error.stack`, or undefined when nothing parses. For an engine-formatted
+ * stack the header (which embeds the current `message`) is located and
+ * stripped first, so a provider-controlled *message* containing newlines
+ * cannot inject frame-shaped text (no header match, no frames). A provider
+ * that overwrites `stack` or `name` outright can still put grammar-shaped
+ * frames in the record: the field is a diagnostic hint, not an attested
+ * location, and the whitelist plus the redactor bound what it can carry.
+ * Each emitted frame still passes
+ * through the request redactor so a registered secret that happens to appear
+ * in a function or file name is masked (fail-closed to `[REDACTION_FAILED]`).
+ */
+export declare function providerErrorStackFrames(error: unknown, redact?: DiagnosticRedactor): string[] | undefined;

package/dist/server/error-stack-frames.js

@@ -0,0 +1,219 @@
+import { redactDiagnosticText } from "../runtime/diagnostic-redactor.js";
+/**
+ * Bounded, whitelist-shaped stack frames for masked (>=500) provider failures.
+ *
+ * `sanitizeDiagnosticText` is a blacklist scrubber for free text: a V8/Bun
+ * frame such as `at inner (/srv/app/probe.ts:3:30)` comes out as
+ * `at inner ([REDACTED])`, and even a bare `serve-implementation.ts:2039:12`
+ * trips the opaque-token heuristics. Stack frames therefore never go through
+ * it. Instead each frame is parsed against a strict grammar and re-emitted
+ * from its parts only: an optional `async`/`new` marker, the function name
+ * (identifier characters only), the file *basename* (never a filesystem
+ * directory, URL, or drive letter) and the numeric line:column. The sole
+ * exception is an engine-internal location (`native`, or a `node:` module id
+ * of identifier-shaped segments), which is kept verbatim because it names no
+ * deployment path. Frames that do not fit the grammar (eval frames, frames
+ * without a location, oversized lines) are dropped rather than passed
+ * through.
+ */
+export const MAX_PROVIDER_ERROR_STACK_FRAMES = 5;
+const MAX_STACK_SCAN_CHARS = 16 * 1024;
+const MAX_STACK_SCAN_LINES = 64;
+const MAX_STACK_LINE_CHARS = 1024;
+const FRAME_LINE = /^\s+at\s+(\S.*)$/;
+const FRAME_MODIFIER = /^(async|new)\s+(.*)$/;
+const FRAME_FUNCTION_NAME = /^[\w$.<>[\] #]{1,80}$/;
+const FRAME_LOCATION = /^(.*):(\d{1,7}):(\d{1,7})$/;
+const MAX_NODE_MODULE_ID_CHARS = 128;
+// Engine-internal module ids only: `node:` plus `/`-separated identifier-shaped
+// segments (`node:async_hooks`, `node:internal/process/task_queues`). Every
+// segment must start with a letter or `_`, so `..` traversal and dotfile
+// segments cannot ride through this branch.
+const FRAME_NODE_MODULE = /^node:[A-Za-z_][\w.-]{0,40}(?:\/[A-Za-z_][\w.-]{0,40}){0,7}$/;
+const FRAME_BASENAME = /^[\w.$-]{1,120}$/;
+// A basename of dots only (`.`, `..`, `...`) names no file.
+const FRAME_BASENAME_HAS_NAME = /[^.]/;
+function parseFunctionName(raw) {
+    let rest = raw.trim();
+    let modifier;
+    const modified = FRAME_MODIFIER.exec(rest);
+    if (modified) {
+        modifier = modified[1];
+        rest = modified[2].trim();
+    }
+    if (rest.length === 0)
+        return { modifier };
+    if (!FRAME_FUNCTION_NAME.test(rest))
+        return undefined;
+    return { modifier, name: rest };
+}
+function parseLocation(raw) {
+    if (/[\s()]/.test(raw))
+        return undefined;
+    const located = FRAME_LOCATION.exec(raw);
+    if (!located)
+        return undefined;
+    const [, path, line, column] = located;
+    let file;
+    if (path === "native" ||
+        (path.length <= MAX_NODE_MODULE_ID_CHARS && FRAME_NODE_MODULE.test(path))) {
+        // Not filesystem paths: engine-internal module ids carry no deployment
+        // information. This is the one branch that keeps a `/`, and the grammar
+        // above bounds it to identifier segments.
+        file = path;
+    }
+    else {
+        const separator = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+        const basename = separator >= 0 ? path.slice(separator + 1) : path;
+        if (!FRAME_BASENAME.test(basename))
+            return undefined;
+        // `.` and `..` pass the basename character class but name no file: they
+        // are the traversal tokens the grammar exists to exclude, so a path such
+        // as `/srv/app/..:1:1` must not be emitted as `..:1:1`.
+        if (!FRAME_BASENAME_HAS_NAME.test(basename))
+            return undefined;
+        file = basename;
+    }
+    return `${file}:${line}:${column}`;
+}
+/** Parses one `at ...` line into `[async |new ][fn ](basename:line:col)`, or undefined. */
+export function parseProviderErrorStackFrame(line) {
+    if (line.length > MAX_STACK_LINE_CHARS)
+        return undefined;
+    const frame = FRAME_LINE.exec(line);
+    if (!frame)
+        return undefined;
+    const rest = frame[1].trimEnd();
+    let functionPart;
+    let locationPart;
+    if (rest.endsWith(")")) {
+        const open = rest.lastIndexOf("(");
+        if (open < 0)
+            return undefined;
+        functionPart = rest.slice(0, open);
+        locationPart = rest.slice(open + 1, -1);
+    }
+    else {
+        // A frame with no parenthesized location still carries its `async`/`new`
+        // modifier inline (`at async file:///app/index.mjs:12:3`, emitted by V8
+        // for an anonymous async frame such as a module's top-level await).
+        // Split it off here: `parseLocation` rejects anything containing
+        // whitespace, so leaving it attached dropped the whole frame.
+        const modified = FRAME_MODIFIER.exec(rest);
+        functionPart = modified ? modified[1] : "";
+        locationPart = modified ? modified[2].trim() : rest;
+    }
+    // Eval frames nest parentheses inside the function part; never pass them through.
+    if (/[()]/.test(functionPart))
+        return undefined;
+    const location = parseLocation(locationPart);
+    if (!location)
+        return undefined;
+    const fn = parseFunctionName(functionPart);
+    if (!fn)
+        return undefined;
+    const prefix = [fn.modifier, fn.name].filter((part) => part !== undefined).join(" ");
+    return prefix.length > 0 ? `${prefix} (${location})` : `(${location})`;
+}
+// V8 (Node >= 21) installs `stack` as a shared native accessor pair on every
+// Error instance; JSC (Bun) installs a data property. Capture the engine's own
+// accessor once so a provider-defined accessor (a different function object) is
+// still rejected while the engine's is trusted. The engine accessor itself can
+// call a process-global `Error.prepareStackTrace` hook, a process-wide trust
+// boundary this module cannot narrow: a provider that installs one already
+// reshapes `stack` for every consumer, and the whitelist grammar below still
+// bounds what the resulting text can carry.
+const NATIVE_STACK_GETTER = Object.getOwnPropertyDescriptor(new Error(), "stack")?.get;
+function readOwnStackString(error) {
+    // Only engine-captured stacks: a thrown plain object is provider-authored text.
+    if (!(error instanceof Error))
+        return undefined;
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(error, "stack");
+        if (descriptor === undefined)
+            return undefined;
+        let stack;
+        if (Object.hasOwn(descriptor, "value")) {
+            stack = descriptor.value;
+        }
+        else if (typeof NATIVE_STACK_GETTER === "function" &&
+            descriptor.get === NATIVE_STACK_GETTER) {
+            stack = Reflect.apply(NATIVE_STACK_GETTER, error, []);
+        }
+        else {
+            // A provider-defined accessor must never run inside the logger.
+            return undefined;
+        }
+        return typeof stack === "string" ? stack : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Header shapes ahead of the frame block: `Name: message` (V8/JSC),
+// `Name [CODE]: message` (node:assert), `Name` (empty message), or the bare
+// message (Playwright rewrites `stack` as message-first). The message itself
+// is matched verbatim, so anything before it must be a short name-like prefix.
+const HEADER_NAME_PREFIX = /^(?:[\w$][\w$ .[\]-]{0,119}: )?$/;
+const HEADER_NAME_ONLY = /^[\w$][\w$ .[\]-]{0,119}$/;
+/**
+ * The frame block that follows the header, or undefined when the header does
+ * not embed the current `message` followed by a newline. Fail closed there: if
+ * `message` was mutated after the stack was formatted, the original message
+ * lines are still in the string and could be parsed as forged frames. (A
+ * mutation that truncates exactly at one of the message's own newlines is
+ * indistinguishable from the string alone; the whitelist grammar and the
+ * redactor still bound what such a line can carry.)
+ */
+function frameBlock(stack, error) {
+    let message;
+    try {
+        message = error.message;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof message !== "string")
+        return undefined;
+    if (message.length === 0) {
+        const newline = stack.indexOf("\n");
+        if (newline < 0 || !HEADER_NAME_ONLY.test(stack.slice(0, newline)))
+            return undefined;
+        return stack.slice(newline + 1);
+    }
+    const at = stack.indexOf(`${message}\n`);
+    if (at < 0 || !HEADER_NAME_PREFIX.test(stack.slice(0, at)))
+        return undefined;
+    return stack.slice(at + message.length + 1);
+}
+/**
+ * Up to {@link MAX_PROVIDER_ERROR_STACK_FRAMES} whitelist-shaped frames from
+ * `error.stack`, or undefined when nothing parses. For an engine-formatted
+ * stack the header (which embeds the current `message`) is located and
+ * stripped first, so a provider-controlled *message* containing newlines
+ * cannot inject frame-shaped text (no header match, no frames). A provider
+ * that overwrites `stack` or `name` outright can still put grammar-shaped
+ * frames in the record: the field is a diagnostic hint, not an attested
+ * location, and the whitelist plus the redactor bound what it can carry.
+ * Each emitted frame still passes
+ * through the request redactor so a registered secret that happens to appear
+ * in a function or file name is masked (fail-closed to `[REDACTION_FAILED]`).
+ */
+export function providerErrorStackFrames(error, redact) {
+    const stack = readOwnStackString(error);
+    if (stack === undefined)
+        return undefined;
+    const body = frameBlock(stack, error);
+    if (body === undefined)
+        return undefined;
+    const frames = [];
+    const lines = body.slice(0, MAX_STACK_SCAN_CHARS).split("\n", MAX_STACK_SCAN_LINES);
+    for (const line of lines) {
+        if (frames.length >= MAX_PROVIDER_ERROR_STACK_FRAMES)
+            break;
+        const frame = parseProviderErrorStackFrame(line);
+        if (frame !== undefined)
+            frames.push(redactDiagnosticText(frame, redact));
+    }
+    return frames.length > 0 ? frames : undefined;
+}

package/dist/server/index.d.ts

@@ -1,9 +1,16 @@
+export type { ProviderLocaleCatalogMap } from "../i18n/catalog.js";
+export type { ProviderLocale, ProviderLocaleCatalog } from "../i18n/keys.js";
 export type { ProxyCacheStatus, ProxyProtocol, ProxyUserAgentSource, ProxyVendorName, SmartproxyAllocatorBodyClass, } from "../config/loader.js";
 export type { ProxyTelemetryHeaderPayload, ProxyHash, ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "../runtime/proxy-telemetry.js";
 export { RequestTelemetry, closedEnum, type ClosedEnum, type GatewayIngestible, type RequestTelemetryLogPayload, type SpanIndex, type TelemetryContributor, type TelemetryKey, type TenantNeutral, } from "../runtime/request-telemetry.js";
+export { OcrTelemetryCollector, bindOcrTelemetry, type OcrTelemetryBackend, type OcrTelemetryEngine, type OcrTelemetryErrorCode, type OcrTelemetryEvent, type OcrTelemetryModel, type OcrTelemetryFinishReason, type OcrTelemetryHeaderPayload, type OcrTelemetryLogPayload, type OcrTelemetrySink, } from "../runtime/ocr-telemetry.js";
 export { ResolverTelemetryCollector, type ResolverAttemptSample, type ResolverCacheReadTelemetryEvent, type ResolverCacheWriteTelemetryEvent, type ResolverFailoverTelemetryEvent, type ResolverIdentityTelemetryEvent, type ResolverOutcomeTelemetryEvent, type ResolverTelemetryAttemptOutcome, type ResolverTelemetryCacheStatus, type ResolverTelemetryCacheWriteReason, type ResolverTelemetryErrorClass, type ResolverTelemetryHeaderPayload, type ResolverTelemetryIdentitySource, type ResolverTelemetryLogPayload, type ResolverTelemetryOutcome, type ResolverTelemetryPhase, type ResolverTelemetrySink, type ResolverVendorAttemptTelemetryEvent, } from "../runtime/resolver-telemetry.js";
+export { StealthTelemetryCollector, type StealthTelemetryAttemptEvent, type StealthTelemetryAttemptKind, type StealthTelemetryAttemptSample, type StealthTelemetryDiagnostics, type StealthTelemetryErrorCode, type StealthTelemetryHeaderPayload, type StealthTelemetryLogPayload, type StealthTelemetryRequestClass, type StealthTelemetrySbsdEvent, type StealthTelemetrySbsdOutcome, type StealthTelemetrySink, } from "../runtime/stealth-telemetry.js";
+export { SttTelemetryCollector, bindSttTelemetry, type SttTelemetryBackend, type SttTelemetryEngine, type SttTelemetryErrorCode, type SttTelemetryEvent, type SttTelemetryModel, type SttTelemetryHeaderPayload, type SttTelemetryLogPayload, type SttTelemetrySink, } from "../runtime/stt-telemetry.js";
+export { BrowserTelemetryCollector, type BrowserTelemetryErrorCode, type BrowserTelemetryHeaderPayload, type BrowserTelemetryLogPayload, type BrowserTelemetryPoolAcquireOutcome, type BrowserTelemetrySink, type BrowserTelemetrySampleName, type BrowserTelemetryEngine, } from "../runtime/browser-telemetry.js";
 export type { ResolverVendorUnavailableReason } from "../runtime/resolver-vendors/types.js";
 export type { Span, TraceContext } from "../runtime/trace.js";
+export type { StealthBrowser, StealthOS, StealthProfileDescriptor } from "../types.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderErrorCauseFrame, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
 export type { ProviderErrorObservability } from "../errors.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
@@ -12,4 +19,6 @@ export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, type SelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";
+export { HttpTelemetryCollector, type HttpTelemetrySink, type HttpTelemetryRequestSink, type HttpAttemptTelemetryEvent, type HttpAttemptSample, type HttpTelemetryErrorCode, type HttpTelemetryRetryPayload, type HttpTelemetryLogPayload, type HttpTelemetryHeaderPayload, } from "../runtime/http-telemetry.js";
+export type { HttpRetrySummary } from "../types.js";
 export { NativeTelemetryCollector, type NativeAttemptSample, type NativeConnectTelemetryEvent, type NativeLifecycleTelemetryEvent, type NativeTelemetryDiagnostics, type NativeTelemetryErrorCode, type NativeTelemetryHeaderPayload, type NativeTelemetryKind, type NativeTelemetryLifecycleKind, type NativeTelemetryLogPayload, type NativeTelemetryOutcome, type NativeTelemetrySink, type NativeTelemetryVendorSkipReason, type NativeVendorSkipTelemetryEvent, } from "../runtime/native-telemetry.js";

package/dist/server/index.js

@@ -1,9 +1,14 @@
 export { RequestTelemetry, closedEnum, } from "../runtime/request-telemetry.js";
+export { OcrTelemetryCollector, bindOcrTelemetry, } from "../runtime/ocr-telemetry.js";
 export { ResolverTelemetryCollector, } from "../runtime/resolver-telemetry.js";
+export { StealthTelemetryCollector, } from "../runtime/stealth-telemetry.js";
+export { SttTelemetryCollector, bindSttTelemetry, } from "../runtime/stt-telemetry.js";
+export { BrowserTelemetryCollector, } from "../runtime/browser-telemetry.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
 export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";
+export { HttpTelemetryCollector, } from "../runtime/http-telemetry.js";
 export { NativeTelemetryCollector, } from "../runtime/native-telemetry.js";

package/dist/server/sdk-version.d.ts

@@ -0,0 +1,3 @@
+/** Published @apifuse/provider-sdk version, read from the package manifest; "unknown" when unreadable. */
+export declare function resolveSdkVersion(): string;
+export declare const SDK_VERSION: string;

package/dist/server/sdk-version.js

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+/** Published @apifuse/provider-sdk version, read from the package manifest; "unknown" when unreadable. */
+export function resolveSdkVersion() {
+    try {
+        const packageJsonUrl = new URL("../../package.json", import.meta.url);
+        const parsed = JSON.parse(readFileSync(packageJsonUrl, "utf8"));
+        if (parsed &&
+            typeof parsed === "object" &&
+            "version" in parsed &&
+            typeof parsed.version === "string") {
+            return parsed.version;
+        }
+    }
+    catch {
+        // fall through to unknown
+    }
+    return "unknown";
+}
+export const SDK_VERSION = resolveSdkVersion();