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

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";

package/dist/server/index.js

@@ -1,5 +1,9 @@
 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";

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();

package/dist/server/self-test.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
 import { TURN_KINDS } from "../auth-turn/index.js";
+import { SDK_VERSION } from "./sdk-version.js";
 import { Hono } from "hono";
 import { z } from "zod";
 import { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
@@ -58,23 +58,6 @@ export const SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON = "auth_flow_rejected";
  */
 const AUTH_REJECTION_HTTP_STATUSES = new Set([401, 403]);
 const INTERACTIVE_TURN_KIND_SET = new Set(TURN_KINDS.filter((descriptor) => descriptor.rendering !== "terminal" && descriptor.kind !== "retry").map((descriptor) => descriptor.kind));
-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";
-}
-const SDK_VERSION = resolveSdkVersion();
 function healthCheckSuite(operation) {
     return operation.healthCheck;
 }

package/dist/server/sensitive-values.d.ts

@@ -1,7 +1,7 @@
 import type { ProviderDefinition } from "../types.js";
 export declare const SELF_TEST_SENSITIVE_SOURCE_KINDS: readonly ["selfTestMasterSecrets", "providerSecrets", "healthProbeSecrets", "requestCredentials"];
 /** Explicit source allowlist: no environment-name or payload-shape secret sweep. */
-export declare const DIAGNOSTIC_SENSITIVE_SOURCE_KINDS: readonly ["selfTestMasterSecrets", "providerSecrets", "healthProbeSecrets", "requestCredentials", "engineProxyCredentials", "engineSolverKeys", "engineCeremonyLeaseCredentials", "ocrCredentials", "sttCredentials", "cdpCredentials", "statefulForwardingSecret", "redisCredentials", "otlpHeaders", "cacheKeyPepper", "sensitiveParams"];
+export declare const DIAGNOSTIC_SENSITIVE_SOURCE_KINDS: readonly ["selfTestMasterSecrets", "providerSecrets", "healthProbeSecrets", "requestCredentials", "engineProxyCredentials", "engineSolverKeys", "engineCeremonyLeaseCredentials", "engineClientCredentials", "ocrCredentials", "sttCredentials", "cdpCredentials", "statefulForwardingSecret", "redisCredentials", "otlpHeaders", "cacheKeyPepper", "sensitiveParams"];
 export type DiagnosticSensitiveSourceKind = (typeof DIAGNOSTIC_SENSITIVE_SOURCE_KINDS)[number];
 /**
  * Startup inventory; request-scoped readers additionally register live values on access.

package/dist/server/sensitive-values.js

@@ -1,6 +1,7 @@
 import { resolvedStringVariants, urlCredentialComponents, otlpHeaderCredentialValues, } from "../runtime/diagnostic-env-values.js";
 import { PROVIDER_CACHE_REDIS_URL_ENV, PROVIDER_STATE_REDIS_URL_ENV, REDIS_URL_ENV, } from "../config/loader.js";
 import { ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, } from "../engine.js";
+import { REMOTE_ENGINE_CLIENT_API_KEY_ENV, REMOTE_ENGINE_CLIENT_URL_ENV, } from "../runtime/engine-mode.js";
 import { APIFUSE__CACHE__KEY_PEPPER_ENV } from "../runtime/cache.js";
 import { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "../runtime/egress-lease.js";
 import { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, } from "../runtime/ocr.js";
@@ -20,6 +21,7 @@ export const DIAGNOSTIC_SENSITIVE_SOURCE_KINDS = [
     "engineProxyCredentials",
     "engineSolverKeys",
     "engineCeremonyLeaseCredentials",
+    "engineClientCredentials",
     "ocrCredentials",
     "sttCredentials",
     "cdpCredentials",
@@ -66,6 +68,13 @@ export function collectDiagnosticSensitiveValues(provider, options = {}) {
         // These are the resolver-config API keys after #251's engine credential projection.
         engineSolverKeys: () => resolvedEnvValues(ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES),
         engineCeremonyLeaseCredentials: () => resolvedEnvValues([APIFUSE__ENGINE__CEREMONY_LEASE_KEY]),
+        // Remote engine client credential (projected before the ADR-0011 flip). The
+        // endpoint itself is an internal service URL, so only credentials embedded
+        // in it are inventoried, not the whole URL.
+        engineClientCredentials: () => [
+            ...resolvedEnvValues([REMOTE_ENGINE_CLIENT_API_KEY_ENV]),
+            ...resolvedStringVariants(env[REMOTE_ENGINE_CLIENT_URL_ENV]).flatMap((url) => urlCredentialComponents(url, { includePathAndQuery: false })),
+        ],
         ocrCredentials: () => resolvedEnvValues([APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__OCR__API_KEY_ENV]),
         sttCredentials: () => resolvedEnvValues([APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV]),
         cdpCredentials: () => resolvedStringVariants(env[APIFUSE__CDP_POOL__URL]).flatMap((url) => [

package/dist/server/serve-implementation.d.ts

@@ -1,13 +1,14 @@
 import { Hono } from "hono";
 import { z } from "zod";
-import { type ProviderEngine } from "../engine.js";
+import { type ProviderEngine, type ProviderEngineMode } from "../engine.js";
 import { type ProviderErrorObservability } from "../errors.js";
+import { type ProviderLocaleCatalogMap } from "../i18n/catalog.js";
 import { type ProviderErrorCategory } from "../observability.js";
 import type { HandleTelemetryEvent } from "../handle.js";
 import { type HttpTelemetryLogPayload } from "../runtime/http-telemetry.js";
 import { type ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
 import { type ResolverTelemetryLogPayload } from "../runtime/resolver-telemetry.js";
-import type { OcrContext, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRuntimeState, ResolverContext, SttContext } from "../types.js";
+import type { OcrContext, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRuntimeState, ProviderRuntimeTarget, ResolverContext, SttContext } from "../types.js";
 import type { SelfTestCancellationLogEvent } from "./self-test.js";
 import { type AuthFlowRequest, type OperationRequest } from "./types.js";
 /** Compact SDK-owned error classification emitted separately from the public response body. */
@@ -36,6 +37,7 @@ export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
         requestId: z.ZodString;
         input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         connectionId: z.ZodOptional<z.ZodString>;
+        tenantId: z.ZodOptional<z.ZodString>;
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         trace: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         connection: z.ZodOptional<z.ZodObject<{
@@ -106,6 +108,7 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     retryable?: boolean;
     providerObservability?: ProviderErrorObservability;
     causeChain?: ProviderErrorCauseFrame[];
+    stack?: string[];
     signal?: "unregistered_provider_error_code";
     signalFix?: string;
     issues?: Array<{
@@ -118,6 +121,12 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     event: "provider_secrets_missing";
     providerId: string;
     missingSecrets: string[];
+} | {
+    /** Emitted once at boot when `locales/en.json` exists but cannot be read. */
+    level: "warn";
+    event: "provider_locale_catalogs_unavailable";
+    providerId: string;
+    reason: string;
 } | ({
     level: "info";
     event: "provider_handle";
@@ -138,12 +147,43 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     hookIndex: number;
     errorClass: string;
     message: string;
+} | {
+    /** `warn` when the requested attachment could not be honoured, otherwise `info`. */
+    level: "info" | "warn";
+    event: "provider_engine_mode";
+    providerId: string;
+    /** Resolved attachment; `custom` for an opaque host engine. */
+    mode: ProviderEngineMode | "custom";
+    source: "engine" | "env" | "option" | "default";
+    /** True for every non-remote attachment, whose removal is scheduled by ADR-0011. */
+    deprecated: boolean;
+    /** False when the engine refuses to attach; `/readyz` reports 503. */
+    attached: boolean;
+    sdkVersion: string;
+    runtimeTarget?: ProviderRuntimeTarget;
+    /**
+     * Non-fatal selection findings, e.g. `invalid_env_value`,
+     * `env_overrode_option`, `engine_object_overrode_requested_mode`,
+     * `engine_env_ignored`. Absent when the selection was unambiguous.
+     */
+    warnings?: readonly string[];
 } | SelfTestCancellationLogEvent;
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
 export type ProviderServerOptions<TContext extends Partial<ProviderContext> = ProviderContext> = {
     logger?: ProviderServerLogger;
     /** Capability attachment boundary. Defaults to the local in-process engine. */
     engine?: ProviderEngine;
+    /**
+     * Explicit engine attachment mode. Lowest precedence of the three inputs:
+     * an explicit `engine` object wins, then `APIFUSE__ENGINE__MODE` (the
+     * deployment outranks provider code), then this option, then the in-process
+     * default. Disagreement is never fatal — it is reported on the
+     * `provider_engine_mode` boot event (`env_overrode_option`,
+     * `engine_object_overrode_requested_mode`), which only `serve` emits. A value
+     * that is not a known mode throws `ValidationError`, because unlike the env it
+     * can only come from calling code.
+     */
+    engineMode?: ProviderEngineMode;
     /** Request-file resolver supplied by the engine host when `files` is declared. */
     files?: ProviderFilesContext;
     /** Optional provider-specific operation executor. Stateful providers use this to preserve provider-local runtime semantics. */
@@ -167,6 +207,15 @@ export type ProviderServerOptions<TContext extends Partial<ProviderContext> = Pr
      * resolver is reported as one custom invocation; its internal vendor work is not exposed.
      */
     resolver?: ResolverContext;
+    /**
+     * Pre-loaded provider locale catalogs used to localize auth turns and the
+     * client-facing `message`/`fix` of provider errors.
+     *
+     * Defaults to reading `locales/{en,ko,ja}.json` from the provider directory
+     * once at server construction. Supply this to bundle catalogs instead of
+     * probing the filesystem, or to pin catalogs in tests.
+     */
+    localeCatalogs?: ProviderLocaleCatalogMap;
     /** Optional runtime state override for tests or custom hosts. Production resolves Redis from env and fails closed when unavailable. */
     state?: ProviderRuntimeState;
     /** Allow process-local runtime state only for local development and tests. */