@apifuse/provider-sdk 2.2.0-beta.40 → 2.2.0-beta.41

package/dist/server/serve-implementation.js

@@ -6,8 +6,10 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
 import { validateFailClosedDeclaration } from "../declaration-validation.js";
+import { safeProviderErrorObservability } from "../error-observability.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, } from "../errors.js";
+import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, sourceForCategory, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
@@ -42,6 +44,32 @@ const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
 /** Compact SDK-owned error classification emitted separately from the public response body. */
 export const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
+// Provider errors normally expose `options` through an own data property, but
+// providers can replace that property with a throwing accessor. Provider-controlled
+// accessor failures are absorbed into canonical classification rather than
+// propagated. By contract, read `options` directly instead of the public
+// `fix`/`details` convenience getters; provider-controlled accessors are not trusted.
+function providerErrorOption(error, key) {
+    if (!isProviderError(error))
+        return undefined;
+    try {
+        return error.options?.[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+function providerErrorCode(error) {
+    if (!isProviderError(error))
+        return undefined;
+    try {
+        const code = error.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"];
 const retryResponseMeta = new WeakMap();
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
@@ -655,16 +683,17 @@ function publicErrorSource(error, category) {
     if (error instanceof StatefulRoutingDeadlineError)
         return "apifuse";
     if (isProviderError(error)) {
-        if (error.code === MISSING_SECRET_CODE)
+        const code = providerErrorCode(error);
+        if (code === MISSING_SECRET_CODE)
             return "apifuse";
-        if (error.code === "UPSTREAM_ERROR" || error.code === "BLOCKED") {
+        if (code === "UPSTREAM_ERROR" || code === "BLOCKED") {
             return "upstream_failure";
         }
     }
     return sourceForCategory(category);
 }
-function toErrorResponse(error, requestId, declaredErrorCode) {
-    const observability = errorObservabilityDetails(error, declaredErrorCode);
+function toErrorResponse(error, requestId, observabilityDetails) {
+    const observability = observabilityDetails;
     const source = publicErrorSource(error, observability.category);
     if (error instanceof StatefulRoutingDeadlineError) {
         return {
@@ -678,15 +707,15 @@ function toErrorResponse(error, requestId, declaredErrorCode) {
         };
     }
     if (isProviderError(error)) {
-        const details = error.details;
+        const details = providerErrorOption(error, "details");
         return {
             error: {
-                code: error.code ?? "provider_error",
+                code: providerErrorCode(error) ?? "provider_error",
                 message: publicProviderErrorMessage(error),
                 ...(requestId ? { requestId } : {}),
                 retryable: observability.retryable,
                 source,
-                ...(error.fix ? { fix: error.fix } : {}),
+                ...(providerErrorOption(error, "fix") ? { fix: providerErrorOption(error, "fix") } : {}),
                 ...(details !== undefined ? { details } : {}),
             },
         };
@@ -740,9 +769,9 @@ function providerObservabilityDetails(error, declaredErrorCode) {
     // signal for exactly the retryOnAuthRefresh operations it is meant to enable.
     if (isSessionExpiredError(error)) {
         return {
-            category: error.options?.category ?? "credential_expired",
+            category: providerErrorOption(error, "category") ?? "credential_expired",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? declaredRetryable ?? false,
+            retryable: providerErrorOption(error, "retryable") ?? declaredRetryable ?? false,
         };
     }
     // Missing-secret errors carry the canonical credential_unavailable category
@@ -750,27 +779,27 @@ function providerObservabilityDetails(error, declaredErrorCode) {
     // the upstream. Matched by code (not constructor) so both the SDK-owned
     // runtime gate and any not-yet-migrated provider-thrown MISSING_SECRET
     // serialize identically, including across duplicate SDK module instances.
-    if (isProviderError(error) && error.code === MISSING_SECRET_CODE) {
+    if (isProviderError(error) && providerErrorCode(error) === MISSING_SECRET_CODE) {
         return {
-            category: error.options?.category ?? "credential_unavailable",
+            category: providerErrorOption(error, "category") ?? "credential_unavailable",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? declaredRetryable ?? false,
+            retryable: providerErrorOption(error, "retryable") ?? declaredRetryable ?? false,
         };
     }
     if (!isTransportError(error)) {
         return undefined;
     }
-    const isProxyPoolCode = error.code === PROXY_POOL_EXHAUSTED_CODE ||
-        error.code === PROXY_EDGE_AUTH_REJECTED_CODE ||
-        error.code === "PROXY_ALLOCATION_FAILED";
-    const category = error.options?.category ??
+    const isProxyPoolCode = providerErrorCode(error) === PROXY_POOL_EXHAUSTED_CODE ||
+        providerErrorCode(error) === PROXY_EDGE_AUTH_REJECTED_CODE ||
+        providerErrorCode(error) === "PROXY_ALLOCATION_FAILED";
+    const category = providerErrorOption(error, "category") ??
         (isProxyPoolCode
             ? "proxy_pool"
-            : error.code === PROXY_AUTH_IP_DENIED_CODE
+            : providerErrorCode(error) === PROXY_AUTH_IP_DENIED_CODE
                 ? "anti_bot_blocked"
-                : error.code === "transport_timeout"
+                : providerErrorCode(error) === "transport_timeout"
                     ? "timeout"
-                    : error.code === "transport_network_error"
+                    : providerErrorCode(error) === "transport_network_error"
                         ? "network"
                         : error.upstreamStatus
                             ? categoryForStatus(error.upstreamStatus)
@@ -778,23 +807,24 @@ function providerObservabilityDetails(error, declaredErrorCode) {
     return {
         category,
         taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-        retryable: error.options?.retryable ??
+        retryable: providerErrorOption(error, "retryable") ??
             (category === "upstream_http" && error.upstreamStatus
                 ? error.upstreamStatus >= 500
                 : isRetryableCategory(category)),
         ...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
     };
 }
-function errorObservabilityDetails(error, declaredErrorCode) {
+function classifiedErrorObservabilityDetails(error, declaredErrorCode) {
     const effectiveDeclaration = sdkOwnsErrorResolution(error) ? undefined : declaredErrorCode;
     const providerDetails = providerObservabilityDetails(error, effectiveDeclaration);
     if (providerDetails)
         return providerDetails;
     if (error instanceof z.ZodError || isValidationError(error)) {
         const declaredStatus = effectiveDeclaration?.status;
+        const providerCategory = providerErrorOption(error, "category");
         return {
-            category: isProviderError(error) && error.options?.category
-                ? error.options.category
+            category: providerCategory
+                ? providerCategory
                 : isEmittableErrorStatus(declaredStatus) &&
                     categoryForStatus(declaredStatus) === "upstream_rejected"
                     ? "upstream_rejected"
@@ -803,7 +833,7 @@ function errorObservabilityDetails(error, declaredErrorCode) {
                         : "input_validation",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
             retryable: isProviderError(error)
-                ? (error.options?.retryable ?? effectiveDeclaration?.retryable ?? false)
+                ? (providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false)
                 : false,
         };
     }
@@ -820,15 +850,15 @@ function errorObservabilityDetails(error, declaredErrorCode) {
         // status (409/410/422) classify as upstream_rejected unless the
         // author set an explicit category.
         const declaredStatus = effectiveDeclaration?.status;
-        const rejectionDefault = error.code === "UPSTREAM_REJECTED" ||
+        const rejectionDefault = providerErrorCode(error) === "UPSTREAM_REJECTED" ||
             (isEmittableErrorStatus(declaredStatus) &&
                 categoryForStatus(declaredStatus) === "upstream_rejected")
             ? "upstream_rejected"
             : "provider_error";
         return {
-            category: error.options?.category ?? rejectionDefault,
+            category: providerErrorOption(error, "category") ?? rejectionDefault,
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? effectiveDeclaration?.retryable ?? false,
+            retryable: providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false,
         };
     }
     return {
@@ -837,9 +867,17 @@ function errorObservabilityDetails(error, declaredErrorCode) {
         retryable: false,
     };
 }
-function responseWithErrorObservability(response, error, declaredErrorCode) {
+function errorObservabilityDetails(error, declaredErrorCode) {
+    const details = classifiedErrorObservabilityDetails(error, declaredErrorCode);
+    const providerObservability = safeProviderErrorObservability(error);
+    return {
+        ...details,
+        ...(providerObservability ? { providerObservability } : {}),
+    };
+}
+function responseWithErrorObservability(response, observabilityDetails) {
     const headers = new Headers(response.headers);
-    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error, declaredErrorCode)));
+    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(observabilityDetails));
     return new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
@@ -848,20 +886,20 @@ function responseWithErrorObservability(response, error, declaredErrorCode) {
 }
 function publicProviderErrorMessage(error) {
     if (isTransportError(error)) {
-        if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
+        if (providerErrorCode(error) === PROXY_AUTH_IP_DENIED_CODE) {
             return error.message;
         }
-        if (error.code === PROXY_EDGE_AUTH_REJECTED_CODE) {
+        if (providerErrorCode(error) === PROXY_EDGE_AUTH_REJECTED_CODE) {
             return error.message;
         }
-        if (error.code === PROXY_POOL_EXHAUSTED_CODE) {
+        if (providerErrorCode(error) === PROXY_POOL_EXHAUSTED_CODE) {
             return error.message;
         }
-        if (error.code === "transport_timeout")
+        if (providerErrorCode(error) === "transport_timeout")
             return "Request timed out";
-        if (error.code === "transport_network_error")
+        if (providerErrorCode(error) === "transport_network_error")
             return "Network error";
-        if (error.code === "upstream_http_error" && error.status) {
+        if (providerErrorCode(error) === "upstream_http_error" && error.status) {
             return `Upstream request failed with status ${error.status}`;
         }
         if (error.status) {
@@ -887,17 +925,18 @@ function toStatusCode(error, declaredErrorCode) {
         }
         // Canonical SDK code → status mapping lives in error-resolution.ts so
         // the authoring lint and this runtime path share one source of truth.
-        if (typeof error.code === "string") {
-            const mappedStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(error.code);
+        const code = providerErrorCode(error);
+        if (typeof code === "string") {
+            const mappedStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(code);
             if (mappedStatus !== undefined) {
                 return mappedStatus;
             }
         }
         if (isTransportError(error)) {
-            return error.code === "transport_timeout" ? 504 : 502;
+            return providerErrorCode(error) === "transport_timeout" ? 504 : 502;
         }
         if (isValidationError(error)) {
-            return error.options?.category === "output_validation" ? 500 : 400;
+            return providerErrorOption(error, "category") === "output_validation" ? 500 : 400;
         }
         return 500;
     }
@@ -912,9 +951,10 @@ function sdkOwnsErrorResolution(error) {
         return true;
     if (error instanceof StatefulRoutingDeadlineError)
         return true;
-    return (isProviderError(error) &&
-        typeof error.code === "string" &&
-        SDK_RUNTIME_OWNED_ERROR_CODES.has(error.code));
+    if (!isProviderError(error))
+        return false;
+    const code = providerErrorCode(error);
+    return typeof code === "string" && SDK_RUNTIME_OWNED_ERROR_CODES.has(code);
 }
 function buildOperationErrorCodeLookup(provider) {
     return new Map(Object.entries(provider.operations).flatMap(([operationId, operation]) => {
@@ -925,9 +965,10 @@ function buildOperationErrorCodeLookup(provider) {
     }));
 }
 function declaredErrorCodeFor(error, operationId, lookup) {
-    if (!operationId || !isProviderError(error) || typeof error.code !== "string")
+    const code = providerErrorCode(error);
+    if (!operationId || !code)
         return undefined;
-    return lookup.get(operationId)?.get(error.code);
+    return lookup.get(operationId)?.get(code);
 }
 function extractRequestId(raw) {
     if (!raw || typeof raw !== "object") {
@@ -937,6 +978,13 @@ function extractRequestId(raw) {
     return typeof value === "string" ? value : undefined;
 }
 const MAX_PROVIDER_ERROR_CAUSE_FRAMES = 5;
+const MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH = 300;
+function providerErrorCauseMessage(message) {
+    const sanitized = sanitizeDiagnosticText(message);
+    return sanitized.length > MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH
+        ? `${sanitized.slice(0, MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH)}… [truncated]`
+        : sanitized;
+}
 function providerErrorCauseChain(error) {
     if (!(error instanceof Error) && !isProviderError(error))
         return undefined;
@@ -948,19 +996,24 @@ function providerErrorCauseChain(error) {
         !seen.has(cause)) {
         seen.add(cause);
         const message = cause.message;
+        const providerObservability = safeProviderErrorObservability(cause);
+        const causeCode = providerErrorCode(cause);
         frames.push({
             errorClass: cause.name,
-            ...(isProviderError(cause) && typeof cause.code === "string" ? { code: cause.code } : {}),
+            ...(causeCode !== undefined ? { code: causeCode } : {}),
+            message: providerErrorCauseMessage(message),
             messageLength: message.length,
             messageFingerprint: createHash("sha256").update(message).digest("hex").slice(0, 12),
+            ...(providerObservability ? { providerObservability } : {}),
         });
         cause = cause.cause;
     }
     return frames.length > 0 ? frames : undefined;
 }
-function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode, proxyTelemetry) {
+function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode, proxyTelemetry, observabilityDetails) {
+    const providerCode = isProviderError(error) ? providerErrorCode(error) : undefined;
     const code = isProviderError(error)
-        ? (error.code ?? "provider_error")
+        ? (providerCode ?? "provider_error")
         : error instanceof z.ZodError
             ? "invalid_request"
             : error instanceof StatefulRoutingDeadlineError
@@ -969,15 +1022,21 @@ 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);
-    const details = errorObservabilityDetails(error, declaredErrorCode);
+    const details = observabilityDetails;
     const isUnregisteredProviderErrorCode = status === 500 &&
         isProviderError(error) &&
         !isValidationError(error) &&
-        typeof error.code === "string" &&
-        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code) &&
+        typeof providerCode === "string" &&
+        !SDK_OWNED_PROVIDER_ERROR_CODES.has(providerCode) &&
         declaredErrorCode === undefined;
     const proxy = proxyTelemetry?.toLogPayload();
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
+    // The logger is caller-supplied and may mutate the event synchronously.
+    // Give it an independent snapshot so those mutations cannot corrupt the
+    // observability header serialized immediately afterwards.
+    const providerObservability = details.providerObservability
+        ? { ...details.providerObservability }
+        : undefined;
     emit({
         level: status >= 500 ? "error" : "warn",
         event: "provider_request_failed",
@@ -992,6 +1051,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         errorClass,
         message,
         ...(causeChain ? { causeChain } : {}),
+        ...(providerObservability ? { providerObservability } : {}),
         ...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
         errorCategory: details.category,
         taxonomyVersion: details.taxonomyVersion,
@@ -1629,7 +1689,8 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
     }
     app.notFound((c) => {
         const error = new ProviderError("Not found", { code: "not_found", retryable: false });
-        return responseWithErrorObservability(c.json(toErrorResponse(error), 404), error);
+        const observabilityDetails = errorObservabilityDetails(error);
+        return responseWithErrorObservability(c.json(toErrorResponse(error, undefined, observabilityDetails), 404), observabilityDetails);
     });
     app.get("/health", (c) => c.json({
         status: "ok",
@@ -1744,12 +1805,14 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
         catch (error) {
             const declaredErrorCode = declaredErrorCodeFor(error, operationId, operationErrorCodes);
             const status = toStatusCode(error, declaredErrorCode);
-            if (isProviderError(error) && error.code === "STATEFUL_FORWARDING_REPLAY_CACHE_FULL") {
+            if (isProviderError(error) &&
+                providerErrorCode(error) === "STATEFUL_FORWARDING_REPLAY_CACHE_FULL") {
                 c.header("Retry-After", String(STATEFUL_FORWARDING_REPLAY_RETRY_AFTER_SECONDS));
             }
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "operation", operationId || operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, declaredErrorCode), status), error, declaredErrorCode);
+            const observabilityDetails = errorObservabilityDetails(error, declaredErrorCode);
+            logProviderError(logger, provider, "operation", operationId || operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode, undefined, observabilityDetails);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, observabilityDetails), status), observabilityDetails);
         }
     });
     app.post("/v1/:operation", async (c) => {
@@ -1780,11 +1843,12 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
             const declaredErrorCode = declaredErrorCodeFor(error, operation, operationErrorCodes);
             const status = toStatusCode(error, declaredErrorCode);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode, proxyTelemetry);
+            const observabilityDetails = errorObservabilityDetails(error, declaredErrorCode);
+            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode, proxyTelemetry, observabilityDetails);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, declaredErrorCode), status), error, declaredErrorCode);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, observabilityDetails), status), observabilityDetails);
         }
     });
     app.post("/auth/start", async (c) => {
@@ -1809,11 +1873,12 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "start", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const observabilityDetails = errorObservabilityDetails(error);
+            logProviderError(logger, provider, "auth", "start", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry, observabilityDetails);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, observabilityDetails), status), observabilityDetails);
         }
     });
     app.post("/auth/continue", async (c) => {
@@ -1838,11 +1903,12 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "continue", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const observabilityDetails = errorObservabilityDetails(error);
+            logProviderError(logger, provider, "auth", "continue", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry, observabilityDetails);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, observabilityDetails), status), observabilityDetails);
         }
     });
     app.post("/auth/poll", async (c) => {
@@ -1867,11 +1933,12 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "poll", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const observabilityDetails = errorObservabilityDetails(error);
+            logProviderError(logger, provider, "auth", "poll", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry, observabilityDetails);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, observabilityDetails), status), observabilityDetails);
         }
     });
     app.post("/auth/refresh", async (c) => {
@@ -1896,11 +1963,12 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "refresh", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const observabilityDetails = errorObservabilityDetails(error);
+            logProviderError(logger, provider, "auth", "refresh", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry, observabilityDetails);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, observabilityDetails), status), observabilityDetails);
         }
     });
     app.post("/auth/disconnect", async (c) => {
@@ -1925,11 +1993,12 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "disconnect", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const observabilityDetails = errorObservabilityDetails(error);
+            logProviderError(logger, provider, "auth", "disconnect", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry, observabilityDetails);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, observabilityDetails), status), observabilityDetails);
         }
     });
     return app;

package/dist/types.d.ts

@@ -640,13 +640,22 @@ export interface HealthCheckCaseResult {
  * so authors get IntelliSense and compile-time errors when accessing fields
  * that do not exist on the operation's declared output schema.
  */
-export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
+export type HealthCheckCase<TInput = unknown, TOutput = unknown> = {
     /** Human-readable case name; unique within the suite. */
     name: string;
     /** Optional longer description shown on ops dashboards. */
     description?: string;
     /** Input passed to the operation handler for this case. */
     input: TInput;
+    /** Override per-case degradation threshold (ms); falls back to the suite default. */
+    degradedThresholdMs?: number;
+    /** Override per-case timeout in milliseconds; falls back to the suite/provider/runtime default. */
+    timeoutMs?: number;
+    /** Expected outcome for "negative" cases (e.g., expecting a degraded baseline). Default: `"ok"`. */
+    expectedStatus?: "ok" | "degraded";
+    /** Runtime gate (env-driven); if returns false the case is skipped & logged. */
+    enabled?: () => boolean;
+} & ({
     /**
      * Optional runtime input preparation hook for volatile probes. Use this when
      * the durable probe input must be derived from a live read-only operation
@@ -664,15 +673,14 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
      * + lambda only.
      */
     assertions: (ctx: HealthCheckAssertionContext<TOutput>) => void | Promise<void> | HealthCheckCaseResult | Promise<HealthCheckCaseResult>;
-    /** Override per-case degradation threshold (ms); falls back to the suite default. */
-    degradedThresholdMs?: number;
-    /** Override per-case timeout in milliseconds; falls back to the suite/provider/runtime default. */
-    timeoutMs?: number;
-    /** Expected outcome for "negative" cases (e.g., expecting a degraded baseline). Default: `"ok"`. */
-    expectedStatus?: "ok" | "degraded";
-    /** Runtime gate (env-driven); if returns false the case is skipped & logged. */
-    enabled?: () => boolean;
-}
+    /** Declarative scenarios replace the imperative preparation and assertion hooks. */
+    scenario?: never;
+} | {
+    /** Declarative scenario executed by the health-monitor runtime. */
+    scenario: HealthScenario;
+    prepareInput?: never;
+    assertions?: never;
+});
 /**
  * Operation-level health-check suite. At least one case is required when
  * present. All cases share the suite's interval and default timeout.

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.40",
+	"version": "2.2.0-beta.41",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -128,8 +128,7 @@
 		"@microsoft/api-extractor": "^7.58.13",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
-		"ajv": "^8.17",
-		"typescript": "6.0.3"
+		"ajv": "^8.17"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
@@ -146,6 +145,7 @@
 		"safe-regex": "^2.1",
 		"socks": "^2.8.9",
 		"tough-cookie": "^6.0.2",
+		"typescript": "6.0.3",
 		"wreq-js": "3.0.0",
 		"zod": "^4.4.3"
 	},

package/src/cli/commands.ts

@@ -3,6 +3,7 @@ export type ApifuseCommandName =
 	| "dev"
 	| "check"
 	| "sync-assets"
+	| "migrate-shape"
 	| "submit-check"
 	| "bounty-check"
 	| "record"
@@ -55,6 +56,14 @@ export const COMMAND_MANIFEST: Record<
 		examples: ["apifuse sync-assets .", "apifuse sync-assets . --check"],
 		modulePath: "./apifuse-sync-assets",
 	},
+	"migrate-shape": {
+		name: "migrate-shape",
+		summary:
+			"Migrate a provider index.ts from the single-phase defineProvider shape to the two-phase declaration builder.",
+		usage: "apifuse migrate-shape [path] [--check] [--json]",
+		examples: ["apifuse migrate-shape .", "apifuse migrate-shape . --check"],
+		modulePath: "./apifuse-migrate-shape",
+	},
 	"submit-check": {
 		name: "submit-check",
 		summary:
@@ -113,6 +122,7 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"dev",
 	"check",
 	"sync-assets",
+	"migrate-shape",
 	"submit-check",
 	"record",
 	"test",

package/src/cli/create.ts

@@ -519,6 +519,12 @@ export async function buildProviderCreatePlan(
 				sdkSpecifier,
 			}),
 		},
+		{
+			path: resolve(providerRoot, "provider.json"),
+			content: await renderTemplate("provider.json.tpl", {
+				PROVIDER_ID: options.name,
+			}),
+		},
 		{
 			path: resolve(providerRoot, "Dockerfile"),
 			content: await renderTemplate("Dockerfile.tpl", {}),