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

package/dist/server/serve-implementation.js

@@ -1,3 +1,4 @@
+import { bindCapabilityRoot } from "../runtime/capability-telemetry.js";
 import { STATUS_CODES } from "node:http";
 import { readDiagnosticEnv, withDiagnosticEnv } from "../runtime/diagnostic-env.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -9,15 +10,20 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
 import { validateFailClosedDeclaration } from "../declaration-validation.js";
-import { createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, isEngineOwnedEnvName, readEngineProxyCredentials, } from "../engine.js";
+import { ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, isEngineOwnedEnvName, readEngineProxyCredentials, } from "../engine.js";
+import { createEngineForMode, isUnavailableProviderEngine, resolveProviderEngineMode, } from "../runtime/engine-mode.js";
+import { SDK_VERSION } from "./sdk-version.js";
 import { safeProviderErrorObservability } from "../error-observability.js";
+import { providerErrorStackFrames } from "./error-stack-frames.js";
 import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "../error-resolution.js";
 import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, SDKError, } from "../errors.js";
 import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
+import { acceptLanguageHeaderValue, DEFAULT_PROVIDER_ERROR_LOCALE, localizeProviderErrorText, PROVIDER_ERROR_LOCALES, resolveProviderErrorLocale, } from "../i18n/error-messages.js";
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, sourceForCategory, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
 import { createProviderCache } from "../runtime/cache.js";
+import { bindCacheTelemetry, CacheTelemetryCollector } from "../runtime/cache-telemetry.js";
 import { createHandleContext } from "../runtime/handle.js";
 import { createCredentialContext } from "../runtime/credential.js";
 import { bindDiagnosticSensitiveRegistry, compileProcessDiagnosticSensitiveValues, createDiagnosticRedactor, REDACTION_FAILED, isDiagnosticRedactionSuppressed, bindCriticalDiagnosticRedactor, redactCriticalDiagnosticText, redactDiagnosticText, registerDiagnosticSensitiveValues, } from "../runtime/diagnostic-redactor.js";
@@ -30,16 +36,23 @@ import { bindHttpTelemetry, isSupportedHttpBinding, warnUnsupportedHttpBinding,
 import { HttpTelemetryCollector } from "../runtime/http-telemetry.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
+import { bindOcrTelemetry, OcrTelemetryCollector } from "../runtime/ocr-telemetry.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector, } from "../runtime/proxy-telemetry.js";
 import { closedEnum, RequestTelemetry, tenantOpaqueKeys, } from "../runtime/request-telemetry.js";
 import { bindResolverTelemetry, createUnsupportedResolverClient, inheritResolverTelemetryBinding, } from "../runtime/resolver-shared.js";
 import { ResolverTelemetryCollector, } from "../runtime/resolver-telemetry.js";
+import { createResolverRuntimeOptions, resolveNativeProxyPolicy, } from "../runtime/resolver-runtime-options.js";
 import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
+import { StateTelemetryCollector, instrumentProviderRuntimeState, } from "../runtime/state-telemetry.js";
 import { StealthCookieJar } from "../runtime/stealth-cookies.js";
+import { StealthTelemetryCollector } from "../runtime/stealth-telemetry.js";
+import { BrowserTelemetryCollector } from "../runtime/browser-telemetry.js";
+import { bindBrowserTelemetry, isSupportedBrowserBinding, warnUnsupportedBrowserBinding, } from "../runtime/browser-telemetry-binding.js";
 import { createSttClientFromEnv } from "../runtime/stt.js";
+import { bindSttTelemetry, SttTelemetryCollector } from "../runtime/stt-telemetry.js";
 import { createTraceContext, getTraceRecorder, updateTraceContextExportMetadata, } from "../runtime/trace.js";
 import { resolveTraceConfigFromEnv } from "../runtime/trace-config.js";
 import { parseSchema } from "../schema.js";
@@ -83,7 +96,6 @@ function providerErrorCode(error) {
         return undefined;
     }
 }
-const AUTH_FLOW_LOCALES = ["en", "ko", "ja"];
 const retryResponseMeta = new WeakMap();
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
 const STATEFUL_FORWARDING_SOURCE_POD_HEADER = "x-apifuse-stateful-source-pod";
@@ -113,6 +125,18 @@ export const ProviderServerStatefulForwardEnvelopeSchema = z
     }).strict(),
 })
     .strict();
+// Inbound compatibility boundary for rolling deploys, mirroring the outbound
+// one in stateful-provider-owner-forwarder.ts: emitted envelopes stay strict
+// (above), while a received envelope's nested operation request keeps the
+// gateway route's tolerance and strips unknown keys. A source pod on a newer
+// SDK carrying an additive OperationRequestSchema field (tenantId, #164) must
+// not be rejected with STATEFUL_FORWARDING_ENVELOPE_INVALID by an owner pod
+// that predates the field: the rejection is terminal for the operation and the
+// two pods coexist for the whole rolling update. The envelope's own keys stay
+// strict on both sides, because they are protocol rather than payload.
+const ReceivedStatefulForwardEnvelopeSchema = ProviderServerStatefulForwardEnvelopeSchema.extend({
+    operationRequest: z.object(ProviderServerStatefulForwardEnvelopeSchema.shape.operationRequest.shape),
+});
 const require = createRequire(import.meta.url);
 function normalizedCapabilityCause(error) {
     if (error instanceof Error)
@@ -327,24 +351,6 @@ function getProviderStealthBaseUrl(provider) {
 function getProviderStealthProfile(provider) {
     return provider.stealth ? getStealthProfile(provider.stealth) : undefined;
 }
-/** One option set for ctx.resolver and the automatic SBSD solve, so both share identity scope, cache, proxy intent, and telemetry. */
-function createResolverRuntimeOptions(provider, cache, identityScope, proxyPolicy, proxyClientOptions, stealthProfile, telemetry) {
-    return {
-        allowedHosts: provider.allowedHosts,
-        cache,
-        telemetry,
-        identityScope,
-        ...(proxyPolicy
-            ? {
-                proxyIntent: {
-                    mode: proxyPolicy.mode,
-                    ...proxyClientOptions,
-                    ...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
-                },
-            }
-            : {}),
-    };
-}
 /** Shared predicate for the SBSD challenge runtime and the ceremony egress lease. */
 function declaresAkamaiSbsdResolver(provider) {
     return provider.resolver?.kinds.some((kind) => kind === "akamai_sbsd") === true;
@@ -367,12 +373,13 @@ function createStealthChallengeDetection(provider, resolverRuntime, resolverOver
                 ? {
                     async solve(challenge, transport, solveSignal) {
                         const resolver = resolverRuntime.bindResolverSignal((resolverOverride
-                            ? bindResolverTelemetry(resolverOverride, resolverOptions.telemetry)
+                            ? bindResolverTelemetry(resolverOverride, resolverOptions.telemetry, resolverOptions.browserTelemetry)
                             : undefined) ??
                             resolverRuntime.createResolverClientFromEnv(provider.resolver, undefined, {
                                 allowedHosts: resolverOptions.allowedHosts,
                                 cache: resolverOptions.cache,
                                 telemetry: resolverOptions.telemetry,
+                                browserTelemetry: resolverOptions.browserTelemetry,
                                 identityScope: resolverOptions.identityScope,
                                 // No proxyIntent: the transport is already bound to the initiating
                                 // request's lease, and a second identity resolution would allocate
@@ -465,19 +472,16 @@ function resolveOperationConnectionId(request) {
     // absent so it can never override a valid id or key a real scope. Requests
     // without any usable id fall back to the documented missing-connection
     // sentinel scope instead of scoping context/affinity/state under "".
-    return (normalizeConnectionId(request.connection?.id) ?? normalizeConnectionId(request.connectionId));
+    return normalizeIdentifier(request.connection?.id) ?? normalizeIdentifier(request.connectionId);
 }
-function normalizeConnectionId(id) {
-    return id === "" ? undefined : id;
+function resolveOperationTenantId(request) {
+    // Only the gateway-asserted envelope field is consulted; caller headers can
+    // never populate the principal scope. Same rule as connection ids: "" is a
+    // malformed identifier, not a principal.
+    return normalizeIdentifier(request.tenantId);
 }
-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;
+function normalizeIdentifier(id) {
+    return id === "" ? undefined : id;
 }
 function providerSecretNames(provider) {
     return (provider.secrets?.map((secret) => secret.name) ?? []).filter((name) => !isEngineOwnedEnvName(name));
@@ -495,11 +499,12 @@ function createProviderContext(provider, request, operationId, options, state =
         engineCredentials: engineProxyCredentials,
     };
     const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
-    const cache = createProviderCache({ providerId: provider.id });
+    const cache = createProviderCache(bindCacheTelemetry({ providerId: provider.id }, scope.cacheTelemetry));
     const { capabilityModules } = options;
-    const resolverOptions = createResolverRuntimeOptions(provider, cache, resolverIdentityScope, proxyPolicy, proxyClientOptions, stealthProfile, scope.resolverTelemetry);
+    const resolverOptions = createResolverRuntimeOptions(provider, cache, resolverIdentityScope, proxyPolicy, proxyClientOptions, stealthProfile, scope.resolverTelemetry, scope.browserTelemetry);
     const challengeRuntime = createStealthChallengeDetection(provider, capabilityModules.resolver, options.resolver, resolverOptions, scope.trace, signal);
     const stealthClientOptions = {
+        stealthTelemetry: scope.stealthTelemetry,
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
         telemetry: scope.telemetry.proxy,
@@ -524,11 +529,15 @@ function createProviderContext(provider, request, operationId, options, state =
         scopes: request.connection?.scopes,
         values: request.connection?.secrets,
     });
+    const operationTenantId = resolveOperationTenantId(request);
     const requestContext = {
         connectionId: resolveOperationConnectionId(request),
+        // Absent stays absent: an own property with an undefined value would
+        // change the shape of ctx.request for every existing consumer.
+        ...(operationTenantId !== undefined ? { tenantId: operationTenantId } : {}),
         headers: request.headers ?? {},
     };
-    const requestState = state.forConnection(requestContext.connectionId);
+    const requestState = instrumentProviderRuntimeState(state, scope.stateTelemetry, scope.redact).forConnection(requestContext.connectionId);
     const bindings = {
         env,
         credential,
@@ -554,6 +563,7 @@ function createProviderContext(provider, request, operationId, options, state =
                 requireCdpPool: isProductionProviderBrowserMode(provider),
                 stealth: true,
                 engine: provider.browser?.engine,
+                telemetry: scope.browserTelemetry,
             })
             : createBrowserStub(),
         ...(provider.native
@@ -572,15 +582,15 @@ function createProviderContext(provider, request, operationId, options, state =
             : {}),
         trace: scope.trace,
         auth: createAuthStub(),
-        ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
-        stt: options.stt ?? createSttClientFromEnv(provider.stt),
+        ocr: bindCapabilityRoot(bindOcrTelemetry(options.ocr ?? createOcrClientFromEnv(provider.ocr), scope.ocrTelemetry), scope.run),
+        stt: bindCapabilityRoot(bindSttTelemetry(options.stt ?? createSttClientFromEnv(provider.stt), scope.sttTelemetry), scope.run),
         resolver: capabilityModules.resolver
             ? capabilityModules.resolver.bindResolverSignal((options.resolver
-                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry, resolverOptions.browserTelemetry)
                 : undefined) ??
                 capabilityModules.resolver.createResolverClientFromEnv(provider.resolver, undefined, resolverOptions), signal)
             : bindResolverSignalWithoutRuntime((options.resolver
-                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry, resolverOptions.browserTelemetry)
                 : undefined) ??
                 createUnsupportedResolverClient("Provider does not declare resolver capability"), signal),
         handle: createHandleContext({
@@ -595,6 +605,7 @@ function createProviderContext(provider, request, operationId, options, state =
         }),
     };
     const candidateHttp = bindings.http;
+    const candidateBrowser = bindings.browser;
     const attached = options.engine.attach({ provider, bindings });
     const hostHttp = provider.http ? attached.http : undefined;
     const supportedHostHttp = provider.http && isSupportedHttpBinding(hostHttp);
@@ -603,10 +614,23 @@ function createProviderContext(provider, request, operationId, options, state =
     const observedHttp = supportedHostHttp && hostHttp !== candidateHttp
         ? bindHttpTelemetry(hostHttp, scope.httpTelemetry)
         : undefined;
-    const contextTarget = observedHttp
+    const hostBrowser = provider.runtime === "browser" ? attached.browser : undefined;
+    const supportedHostBrowser = provider.runtime === "browser" && isSupportedBrowserBinding(hostBrowser);
+    if (provider.runtime === "browser" && !supportedHostBrowser)
+        warnUnsupportedBrowserBinding();
+    const observedBrowser = supportedHostBrowser && hostBrowser !== candidateBrowser
+        ? bindBrowserTelemetry(hostBrowser, scope.browserTelemetry)
+        : undefined;
+    const contextTarget = observedBrowser || observedHttp
         ? new Proxy(attached, {
             get(target, property, receiver) {
-                return property === "http" ? observedHttp : Reflect.get(target, property, receiver);
+                if (property === "http" && observedHttp)
+                    return observedHttp;
+                if (property === "http" && provider.http && !supportedHostHttp)
+                    return undefined;
+                if (property === "browser" && observedBrowser)
+                    return observedBrowser;
+                return Reflect.get(target, property, receiver);
             },
         })
         : provider.http && !supportedHostHttp
@@ -687,11 +711,12 @@ function createAuthFlowContext(provider, request, route, options, state, scope,
         throw new SDKError("An egress lease was supplied for an auth flow that does not use a ceremony lease", { code: "EGRESS_LEASE_INVALID" });
     }
     const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
-    const cache = createProviderCache({ providerId: provider.id });
+    const cache = createProviderCache(bindCacheTelemetry({ providerId: provider.id }, scope.cacheTelemetry));
     const { capabilityModules } = options;
-    const resolverOptions = createResolverRuntimeOptions(provider, cache, resolverIdentityScope, proxyPolicy, proxyClientOptions, stealthProfile, scope.resolverTelemetry);
+    const resolverOptions = createResolverRuntimeOptions(provider, cache, resolverIdentityScope, proxyPolicy, proxyClientOptions, stealthProfile, scope.resolverTelemetry, scope.browserTelemetry);
     const challengeRuntime = createStealthChallengeDetection(provider, capabilityModules.resolver, options.resolver, resolverOptions, scope.trace, signal);
     const stealthClientOptions = {
+        stealthTelemetry: scope.stealthTelemetry,
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
         telemetry: scope.telemetry.proxy,
@@ -730,12 +755,23 @@ function createAuthFlowContext(provider, request, route, options, state, scope,
             ...(signal ? { signal } : {}),
             httpTelemetry: scope.httpTelemetry,
         }),
-        state: state.forConnection(resolveOperationConnectionId(request)),
+        state: instrumentProviderRuntimeState(state, scope.stateTelemetry, scope.redact).forConnection(resolveOperationConnectionId(request)),
         stealth: stealthBaseUrl
             ? capabilityModules.stealth
                 ? capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthClientOptions)
                 : createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthClientOptions)
             : createStealthStub(),
+        browser: provider.runtime === "browser"
+            ? capabilityModules.browser.createBrowserClient({
+                allowedHosts: provider.allowedHosts,
+                cdpUrl: readDiagnosticEnv("APIFUSE__CDP_POOL__URL"),
+                headless: true,
+                requireCdpPool: isProductionProviderBrowserMode(provider),
+                stealth: true,
+                engine: provider.browser?.engine,
+                telemetry: scope.browserTelemetry,
+            })
+            : createBrowserStub(),
         ...(provider.native
             ? {
                 native: {
@@ -756,15 +792,15 @@ function createAuthFlowContext(provider, request, route, options, state, scope,
         ]),
         credential,
         context: flowContextStore.context,
-        ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
-        stt: options.stt ?? createSttClientFromEnv(provider.stt),
+        ocr: bindCapabilityRoot(bindOcrTelemetry(options.ocr ?? createOcrClientFromEnv(provider.ocr), scope.ocrTelemetry), scope.run),
+        stt: bindCapabilityRoot(bindSttTelemetry(options.stt ?? createSttClientFromEnv(provider.stt), scope.sttTelemetry), scope.run),
         resolver: capabilityModules.resolver
             ? capabilityModules.resolver.bindResolverSignal((options.resolver
-                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry, resolverOptions.browserTelemetry)
                 : undefined) ??
                 capabilityModules.resolver.createResolverClientFromEnv(provider.resolver, undefined, resolverOptions), signal)
             : bindResolverSignalWithoutRuntime((options.resolver
-                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry, resolverOptions.browserTelemetry)
                 : undefined) ??
                 createUnsupportedResolverClient("Provider does not declare resolver capability"), signal),
         auth: createAuthFlowHelpers({ signal }),
@@ -828,7 +864,76 @@ function publicErrorSource(error, category) {
     }
     return sourceForCategory(category);
 }
-function toErrorResponse(error, requestId, observabilityDetails, redact) {
+function localeKeyOption(error, key) {
+    const value = providerErrorOption(error, key);
+    return typeof value === "string" ? value : undefined;
+}
+function declaredLocaleKey(declaration, key) {
+    const value = declaration?.[key];
+    return typeof value === "string" ? value : undefined;
+}
+function providerErrorParams(error) {
+    const params = providerErrorOption(error, "params");
+    return params !== null && typeof params === "object" && !Array.isArray(params)
+        ? params
+        : undefined;
+}
+/**
+ * Resolution order for one localized envelope field:
+ *
+ * 1. the throw site's `messageKey`/`fixKey`;
+ * 2. the declared `errorCodes[]` entry's key for the thrown code;
+ * 3. the derived `errors.<code>.<field>` convention;
+ * 4. the English literal the provider threw.
+ *
+ * Steps 2 and 3 are skipped for SDK-owned failures (transport, Zod, stateful
+ * deadline, SDK runtime codes): their text is the SDK's contract, and a
+ * provider catalog entry must not be able to relabel one. An explicit key on
+ * the thrown error still wins, because that is the provider deliberately
+ * describing an error it constructed itself.
+ */
+function localizedErrorField(error, field, literal, localization) {
+    if (!localization?.catalogs)
+        return literal;
+    const optionKey = field === "message" ? "messageKey" : "fixKey";
+    const candidates = [
+        { kind: "key", key: localeKeyOption(error, optionKey) },
+    ];
+    if (!sdkOwnsErrorResolution(error)) {
+        candidates.push({ kind: "key", key: declaredLocaleKey(localization.declaredErrorCode, optionKey) }, { kind: "derived", code: providerErrorCode(error), field });
+    }
+    return localizeProviderErrorText({
+        catalogs: localization.catalogs,
+        locale: localization.locale,
+        candidates,
+        params: providerErrorParams(error),
+        fallback: literal,
+    });
+}
+/**
+ * Reads `accept-language` out of the request envelope's `headers` map.
+ *
+ * The gateway stamps the negotiated locale there for auth flows (it persists
+ * the start locale on the flow state so continue/poll turns stay in one
+ * language), and the operation route merges HTTP headers into the same map, so
+ * the envelope is the higher-precedence source.
+ */
+function requestBodyAcceptLanguage(rawBody) {
+    if (!rawBody || typeof rawBody !== "object")
+        return undefined;
+    const headers = Object.getOwnPropertyDescriptor(rawBody, "headers")?.value;
+    if (!headers || typeof headers !== "object" || Array.isArray(headers))
+        return undefined;
+    return acceptLanguageHeaderValue(headers);
+}
+function errorEnvelopeLocalization(options) {
+    return {
+        ...(options.catalogs ? { catalogs: options.catalogs } : {}),
+        locale: resolveProviderErrorLocale(requestBodyAcceptLanguage(options.rawBody), options.requestHeaders?.get("accept-language")),
+        ...(options.declaredErrorCode ? { declaredErrorCode: options.declaredErrorCode } : {}),
+    };
+}
+function toErrorResponse(error, requestId, observabilityDetails, redact, localization) {
     const observability = observabilityDetails;
     const source = publicErrorSource(error, observability.category);
     if (error instanceof StatefulRoutingDeadlineError) {
@@ -844,14 +949,17 @@ function toErrorResponse(error, requestId, observabilityDetails, redact) {
     }
     if (isProviderError(error)) {
         const details = providerErrorOption(error, "details");
+        const literalFix = providerErrorOption(error, "fix");
+        const fix = localizedErrorField(error, "fix", typeof literalFix === "string" && literalFix.length > 0 ? literalFix : undefined, localization);
+        const literalMessage = publicProviderErrorMessage(error);
         return {
             error: {
                 code: providerErrorCode(error) ?? "provider_error",
-                message: publicProviderErrorMessage(error),
+                message: localizedErrorField(error, "message", literalMessage, localization) ?? literalMessage,
                 ...(requestId ? { requestId } : {}),
                 retryable: observability.retryable,
                 source,
-                ...(providerErrorOption(error, "fix") ? { fix: providerErrorOption(error, "fix") } : {}),
+                ...(fix ? { fix } : {}),
                 ...(details !== undefined ? { details } : {}),
             },
         };
@@ -1097,6 +1205,11 @@ function publicProviderErrorMessage(error) {
             return "Request timed out";
         if (providerErrorCode(error) === "transport_network_error")
             return "Network error";
+        // Provider-local fault: no request was issued, so an upstream-flavored
+        // message would misattribute it (category is provider_error).
+        if (providerErrorCode(error) === "http_header_factory_failed") {
+            return "Request header preparation failed";
+        }
         if (providerErrorCode(error) === "upstream_http_error" && error.status) {
             return `Upstream request failed with status ${error.status}`;
         }
@@ -1220,6 +1333,11 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
     const causeChain = providerErrorCauseChain(error, redact);
+    // Masked 500 bodies carry only errorClass, so the log is the sole channel
+    // that can locate the throw. Declared 5xx (502/504) are included too: their
+    // body carries code+message, but frame[0] is still the throw site inside
+    // provider code. 4xx failures keep the lean record.
+    const stack = status >= 500 ? providerErrorStackFrames(error, redact) : undefined;
     const details = observabilityDetails;
     const isUnregisteredProviderErrorCode = status === 500 &&
         isProviderError(error) &&
@@ -1261,6 +1379,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         errorClass: redactDiagnosticText(errorClass, redact),
         message: sanitizeDiagnosticText(redactDiagnosticText(message, redact)),
         ...(causeChain ? { causeChain } : {}),
+        ...(stack ? { stack } : {}),
         ...(providerObservability ? { providerObservability } : {}),
         ...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
         errorCategory: details.category,
@@ -1462,6 +1581,7 @@ function createRequestScope(input) {
         observe: createDiagnosticEnvObserver(input.provider, sensitiveRegistry.add, sensitiveRegistry.has),
         finished: false,
         staticValues: input.staticSensitiveValues,
+        register: sensitiveRegistry.add,
     };
     const traceConfig = withDiagnosticEnv(observeEnv, () => resolveTraceConfigFromEnv());
     const details = {
@@ -1492,11 +1612,23 @@ function createRequestScope(input) {
     const resolverCollector = new ResolverTelemetryCollector({ redact });
     const nativeCollector = new NativeTelemetryCollector({ redact });
     const httpCollector = new HttpTelemetryCollector({ redact });
+    const stealthCollector = new StealthTelemetryCollector({ redact });
+    const ocrCollector = new OcrTelemetryCollector({ redact });
+    const sttCollector = new SttTelemetryCollector({ redact });
+    const browserCollector = new BrowserTelemetryCollector({ redact });
+    const cacheTelemetry = new CacheTelemetryCollector({ redact });
+    const stateTelemetry = new StateTelemetryCollector({ redact });
     const telemetry = new RequestTelemetry(trace);
     telemetry.register(proxyCollector);
     telemetry.register(resolverCollector);
     telemetry.register(nativeCollector);
     telemetry.register(httpCollector);
+    telemetry.register(stealthCollector);
+    telemetry.register(browserCollector);
+    telemetry.register(ocrCollector);
+    telemetry.register(sttCollector);
+    telemetry.register(cacheTelemetry);
+    telemetry.register(stateTelemetry);
     let rootRunner = (fn) => fn();
     let resolveRoot;
     const rootTerminal = new Promise((resolve) => {
@@ -1575,6 +1707,12 @@ function createRequestScope(input) {
         resolverTelemetry: resolverCollector,
         nativeTelemetry: nativeCollector,
         httpTelemetry: httpCollector,
+        stealthTelemetry: stealthCollector,
+        ocrTelemetry: ocrCollector,
+        sttTelemetry: sttCollector,
+        browserTelemetry: browserCollector,
+        cacheTelemetry,
+        stateTelemetry,
         seedCredentials(rawBody, kind) {
             const harvested = rawRequestCredentials(rawBody, kind);
             sensitiveRegistry.add(harvested.values);
@@ -2015,50 +2153,49 @@ function toAuthFlowResponse(result, contextPatch, engine) {
         ...(engine ? { engine } : {}),
     };
 }
-function authFlowLocaleFromHeaders(headers) {
-    const header = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === "accept-language")?.[1];
-    for (const token of (header ?? "").split(",")) {
-        const language = token.trim().split(";")[0]?.split("-")[0]?.toLowerCase();
-        if (isAuthFlowLocale(language)) {
-            return language;
-        }
-    }
-    return "en";
-}
-function isAuthFlowLocale(value) {
-    return value === "en" || value === "ko" || value === "ja";
-}
 function isAuthTurn(value) {
     return !!value && typeof value === "object" && "kind" in value && "turnId" in value;
 }
-function loadAuthFlowLocaleCatalogs(provider) {
+/**
+ * Loads the provider's locale catalogs once, at `createServerApp` time.
+ *
+ * Only the locales that actually exist on disk are read: a provider with
+ * `en`+`ko` but no `ja.json` used to make the whole load throw and silently
+ * disable localization for every turn. Absence of catalogs is not an error —
+ * every localized field falls back to its English literal — but a catalog that
+ * exists and cannot be read is logged once so a packaging mistake is visible at
+ * boot instead of per request.
+ */
+function resolveProviderLocaleCatalogs(provider, options, logger) {
+    if (options.localeCatalogs)
+        return options.localeCatalogs;
     for (const providerDir of [
         process.cwd(),
         join(process.cwd(), "providers", provider.id),
         join(process.cwd(), "providers-staging", provider.id),
     ]) {
-        if (!existsSync(join(providerDir, "locales", "en.json")))
+        const locales = PROVIDER_ERROR_LOCALES.filter((locale) => existsSync(join(providerDir, "locales", `${locale}.json`)));
+        if (!locales.includes(DEFAULT_PROVIDER_ERROR_LOCALE))
             continue;
         try {
-            return loadProviderLocaleCatalogs({
-                providerDir,
-                locales: AUTH_FLOW_LOCALES,
-            });
+            return loadProviderLocaleCatalogs({ providerDir, locales });
         }
-        catch {
+        catch (error) {
+            logger({
+                level: "warn",
+                event: "provider_locale_catalogs_unavailable",
+                providerId: provider.id,
+                reason: sanitizeDiagnosticText(error instanceof Error ? error.message : String(error)),
+            });
             return undefined;
         }
     }
     return undefined;
 }
-function materializeAuthFlowTurn(provider, request, turn) {
-    const catalogs = loadAuthFlowLocaleCatalogs(provider);
+function materializeAuthFlowTurn(turn, catalogs, locale) {
     if (!catalogs)
         return turn;
-    return localizeAuthTurn(turn, {
-        catalogs,
-        locale: authFlowLocaleFromHeaders(request.headers),
-    });
+    return localizeAuthTurn(turn, { catalogs, locale });
 }
 function withAuthRequestHeaders(request, headers) {
     return {
@@ -2137,7 +2274,15 @@ async function handleOperation(provider, request, operationId, options, state =
             await cleanup();
     }
 }
-async function handleAuthFlow(provider, request, route, options, state, scope, signal) {
+async function handleAuthFlow(provider, request, route, options, state, scope, 
+/**
+ * Negotiated once per request by the route so a successful turn and an error
+ * envelope from the same request can never disagree. `withAuthRequestHeaders`
+ * lets the HTTP header shadow the envelope's `Accept-Language`, but the
+ * gateway stamps the flow's start locale into the envelope precisely so
+ * continue/poll turns stay in one language, so the envelope wins here.
+ */
+locale, signal) {
     const flow = provider.auth?.flow;
     if (!flow) {
         throw new ProviderError("Auth flow is not configured", {
@@ -2179,7 +2324,7 @@ async function handleAuthFlow(provider, request, route, options, state, scope, s
             !(result instanceof Response) &&
             !(result instanceof ReadableStream) &&
             isAuthTurn(result)
-            ? materializeAuthFlowTurn(provider, request, result)
+            ? materializeAuthFlowTurn(result, options.localeCatalogs, locale)
             : result;
         return toAuthFlowResponse(materializedResult, getPatch(), getEngineState());
     }
@@ -2301,7 +2446,7 @@ function operationRequestFromForwardingEnvelope(envelope) {
     };
 }
 function parseStatefulForwardingEnvelope(rawBody, redact) {
-    const parsed = ProviderServerStatefulForwardEnvelopeSchema.safeParse(rawBody);
+    const parsed = ReceivedStatefulForwardEnvelopeSchema.safeParse(rawBody);
     if (parsed.success)
         return parsed.data;
     throw new ProviderError("Stateful forwarding envelope is invalid.", {
@@ -2333,12 +2478,59 @@ export function createServerApp(provider, options = {}) {
     validateStatefulServerConfig(runtimeOptions);
     return createServerAppWithCapabilityModules(runtimeProvider, runtimeOptions, loadProviderCapabilityModulesSync(runtimeProvider));
 }
+/**
+ * Resolve the engine once at boot, before any route exists. An explicit engine
+ * object is used as given; otherwise the resolved mode selects the engine.
+ *
+ * Deliberately never throws for deployment-authored input: a mode this release
+ * cannot serve yields an engine that fails every request and a `/readyz` 503,
+ * because a boot crash would trade a structured signal for CrashLoopBackOff
+ * across the fleet (same trade-off as `provider_secrets_missing` above).
+ */
+function resolveServerEngine(serverOptions) {
+    const resolution = resolveProviderEngineMode({
+        option: serverOptions.engineMode,
+        engine: serverOptions.engine,
+    });
+    if (serverOptions.engine !== undefined)
+        return { engine: serverOptions.engine, resolution };
+    return { engine: createEngineForMode(resolution.mode), resolution };
+}
+/**
+ * `engine_env_ignored` is expected for the whole migration window: the manifest
+ * generator projects the remote engine env fleet-wide before any mode flips, so
+ * escalating on it would turn every healthy boot into a warn line. The
+ * disagreement warnings still escalate.
+ */
+const ENGINE_MODE_INFO_WARNINGS = new Set(["engine_env_ignored"]);
+function engineModeLogEvent(provider, resolution, attached) {
+    const escalating = resolution.warnings.filter((warning) => !ENGINE_MODE_INFO_WARNINGS.has(warning));
+    return {
+        level: attached && escalating.length === 0 ? "info" : "warn",
+        event: "provider_engine_mode",
+        providerId: provider.id,
+        mode: resolution.mode,
+        source: resolution.source,
+        deprecated: resolution.deprecated,
+        attached,
+        sdkVersion: SDK_VERSION,
+        ...(provider.runtimeTarget === undefined ? {} : { runtimeTarget: provider.runtimeTarget }),
+        ...(resolution.warnings.length === 0 ? {} : { warnings: resolution.warnings }),
+    };
+}
 function createServerAppWithCapabilityModules(provider, serverOptions, capabilityModules) {
+    const engineSelection = resolveServerEngine(serverOptions);
+    // Read the provider's locale catalogs once here rather than per turn: the
+    // previous auth-flow loader re-read all three JSON files on every turn and
+    // threw the whole map away when one locale file was absent.
+    const localeCatalogs = resolveProviderLocaleCatalogs(provider, serverOptions, serverOptions.logger ?? defaultProviderServerLogger);
     const options = {
         ...serverOptions,
+        ...(localeCatalogs ? { localeCatalogs } : {}),
         capabilityModules,
-        engine: serverOptions.engine ?? createInProcessProviderEngine(),
+        engine: engineSelection.engine,
     };
+    const engineAttached = !isUnavailableProviderEngine(options.engine);
     const app = new Hono();
     // Compile the startup inventory once, composed with the shared outside-context fallback.
     const staticSensitiveValues = compileProcessDiagnosticSensitiveValues(collectStaticDiagnosticSensitiveValues(provider, {
@@ -2370,13 +2562,33 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
     app.notFound((c) => {
         const error = new ProviderError("Not found", { code: "not_found", retryable: false });
         const observabilityDetails = errorObservabilityDetails(error);
-        return responseWithErrorObservability(c.json(toErrorResponse(error, undefined, observabilityDetails), 404), observabilityDetails);
+        return responseWithErrorObservability(c.json(toErrorResponse(error, undefined, observabilityDetails, undefined, errorEnvelopeLocalization({
+            catalogs: localeCatalogs,
+            requestHeaders: c.req.raw.headers,
+        })), 404), observabilityDetails);
     });
+    // Liveness. Deliberately static and engine-blind: generated manifests point
+    // liveness at this route, so making it depend on engine reachability would
+    // restart every provider pod on one engine incident. Engine state belongs to
+    // /readyz, which manifests wire to readiness and startup only.
     app.get("/health", (c) => c.json({
         status: "ok",
         provider: provider.id,
         version: provider.version,
     }));
+    // Readiness. Reports the boot-resolved attachment; does not probe the engine
+    // per call, so it cannot amplify an engine incident into request load.
+    app.get("/readyz", (c) => c.json({
+        status: engineAttached ? "ok" : "unavailable",
+        provider: provider.id,
+        version: provider.version,
+        engine: {
+            // The resolution, not the raw engine `kind`: normalized, so this
+            // body and the `provider_engine_mode` boot event never disagree.
+            mode: engineSelection.resolution.mode,
+            attached: engineAttached,
+        },
+    }, engineAttached ? 200 : 503));
     app.post(STATEFUL_INTERNAL_OPERATIONS_ROUTE, async (c) => {
         let rawBodyText = "";
         let rawBody;
@@ -2482,7 +2694,10 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 requestId: request.requestId,
                 operationId,
                 headers: request.headers ?? {},
-                correlation: { connectionId: envelope.connectionId },
+                correlation: {
+                    connectionId: envelope.connectionId,
+                    tenantId: resolveOperationTenantId(request),
+                },
             });
             const response = await requestScope.run(async () => {
                 const ctx = createProviderContext(provider, request, operationId, options, state, requestScope, signal);
@@ -2517,7 +2732,12 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 ...(requestId ? { requestId } : {}),
             });
             const observabilityDetails = errorObservabilityDetails(error, declaredErrorCode);
-            const response = c.json(toErrorResponse(error, requestId, observabilityDetails, requestScope.redact), status);
+            const response = c.json(toErrorResponse(error, requestId, observabilityDetails, requestScope.redact, errorEnvelopeLocalization({
+                catalogs: localeCatalogs,
+                requestHeaders: c.req.raw.headers,
+                rawBody,
+                ...(declaredErrorCode ? { declaredErrorCode } : {}),
+            })), status);
             return finalizeRequestResponse(requestScope, response, {
                 kind: "failed",
                 status,
@@ -2551,7 +2771,10 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
             requestScope.enrich({
                 requestId: body.requestId,
                 headers: body.headers,
-                correlation: { connectionId: resolveOperationConnectionId(body) },
+                correlation: {
+                    connectionId: resolveOperationConnectionId(body),
+                    tenantId: resolveOperationTenantId(body),
+                },
             });
             const streaming = provider.operations[operation]?.transport?.kind
                 ? provider.operations[operation]?.transport?.kind !== "json"
@@ -2581,7 +2804,12 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
             const requestId = extractRequestId(rawBody);
             requestScope.enrich({ ...(requestId ? { requestId } : {}) });
             const observabilityDetails = errorObservabilityDetails(error, declaredErrorCode);
-            const response = c.json(toErrorResponse(error, requestId, observabilityDetails, requestScope.redact), status);
+            const response = c.json(toErrorResponse(error, requestId, observabilityDetails, requestScope.redact, errorEnvelopeLocalization({
+                catalogs: localeCatalogs,
+                requestHeaders: c.req.raw.headers,
+                rawBody,
+                ...(declaredErrorCode ? { declaredErrorCode } : {}),
+            })), status);
             return finalizeRequestResponse(requestScope, response, {
                 kind: "failed",
                 status,
@@ -2599,6 +2827,12 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
     for (const { path, flowRoute, logRoute } of authRoutes) {
         app.post(path, async (c) => {
             let rawBody;
+            // Negotiated once and shared by the success and failure paths so an
+            // auth turn and an error envelope from the same request agree.
+            let localization = errorEnvelopeLocalization({
+                catalogs: localeCatalogs,
+                requestHeaders: c.req.raw.headers,
+            });
             const requestScope = createRequestScope({
                 provider,
                 staticSensitiveValues,
@@ -2613,6 +2847,11 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                     .clone()
                     .json()
                     .catch(() => undefined);
+                localization = errorEnvelopeLocalization({
+                    catalogs: localeCatalogs,
+                    requestHeaders: c.req.raw.headers,
+                    rawBody,
+                });
                 requestScope.seedCredentials(rawBody, "auth");
                 const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
                 requestScope.enrich({
@@ -2622,14 +2861,14 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                     correlation: {
                         connectionId: resolveOperationConnectionId(body),
                         flowId: body.flowId,
-                        tenantId: body.tenantId,
+                        tenantId: normalizeIdentifier(body.tenantId),
                         requestedProviderId: body.providerId !== undefined && body.providerId !== provider.id
                             ? body.providerId
                             : undefined,
                     },
                 });
                 const response = await requestScope.run(async () => {
-                    const handled = await handleAuthFlow(provider, body, flowRoute, options, state, requestScope, c.req.raw.signal);
+                    const handled = await handleAuthFlow(provider, body, flowRoute, options, state, requestScope, localization.locale, c.req.raw.signal);
                     return handled instanceof Response ? handled : c.json(handled);
                 });
                 return finalizeRequestResponse(requestScope, response, {
@@ -2642,7 +2881,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 const requestId = extractRequestId(rawBody);
                 requestScope.enrich({ ...(requestId ? { requestId } : {}) });
                 const observabilityDetails = errorObservabilityDetails(error);
-                const response = c.json(toErrorResponse(error, requestId, observabilityDetails, requestScope.redact), status);
+                const response = c.json(toErrorResponse(error, requestId, observabilityDetails, requestScope.redact, localization), status);
                 return finalizeRequestResponse(requestScope, response, {
                     kind: "failed",
                     status,
@@ -2704,13 +2943,18 @@ export async function serve(provider, options = {}) {
     const configuredTimeoutMs = shutdownTimeout(options.shutdown?.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS);
     const configuredSignals = resolveShutdownSignals(options.shutdown?.signals ?? true);
     const selfTestSecrets = resolveSelfTestMasterSecrets();
+    // Resolve the engine here so the boot event reports the truthful source
+    // (option/env/default) and the app is handed the engine already selected —
+    // one resolution per process, not one per app construction.
+    const engineSelection = resolveServerEngine(options);
     const serverAppOptions = {
         logger: options.logger,
-        engine: options.engine,
+        engine: engineSelection.engine,
         files: options.files,
         ocr: options.ocr,
         stt: options.stt,
         resolver: options.resolver,
+        localeCatalogs: options.localeCatalogs,
         state: options.state,
         allowMemoryStateFallback: options.allowMemoryStateFallback,
         operationExecutor: options.operationExecutor,
@@ -2721,6 +2965,9 @@ export async function serve(provider, options = {}) {
         createServerAppAsync(provider, serverAppOptions),
         selfTestSecrets ? import("./self-test.js") : undefined,
     ]);
+    // One structured line per process boot, before the listener binds: the fleet
+    // audit (ADR-0011 migration) counts these.
+    logger(engineModeLogEvent(provider, engineSelection.resolution, !isUnavailableProviderEngine(engineSelection.engine)));
     const servers = [];
     try {
         servers.push(bunRuntime.serve({