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

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. */