@apifuse/provider-sdk 2.2.0-beta.57 → 2.2.0-beta.59

package/dist/schema.d.ts

@@ -13,6 +13,8 @@ export declare function safeParseSchemaSync<TSchema extends SchemaLike>(schema:
 export declare const APIFUSE_SENSITIVE_META_KEY = "x-apifuse-sensitive";
 export declare const APIFUSE_SENSITIVE_KIND_META_KEY = "x-apifuse-sensitive-kind";
 export declare const APIFUSE_DESCRIPTION_KEY_META_KEY = "x-apifuse-description-key";
+export declare const APIFUSE_CONTENT_TRUST_META_KEY = "x-apifuse-content-trust";
+export declare const APIFUSE_CONTENT_PROVENANCE_META_KEY = "x-apifuse-content-provenance";
 export declare const APIFUSE_REDACTION_MARKER = "<redacted>";
 export type SensitivePathSegment = string | "*";
 export type SensitivePath = readonly SensitivePathSegment[];
@@ -32,6 +34,13 @@ export interface SensitiveFieldOptions {
     description?: string;
 }
 export declare function describeKey<TSchema extends ZodType>(schema: TSchema, key: ProviderLocaleKey | string): TSchema;
+/**
+ * Mark an output field as externally authored text (listing bodies, reviews,
+ * posts) that the provider relays verbatim. Sets both content-trust JSON Schema
+ * meta keys on the field node so the platform can enforce the boundary when it
+ * assembles tool output; validation and the parsed value are unchanged.
+ */
+export declare function untrustedContent<TSchema extends ZodType>(schema: TSchema): TSchema;
 declare module "zod" {
     interface ZodType {
         describeKey(key: ProviderLocaleKey | string): this;

package/dist/schema.js

@@ -41,6 +41,8 @@ export function safeParseSchemaSync(schema, value, fieldPath) {
 export const APIFUSE_SENSITIVE_META_KEY = "x-apifuse-sensitive";
 export const APIFUSE_SENSITIVE_KIND_META_KEY = "x-apifuse-sensitive-kind";
 export const APIFUSE_DESCRIPTION_KEY_META_KEY = "x-apifuse-description-key";
+export const APIFUSE_CONTENT_TRUST_META_KEY = "x-apifuse-content-trust";
+export const APIFUSE_CONTENT_PROVENANCE_META_KEY = "x-apifuse-content-provenance";
 export const APIFUSE_REDACTION_MARKER = "<redacted>";
 export function describeKey(schema, key) {
     const descriptionKey = providerLocaleKey(key);
@@ -50,6 +52,20 @@ export function describeKey(schema, key) {
         [APIFUSE_DESCRIPTION_KEY_META_KEY]: descriptionKey,
     });
 }
+/**
+ * Mark an output field as externally authored text (listing bodies, reviews,
+ * posts) that the provider relays verbatim. Sets both content-trust JSON Schema
+ * meta keys on the field node so the platform can enforce the boundary when it
+ * assembles tool output; validation and the parsed value are unchanged.
+ */
+export function untrustedContent(schema) {
+    const metadata = schema.meta() ?? {};
+    return schema.meta({
+        ...metadata,
+        [APIFUSE_CONTENT_TRUST_META_KEY]: "untrusted",
+        [APIFUSE_CONTENT_PROVENANCE_META_KEY]: "external",
+    });
+}
 const describeKeyMethod = function (key) {
     return describeKey(this, key);
 };

package/dist/server/index.d.ts

@@ -1,6 +1,8 @@
 export type { ProxyCacheStatus, ProxyProtocol, ProxyUserAgentSource, ProxyVendorName, SmartproxyAllocatorBodyClass, } from "../config/loader.js";
 export type { ProxyTelemetryHeaderPayload, ProxyHash, ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "../runtime/proxy-telemetry.js";
 export { RequestTelemetry, closedEnum, type ClosedEnum, type GatewayIngestible, type RequestTelemetryLogPayload, type SpanIndex, type TelemetryContributor, type TelemetryKey, type TenantNeutral, } from "../runtime/request-telemetry.js";
+export { ResolverTelemetryCollector, type ResolverAttemptSample, type ResolverCacheReadTelemetryEvent, type ResolverCacheWriteTelemetryEvent, type ResolverFailoverTelemetryEvent, type ResolverIdentityTelemetryEvent, type ResolverOutcomeTelemetryEvent, type ResolverTelemetryAttemptOutcome, type ResolverTelemetryCacheStatus, type ResolverTelemetryCacheWriteReason, type ResolverTelemetryErrorClass, type ResolverTelemetryHeaderPayload, type ResolverTelemetryIdentitySource, type ResolverTelemetryLogPayload, type ResolverTelemetryOutcome, type ResolverTelemetryPhase, type ResolverTelemetrySink, type ResolverVendorAttemptTelemetryEvent, } from "../runtime/resolver-telemetry.js";
+export type { ResolverVendorUnavailableReason } from "../runtime/resolver-vendors/types.js";
 export type { Span, TraceContext } from "../runtime/trace.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderErrorCauseFrame, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
 export type { ProviderErrorObservability } from "../errors.js";

package/dist/server/index.js

@@ -1,4 +1,5 @@
 export { RequestTelemetry, closedEnum, } from "../runtime/request-telemetry.js";
+export { ResolverTelemetryCollector, } from "../runtime/resolver-telemetry.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
 export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";

package/dist/server/self-test.d.ts

@@ -88,6 +88,10 @@ export type SelfTestAuthFlowInvoke = (args: {
     externalRef?: string;
     input?: Record<string, unknown>;
     context?: Record<string, unknown>;
+    /** Opaque engine state from the previous turn (`engine` in the auth response), sent verbatim. */
+    engine?: {
+        egressLease: string;
+    };
     signal?: AbortSignal;
 }) => Promise<{
     status: number;

package/dist/server/self-test.js

@@ -187,17 +187,21 @@ function logSelfTestCancellation(provider, options, requestId, selected, signal,
 }
 /** Binds the self-test auth-flow driver to a tenant app's /auth pipeline in-process. */
 export function createSelfTestAuthFlowInvoke(app) {
-    return async ({ route, requestId, flowId, connectionId, externalRef, input, context, signal, }) => {
+    return async ({ route, requestId, flowId, connectionId, externalRef, input, context, engine, signal, }) => {
         const response = await app.request(`/auth/${route}`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({
                 requestId,
                 flowId,
+                // Engine ceremony leases are scoped to a tenant; the self-test has no
+                // customer tenant, so it presents a fixed one that never collides.
+                tenantId: "self-test",
                 ...(connectionId ? { connectionId } : {}),
                 ...(externalRef ? { externalRef } : {}),
                 ...(input ? { input } : {}),
                 ...(context ? { context } : {}),
+                ...(engine ? { engine } : {}),
             }),
             ...(signal ? { signal } : {}),
         });
@@ -329,6 +333,7 @@ function parseAuthFlowResponse(result) {
         };
     }
     const contextPatch = objectProperty(result.body, "contextPatch");
+    const egressLease = objectProperty(objectProperty(result.body, "engine"), "egressLease");
     return {
         ok: true,
         turn: {
@@ -339,6 +344,7 @@ function parseAuthFlowResponse(result) {
         ...(contextPatch && typeof contextPatch === "object" && !Array.isArray(contextPatch)
             ? { contextPatch: contextPatch }
             : {}),
+        ...(typeof egressLease === "string" && egressLease ? { engine: { egressLease } } : {}),
     };
 }
 function applyAuthFlowContextPatch(base, patch) {
@@ -499,6 +505,9 @@ async function materializeFlowCredential(execution, inputs, options = {}) {
             ...(options.externalRef ? { externalRef: options.externalRef } : {}),
             input: submitInputs,
             ...(Object.keys(flowContext).length > 0 ? { context: flowContext } : {}),
+            // The ceremony egress lease is engine state, not flow context: carry it the
+            // way the gateway does so the continue turn stays on the start turn's egress.
+            ...(started.engine ? { engine: started.engine } : {}),
             ...(options.signal ? { signal: options.signal } : {}),
         }));
         if (!continued.ok) {

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

@@ -4,6 +4,7 @@ import { type ProviderEngine } from "../engine.js";
 import { type ProviderErrorObservability } from "../errors.js";
 import { type ProviderErrorCategory } from "../observability.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 { SelfTestCancellationLogEvent } from "./self-test.js";
 import { type AuthFlowRequest, type OperationRequest } from "./types.js";
@@ -85,6 +86,7 @@ type ProviderServerLogEventBase = ProviderRequestCost & {
     requestedProviderId?: string;
     status: number;
     proxy?: ProxyTelemetryLogPayload;
+    resolver?: ResolverTelemetryLogPayload;
 };
 export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     level: "info";
@@ -164,7 +166,11 @@ export type ProviderServerOptions<TContext extends Partial<ProviderContext> = Pr
     stt?: SttContext;
     /** Optional OCR override for tests or custom hosts; local/prod normally resolves from env. */
     ocr?: OcrContext;
-    /** Optional resolver override for tests or custom hosts; local/prod normally resolves from env. */
+    /**
+     * Optional resolver override for tests or custom hosts; local/prod normally resolves from env.
+     * SDK chains are reconstructed with each request's telemetry sink. An opaque host
+     * resolver is reported as one custom invocation; its internal vendor work is not exposed.
+     */
     resolver?: ResolverContext;
     /** Optional runtime state override for tests or custom hosts. Production resolves Redis from env and fails closed when unavailable. */
     state?: ProviderRuntimeState;

package/dist/server/serve-implementation.js

@@ -10,7 +10,7 @@ import { validateFailClosedDeclaration } from "../declaration-validation.js";
 import { safeProviderErrorObservability } from "../error-observability.js";
 import { createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, isEngineOwnedEnvName, readEngineProxyCredentials, } from "../engine.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 { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, SDKError, } 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";
@@ -18,6 +18,7 @@ import { createScratchpad } from "../runtime/auth-flow.js";
 import { createProviderCache } from "../runtime/cache.js";
 import { createProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "../runtime/choice.js";
 import { createCredentialContext } from "../runtime/credential.js";
+import { createCeremonyEgressLeaseRuntime, ENGINE_CEREMONY_EGRESS_LEASE, } from "../runtime/egress-lease.js";
 import { createEnvContext } from "../runtime/env.js";
 import { executeOperation } from "../runtime/executor.js";
 import { createHttpClient } from "../runtime/http.js";
@@ -27,12 +28,13 @@ import { createOcrClientFromEnv } from "../runtime/ocr.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 { createUnsupportedResolverClient, } from "../runtime/resolver-shared.js";
+import { ResolverTelemetryCollector, } from "../runtime/resolver-telemetry.js";
+import { createUnsupportedResolverClient, bindResolverTelemetry, inheritResolverTelemetryBinding, } from "../runtime/resolver-shared.js";
 import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
 import { StealthCookieJar } from "../runtime/stealth-cookies.js";
 import { createSttClientFromEnv } from "../runtime/stt.js";
-import { createTraceContext, updateTraceContextExportMetadata, } from "../runtime/trace.js";
+import { createTraceContext, getTraceRecorder, updateTraceContextExportMetadata, } from "../runtime/trace.js";
 import { resolveTraceConfigFromEnv } from "../runtime/trace-config.js";
 import { parseSchema } from "../schema.js";
 import { STATEFUL_NONCE_HEADER as STATEFUL_FORWARDING_NONCE_HEADER, STATEFUL_SIGNATURE_HEADER as STATEFUL_FORWARDING_SIGNATURE_HEADER, STATEFUL_TIMESTAMP_HEADER as STATEFUL_FORWARDING_TIMESTAMP_HEADER, verifyStatefulRequestSignature, } from "../stateful-signing.js";
@@ -268,6 +270,9 @@ function createLazyStealthClient(onCleanupError, ...createArgs) {
                 async fetch(...args) {
                     return (await getSession()).fetch(...args);
                 },
+                async replayChallenged(...args) {
+                    return (await getSession()).replayChallenged(...args);
+                },
                 redirects: {
                     async run(...args) {
                         return (await getSession()).redirects.run(...args);
@@ -304,13 +309,15 @@ function createLazyStealthClient(onCleanupError, ...createArgs) {
 function bindResolverSignalWithoutRuntime(resolver, defaultSignal) {
     if (!defaultSignal)
         return resolver;
-    return {
+    const boundResolver = {
         solve(challenge, signal = defaultSignal, traceRecorder) {
             // Forward the instrumentation trace recorder so resolver.vendor.* spans
             // survive this wrapper. See ResolverSolveWithRecorder in resolver-shared.ts.
             return resolver.solve(challenge, signal, traceRecorder);
         },
     };
+    inheritResolverTelemetryBinding(resolver, boundResolver);
+    return boundResolver;
 }
 function getProviderStealthBaseUrl(provider) {
     const baseUrl = getProviderBaseUrl(provider);
@@ -323,6 +330,73 @@ 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;
+}
+function createStealthChallengeDetection(provider, resolverRuntime, resolverOverride, resolverOptions, trace, signal) {
+    const resolverDeclared = declaresAkamaiSbsdResolver(provider);
+    const detectOnly = provider.stealth?.challengeDetection?.akamaiSbsd === true;
+    if (!resolverDeclared && !detectOnly) {
+        return undefined;
+    }
+    return {
+        akamaiSbsd: {
+            allowedHosts: provider.allowedHosts ?? [],
+            // The profile belongs to the SBSD resolver; a resolver declared for other kinds
+            // may name a different browser without affecting detect-only classification.
+            ...(resolverDeclared && provider.resolver?.clientProfile
+                ? { clientProfile: provider.resolver.clientProfile }
+                : {}),
+            ...(resolverDeclared && resolverRuntime
+                ? {
+                    async solve(challenge, transport, solveSignal) {
+                        const resolver = resolverRuntime.bindResolverSignal((resolverOverride
+                            ? bindResolverTelemetry(resolverOverride, resolverOptions.telemetry)
+                            : undefined) ??
+                            resolverRuntime.createResolverClientFromEnv(provider.resolver, undefined, {
+                                allowedHosts: resolverOptions.allowedHosts,
+                                cache: resolverOptions.cache,
+                                telemetry: resolverOptions.telemetry,
+                                identityScope: resolverOptions.identityScope,
+                                // No proxyIntent: the transport is already bound to the initiating
+                                // request's lease, and a second identity resolution would allocate
+                                // again (and fail closed without allocator credentials) for nothing
+                                // the SBSD adapters consume.
+                                createTransport: () => transport,
+                            }), signal);
+                        // Same span and recorder threading as the instrumented ctx.resolver.solve.
+                        const recorder = getTraceRecorder(trace);
+                        const solve = () => resolver.solve(challenge, solveSignal, recorder ?? undefined);
+                        return recorder
+                            ? recorder.runSpan("resolver.solve", solve, {
+                                attributes: { challenge_kind: challenge.kind },
+                            })
+                            : solve();
+                    },
+                }
+                : {}),
+        },
+    };
+}
 function isProductionProviderBrowserMode(provider, env = process.env) {
     if (provider.runtime !== "browser") {
         return false;
@@ -424,16 +498,28 @@ function createProviderContext(provider, request, operationId, options, state =
         engineCredentials: engineProxyCredentials,
     };
     const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
+    const cache = createProviderCache({ providerId: provider.id });
     let wrappedContext;
+    const { capabilityModules } = options;
+    const resolverOptions = createResolverRuntimeOptions(provider, cache, resolverIdentityScope, proxyPolicy, proxyClientOptions, stealthProfile, scope.resolverTelemetry);
+    const challengeRuntime = createStealthChallengeDetection(provider, capabilityModules.resolver, options.resolver, resolverOptions, scope.trace, signal);
     const stealthClientOptions = {
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
         telemetry: scope.telemetry.proxy,
         engineCredentials: engineProxyCredentials,
         ...(signal ? { signal } : {}),
-        ...(provider.stealth ? { stealth: provider.stealth } : {}),
+        // A declared resolver without a `stealth` block still gets the default Chrome client
+        // (auth FlowContext is not capability-gated), so the runtime must ride along.
+        ...(provider.stealth || challengeRuntime
+            ? {
+                stealth: {
+                    ...(provider.stealth ?? {}),
+                    ...(challengeRuntime ? { challengeRuntime } : {}),
+                },
+            }
+            : {}),
     };
-    const { capabilityModules } = options;
     const logStealthCleanupError = (error) => logProviderCleanupError(options.logger, provider, "operation", operationId, request.requestId, "stealth", error);
     const env = createEnvContext([
         ...providerSecretNames(provider),
@@ -450,7 +536,6 @@ function createProviderContext(provider, request, operationId, options, state =
         headers: request.headers ?? {},
     };
     const requestState = state.forConnection(requestContext.connectionId);
-    const cache = createProviderCache({ providerId: provider.id });
     const bindings = {
         env,
         credential,
@@ -499,22 +584,13 @@ function createProviderContext(provider, request, operationId, options, state =
         ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
         stt: options.stt ?? createSttClientFromEnv(provider.stt),
         resolver: capabilityModules.resolver
-            ? capabilityModules.resolver.bindResolverSignal(options.resolver ??
-                capabilityModules.resolver.createResolverClientFromEnv(provider.resolver, undefined, {
-                    allowedHosts: provider.allowedHosts,
-                    cache,
-                    identityScope: resolverIdentityScope,
-                    ...(proxyPolicy
-                        ? {
-                            proxyIntent: {
-                                mode: proxyPolicy.mode,
-                                ...proxyClientOptions,
-                                ...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
-                            },
-                        }
-                        : {}),
-                }), signal)
-            : bindResolverSignalWithoutRuntime(options.resolver ??
+            ? capabilityModules.resolver.bindResolverSignal((options.resolver
+                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+                : undefined) ??
+                capabilityModules.resolver.createResolverClientFromEnv(provider.resolver, undefined, resolverOptions), signal)
+            : bindResolverSignalWithoutRuntime((options.resolver
+                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+                : undefined) ??
                 createUnsupportedResolverClient("Provider does not declare resolver capability"), signal),
         choice: createProviderChoiceContext({
             providerId: provider.id,
@@ -564,7 +640,7 @@ export function resolveAuthFlowProxyAffinityKey(provider, request) {
         request.providerId ??
         provider.id);
 }
-function createAuthFlowContext(provider, request, options, state, scope, signal) {
+function createAuthFlowContext(provider, request, route, options, state, scope, signal) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
@@ -578,16 +654,49 @@ function createAuthFlowContext(provider, request, options, state, scope, signal)
         telemetry: scope.telemetry.proxy,
         engineCredentials: engineProxyCredentials,
     };
+    // The lease pins the proxy egress a challenged ceremony solved on, so only providers
+    // that declare the akamai_sbsd resolver kind carry one (same predicate as the challenge
+    // runtime). `abort` never evaluates the key or tenant: a user must be able to cancel a
+    // stranded flow even when engine provisioning is broken, and an abort is not a
+    // continuation of the ceremony the lease pins.
+    const ceremonyEgressLease = route !== "abort" &&
+        declaresAkamaiSbsdResolver(provider) &&
+        proxyPolicy &&
+        proxyPolicy.mode !== "disabled"
+        ? createCeremonyEgressLeaseRuntime({
+            tenantId: request.tenantId,
+            providerId: provider.id,
+            flowId: request.flowId,
+            affinityKey: proxyClientOptions.affinityKey,
+            ...(request.engine?.egressLease ? { handle: request.engine.egressLease } : {}),
+        })
+        : undefined;
+    if (route !== "abort" && request.engine?.egressLease && !ceremonyEgressLease) {
+        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 { capabilityModules } = options;
+    const resolverOptions = createResolverRuntimeOptions(provider, cache, resolverIdentityScope, proxyPolicy, proxyClientOptions, stealthProfile, scope.resolverTelemetry);
+    const challengeRuntime = createStealthChallengeDetection(provider, capabilityModules.resolver, options.resolver, resolverOptions, scope.trace, signal);
     const stealthClientOptions = {
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
         telemetry: scope.telemetry.proxy,
         engineCredentials: engineProxyCredentials,
+        ...(ceremonyEgressLease ? { [ENGINE_CEREMONY_EGRESS_LEASE]: ceremonyEgressLease } : {}),
         ...(signal ? { signal } : {}),
-        ...(provider.stealth ? { stealth: provider.stealth } : {}),
+        // A declared resolver without a `stealth` block still gets the default Chrome client
+        // (auth FlowContext is not capability-gated), so the runtime must ride along.
+        ...(provider.stealth || challengeRuntime
+            ? {
+                stealth: {
+                    ...(provider.stealth ?? {}),
+                    ...(challengeRuntime ? { challengeRuntime } : {}),
+                },
+            }
+            : {}),
     };
-    const { capabilityModules } = options;
     const logStealthCleanupError = (error) => logProviderCleanupError(options.logger, provider, "auth", "flow", request.requestId, "stealth", error);
     const credential = request.connection
         ? createCredentialContext({
@@ -597,7 +706,6 @@ function createAuthFlowContext(provider, request, options, state, scope, signal)
             values: request.connection.secrets,
         })
         : undefined;
-    const cache = createProviderCache({ providerId: provider.id });
     const context = wrapWithInstrumentation({
         flowId: request.flowId,
         connectionId: resolveOperationConnectionId(request),
@@ -636,28 +744,23 @@ function createAuthFlowContext(provider, request, options, state, scope, signal)
         ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
         stt: options.stt ?? createSttClientFromEnv(provider.stt),
         resolver: capabilityModules.resolver
-            ? capabilityModules.resolver.bindResolverSignal(options.resolver ??
-                capabilityModules.resolver.createResolverClientFromEnv(provider.resolver, undefined, {
-                    allowedHosts: provider.allowedHosts,
-                    cache,
-                    identityScope: resolverIdentityScope,
-                    ...(proxyPolicy
-                        ? {
-                            proxyIntent: {
-                                mode: proxyPolicy.mode,
-                                ...proxyClientOptions,
-                                ...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
-                            },
-                        }
-                        : {}),
-                }), signal)
-            : bindResolverSignalWithoutRuntime(options.resolver ??
+            ? capabilityModules.resolver.bindResolverSignal((options.resolver
+                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+                : undefined) ??
+                capabilityModules.resolver.createResolverClientFromEnv(provider.resolver, undefined, resolverOptions), signal)
+            : bindResolverSignalWithoutRuntime((options.resolver
+                ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+                : undefined) ??
                 createUnsupportedResolverClient("Provider does not declare resolver capability"), signal),
         auth: createAuthFlowHelpers({ signal }),
     });
     return {
         context,
         getPatch: flowContextStore.getPatch,
+        getEngineState() {
+            const egressLease = ceremonyEgressLease?.handle();
+            return egressLease ? { egressLease } : undefined;
+        },
     };
 }
 const defaultProviderServerLogger = (event) => {
@@ -1199,8 +1302,10 @@ function createRequestScope(input) {
         })
         : createTraceContext();
     const proxyCollector = new ProxyTelemetryCollector();
+    const resolverCollector = new ResolverTelemetryCollector();
     const telemetry = new RequestTelemetry(trace);
     telemetry.register(proxyCollector);
+    telemetry.register(resolverCollector);
     let rootRunner = (fn) => fn();
     let resolveRoot;
     const rootTerminal = new Promise((resolve) => {
@@ -1275,6 +1380,7 @@ function createRequestScope(input) {
     const scope = {
         trace,
         telemetry,
+        resolverTelemetry: resolverCollector,
         enrich(enrichment) {
             if (terminalOutcome)
                 return;
@@ -1384,14 +1490,34 @@ function createRequestScope(input) {
     };
     return scope;
 }
-function responseWithRequestScopeHeaders(response, finished) {
+// A raw `Response` result skips `toErrorResponse`, so its body stays
+// provider-owned, but the observability header is still SDK-owned: derive it
+// from the status. Only timeouts, rate limits, and 5xx are retryable;
+// `isRetryableCategory` would otherwise mark every other 4xx (`upstream_http`)
+// as retryable.
+function rawResponseErrorObservability(status) {
+    return {
+        category: categoryForStatus(status),
+        taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+        retryable: status === 408 || status === 429 || status >= 500,
+    };
+}
+// `rawStatusFallback` is decided by the caller from the outcome, not from a
+// missing snapshot: a failed outcome whose thrown value is `undefined` also has
+// no `errorObservability`, and its 500 carries the SDK envelope, not a raw body.
+function responseWithRequestScopeHeaders(response, finished, rawStatusFallback) {
     const headers = new Headers(response.headers);
     headers.delete(PROVIDER_TELEMETRY_HEADER);
     if (finished.providerTelemetryHeader) {
         headers.set(PROVIDER_TELEMETRY_HEADER, finished.providerTelemetryHeader);
     }
-    if (finished.errorObservability) {
-        headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(finished.errorObservability));
+    headers.delete(ERROR_OBSERVABILITY_HEADER);
+    const errorObservability = finished.errorObservability ??
+        (rawStatusFallback && response.status >= 400
+            ? rawResponseErrorObservability(response.status)
+            : undefined);
+    if (errorObservability) {
+        headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservability));
     }
     return new Response(response.body, {
         headers,
@@ -1402,7 +1528,7 @@ function responseWithRequestScopeHeaders(response, finished) {
 function finalizeRequestResponse(scope, response, outcome) {
     try {
         const error = outcome.kind === "failed" ? outcome.error : undefined;
-        const finalResponse = responseWithRequestScopeHeaders(response, scope.snapshotHeaders(error));
+        const finalResponse = responseWithRequestScopeHeaders(response, scope.snapshotHeaders(error), outcome.kind === "completed");
         scope.terminalize(outcome);
         return finalResponse;
     }
@@ -1679,7 +1805,7 @@ function getSseTransport(operation) {
 function getHttpStreamTransport(operation) {
     return operation.transport?.kind === "http-stream" ? operation.transport : undefined;
 }
-function toAuthFlowResponse(result, contextPatch) {
+function toAuthFlowResponse(result, contextPatch, engine) {
     if (result instanceof Response) {
         return result;
     }
@@ -1689,6 +1815,7 @@ function toAuthFlowResponse(result, contextPatch) {
     return {
         data: result,
         ...(contextPatch ? { contextPatch } : {}),
+        ...(engine ? { engine } : {}),
     };
 }
 function authFlowLocaleFromHeaders(headers) {
@@ -1823,8 +1950,9 @@ async function handleAuthFlow(provider, request, route, options, state, scope, s
     // depend on declared secrets (client ids/secrets), so fail structured before
     // any flow code runs instead of at whatever point the ceremony first reads
     // the env. `abort` stays exempt: a user must always be able to cancel a
-    // stranded flow even when provisioning is broken.
-    const { context, getPatch } = createAuthFlowContext(provider, request, options, state, scope, signal);
+    // stranded flow even when provisioning is broken (createAuthFlowContext
+    // applies the same exemption to the engine ceremony lease).
+    const { context, getPatch, getEngineState } = createAuthFlowContext(provider, request, route, options, state, scope, signal);
     try {
         if (route !== "abort") {
             assertRequiredSecretsPresent(provider, context.env);
@@ -1855,11 +1983,11 @@ async function handleAuthFlow(provider, request, route, options, state, scope, s
             isAuthTurn(result)
             ? materializeAuthFlowTurn(provider, request, result)
             : result;
-        return toAuthFlowResponse(materializedResult, getPatch());
+        return toAuthFlowResponse(materializedResult, getPatch(), getEngineState());
     }
     catch (error) {
         if (error instanceof AuthAbortError) {
-            return toAuthFlowResponse(error.turn, getPatch());
+            return toAuthFlowResponse(error.turn, getPatch(), getEngineState());
         }
         throw error;
     }
@@ -2228,7 +2356,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 const handled = await handleOperation(provider, body, operation, options, state, requestScope, c.req.raw.signal);
                 const response = handled instanceof Response ? handled : c.json(handled);
                 return streaming
-                    ? responseWithRequestScopeHeaders(response, requestScope.snapshotHeaders())
+                    ? responseWithRequestScopeHeaders(response, requestScope.snapshotHeaders(), true)
                     : response;
             };
             const response = streaming

package/dist/server/types.d.ts

@@ -115,6 +115,9 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    engine: z.ZodOptional<z.ZodObject<{
+        egressLease: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
@@ -133,6 +136,9 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
 export declare const AuthFlowSuccessResponseSchema: z.ZodObject<{
     data: z.ZodUnknown;
     contextPatch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodUnknown>>>;
+    engine: z.ZodOptional<z.ZodObject<{
+        egressLease: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const AuthFlowErrorResponseSchema: z.ZodObject<{
     error: z.ZodObject<{

package/dist/server/types.js

@@ -85,10 +85,24 @@ export const AuthFlowRequestSchema = z.object({
     headers: z.record(z.string(), z.string()).optional(),
     input: z.record(z.string(), z.unknown()).optional(),
     context: z.record(z.string(), z.unknown()).optional(),
+    /** Opaque engine state. This is never projected into FlowContext or provider contextPatch. */
+    engine: z
+        .object({
+        egressLease: z.string().min(1).max(16_384).optional(),
+    })
+        .strict()
+        .optional(),
     connection: OperationConnectionSchema.optional(),
 });
 export const AuthFlowSuccessResponseSchema = z.object({
     data: z.unknown(),
     contextPatch: z.record(z.string(), z.unknown().nullable()).optional(),
+    /** Opaque engine state to carry verbatim to the next auth turn. */
+    engine: z
+        .object({
+        egressLease: z.string().min(1).max(16_384).optional(),
+    })
+        .strict()
+        .optional(),
 });
 export const AuthFlowErrorResponseSchema = OperationErrorResponseSchema;

package/dist/stealth/profiles.d.ts

@@ -1,4 +1,4 @@
-import type { StealthProfile, StealthProfileDescriptor, StealthProfileSelection } from "../types.js";
+import type { StealthBrowser, StealthProfile, StealthProfileDescriptor, StealthProfileSelection } from "../types.js";
 export declare const DEFAULT_STEALTH_BROWSER: "chrome";
 export declare const DEFAULT_STEALTH_OS: "macos";
 /** Internal detector used to keep version-pinned string failures actionable. */
@@ -6,4 +6,10 @@ export declare function getVersionPinnedStealthReplacement(name: string): string
 /** Resolve omitted axes and validate that the resulting pair is supported. */
 export declare function resolveStealthProfileSelection(selection: StealthProfileSelection | undefined, base?: StealthProfileDescriptor): StealthProfileDescriptor;
 export declare function getStealthProfile(selection?: StealthProfileSelection): StealthProfile;
+/**
+ * The transport owns the browser version (Chromium follows the pinned wreq-js build), so a
+ * resolver `clientProfile` such as `safari17_0` or `chrome_149` only has to name the same
+ * browser family as the stealth session it runs on.
+ */
+export declare function resolverClientProfileFamily(clientProfile: string): StealthBrowser | undefined;
 export declare function listStealthProfiles(): StealthProfileDescriptor[];