@apifuse/provider-sdk 2.2.0-beta.13 → 2.2.0-beta.15

package/AUTHORING.md

@@ -393,6 +393,70 @@ External contributors are expected to submit standalone Provider source plus:
 Maintainers own monorepo import under `providers/<id>/`, registry generation,
 deployment projection checks, and release workflows.
 
+### Error responses
+
+Provider-server failures use a stable public envelope:
+
+```json
+{
+  "error": {
+    "code": "UPSTREAM_ERROR",
+    "message": "The upstream service failed",
+    "requestId": "req_123",
+    "retryable": true,
+    "details": { "providerReason": "temporarily_unavailable" }
+  }
+}
+```
+
+`retryable` is always present on responses emitted by the current SDK. Set
+`retryable` in the `ProviderError` options when the provider knows the answer;
+an explicit `true` or `false` wins over SDK derivation. When it is omitted, the
+SDK derives the value for its known error classes and otherwise defaults to
+`false`. During stateful rolling upgrades, the forwarding client also accepts
+an older owner response that omits `retryable` and treats it as `false` without
+loosening the emitted response contract. Existing optional `fix` guidance is
+also preserved when a `ProviderError` supplies it.
+
+`details` belongs exclusively to the provider. The server passes
+`ProviderError.options.details` through verbatim, including strings and arrays,
+and never merges, overwrites, or wraps it. Do not put SDK taxonomy fields there.
+SDK-owned validation and masked-internal-error paths retain their own diagnostic
+details.
+
+SDK observability is emitted separately in the
+`X-ApiFuse-Error-Observability` response header as compact, single-line JSON:
+
+```json
+{"category":"upstream_http","taxonomyVersion":"2026-05-26","retryable":true,"upstreamStatus":502}
+```
+
+Treat this header as telemetry, not as provider-controlled public error detail.
+Its category, taxonomy version, retryability, and optional upstream status match
+the structured `provider_request_failed` log event.
+
+Registered error-code mappings take precedence for every `ProviderError`,
+including `ValidationError`:
+
+| Error code or fallback | HTTP status |
+| --- | ---: |
+| `AUTH_REQUIRED`, `reauth_required` | 401 |
+| `MISSING_SECRET` | 400 |
+| `NOT_FOUND`, `not_found`, `NO_DATA` | 404 |
+| `RATE_LIMITED`, `UPSTREAM_RATE_LIMIT`, `LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR` | 429 |
+| `UPSTREAM_ERROR`, `BLOCKED` | 502 |
+| `STT_UNAVAILABLE`, `UNSUPPORTED_STT_BACKEND`, `STATEFUL_FORWARDING_REPLAY_CACHE_FULL` | 503 |
+| Unregistered input `ValidationError` code | 400 |
+| Other unregistered `ProviderError` code | 500 |
+
+An unregistered non-validation `ProviderError` code returns HTTP 500 and emits
+the greppable `unregistered_provider_error_code` signal with the code in the
+structured failure log. Before publishing a new code, register its status in
+the SDK mapping and add it to the mapping tests; declaring it only in operation
+documentation does not change runtime status selection. The HTTP 400
+`ValidationError` behavior is only the fallback for unregistered input
+validation codes; a registered code such as `NOT_FOUND` retains its mapped 404.
+
 ### Declared secrets are SDK-enforced
 
 Environment/secret presence validation is single-sourced in the SDK. Declare
@@ -411,12 +475,12 @@ secrets: [
 The runtime validates every `required: true` declaration before any operation
 handler or auth-flow handler (except `abort`) runs. When a required secret is
 unset or whitespace-only, the invocation fails with the canonical structured
-error — code `MISSING_SECRET`, HTTP 400, `details.category:
-"credential_unavailable"`, `retryable: false`, and a `fix` naming every missing
-secret — across `/v1/{operation}`, self-test probes, `apifuse perf`, and
-`apifuse record`. The server also emits a `provider_secrets_missing` warn log
-at boot so unprovisioned deployments are visible immediately without crashing
-the pod.
+error — code `MISSING_SECRET`, HTTP 400, top-level `retryable: false`, and a
+`fix` naming every missing secret — across `/v1/{operation}`, self-test probes,
+`apifuse perf`, and `apifuse record`. Its error-observability header carries the
+`credential_unavailable` category. The server also emits a
+`provider_secrets_missing` warn log at boot so unprovisioned deployments are
+visible immediately without crashing the pod.
 
 Provider-local presence re-validation is **deprecated**: do not write
 `requireServiceKey`/`requireApiKey`-style guards that re-check `ctx.env.get()`

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.15
+
+- Release candidate for main commit b5ebd25e48f6502e4ddb775d4e0a25f5c8276712.
+
+## 2.2.0-beta.14
+
+- Release candidate for main commit 3491acd253ca17b517985e8a618f1c2904a664a9.
+
 ## 2.2.0-beta.13
 
 - Release candidate for main commit 75e840d0614aea3b99a1e5cef4f93f8cdccf0507.
@@ -82,6 +90,10 @@
 
 ## Unreleased
 
+- Add an opt-in same-origin redirect hop policy to `ctx.http`, with bounded manual following and typed failures before a refused target is requested.
+- Enforce provider-declared native TCP/TLS egress before proxy or socket setup, with revocable and expiring dynamic grants plus typed authorization failures; providers without a native egress declaration retain legacy behavior.
+- **Breaking:** Provider error `details` is now passed through verbatim; SDK observability fields (`category`, `taxonomyVersion`, `upstreamStatus`, and derived `retryable`) are no longer merged into the public body. Emitted error envelopes now require top-level `retryable`, while inbound stateful forwarding tolerates an older owner response that omits it and defaults it to `false`. The removed observability metadata is available in the new `X-ApiFuse-Error-Observability` response header.
+- Unregistered `ProviderError` codes now default to HTTP 500 instead of 400 and emit an `unregistered_provider_error_code` structured-log signal; registered mappings remain unchanged and take precedence over the HTTP 400 fallback for unregistered input `ValidationError` codes.
 - Add an opt-in native connection idle read timeout with a typed error, independently from TCP/SOCKS/TLS establishment deadlines.
 - Add opt-in `maxBodyBytes` enforcement to stealth fetches and redirect hops, aborting oversized decoded response streams with `response_too_large`.
 - Resolve relative date tokens in fixture requests before input-schema validation, add KST capture-date `fixtures.recordedAt` metadata, and support explicit KST/UTC calendars in the shared health-input resolver.

package/dist/define.js

@@ -1,5 +1,6 @@
 import ms from "ms";
 import { ProviderError, ValidationError } from "./errors.js";
+import { NativeEgressPolicyValidationError, validateNativeProviderConfig, } from "./native-egress-policy.js";
 import { safeParseSchemaSync } from "./schema.js";
 import { resolveHealthCheckInputDateTokens } from "./server/self-test-input-tokens.js";
 import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
@@ -1407,6 +1408,14 @@ export function defineProvider(config) {
     validateProviderHealthMonitor(config.id, config.healthProbe ?? config.healthMonitor, config.healthProbe !== undefined ? "healthProbe" : "healthMonitor");
     validateOperationFixtures(config.id, operations);
     validateProviderDeployment(config.id, config.deployment);
+    try {
+        validateNativeProviderConfig(config.native);
+    }
+    catch (error) {
+        if (error instanceof NativeEgressPolicyValidationError)
+            throw new ValidationError(error.message);
+        throw error;
+    }
     validateProviderProxy(config);
     validateProviderStt(config);
     if (config.runtime === "browser" && !config.browser)

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import type { ProviderErrorCategory } from "./observability.js";
+import type { HttpRedirectFailureReason } from "./types.js";
 export type ProviderErrorOptions = {
     fix?: string;
     code?: string;
@@ -44,9 +45,21 @@ export declare class TransportError extends ProviderError {
     readonly upstreamStatus?: number;
     constructor(message: string, options?: TransportErrorOptions);
 }
+export type HttpRedirectErrorOptions = TransportErrorOptions & {
+    reason: HttpRedirectFailureReason;
+    /** Redacted redirect target suitable for provider diagnostics. */
+    target?: string;
+};
+/** Raised when an opt-in ctx.http redirect policy refuses or cannot resolve a hop. */
+export declare class HttpRedirectError extends TransportError {
+    readonly reason: HttpRedirectFailureReason;
+    readonly target?: string;
+    constructor(message: string, options: HttpRedirectErrorOptions);
+}
 export declare function isProviderError(value: unknown): value is ProviderError;
 export declare function isSessionExpiredError(value: unknown): value is SessionExpiredError;
 export declare function isTransportError(value: unknown): value is TransportError;
+export declare function isValidationError(value: unknown): value is ValidationError;
 export declare class ProviderSecretError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }

package/dist/errors.js

@@ -8,6 +8,7 @@ const PROVIDER_ERROR_BRAND = Symbol.for("@apifuse/provider-sdk/error-brand@1");
 const PROVIDER_ERROR_BRAND_VALUE = 1;
 const SESSION_EXPIRED_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/session-expired@1");
 const TRANSPORT_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/transport@1");
+const VALIDATION_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/validation@1");
 // Defines a non-enumerable, non-writable, non-configurable own data property.
 // Immutable + own means a guard can trust it via a single descriptor read
 // without invoking attacker-controlled getters or accepting inherited brands.
@@ -96,6 +97,7 @@ export class ValidationError extends ProviderError {
         super(message, options);
         this.name = "ValidationError";
         this.zodError = options?.zodError;
+        defineErrorBrand(this, VALIDATION_BRAND, true);
     }
 }
 export class TransportError extends ProviderError {
@@ -109,6 +111,25 @@ export class TransportError extends ProviderError {
         defineErrorBrand(this, TRANSPORT_BRAND, true);
     }
 }
+/** Raised when an opt-in ctx.http redirect policy refuses or cannot resolve a hop. */
+export class HttpRedirectError extends TransportError {
+    reason;
+    target;
+    constructor(message, options) {
+        const { reason, target, ...transportOptions } = options;
+        super(message, {
+            ...transportOptions,
+            code: `http_redirect_${reason}`,
+            details: {
+                reason,
+                ...(target ? { target } : {}),
+            },
+        });
+        this.name = "HttpRedirectError";
+        this.reason = reason;
+        this.target = target;
+    }
+}
 // Cross-module type guards. Prefer these over `instanceof` at any boundary that
 // may receive an error from a different copy/entrypoint of the SDK (see the HTTP
 // server error boundary). They recognize branded errors regardless of which
@@ -122,6 +143,10 @@ export function isSessionExpiredError(value) {
 export function isTransportError(value) {
     return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
 }
+export function isValidationError(value) {
+    return (isProviderError(value) &&
+        (hasOwnBrand(value, VALIDATION_BRAND, true) || value.name === "ValidationError"));
+}
 export class ProviderSecretError extends ProviderError {
     constructor(message, options) {
         super(message, { code: "provider_secret_error", ...options });

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { type CreateCredentialContextOptions, createCredentialContext, } from ".
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, } from "./runtime/native-network.js";
+export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, } from "./runtime/native-network.js";
 export type { Insight, InsightSeverity } from "./runtime/insights.js";
 export { generateInsights } from "./runtime/insights.js";
 export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation.js";
@@ -34,10 +34,10 @@ export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { type CreateTraceContextOptions, createTraceContext, type Span, type TraceContext, } from "./runtime/trace.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
-export { createServerApp, type ServeOptions, serve } from "./server/index.js";
+export { createServerApp, ERROR_OBSERVABILITY_HEADER, type ServeOptions, serve, } from "./server/index.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";

package/dist/index.js

@@ -20,7 +20,7 @@ export { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
+export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
 export { generateInsights } from "./runtime/insights.js";
 export { wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { prevalidate } from "./runtime/prevalidate.js";
@@ -31,7 +31,7 @@ export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { createTraceContext, } from "./runtime/trace.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, z, } from "./schema.js";
-export { createServerApp, serve } from "./server/index.js";
+export { createServerApp, ERROR_OBSERVABILITY_HEADER, serve, } from "./server/index.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";

package/dist/native-egress-policy.d.ts

@@ -0,0 +1,27 @@
+import type { NativeTcpPortRange, NativeTcpTlsMode } from "./types.js";
+export type StaticEgressRuleSnapshot = {
+    readonly host: string;
+    readonly ports: readonly number[];
+    readonly tls: NativeTcpTlsMode;
+};
+export type DynamicEgressRuleSnapshot = {
+    readonly sourceHost?: string;
+    readonly sourceHostSuffixes: readonly string[];
+    readonly sourcePorts: readonly number[];
+    readonly sourcePortRanges: readonly NativeTcpPortRange[];
+    readonly targetHostSuffixes: readonly string[];
+    readonly targetPorts: readonly number[];
+    readonly targetPortRanges: readonly NativeTcpPortRange[];
+    readonly tls: NativeTcpTlsMode;
+    readonly ttlMs?: number;
+    readonly maxGrants?: number;
+};
+export type NativeEgressPolicySnapshot = {
+    readonly staticRules: readonly StaticEgressRuleSnapshot[];
+    readonly dynamicRules: readonly DynamicEgressRuleSnapshot[];
+};
+export declare class NativeEgressPolicyValidationError extends Error {
+    constructor(message: string);
+}
+export declare function parseNativeEgressPolicy(value: unknown): NativeEgressPolicySnapshot;
+export declare function validateNativeProviderConfig(value: unknown): void;

package/dist/native-egress-policy.js

@@ -0,0 +1,225 @@
+const NATIVE_PROVIDER_FIELD_RECORD = {
+    network: true,
+};
+const NATIVE_NETWORK_FIELD_RECORD = {
+    tcp: true,
+    dynamicTcp: true,
+};
+const NATIVE_TCP_RULE_FIELD_RECORD = {
+    host: true,
+    ports: true,
+    tls: true,
+};
+const NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD = {
+    sourceHost: true,
+    sourceHostSuffixes: true,
+    sourcePorts: true,
+    sourcePortRanges: true,
+    targetHostSuffixes: true,
+    targetPorts: true,
+    targetPortRanges: true,
+    tls: true,
+    ttlMs: true,
+    maxGrants: true,
+};
+const NATIVE_TCP_PORT_RANGE_FIELD_RECORD = {
+    start: true,
+    end: true,
+};
+const NATIVE_PROVIDER_FIELDS = Object.keys(NATIVE_PROVIDER_FIELD_RECORD);
+const NATIVE_NETWORK_FIELDS = Object.keys(NATIVE_NETWORK_FIELD_RECORD);
+const NATIVE_TCP_RULE_FIELDS = Object.keys(NATIVE_TCP_RULE_FIELD_RECORD);
+const NATIVE_DYNAMIC_TCP_RULE_FIELDS = Object.keys(NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD);
+const NATIVE_TCP_PORT_RANGE_FIELDS = Object.keys(NATIVE_TCP_PORT_RANGE_FIELD_RECORD);
+export class NativeEgressPolicyValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NativeEgressPolicyValidationError";
+    }
+}
+function fail(message) {
+    throw new NativeEgressPolicyValidationError(message);
+}
+function dataRecord(value, fieldPath, allowed) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail(`${fieldPath} must be an object`);
+    const prototype = Reflect.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        fail(`${fieldPath} must be a plain object`);
+    const record = {};
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string")
+            fail(`${fieldPath} must not contain symbol fields`);
+        if (!allowed.includes(key))
+            fail(`Unknown field ${fieldPath}.${key}`);
+        const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !("value" in descriptor))
+            fail(`${fieldPath}.${key} must be a data field`);
+        record[key] = descriptor.value;
+    }
+    return record;
+}
+function dataArray(value, fieldPath) {
+    if (!Array.isArray(value))
+        fail(`${fieldPath} must be an array`);
+    const result = [];
+    for (const key of Reflect.ownKeys(value)) {
+        if (key === "length")
+            continue;
+        if (typeof key !== "string" || !/^(?:0|[1-9]\d*)$/.test(key))
+            fail(`${fieldPath} must not contain non-index fields`);
+        const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !("value" in descriptor))
+            fail(`${fieldPath}[${key}] must be a data field`);
+        result[Number(key)] = descriptor.value;
+    }
+    if (result.length !== value.length)
+        fail(`${fieldPath} must not be sparse`);
+    for (let index = 0; index < result.length; index += 1) {
+        if (!(index in result))
+            fail(`${fieldPath} must not be sparse`);
+    }
+    return result;
+}
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 31 || code === 127)
+            return true;
+    }
+    return false;
+}
+function host(value, fieldPath, suffix = false) {
+    if (typeof value !== "string" ||
+        !value.trim() ||
+        hasControlCharacter(value) ||
+        /\s/.test(value) ||
+        value.includes("://"))
+        fail(`${fieldPath} must be a non-empty hostname`);
+    if (value.includes("*"))
+        fail(`${fieldPath} must be an exact ${suffix ? "DNS suffix" : "hostname"}, not a wildcard`);
+    const normalized = value.trim().toLowerCase().replace(/\.$/, "");
+    if (!normalized)
+        fail(`${fieldPath} must be a non-empty hostname`);
+    return normalized;
+}
+function port(value, fieldPath) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > 65_535)
+        fail(`${fieldPath} must be an integer from 1 to 65535`);
+    return value;
+}
+function ports(value, fieldPath) {
+    return dataArray(value, fieldPath).map((value, index) => port(value, `${fieldPath}[${index}]`));
+}
+function hostSuffixes(value, fieldPath) {
+    return dataArray(value, fieldPath).map((value, index) => host(value, `${fieldPath}[${index}]`, true));
+}
+function ranges(value, fieldPath) {
+    return dataArray(value, fieldPath).map((value, index) => {
+        const rangePath = `${fieldPath}[${index}]`;
+        const record = dataRecord(value, rangePath, NATIVE_TCP_PORT_RANGE_FIELDS);
+        const start = port(record.start, `${rangePath}.start`);
+        const end = port(record.end, `${rangePath}.end`);
+        if (start > end)
+            fail(`${rangePath}.start must not exceed end`);
+        return { start, end };
+    });
+}
+function tls(value, fieldPath) {
+    if (value !== "required" && value !== "allowed" && value !== "disabled")
+        fail(`${fieldPath} must be required, allowed, or disabled`);
+    return value;
+}
+function positiveInteger(value, fieldPath) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+        fail(`${fieldPath} must be a positive integer`);
+    return value;
+}
+export function parseNativeEgressPolicy(value) {
+    try {
+        const policy = dataRecord(value, "native.network", NATIVE_NETWORK_FIELDS);
+        const staticRules = policy.tcp === undefined
+            ? []
+            : dataArray(policy.tcp, "native.network.tcp").map((value, index) => {
+                const fieldPath = `native.network.tcp[${index}]`;
+                const rule = dataRecord(value, fieldPath, NATIVE_TCP_RULE_FIELDS);
+                const declaredPorts = ports(rule.ports, `${fieldPath}.ports`);
+                if (declaredPorts.length === 0)
+                    fail(`${fieldPath}.ports must not be empty`);
+                return {
+                    host: host(rule.host, `${fieldPath}.host`),
+                    ports: declaredPorts,
+                    tls: tls(rule.tls, `${fieldPath}.tls`),
+                };
+            });
+        const dynamicRules = policy.dynamicTcp === undefined
+            ? []
+            : dataArray(policy.dynamicTcp, "native.network.dynamicTcp").map((value, index) => {
+                const fieldPath = `native.network.dynamicTcp[${index}]`;
+                const rule = dataRecord(value, fieldPath, NATIVE_DYNAMIC_TCP_RULE_FIELDS);
+                const sourceHost = rule.sourceHost === undefined
+                    ? undefined
+                    : host(rule.sourceHost, `${fieldPath}.sourceHost`);
+                const sourceHostSuffixes = rule.sourceHostSuffixes === undefined
+                    ? []
+                    : hostSuffixes(rule.sourceHostSuffixes, `${fieldPath}.sourceHostSuffixes`);
+                if (sourceHost === undefined && sourceHostSuffixes.length === 0)
+                    fail(`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes list`);
+                const sourcePorts = rule.sourcePorts === undefined
+                    ? []
+                    : ports(rule.sourcePorts, `${fieldPath}.sourcePorts`);
+                const sourcePortRanges = rule.sourcePortRanges === undefined
+                    ? []
+                    : ranges(rule.sourcePortRanges, `${fieldPath}.sourcePortRanges`);
+                if (sourcePorts.length === 0 && sourcePortRanges.length === 0)
+                    fail(`${fieldPath} must declare a non-empty sourcePorts or sourcePortRanges list`);
+                const targetHostSuffixes = hostSuffixes(rule.targetHostSuffixes, `${fieldPath}.targetHostSuffixes`);
+                if (targetHostSuffixes.length === 0)
+                    fail(`${fieldPath}.targetHostSuffixes must not be empty`);
+                const targetPorts = rule.targetPorts === undefined
+                    ? []
+                    : ports(rule.targetPorts, `${fieldPath}.targetPorts`);
+                const targetPortRanges = rule.targetPortRanges === undefined
+                    ? []
+                    : ranges(rule.targetPortRanges, `${fieldPath}.targetPortRanges`);
+                if (targetPorts.length === 0 && targetPortRanges.length === 0)
+                    fail(`${fieldPath} must declare a non-empty targetPorts or targetPortRanges list`);
+                return {
+                    ...(sourceHost === undefined ? {} : { sourceHost }),
+                    sourceHostSuffixes,
+                    sourcePorts,
+                    sourcePortRanges,
+                    targetHostSuffixes,
+                    targetPorts,
+                    targetPortRanges,
+                    tls: tls(rule.tls, `${fieldPath}.tls`),
+                    ...(rule.ttlMs === undefined
+                        ? {}
+                        : { ttlMs: positiveInteger(rule.ttlMs, `${fieldPath}.ttlMs`) }),
+                    ...(rule.maxGrants === undefined
+                        ? {}
+                        : { maxGrants: positiveInteger(rule.maxGrants, `${fieldPath}.maxGrants`) }),
+                };
+            });
+        return { staticRules, dynamicRules };
+    }
+    catch (error) {
+        if (error instanceof NativeEgressPolicyValidationError)
+            throw error;
+        throw new NativeEgressPolicyValidationError("Native egress policy could not be inspected safely");
+    }
+}
+export function validateNativeProviderConfig(value) {
+    if (value === undefined)
+        return;
+    try {
+        const native = dataRecord(value, "native", NATIVE_PROVIDER_FIELDS);
+        if (native.network !== undefined)
+            parseNativeEgressPolicy(native.network);
+    }
+    catch (error) {
+        if (error instanceof NativeEgressPolicyValidationError)
+            throw error;
+        throw new NativeEgressPolicyValidationError("Native provider config could not be inspected safely");
+    }
+}

package/dist/provider.d.ts

@@ -3,10 +3,10 @@ export type { CredentialsAuthChallengeDefinition, CredentialsAuthChallengeReques
 export { createFormCeremony } from "./ceremonies/index.js";
 export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, type ProviderChoiceTokenErrorReason, type ProviderChoiceTokenPayload, parseProviderChoiceToken, } from "./choice-token.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
-export { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
+export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
-export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, } from "./runtime/native-network.js";
+export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types.js";
+export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, } from "./runtime/native-network.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/provider.js

@@ -2,9 +2,9 @@ export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, define
 export { createFormCeremony } from "./ceremonies/index.js";
 export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, parseProviderChoiceToken, } from "./choice-token.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
-export { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
+export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, z, } from "./schema.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
+export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/runtime/executor.js

@@ -1,4 +1,5 @@
-import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
+import { isSessionExpiredError, isValidationError, ProviderError, SessionExpiredError, ValidationError, } from "../errors.js";
+import { z } from "zod";
 import { parseSchema } from "../schema.js";
 import { assertRequiredSecretsPresent } from "./secrets.js";
 export function isStreamingOperation(provider, operationId) {
@@ -59,5 +60,19 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
     if (isStreamingOperation(provider, operationId)) {
         return result;
     }
-    return parseSchema(operation.output, result, `operations.${operationId}.output`);
+    try {
+        return await parseSchema(operation.output, result, `operations.${operationId}.output`);
+    }
+    catch (cause) {
+        if (!(cause instanceof z.ZodError) && !isValidationError(cause)) {
+            throw cause;
+        }
+        throw new ValidationError(`Operation handler output failed schema validation.`, {
+            code: "OUTPUT_VALIDATION_FAILED",
+            category: "output_validation",
+            retryable: false,
+            zodError: isValidationError(cause) ? cause.zodError : cause,
+            ...(cause instanceof Error ? { cause } : {}),
+        });
+    }
 }