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

package/src/schema.ts

@@ -83,6 +83,8 @@ export function safeParseSchemaSync(
 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 type SensitivePathSegment = string | "*";
@@ -127,6 +129,21 @@ export function describeKey<TSchema extends ZodType>(
 	});
 }
 
+/**
+ * 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<TSchema extends ZodType>(schema: TSchema): TSchema {
+	const metadata = schema.meta() ?? {};
+	return schema.meta({
+		...metadata,
+		[APIFUSE_CONTENT_TRUST_META_KEY]: "untrusted",
+		[APIFUSE_CONTENT_PROVENANCE_META_KEY]: "external",
+	});
+}
+
 declare module "zod" {
 	interface ZodType {
 		describeKey(key: ProviderLocaleKey | string): this;

package/src/server/index.ts

@@ -23,6 +23,27 @@ export {
 	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,

package/src/server/self-test.ts

@@ -117,6 +117,8 @@ 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;
@@ -343,6 +345,7 @@ export function createSelfTestAuthFlowInvoke(app: {
 		externalRef,
 		input,
 		context,
+		engine,
 		signal,
 	}) => {
 		const response = await app.request(`/auth/${route}`, {
@@ -351,10 +354,14 @@ export function createSelfTestAuthFlowInvoke(app: {
 			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 } : {}),
 		});
@@ -550,6 +557,7 @@ type ParsedAuthFlowTurn =
 			ok: true;
 			turn: { kind: string; data?: unknown; expectedInput?: unknown };
 			contextPatch?: Record<string, unknown>;
+			engine?: { egressLease: string };
 	  }
 	| { ok: false; code: string; message: string; httpStatus: number };
 
@@ -578,6 +586,7 @@ function parseAuthFlowResponse(result: { status: number; body: unknown }): Parse
 		};
 	}
 	const contextPatch = objectProperty(result.body, "contextPatch");
+	const egressLease = objectProperty(objectProperty(result.body, "engine"), "egressLease");
 	return {
 		ok: true,
 		turn: {
@@ -588,6 +597,7 @@ function parseAuthFlowResponse(result: { status: number; body: unknown }): Parse
 		...(contextPatch && typeof contextPatch === "object" && !Array.isArray(contextPatch)
 			? { contextPatch: contextPatch as Record<string, unknown> }
 			: {}),
+		...(typeof egressLease === "string" && egressLease ? { engine: { egressLease } } : {}),
 	};
 }
 
@@ -777,6 +787,9 @@ async function materializeFlowCredential(
 				...(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 } : {}),
 			}),
 		);

package/src/server/serve-implementation.ts

@@ -29,6 +29,7 @@ import {
 	isTransportError,
 	isValidationError,
 	ProviderError,
+	SDKError,
 	type ProviderErrorObservability,
 	type ProviderErrorOptions,
 } from "../errors.js";
@@ -55,6 +56,10 @@ import {
 	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";
@@ -80,9 +85,15 @@ import {
 	type TenantNeutral,
 	type TenantOpaqueKeys,
 } from "../runtime/request-telemetry.js";
+import {
+	ResolverTelemetryCollector,
+	type ResolverTelemetryLogPayload,
+} from "../runtime/resolver-telemetry.js";
 import type * as ResolverRuntimeModule from "../runtime/resolver.js";
 import {
 	createUnsupportedResolverClient,
+	bindResolverTelemetry,
+	inheritResolverTelemetryBinding,
 	type ResolverSolveWithRecorder,
 } from "../runtime/resolver-shared.js";
 import {
@@ -96,9 +107,11 @@ import {
 } from "../runtime/state.js";
 import { StealthCookieJar } from "../runtime/stealth-cookies.js";
 import type * as StealthRuntimeModule from "../runtime/stealth.js";
+import type { StealthChallengeRuntime } from "../runtime/stealth-akamai-sbsd.js";
 import { createSttClientFromEnv } from "../runtime/stt.js";
 import {
 	createTraceContext,
+	getTraceRecorder,
 	type TraceContext as RuntimeTraceContext,
 	type TraceRecorder,
 	updateTraceContextExportMetadata,
@@ -513,6 +526,9 @@ function createLazyStealthClient(
 				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);
@@ -553,7 +569,7 @@ function bindResolverSignalWithoutRuntime(
 	defaultSignal: AbortSignal | undefined,
 ): ResolverContext {
 	if (!defaultSignal) return resolver;
-	return {
+	const boundResolver: ResolverContext = {
 		solve(challenge, signal = defaultSignal, traceRecorder?: TraceRecorder) {
 			// Forward the instrumentation trace recorder so resolver.vendor.* spans
 			// survive this wrapper. See ResolverSolveWithRecorder in resolver-shared.ts.
@@ -564,6 +580,8 @@ function bindResolverSignalWithoutRuntime(
 			);
 		},
 	};
+	inheritResolverTelemetryBinding(resolver, boundResolver);
+	return boundResolver;
 }
 
 function getProviderStealthBaseUrl(provider: ProviderDefinition): string | undefined {
@@ -579,6 +597,99 @@ function getProviderStealthProfile(provider: ProviderDefinition) {
 	return provider.stealth ? getStealthProfile(provider.stealth) : undefined;
 }
 
+type ResolverRuntimeOptions = ResolverRuntimeModule.ResolverRuntimeOptions;
+
+/** One option set for ctx.resolver and the automatic SBSD solve, so both share identity scope, cache, proxy intent, and telemetry. */
+function createResolverRuntimeOptions(
+	provider: ProviderDefinition,
+	cache: ReturnType<typeof createProviderCache>,
+	identityScope: string,
+	proxyPolicy: ProviderProxyPolicy | undefined,
+	proxyClientOptions: Omit<
+		NonNullable<ResolverRuntimeOptions["proxyIntent"]>,
+		"mode" | "userAgent"
+	>,
+	stealthProfile: { readonly userAgent: string } | undefined,
+	telemetry: ResolverTelemetryCollector,
+): ResolverRuntimeOptions {
+	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: ProviderDefinition): boolean {
+	return provider.resolver?.kinds.some((kind) => kind === "akamai_sbsd") === true;
+}
+
+function createStealthChallengeDetection(
+	provider: ProviderDefinition,
+	resolverRuntime: typeof ResolverRuntimeModule | undefined,
+	resolverOverride: ResolverContext | undefined,
+	resolverOptions: ResolverRuntimeOptions,
+	trace: RuntimeTraceContext,
+	signal: AbortSignal | undefined,
+): StealthChallengeRuntime | undefined {
+	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,
+							) as ResolverContext & Partial<ResolverSolveWithRecorder>;
+							// 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: ProviderDefinition, env = process.env): boolean {
 	if (provider.runtime !== "browser") {
 		return false;
@@ -714,6 +825,7 @@ function providerSecretNames(provider: ProviderDefinition): string[] {
 type RequestScopeContext = {
 	trace: RuntimeTraceContext;
 	telemetry: RequestTelemetry;
+	resolverTelemetry: ResolverTelemetryCollector;
 };
 
 function createProviderContext(
@@ -741,16 +853,43 @@ function createProviderContext(
 		proxyClientOptions.affinityKey,
 		request.requestId,
 	);
+	const cache = createProviderCache({ providerId: provider.id });
 	let wrappedContext: ProviderContext | undefined;
+	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: unknown) =>
 		logProviderCleanupError(
 			options.logger,
@@ -777,7 +916,6 @@ function createProviderContext(
 		headers: request.headers ?? {},
 	};
 	const requestState = state.forConnection(requestContext.connectionId);
-	const cache = createProviderCache({ providerId: provider.id });
 	const bindings: ProviderEngineBindingCandidates = {
 		env,
 		credential,
@@ -829,25 +967,20 @@ function createProviderContext(
 		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 } : {}),
-										},
-									}
-								: {}),
-						}),
+					(options.resolver
+						? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+						: undefined) ??
+						capabilityModules.resolver.createResolverClientFromEnv(
+							provider.resolver,
+							undefined,
+							resolverOptions,
+						),
 					signal,
 				)
 			: bindResolverSignalWithoutRuntime(
-					options.resolver ??
+					(options.resolver
+						? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+						: undefined) ??
 						createUnsupportedResolverClient("Provider does not declare resolver capability"),
 					signal,
 				),
@@ -927,6 +1060,7 @@ export function resolveAuthFlowProxyAffinityKey(
 function createAuthFlowContext(
 	provider: ProviderDefinition,
 	request: AuthFlowRequest,
+	route: AuthRoute,
 	options: ProviderServerRuntimeOptions,
 	state: ProviderRuntimeState,
 	scope: RequestScopeContext,
@@ -934,6 +1068,7 @@ function createAuthFlowContext(
 ): {
 	context: FlowContext;
 	getPatch: () => Record<string, unknown | null> | undefined;
+	getEngineState: () => AuthFlowSuccessResponse["engine"];
 } {
 	const baseUrl = getProviderBaseUrl(provider);
 	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
@@ -951,20 +1086,72 @@ function createAuthFlowContext(
 		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: unknown) =>
 		logProviderCleanupError(
 			options.logger,
@@ -983,8 +1170,6 @@ function createAuthFlowContext(
 				values: request.connection.secrets,
 			})
 		: undefined;
-	const cache = createProviderCache({ providerId: provider.id });
-
 	const context: FlowContext = wrapWithInstrumentation({
 		flowId: request.flowId,
 		connectionId: resolveOperationConnectionId(request),
@@ -1026,25 +1211,20 @@ function createAuthFlowContext(
 		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 } : {}),
-										},
-									}
-								: {}),
-						}),
+					(options.resolver
+						? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+						: undefined) ??
+						capabilityModules.resolver.createResolverClientFromEnv(
+							provider.resolver,
+							undefined,
+							resolverOptions,
+						),
 					signal,
 				)
 			: bindResolverSignalWithoutRuntime(
-					options.resolver ??
+					(options.resolver
+						? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
+						: undefined) ??
 						createUnsupportedResolverClient("Provider does not declare resolver capability"),
 					signal,
 				),
@@ -1054,6 +1234,10 @@ function createAuthFlowContext(
 	return {
 		context,
 		getPatch: flowContextStore.getPatch,
+		getEngineState() {
+			const egressLease = ceremonyEgressLease?.handle();
+			return egressLease ? { egressLease } : undefined;
+		},
 	};
 }
 
@@ -1082,6 +1266,7 @@ type ProviderServerLogEventBase = ProviderRequestCost & {
 	requestedProviderId?: string;
 	status: number;
 	proxy?: ProxyTelemetryLogPayload;
+	resolver?: ResolverTelemetryLogPayload;
 };
 
 export type ProviderServerLogEvent =
@@ -1167,7 +1352,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;
@@ -1888,8 +2077,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: <T>(fn: () => Promise<T>) => Promise<T> = (fn) => fn();
 	let resolveRoot!: (outcome: RequestTerminalOutcome) => void;
 	const rootTerminal = new Promise<RequestTerminalOutcome>((resolve) => {
@@ -1967,6 +2158,7 @@ function createRequestScope(input: {
 	const scope: RequestScope = {
 		trace,
 		telemetry,
+		resolverTelemetry: resolverCollector,
 		enrich(enrichment): void {
 			if (terminalOutcome) return;
 			if (enrichment.route !== undefined) details.route = enrichment.route;
@@ -2089,17 +2281,40 @@ function createRequestScope(input: {
 	return scope;
 }
 
+// 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: number): ErrorObservabilityDetails {
+	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: Response,
 	finished: RequestScopeFinishResult,
+	rawStatusFallback: boolean,
 ): Response {
 	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,
@@ -2118,6 +2333,7 @@ function finalizeRequestResponse(
 		const finalResponse = responseWithRequestScopeHeaders(
 			response,
 			scope.snapshotHeaders(error),
+			outcome.kind === "completed",
 		);
 		scope.terminalize(outcome);
 		return finalResponse;
@@ -2484,6 +2700,7 @@ function getHttpStreamTransport(
 function toAuthFlowResponse(
 	result: unknown,
 	contextPatch: Record<string, unknown | null> | undefined,
+	engine: AuthFlowSuccessResponse["engine"],
 ): Response | AuthFlowSuccessResponse {
 	if (result instanceof Response) {
 		return result;
@@ -2496,6 +2713,7 @@ function toAuthFlowResponse(
 	return {
 		data: result,
 		...(contextPatch ? { contextPatch } : {}),
+		...(engine ? { engine } : {}),
 	};
 }
 
@@ -2672,10 +2890,12 @@ async function handleAuthFlow(
 	// 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(
+	// 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,
@@ -2715,10 +2935,10 @@ async function handleAuthFlow(
 			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;
 	} finally {
@@ -3185,7 +3405,7 @@ function createServerAppWithCapabilityModules(
 				);
 				const response = handled instanceof Response ? handled : c.json(handled);
 				return streaming
-					? responseWithRequestScopeHeaders(response, requestScope.snapshotHeaders())
+					? responseWithRequestScopeHeaders(response, requestScope.snapshotHeaders(), true)
 					: response;
 			};
 			const response = streaming