@apifuse/provider-sdk 2.2.0-beta.47 → 2.2.0-beta.49

package/src/runtime/trace-config.ts

@@ -6,9 +6,10 @@ export const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
 
 type EnvLike = Record<string, string | undefined>;
 
-const TRACE_EXPORTER_LOOKUP: Record<Exclude<NonNullable<TraceConfig["exporter"]>, "otlp">, true> = {
+const TRACE_EXPORTER_LOOKUP: Record<NonNullable<TraceConfig["exporter"]>, true> = {
 	console: true,
 	json: true,
+	otlp: true,
 	none: true,
 };
 const TRACE_EXPORTERS = new Set(Object.keys(TRACE_EXPORTER_LOOKUP));
@@ -66,7 +67,7 @@ export function resolveTraceConfigFromEnv(env: EnvLike = process.env): TraceConf
 	if (exporterRaw !== undefined && exporter === "none" && normalizedExporter !== "none") {
 		warnOnce(
 			APIFUSE__TRACE__EXPORTER,
-			`[apifuse] Invalid APIFUSE__TRACE__EXPORTER value "${normalizedExporter ?? exporterRaw}" (OTLP is unsupported for server output); supported exporters are "console", "json", and "none"; falling back to exporter "none".`,
+			`[apifuse] Invalid APIFUSE__TRACE__EXPORTER value "${normalizedExporter ?? exporterRaw}"; supported exporters are "console", "json", "otlp", and "none"; falling back to exporter "none".`,
 		);
 	}
 

package/src/runtime/trace.ts

@@ -21,6 +21,11 @@ export interface CreateTraceContextOptions {
 	onSpan?: (span: Span) => void;
 	exportOptions?: OTLPExportOptions;
 	resourceAttributes?: Record<string, string>;
+	/**
+	 * Applied to a detached copy of each span immediately before OTLP export; never touches
+	 * getSpans() or onSpan. Returning nothing (or throwing) drops that export batch.
+	 */
+	sanitizeSpanForExport?: (span: Span) => Span | undefined;
 }
 
 type SpanHookOptions<T> = {
@@ -41,6 +46,8 @@ type PendingSpan = {
 type CompletedSpanEntry = {
 	sequence: number;
 	span: Span;
+	/** Set once the span has been handed to the exporter so no batch re-sends it. */
+	exported: boolean;
 };
 
 export interface TraceRecorder {
@@ -51,8 +58,6 @@ export const TRACE_RECORDER = Symbol.for("@apifuse/provider-sdk/runtime/trace-re
 
 type InternalTraceContext = TraceContext & {
 	[TRACE_RECORDER]: TraceRecorder;
-	_exportOptions?: OTLPExportOptions;
-	_resourceAttributes?: Record<string, string>;
 };
 
 function buildOTLPExportOptions(config?: TraceConfig): OTLPExportOptions | undefined {
@@ -124,6 +129,20 @@ function insertCompletedSpan(
 	}
 }
 
+/** Hands the hook a copy whose attributes are detached from the recorded span; a hook that returns nothing fails closed. */
+function prepareSpanForExport(
+	span: Span,
+	sanitize: CreateTraceContextOptions["sanitizeSpanForExport"],
+): Span {
+	const copy: Span = { ...span, attributes: { ...span.attributes } };
+	if (!sanitize) return copy;
+	const sanitized = sanitize(copy);
+	if (!sanitized || typeof sanitized !== "object") {
+		throw new Error("sanitizeSpanForExport returned no span");
+	}
+	return sanitized;
+}
+
 export function getTraceRecorder(trace: BaseTraceContext): TraceRecorder | null {
 	return (trace as Partial<InternalTraceContext>)[TRACE_RECORDER] ?? null;
 }
@@ -133,20 +152,41 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 	const completed: CompletedSpanEntry[] = [];
 	const activeSpanStorage = new AsyncLocalStorage<PendingSpan | undefined>();
 	let sequence = 0;
-	let traceContext!: InternalTraceContext;
-
+	// Export configuration (which can carry collector credentials) stays in this closure;
+	// the context object handed to provider code never exposes it.
+	const exportOptions = options.exportOptions;
+	const exportResourceAttributes = options.resourceAttributes
+		? { ...options.resourceAttributes }
+		: undefined;
+	// One trace id per context so every export batch of this request shares it and
+	// two processes can never mint the same id.
+	const exportTraceId = crypto.randomUUID().replace(/-/g, "");
+	let exportScheduled = false;
+
+	// One pending batch per context: roots completing before the flush share it, and a span is
+	// handed to the exporter exactly once, so later roots never re-send earlier spans.
 	const scheduleExport = () => {
-		if (!traceContext._exportOptions) {
+		if (!exportOptions || exportScheduled) {
 			return;
 		}
+		exportScheduled = true;
 
-		const spans = completed.map((entry) => ({ ...entry.span }));
 		setImmediate(() => {
-			void exportSpansOTLP(
-				spans,
-				traceContext._exportOptions as OTLPExportOptions,
-				traceContext._resourceAttributes,
-			);
+			exportScheduled = false;
+			const pending = completed.filter((entry) => !entry.exported);
+			for (const entry of pending) entry.exported = true;
+			if (pending.length === 0) return;
+			// Sanitization runs off the request path; a faulty sanitizer drops the batch, never the request.
+			let spans: Span[];
+			try {
+				spans = pending.map((entry) =>
+					prepareSpanForExport(entry.span, options.sanitizeSpanForExport),
+				);
+			} catch {
+				console.warn("[apifuse] OTLP export skipped; span sanitization failed.");
+				return;
+			}
+			void exportSpansOTLP(spans, exportOptions, exportResourceAttributes, exportTraceId);
 		});
 	};
 
@@ -189,7 +229,11 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 					...(pendingSpan.parentId ? { parentId: pendingSpan.parentId } : {}),
 				};
 
-				insertCompletedSpan(completed, { sequence: pendingSpan.sequence, span }, maxSpans);
+				insertCompletedSpan(
+					completed,
+					{ sequence: pendingSpan.sequence, span, exported: false },
+					maxSpans,
+				);
 				options.onSpan?.(span);
 
 				if (!pendingSpan.parentId) {
@@ -213,17 +257,13 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 		},
 	};
 
-	traceContext = {
+	const traceContext: InternalTraceContext = {
 		span(name, fn) {
 			return recorder.runSpan(name, fn);
 		},
 		getSpans() {
 			return completed.map((entry) => ({ ...entry.span }));
 		},
-		...(options.exportOptions ? { _exportOptions: options.exportOptions } : {}),
-		...(options.resourceAttributes
-			? { _resourceAttributes: { ...options.resourceAttributes } }
-			: {}),
 		[TRACE_RECORDER]: recorder,
 	};
 

package/src/server/self-test.ts

@@ -245,17 +245,10 @@ export function computeSelfTestPlanDigest(provider: ProviderDefinition): string
 
 /**
  * Fail-closed read-only classification: an operation may self-test only when
- * its own metadata marks it read-only (annotations.readOnly or
- * toolRouter.riskClass "read") and nothing marks it side-effecting. Unclassified
- * operations are refused so the endpoint cannot become a mutation oracle.
+ * its authored safety source of truth classifies it as read-only.
  */
 export function isSelfTestReadOnlyOperation(operation: OperationDefinition): boolean {
-	const annotations = operation.annotations;
-	if (annotations?.readOnly === false) return false;
-	if (annotations?.destructive === true) return false;
-	const riskClass = operation.toolRouter?.riskClass;
-	if (riskClass !== undefined && riskClass !== "read") return false;
-	return annotations?.readOnly === true || riskClass === "read";
+	return operation.riskClass === "read";
 }
 
 /** Binds the self-test executor to a tenant app's /v1 pipeline in-process. */

package/src/server/serve-implementation.ts

@@ -8,6 +8,14 @@ import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
 import { validateFailClosedDeclaration } from "../declaration-validation.js";
 import { safeProviderErrorObservability } from "../error-observability.js";
+import {
+	createInProcessProviderEngine,
+	ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES,
+	isEngineOwnedEnvName,
+	readEngineProxyCredentials,
+	type ProviderEngine,
+	type ProviderEngineBindingCandidates,
+} from "../engine.js";
 import {
 	SDK_OWNED_PROVIDER_ERROR_CODES,
 	SDK_RUNTIME_OWNED_ERROR_CODES,
@@ -112,6 +120,7 @@ import type {
 	ProviderErrorStatus,
 	ProviderContext,
 	ProviderDefinition,
+	ProviderFilesContext,
 	ProviderProxyPolicy,
 	ProviderRuntimeState,
 	ProviderStreamEvent,
@@ -262,6 +271,7 @@ type ProviderCapabilityModules = {
 
 type ProviderServerRuntimeOptions = ProviderServerOptions & {
 	readonly capabilityModules: ProviderCapabilityModules;
+	readonly engine: ProviderEngine;
 };
 
 const require = createRequire(import.meta.url);
@@ -518,7 +528,7 @@ function getProviderStealthBaseUrl(provider: ProviderDefinition): string | undef
 }
 
 function getProviderStealthProfile(provider: ProviderDefinition) {
-	return provider.stealth?.profile ? getStealthProfile(provider.stealth.profile) : undefined;
+	return provider.stealth ? getStealthProfile(provider.stealth) : undefined;
 }
 
 function isProductionProviderBrowserMode(provider: ProviderDefinition, env = process.env): boolean {
@@ -647,6 +657,12 @@ function resolveNativeProxyPolicy(provider: ProviderDefinition): ProviderProxyPo
 	return undefined;
 }
 
+function providerSecretNames(provider: ProviderDefinition): string[] {
+	return (provider.secrets?.map((secret) => secret.name) ?? []).filter(
+		(name) => !isEngineOwnedEnvName(name),
+	);
+}
+
 function createProviderContext(
 	provider: ProviderDefinition,
 	request: OperationRequest,
@@ -661,10 +677,12 @@ function createProviderContext(
 	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
 	const stealthProfile = getProviderStealthProfile(provider);
 	const proxyPolicy = resolveNativeProxyPolicy(provider);
+	const engineProxyCredentials = readEngineProxyCredentials();
 	const proxyClientOptions = {
 		upstream: { proxy: provider.proxy },
 		affinityKey: resolveProviderProxyAffinityKey(provider, request, operationId),
 		telemetry: proxyTelemetry,
+		engineCredentials: engineProxyCredentials,
 	};
 	const resolverIdentityScope = resolveProviderResolverIdentityScope(
 		provider,
@@ -676,7 +694,9 @@ function createProviderContext(
 		upstream: proxyClientOptions.upstream,
 		affinityKey: proxyClientOptions.affinityKey,
 		telemetry: proxyTelemetry,
+		engineCredentials: engineProxyCredentials,
 		...(signal ? { signal } : {}),
+		...(provider.stealth ? { stealth: provider.stealth } : {}),
 	};
 	const { capabilityModules } = options;
 	const logStealthCleanupError = (error: unknown) =>
@@ -691,7 +711,7 @@ function createProviderContext(
 		);
 
 	const env = createEnvContext([
-		...(provider.secrets?.map((secret) => secret.name) ?? []),
+		...providerSecretNames(provider),
 		PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 	]);
 	const credential = createCredentialContext({
@@ -706,9 +726,10 @@ function createProviderContext(
 	};
 	const requestState = state.forConnection(requestContext.connectionId);
 	const cache = createProviderCache({ providerId: provider.id });
-	const context = wrapWithInstrumentation({
+	const bindings: ProviderEngineBindingCandidates = {
 		env,
 		credential,
+		...(options.files ? { files: options.files } : {}),
 		request: requestContext,
 		http: createHttpClient(baseUrl, {
 			...proxyClientOptions,
@@ -722,21 +743,8 @@ function createProviderContext(
 		state: requestState,
 		stealth: stealthBaseUrl
 			? capabilityModules.stealth
-				? stealthProfile
-					? capabilityModules.stealth.createStealthClient(
-							stealthBaseUrl,
-							provider.stealth!.profile,
-							stealthClientOptions,
-						)
-					: capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthClientOptions)
-				: stealthProfile
-					? createLazyStealthClient(
-							logStealthCleanupError,
-							stealthBaseUrl,
-							provider.stealth!.profile,
-							stealthClientOptions,
-						)
-					: createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthClientOptions)
+				? capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthClientOptions)
+				: createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthClientOptions)
 			: createStealthStub(),
 		browser:
 			provider.runtime === "browser"
@@ -756,7 +764,9 @@ function createProviderContext(
 							egress: provider.native.network,
 							proxyPolicy: resolveNativeProxyPolicy(provider),
 							affinityKey: proxyClientOptions.affinityKey,
-							credentials: capabilityModules.nativeNetwork!.createEnvVendorCredentialResolver(env),
+							credentials: capabilityModules.nativeNetwork!.createEnvVendorCredentialResolver(
+								createEnvContext([...ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES]),
+							),
 						}),
 					},
 				}
@@ -810,7 +820,10 @@ function createProviderContext(
 					...event,
 				}),
 		}),
-	} as ProviderContext);
+	};
+	const context = wrapWithInstrumentation(
+		options.engine.attach({ provider, bindings }) as ProviderContext,
+	);
 	wrappedContext = context;
 	return context;
 }
@@ -882,6 +895,7 @@ function createAuthFlowContext(
 	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
 	const stealthProfile = getProviderStealthProfile(provider);
 	const proxyPolicy = resolveNativeProxyPolicy(provider);
+	const engineProxyCredentials = readEngineProxyCredentials();
 	const contextData = request.context ?? {};
 	const flowContextStore = createFlowContextStore(
 		provider.context?.keys ?? Object.keys(contextData),
@@ -891,6 +905,7 @@ function createAuthFlowContext(
 		upstream: { proxy: provider.proxy },
 		affinityKey: resolveAuthFlowProxyAffinityKey(provider, request),
 		telemetry: proxyTelemetry,
+		engineCredentials: engineProxyCredentials,
 	};
 	const resolverIdentityScope = resolveProviderResolverIdentityScope(
 		provider,
@@ -901,7 +916,9 @@ function createAuthFlowContext(
 		upstream: proxyClientOptions.upstream,
 		affinityKey: proxyClientOptions.affinityKey,
 		telemetry: proxyTelemetry,
+		engineCredentials: engineProxyCredentials,
 		...(signal ? { signal } : {}),
+		...(provider.stealth ? { stealth: provider.stealth } : {}),
 	};
 	const { capabilityModules } = options;
 	const logStealthCleanupError = (error: unknown) =>
@@ -938,21 +955,8 @@ function createAuthFlowContext(
 			state: state.forConnection(resolveOperationConnectionId(request)),
 			stealth: stealthBaseUrl
 				? capabilityModules.stealth
-					? stealthProfile
-						? capabilityModules.stealth.createStealthClient(
-								stealthBaseUrl,
-								provider.stealth!.profile,
-								stealthClientOptions,
-							)
-						: capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthClientOptions)
-					: stealthProfile
-						? createLazyStealthClient(
-								logStealthCleanupError,
-								stealthBaseUrl,
-								provider.stealth!.profile,
-								stealthClientOptions,
-							)
-						: createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthClientOptions)
+					? capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthClientOptions)
+					: createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthClientOptions)
 				: createStealthStub(),
 			...(provider.native
 				? {
@@ -962,14 +966,14 @@ function createAuthFlowContext(
 								proxyPolicy: resolveNativeProxyPolicy(provider),
 								affinityKey: proxyClientOptions.affinityKey,
 								credentials: capabilityModules.nativeNetwork!.createEnvVendorCredentialResolver(
-									createEnvContext(provider.secrets?.map((secret) => secret.name)),
+									createEnvContext([...ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES]),
 								),
 							}),
 						},
 					}
 				: {}),
 			env: createEnvContext([
-				...(provider.secrets?.map((secret) => secret.name) ?? []),
+				...providerSecretNames(provider),
 				...(provider.auth?.mode === "oauth2_proxied" ? ["APIFUSE__AUTH_PROXY__URL"] : []),
 			]),
 			credential,
@@ -1086,6 +1090,10 @@ export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
 
 export type ProviderServerOptions<TContext extends Partial<ProviderContext> = ProviderContext> = {
 	logger?: ProviderServerLogger;
+	/** Capability attachment boundary. Defaults to the local in-process engine. */
+	engine?: ProviderEngine;
+	/** Request-file resolver supplied by the engine host when `files` is declared. */
+	files?: ProviderFilesContext;
 	/** Optional provider-specific operation executor. Stateful providers use this to preserve provider-local runtime semantics. */
 	operationExecutor?: ProviderServerOperationExecutor<TContext>;
 	/** Optional signed internal executor for stateful owner forwarding. */
@@ -1275,11 +1283,8 @@ function providerObservabilityDetails(
 	const declaredRetryable = sdkOwnsErrorResolution(error)
 		? undefined
 		: declaredErrorCode?.retryable;
-	// Session-expiry surfaces the credential_expired category + the opt-in
-	// retryable signal so Gateway/Credential Service can refresh and re-drive the
-	// operation (see design.md §4.3 D3). Without this branch the auth error would
-	// serialize as a bare 401 with no retryable/category, losing the refresh
-	// signal for exactly the retryOnAuthRefresh operations it is meant to enable.
+	// Session-expiry surfaces the credential_expired category so Gateway and
+	// Credential Service can distinguish an expired credential from other 401s.
 	if (isSessionExpiredError(error)) {
 		return {
 			category: providerErrorOption(error, "category") ?? "credential_expired",
@@ -1496,7 +1501,7 @@ type OperationErrorCodeLookup = ReadonlyMap<string, ReadonlyMap<string, Operatio
 function buildOperationErrorCodeLookup(provider: ProviderDefinition): OperationErrorCodeLookup {
 	return new Map(
 		Object.entries(provider.operations).flatMap(([operationId, operation]) => {
-			const errorCodes = operation.docs?.errorCodes;
+			const errorCodes = operation.errorCodes;
 			return errorCodes?.length
 				? [[operationId, new Map(errorCodes.map((entry) => [entry.code, entry]))] as const]
 				: [];
@@ -1635,7 +1640,7 @@ function logProviderError(
 			? {
 					signal: "unregistered_provider_error_code" as const,
 					signalFix:
-						"Declare this code (with status and retryable) in the operation's docs.errorCodes so it serves its intended status instead of 500.",
+						"Declare this code (with status and retryable) in the operation's errorCodes so it serves its intended status instead of 500.",
 				}
 			: {}),
 		...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
@@ -1704,7 +1709,7 @@ function toJsonSuccessResponse(
 		return new Response(result);
 	}
 
-	const cacheMeta = ctx?.cache.responseMeta();
+	const cacheMeta = ctx && "cache" in ctx ? ctx.cache.responseMeta() : undefined;
 	const retryMeta = ctx ? retryResponseMeta.get(ctx) : undefined;
 	const meta =
 		cacheMeta || retryMeta
@@ -2105,31 +2110,35 @@ async function handleOperation(
 	const cleanup = async () => {
 		if (cleanupCalled) return;
 		cleanupCalled = true;
-		try {
-			ctx.stealth.close?.();
-		} catch (error) {
-			logProviderCleanupError(
-				options.logger,
-				provider,
-				"operation",
-				operationId,
-				request.requestId,
-				"stealth",
-				error,
-			);
+		if ("stealth" in ctx) {
+			try {
+				ctx.stealth.close?.();
+			} catch (error) {
+				logProviderCleanupError(
+					options.logger,
+					provider,
+					"operation",
+					operationId,
+					request.requestId,
+					"stealth",
+					error,
+				);
+			}
 		}
-		try {
-			await ctx.browser.close?.();
-		} catch (error) {
-			logProviderCleanupError(
-				options.logger,
-				provider,
-				"operation",
-				operationId,
-				request.requestId,
-				"browser",
-				error,
-			);
+		if ("browser" in ctx) {
+			try {
+				await ctx.browser.close?.();
+			} catch (error) {
+				logProviderCleanupError(
+					options.logger,
+					provider,
+					"operation",
+					operationId,
+					request.requestId,
+					"browser",
+					error,
+				);
+			}
 		}
 	};
 	try {
@@ -2141,7 +2150,9 @@ async function handleOperation(
 					request,
 					signal,
 				})
-			: await executeOperation(provider, operationId, ctx, request.input);
+			: await executeOperation(provider, operationId, ctx, request.input, {
+					env: createEnvContext(providerSecretNames(provider)),
+				});
 		if (streaming && operation) {
 			return toStreamingResponse(operation, result, cleanup, request.requestId);
 		}
@@ -2427,7 +2438,11 @@ function createServerAppWithCapabilityModules(
 	serverOptions: ProviderServerOptions,
 	capabilityModules: ProviderCapabilityModules,
 ): Hono {
-	const options: ProviderServerRuntimeOptions = { ...serverOptions, capabilityModules };
+	const options: ProviderServerRuntimeOptions = {
+		...serverOptions,
+		capabilityModules,
+		engine: serverOptions.engine ?? createInProcessProviderEngine(),
+	};
 	const app = new Hono();
 	const logger = options.logger ?? defaultProviderServerLogger;
 	const operationErrorCodes = buildOperationErrorCodeLookup(provider);
@@ -2449,7 +2464,7 @@ function createServerAppWithCapabilityModules(
 	// CrashLoopBackOff. Requests still fail closed via the executeOperation gate.
 	const missingSecretsAtBoot = listMissingRequiredSecrets(
 		provider,
-		createEnvContext(provider.secrets?.map((secret) => secret.name)),
+		createEnvContext(providerSecretNames(provider)),
 	);
 	if (missingSecretsAtBoot.length > 0) {
 		logger({
@@ -3155,6 +3170,8 @@ export async function serve<TContext extends Partial<ProviderContext> = Provider
 	const selfTestSecrets = resolveSelfTestMasterSecrets();
 	const serverAppOptions: ProviderServerOptions<TContext> = {
 		logger: options.logger,
+		engine: options.engine,
+		files: options.files,
 		ocr: options.ocr,
 		stt: options.stt,
 		resolver: options.resolver,

package/src/server/trace-output.ts

@@ -1,15 +1,101 @@
+import { isSensitiveFixtureKey, REDACTED_FIXTURE_VALUE } from "../fixture-sanitization.js";
+import {
+	OTEL_EXPORTER_OTLP_ENDPOINT,
+	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+	type OTLPExportOptions,
+	type OTLPExportResolution,
+	type OTLPResourceResolution,
+	resolveOTLPExportOptions,
+	resolveOTLPResourceAttributes,
+} from "../runtime/otlp.js";
 import {
-	resolveTraceContextOptions,
 	type CreateTraceContextOptions,
+	resolveTraceContextOptions,
 	type Span,
 } from "../runtime/trace.js";
-import { sanitizeSpanForOutput } from "../trace-sanitization.js";
+import {
+	sanitizeSpanForOutput,
+	sanitizeSpanNameForOutput,
+	sanitizeTraceAttributes,
+} from "../trace-sanitization.js";
 import type { TraceConfig } from "../types.js";
 
+type EnvLike = Record<string, string | undefined>;
+
+// Warn once per environment object: process.env in production, each injected env in tests.
+const warnedEnvironments = new WeakSet<EnvLike>();
+const warnedResourceEnvironments = new WeakSet<EnvLike>();
+
+function warnDiscardedResourceAttributes(env: EnvLike, resolution: OTLPResourceResolution): void {
+	if (resolution.discarded.length === 0 || warnedResourceEnvironments.has(env)) return;
+	warnedResourceEnvironments.add(env);
+	console.warn(
+		`[apifuse] ${resolution.discarded.join(", ")} could not be parsed as an OTel key=value list and was ignored.`,
+	);
+}
+
+function warnExportDisabled(
+	env: EnvLike,
+	resolution: Exclude<OTLPExportResolution, { status: "resolved" }>,
+): void {
+	if (warnedEnvironments.has(env)) return;
+	warnedEnvironments.add(env);
+	console.warn(
+		resolution.status === "unconfigured"
+			? `[apifuse] OTLP trace export is enabled but no endpoint is configured; set ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT} or ${OTEL_EXPORTER_OTLP_ENDPOINT}. Trace export is disabled.`
+			: `[apifuse] OTLP trace export is enabled but ${resolution.source} ${resolution.reason}. Trace export is disabled.`,
+	);
+}
+
+function resolveServerOTLPExportOptions(
+	config: TraceConfig,
+	env: EnvLike,
+): OTLPExportOptions | undefined {
+	const resolution = resolveOTLPExportOptions(
+		{
+			endpoint: config.otlp?.endpoint ?? config.endpoint,
+			headers: config.otlp?.headers,
+			timeout: config.otlp?.timeout,
+		},
+		env,
+	);
+	if (resolution.status === "resolved") return resolution.options;
+	warnExportDisabled(env, resolution);
+	return undefined;
+}
+
+/**
+ * Per-request attributes carry client-supplied values (request_id) and get the full attribute
+ * sanitizer, exactly as on the console path. Operator-configured attributes from the process
+ * environment are identifiers rather than request data: their values are kept, with control
+ * characters neutralized, length bounded, and secret-named keys redacted.
+ */
+function resolveExportResourceAttributes(
+	requestAttributes: Record<string, string>,
+	env: EnvLike,
+): Record<string, string> {
+	const resolution = resolveOTLPResourceAttributes({}, env);
+	warnDiscardedResourceAttributes(env, resolution);
+	const operatorAttributes = Object.fromEntries(
+		Object.entries(resolution.attributes).map(([key, value]) => [
+			sanitizeSpanNameForOutput(key),
+			isSensitiveFixtureKey(key) ? REDACTED_FIXTURE_VALUE : sanitizeSpanNameForOutput(value),
+		]),
+	);
+	const sanitizedRequestAttributes = Object.fromEntries(
+		Object.entries(sanitizeTraceAttributes(requestAttributes)).map(([key, value]) => [
+			key,
+			String(value),
+		]),
+	);
+	return { ...operatorAttributes, ...sanitizedRequestAttributes };
+}
+
 /** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
 export function resolveServerTraceContextOptions(
 	config: TraceConfig,
 	resourceAttributes: Record<string, string>,
+	env: EnvLike = process.env,
 ): CreateTraceContextOptions {
 	const resolved = resolveTraceContextOptions(config);
 	const outputEnabled = config.enabled !== false && config.exporter !== "none";
@@ -24,9 +110,20 @@ export function resolveServerTraceContextOptions(
 					resolved.onSpan?.(span);
 				}
 			: (consoleHook ?? resolved.onSpan);
+	const exportOptions =
+		outputEnabled && config.exporter === "otlp"
+			? resolveServerOTLPExportOptions(config, env)
+			: undefined;
 
 	return {
 		maxSpans: resolved.maxSpans,
 		onSpan,
+		...(exportOptions
+			? {
+					exportOptions,
+					resourceAttributes: resolveExportResourceAttributes(resourceAttributes, env),
+					sanitizeSpanForExport: (span: Span) => sanitizeSpanForOutput(span),
+				}
+			: {}),
 	};
 }