@apifuse/provider-sdk 2.1.0-beta.3 → 2.1.0-beta.4

package/src/server/serve.ts

@@ -1,24 +1,56 @@
 import { Hono } from "hono";
 import { z } from "zod";
-
 import { ProviderError, TransportError } from "../errors";
+import {
+	categoryForStatus,
+	isRetryableCategory,
+	PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+	type ProviderErrorCategory,
+} from "../observability";
 import { createScratchpad } from "../runtime/auth-flow";
 import { createBrowserClient } from "../runtime/browser";
+import { createProviderCache } from "../runtime/cache";
 import { createCredentialContext } from "../runtime/credential";
 import { createEnvContext } from "../runtime/env";
 import { executeOperation } from "../runtime/executor";
 import { createHttpClient } from "../runtime/http";
+import { wrapWithInstrumentation } from "../runtime/instrumentation";
 import { getProviderBaseUrl } from "../runtime/provider";
-import { createTlsClient } from "../runtime/tls";
+import {
+	PROXY_AUTH_IP_DENIED_CODE,
+	PROXY_EDGE_AUTH_REJECTED_CODE,
+	PROXY_POOL_EXHAUSTED_CODE,
+} from "../runtime/proxy-errors";
+import {
+	PROVIDER_TELEMETRY_HEADER,
+	ProxyTelemetryCollector,
+} from "../runtime/proxy-telemetry";
+import { createUnsupportedProviderRuntimeState } from "../runtime/state";
+import { createStealthClient } from "../runtime/stealth";
+import { createSttClientFromEnv } from "../runtime/stt";
 import { createTraceContext } from "../runtime/trace";
+import { parseSchema } from "../schema";
+import { getStealthProfile } from "../stealth/profiles";
+import {
+	APIFUSE_STREAM_DONE_EVENT,
+	APIFUSE_STREAM_ERROR_EVENT,
+	encodeSseEvent,
+	error as streamError,
+} from "../stream";
 import type {
 	AuthContext,
 	BrowserClient,
 	FlowContext,
 	FlowContextStore,
+	HttpRetrySummary,
+	OperationDefinition,
+	OperationHttpStreamTransport,
+	OperationSseTransport,
 	ProviderContext,
 	ProviderDefinition,
-	TlsClient,
+	ProviderStreamEvent,
+	StealthClient,
+	SttContext,
 } from "../types";
 import {
 	type AuthFlowRequest,
@@ -34,6 +66,7 @@ import {
 
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
+const retryResponseMeta = new WeakMap<ProviderContext, HttpRetrySummary>();
 
 function createAuthStub(): AuthContext {
 	return {
@@ -56,28 +89,85 @@ function createBrowserStub(): BrowserClient {
 	};
 }
 
-function createTlsStub(): TlsClient {
+function createStealthStub(): StealthClient {
 	return {
 		async fetch() {
-			throw new ProviderError("TLS runtime is not available", {
-				code: "TLS_RUNTIME_UNSUPPORTED",
+			throw new ProviderError("Stealth runtime is not available", {
+				code: "STEALTH_RUNTIME_UNSUPPORTED",
 			});
 		},
 		createSession() {
-			throw new ProviderError("TLS runtime is not available", {
-				code: "TLS_RUNTIME_UNSUPPORTED",
+			throw new ProviderError("Stealth runtime is not available", {
+				code: "STEALTH_RUNTIME_UNSUPPORTED",
 			});
 		},
+		close() {
+			// no-op
+		},
 	};
 }
 
+function getProviderStealthBaseUrl(
+	provider: ProviderDefinition,
+): string | undefined {
+	const baseUrl = getProviderBaseUrl(provider);
+	if (baseUrl) {
+		return baseUrl;
+	}
+	const firstHost = provider.allowedHosts?.[0];
+	return firstHost ? `https://${firstHost}` : undefined;
+}
+
+function getProviderStealthProfile(provider: ProviderDefinition) {
+	return provider.stealth?.profile
+		? getStealthProfile(provider.stealth.profile)
+		: undefined;
+}
+
+export function resolveProviderProxyAffinityKey(
+	provider: ProviderDefinition,
+	request: OperationRequest,
+	operationId: string,
+): string {
+	const connectionKey =
+		request.connection?.id ?? request.connection?.externalRef;
+	const affinity =
+		typeof provider.proxy === "object"
+			? provider.proxy.session?.affinity
+			: undefined;
+	if (affinity === "operation") {
+		return `${provider.id}/${operationId}`;
+	}
+	return connectionKey ?? provider.id;
+}
+
 function createProviderContext(
 	provider: ProviderDefinition,
 	request: OperationRequest,
+	operationId: string,
+	options: ProviderServerOptions = {},
+	proxyTelemetry?: ProxyTelemetryCollector,
 ): ProviderContext {
 	const baseUrl = getProviderBaseUrl(provider);
+	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
+	const stealthProfile = getProviderStealthProfile(provider);
+	const proxyClientOptions = {
+		upstream: { proxy: provider.proxy },
+		affinityKey: resolveProviderProxyAffinityKey(
+			provider,
+			request,
+			operationId,
+		),
+		telemetry: proxyTelemetry,
+	};
+	let wrappedContext: ProviderContext | undefined;
+	const stealthClientOptions = {
+		upstream: proxyClientOptions.upstream,
+		affinityKey: proxyClientOptions.affinityKey,
+		telemetry: proxyTelemetry,
+	};
 
-	return {
+	const context = wrapWithInstrumentation({
 		env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
 		credential: createCredentialContext({
 			allowedKeys: provider.credential?.keys,
@@ -89,13 +179,28 @@ function createProviderContext(
 			connectionId: request.connection?.id,
 			headers: request.headers ?? {},
 		},
-		http: createHttpClient(baseUrl),
-		tls: baseUrl ? createTlsClient(baseUrl) : createTlsStub(),
+		http: createHttpClient(baseUrl, {
+			...proxyClientOptions,
+			onRetrySummary: (summary) => {
+				if (summary.attempts <= 1 || !wrappedContext) return;
+				retryResponseMeta.set(wrappedContext, summary);
+			},
+		}),
+		cache: createProviderCache({ providerId: provider.id }),
+		state: createUnsupportedProviderRuntimeState(),
+		stealth: stealthBaseUrl
+			? stealthProfile
+				? createStealthClient(
+						stealthBaseUrl,
+						stealthProfile.name,
+						stealthClientOptions,
+					)
+				: createStealthClient(stealthBaseUrl, stealthClientOptions)
+			: createStealthStub(),
 		browser:
 			provider.runtime === "browser"
 				? createBrowserClient({
-						cdpUrl:
-							process.env.CDP_POOL_URL ?? process.env.APIFUSE_CDP_POOL_URL,
+						cdpUrl: process.env.APIFUSE__CDP_POOL__URL,
 						headless: true,
 						stealth: true,
 						engine: provider.browser?.engine,
@@ -103,7 +208,10 @@ function createProviderContext(
 				: createBrowserStub(),
 		trace: createTraceContext(),
 		auth: createAuthStub(),
-	};
+		stt: options.stt ?? createSttClientFromEnv(provider.stt),
+	});
+	wrappedContext = context;
+	return context;
 }
 
 function createFlowContextStore(
@@ -145,16 +253,32 @@ function createFlowContextStore(
 function createAuthFlowContext(
 	provider: ProviderDefinition,
 	request: AuthFlowRequest,
+	options: ProviderServerOptions = {},
 ): {
 	context: FlowContext;
 	getPatch: () => Record<string, unknown | null> | undefined;
 } {
 	const baseUrl = getProviderBaseUrl(provider);
+	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
+	const stealthProfile = getProviderStealthProfile(provider);
 	const contextData = request.context ?? {};
 	const flowContextStore = createFlowContextStore(
 		provider.context?.keys ?? Object.keys(contextData),
 		contextData,
 	);
+	const proxyClientOptions = {
+		upstream: { proxy: provider.proxy },
+		affinityKey:
+			request.connectionId ??
+			request.externalRef ??
+			request.tenantId ??
+			request.providerId ??
+			provider.id,
+	};
+	const stealthClientOptions = {
+		upstream: proxyClientOptions.upstream,
+		affinityKey: proxyClientOptions.affinityKey,
+	};
 
 	return {
 		context: {
@@ -162,39 +286,97 @@ function createAuthFlowContext(
 			externalRef: request.externalRef,
 			tenantId: request.tenantId ?? "",
 			providerId: request.providerId ?? provider.id,
-			http: createHttpClient(baseUrl),
+			http: createHttpClient(baseUrl, proxyClientOptions),
+			stealth: stealthBaseUrl
+				? stealthProfile
+					? createStealthClient(
+							stealthBaseUrl,
+							stealthProfile.name,
+							stealthClientOptions,
+						)
+					: createStealthClient(stealthBaseUrl, stealthClientOptions)
+				: createStealthStub(),
 			env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
 			context: flowContextStore.context,
+			stt: options.stt ?? createSttClientFromEnv(provider.stt),
 		},
 		getPatch: flowContextStore.getPatch,
 	};
 }
 
-export type ProviderServerLogEvent = {
-	level: "warn" | "error";
-	event: "provider_request_failed";
+type ProviderRequestCost = {
+	durationMs: number;
+	cpuUserMicros: number;
+	cpuSystemMicros: number;
+	cpuTotalMicros: number;
+};
+
+type ProviderServerLogEventBase = ProviderRequestCost & {
 	providerId: string;
 	kind: "operation" | "auth";
 	route: string;
 	requestId?: string;
 	status: number;
-	code: string;
-	errorClass: string;
-	message: string;
-	upstreamStatus?: number;
-	issues?: Array<{ path: string; code: string; message: string }>;
 };
 
+export type ProviderServerLogEvent =
+	| (ProviderServerLogEventBase & {
+			level: "info";
+			event: "provider_request_completed";
+	  })
+	| (ProviderServerLogEventBase & {
+			level: "warn" | "error";
+			event: "provider_request_failed";
+			code: string;
+			errorClass: string;
+			message: string;
+			upstreamStatus?: number;
+			errorCategory?: ProviderErrorCategory;
+			taxonomyVersion?: string;
+			retryable?: boolean;
+			issues?: Array<{ path: string; code: string; message: string }>;
+	  });
+
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
 
 export type ProviderServerOptions = {
 	logger?: ProviderServerLogger;
+	/** Optional STT override for tests or custom hosts; local/prod normally resolves from env. */
+	stt?: SttContext;
 };
 
 const defaultProviderServerLogger: ProviderServerLogger = (event) => {
-	console.error(JSON.stringify(event));
+	const line = JSON.stringify(event);
+	if (event.level === "info") {
+		console.log(line);
+		return;
+	}
+	console.error(line);
 };
 
+function startRequestCost(): {
+	startedAtMs: number;
+	cpuStart: NodeJS.CpuUsage;
+} {
+	return {
+		startedAtMs: performance.now(),
+		cpuStart: process.cpuUsage(),
+	};
+}
+
+function finishRequestCost(input: {
+	startedAtMs: number;
+	cpuStart: NodeJS.CpuUsage;
+}): ProviderRequestCost {
+	const cpuDelta = process.cpuUsage(input.cpuStart);
+	return {
+		durationMs: Math.max(0, Math.round(performance.now() - input.startedAtMs)),
+		cpuUserMicros: Math.max(0, cpuDelta.user),
+		cpuSystemMicros: Math.max(0, cpuDelta.system),
+		cpuTotalMicros: Math.max(0, cpuDelta.user + cpuDelta.system),
+	};
+}
+
 function zodDetails(error: z.ZodError): Array<{
 	path: string;
 	code: string;
@@ -212,14 +394,14 @@ function toErrorResponse(
 	requestId?: string,
 ): OperationErrorResponse {
 	if (error instanceof ProviderError) {
+		const details = publicProviderErrorDetails(error);
 		return {
 			error: {
 				code: error.code ?? "provider_error",
 				message: publicProviderErrorMessage(error),
 				...(requestId ? { requestId } : {}),
-				...(error instanceof TransportError && error.status
-					? { details: { upstreamStatus: error.status } }
-					: {}),
+				...(error.fix ? { fix: error.fix } : {}),
+				...(details ? { details } : {}),
 			},
 		};
 	}
@@ -244,8 +426,80 @@ function toErrorResponse(
 	};
 }
 
+function publicProviderErrorDetails(error: ProviderError): unknown {
+	const providerDetails = error.details;
+	const observabilityDetails = providerObservabilityDetails(error);
+
+	if (providerDetails === undefined) {
+		return observabilityDetails;
+	}
+	if (observabilityDetails === undefined) {
+		return providerDetails;
+	}
+	if (isPlainRecord(providerDetails) && isPlainRecord(observabilityDetails)) {
+		return { ...providerDetails, ...observabilityDetails };
+	}
+	return {
+		provider: providerDetails,
+		observability: observabilityDetails,
+	};
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function providerObservabilityDetails(error: ProviderError):
+	| {
+			category: ProviderErrorCategory;
+			taxonomyVersion: string;
+			retryable: boolean;
+			upstreamStatus?: number;
+	  }
+	| undefined {
+	if (!(error instanceof TransportError)) {
+		return undefined;
+	}
+	const isProxyPoolCode =
+		error.code === PROXY_POOL_EXHAUSTED_CODE ||
+		error.code === PROXY_EDGE_AUTH_REJECTED_CODE ||
+		error.code === "PROXY_ALLOCATION_FAILED";
+	const category =
+		error.options?.category ??
+		(isProxyPoolCode
+			? "proxy_pool"
+			: error.code === PROXY_AUTH_IP_DENIED_CODE
+				? "anti_bot_blocked"
+				: error.code === "transport_timeout"
+					? "timeout"
+					: error.code === "transport_network_error"
+						? "network"
+						: error.upstreamStatus
+							? categoryForStatus(error.upstreamStatus)
+							: "upstream_http");
+	return {
+		category,
+		taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+		retryable:
+			error.options?.retryable ??
+			(category === "upstream_http" && error.upstreamStatus
+				? error.upstreamStatus >= 500
+				: isRetryableCategory(category)),
+		...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
+	};
+}
+
 function publicProviderErrorMessage(error: ProviderError): string {
 	if (error instanceof TransportError) {
+		if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
+			return error.message;
+		}
+		if (error.code === PROXY_EDGE_AUTH_REJECTED_CODE) {
+			return error.message;
+		}
+		if (error.code === PROXY_POOL_EXHAUSTED_CODE) {
+			return error.message;
+		}
 		if (error.code === "transport_timeout") return "Request timed out";
 		if (error.code === "transport_network_error") return "Network error";
 		if (error.code === "upstream_http_error" && error.status) {
@@ -259,7 +513,7 @@ function publicProviderErrorMessage(error: ProviderError): string {
 	return error.message;
 }
 
-function toStatusCode(error: unknown): 400 | 404 | 429 | 500 | 502 | 504 {
+function toStatusCode(error: unknown): 400 | 404 | 429 | 500 | 502 | 503 | 504 {
 	if (error instanceof z.ZodError) {
 		return 400;
 	}
@@ -280,6 +534,9 @@ function toStatusCode(error: unknown): 400 | 404 | 429 | 500 | 502 | 504 {
 				return 429;
 			case "UPSTREAM_ERROR":
 				return 502;
+			case "STT_UNAVAILABLE":
+			case "UNSUPPORTED_STT_BACKEND":
+				return 503;
 		}
 
 		return 400;
@@ -305,6 +562,7 @@ function logProviderError(
 	requestId: string | undefined,
 	error: unknown,
 	status: number,
+	cost: ProviderRequestCost,
 ): void {
 	const code =
 		error instanceof ProviderError
@@ -314,6 +572,10 @@ function logProviderError(
 				: "internal_error";
 	const errorClass = error instanceof Error ? error.name : typeof error;
 	const message = error instanceof Error ? error.message : String(error);
+	const details =
+		error instanceof ProviderError
+			? providerObservabilityDetails(error)
+			: undefined;
 	const emit =
 		typeof logger === "function" ? logger : defaultProviderServerLogger;
 	emit({
@@ -324,18 +586,50 @@ function logProviderError(
 		route,
 		...(requestId ? { requestId } : {}),
 		status,
+		...cost,
 		code,
 		errorClass,
 		message,
-		...(error instanceof TransportError && error.status
-			? { upstreamStatus: error.status }
+		...(error instanceof TransportError && error.upstreamStatus
+			? { upstreamStatus: error.upstreamStatus }
+			: {}),
+		...(details
+			? {
+					errorCategory: details.category,
+					taxonomyVersion: details.taxonomyVersion,
+					retryable: details.retryable,
+				}
 			: {}),
 		...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
 	});
 }
 
+function logProviderSuccess(
+	logger: ProviderServerLogger | unknown,
+	provider: ProviderDefinition,
+	kind: "operation" | "auth",
+	route: string,
+	requestId: string | undefined,
+	status: number,
+	cost: ProviderRequestCost,
+): void {
+	const emit =
+		typeof logger === "function" ? logger : defaultProviderServerLogger;
+	emit({
+		level: "info",
+		event: "provider_request_completed",
+		providerId: provider.id,
+		kind,
+		route,
+		...(requestId ? { requestId } : {}),
+		status,
+		...cost,
+	});
+}
+
 function toJsonSuccessResponse(
 	result: unknown,
+	ctx?: ProviderContext,
 ): Response | OperationSuccessResponse {
 	if (result instanceof Response) {
 		return result;
@@ -345,7 +639,335 @@ function toJsonSuccessResponse(
 		return new Response(result);
 	}
 
-	return { data: result };
+	const cacheMeta = ctx?.cache.responseMeta();
+	const retryMeta = ctx ? retryResponseMeta.get(ctx) : undefined;
+	const meta =
+		cacheMeta || retryMeta
+			? {
+					...(cacheMeta
+						? {
+								cached: cacheMeta.hit,
+								stale: cacheMeta.stale,
+								cache: cacheMeta,
+							}
+						: {}),
+					...(retryMeta ? { retry: retryMeta } : {}),
+				}
+			: undefined;
+	return {
+		data: result,
+		...(meta ? { meta } : {}),
+	};
+}
+
+function isAsyncIterable<T = unknown>(
+	value: unknown,
+): value is AsyncIterable<T> {
+	if (!value || typeof value !== "object") return false;
+	const iterator = Reflect.get(value, Symbol.asyncIterator);
+	return typeof iterator === "function";
+}
+
+function responseWithCleanup(
+	response: Response,
+	cleanup: () => void,
+): Response {
+	if (!response.body) {
+		cleanup();
+		return response;
+	}
+	const reader = response.body.getReader();
+	let cleaned = false;
+	const runCleanup = () => {
+		if (cleaned) return;
+		cleaned = true;
+		cleanup();
+	};
+	const body = new ReadableStream<Uint8Array>({
+		async pull(controller) {
+			try {
+				const { done, value } = await reader.read();
+				if (done) {
+					controller.close();
+					runCleanup();
+					return;
+				}
+				if (value) controller.enqueue(value);
+			} catch (error) {
+				runCleanup();
+				controller.error(error);
+			}
+		},
+		async cancel(reason) {
+			try {
+				await reader.cancel(reason);
+			} finally {
+				runCleanup();
+			}
+		},
+	});
+	return new Response(body, {
+		headers: response.headers,
+		status: response.status,
+		statusText: response.statusText,
+	});
+}
+
+async function validateSseEvent(
+	operation: OperationDefinition,
+	event: ProviderStreamEvent,
+): Promise<ProviderStreamEvent> {
+	const transport = getSseTransport(operation);
+	const schema = transport?.events?.[event.event];
+	if (!schema) {
+		if (
+			event.event === APIFUSE_STREAM_ERROR_EVENT ||
+			event.event === APIFUSE_STREAM_DONE_EVENT
+		) {
+			return event;
+		}
+		throw new ProviderError(
+			`SSE event "${event.event}" is not declared in operation transport.events.`,
+			{
+				code: "SSE_EVENT_UNDECLARED",
+				category: "output_validation",
+				retryable: false,
+				fix: `Add "${event.event}" to transport.events or stop emitting that event.`,
+			},
+		);
+	}
+	const data = await parseSchema(
+		schema,
+		event.data,
+		`transport.events.${event.event}`,
+	);
+	return { ...event, data };
+}
+
+function byteLength(value: Uint8Array | string): number {
+	if (typeof value === "string") {
+		return new TextEncoder().encode(value).byteLength;
+	}
+	return value.byteLength;
+}
+
+function assertStreamPayloadWithinLimit(
+	actualBytes: number,
+	maxBytes: number | undefined,
+	kind: "event" | "chunk",
+): void {
+	if (maxBytes === undefined || actualBytes <= maxBytes) return;
+	throw new ProviderError(
+		`Stream ${kind} exceeded declared byte limit (${actualBytes} > ${maxBytes}).`,
+		{
+			code:
+				kind === "event" ? "STREAM_EVENT_TOO_LARGE" : "STREAM_CHUNK_TOO_LARGE",
+			retryable: false,
+			category: "input_validation",
+			fix:
+				kind === "event"
+					? "Emit smaller SSE events or increase transport.maxEventBytes."
+					: "Emit smaller stream chunks or increase transport.maxChunkBytes.",
+		},
+	);
+}
+
+function toSseResponse(
+	operation: OperationDefinition,
+	result: AsyncIterable<ProviderStreamEvent>,
+	cleanup: () => void,
+	requestId?: string,
+): Response {
+	const encoder = new TextEncoder();
+	const iterator = result[Symbol.asyncIterator]();
+	const transport = getSseTransport(operation);
+	let done = false;
+	let cleaned = false;
+	const runCleanup = () => {
+		if (cleaned) return;
+		cleaned = true;
+		cleanup();
+	};
+	const body = new ReadableStream<Uint8Array>({
+		async pull(controller) {
+			try {
+				if (done) {
+					controller.close();
+					runCleanup();
+					return;
+				}
+				const next = await iterator.next();
+				if (next.done) {
+					done = true;
+					controller.close();
+					runCleanup();
+					return;
+				}
+				const validated = await validateSseEvent(operation, next.value);
+				const encodedEvent = encodeSseEvent(validated);
+				const encodedBytes = encoder.encode(encodedEvent);
+				assertStreamPayloadWithinLimit(
+					encodedBytes.byteLength,
+					transport?.maxEventBytes,
+					"event",
+				);
+				controller.enqueue(encodedBytes);
+			} catch (error) {
+				const message =
+					error instanceof Error ? error.message : "Stream failed";
+				controller.enqueue(
+					encoder.encode(
+						encodeSseEvent(
+							streamError("stream_error", message, {
+								...(requestId ? { requestId } : {}),
+							}),
+						),
+					),
+				);
+				controller.close();
+				done = true;
+				runCleanup();
+			}
+		},
+		async cancel(reason) {
+			try {
+				await iterator.return?.(reason);
+			} finally {
+				runCleanup();
+			}
+		},
+	});
+	return new Response(body, {
+		headers: {
+			"Cache-Control": "no-cache, no-transform",
+			Connection: "keep-alive",
+			"Content-Type": "text/event-stream; charset=utf-8",
+		},
+	});
+}
+
+function enforceStreamChunkLimit(
+	body: ReadableStream<Uint8Array>,
+	maxChunkBytes: number | undefined,
+): ReadableStream<Uint8Array> {
+	if (maxChunkBytes === undefined) return body;
+	const reader = body.getReader();
+	return new ReadableStream<Uint8Array>({
+		async pull(controller) {
+			try {
+				const { done, value } = await reader.read();
+				if (done) {
+					controller.close();
+					return;
+				}
+				if (value) {
+					assertStreamPayloadWithinLimit(
+						byteLength(value),
+						maxChunkBytes,
+						"chunk",
+					);
+					controller.enqueue(value);
+				}
+			} catch (error) {
+				controller.error(error);
+			}
+		},
+		cancel(reason) {
+			return reader.cancel(reason);
+		},
+	});
+}
+
+function toStreamingResponse(
+	operation: OperationDefinition,
+	result: unknown,
+	cleanup: () => void,
+	requestId?: string,
+): Response {
+	const transport = operation.transport?.kind ?? "json";
+	if (
+		transport === "sse" &&
+		(result instanceof Response || result instanceof ReadableStream)
+	) {
+		cleanup();
+		throw new ProviderError(
+			"SSE operations must return an AsyncIterable of typed stream.event(...) values.",
+			{
+				code: "SSE_RESULT_UNSUPPORTED",
+				category: "output_validation",
+				retryable: false,
+				fix: "Return an async generator that yields stream.event(name, data) so APIFuse can validate event schemas and enforce event byte limits.",
+			},
+		);
+	}
+	if (result instanceof Response) {
+		const httpTransport = getHttpStreamTransport(operation);
+		if (
+			httpTransport &&
+			result.body &&
+			httpTransport?.maxChunkBytes !== undefined
+		) {
+			return responseWithCleanup(
+				new Response(
+					enforceStreamChunkLimit(result.body, httpTransport.maxChunkBytes),
+					{
+						headers: result.headers,
+						status: result.status,
+						statusText: result.statusText,
+					},
+				),
+				cleanup,
+			);
+		}
+		return responseWithCleanup(result, cleanup);
+	}
+	if (result instanceof ReadableStream) {
+		const httpTransport = getHttpStreamTransport(operation);
+		const stream =
+			httpTransport !== undefined
+				? enforceStreamChunkLimit(result, httpTransport.maxChunkBytes)
+				: result;
+		return responseWithCleanup(
+			new Response(stream, {
+				headers:
+					transport === "sse"
+						? { "Content-Type": "text/event-stream; charset=utf-8" }
+						: {
+								"Content-Type":
+									operation.transport?.kind === "http-stream"
+										? (operation.transport.contentType ??
+											"application/octet-stream")
+										: "application/octet-stream",
+							},
+			}),
+			cleanup,
+		);
+	}
+	if (transport === "sse" && isAsyncIterable<ProviderStreamEvent>(result)) {
+		return toSseResponse(operation, result, cleanup, requestId);
+	}
+	cleanup();
+	throw new ProviderError(
+		`Streaming operation returned unsupported result for transport "${transport}"`,
+		{
+			code: "STREAM_RESULT_UNSUPPORTED",
+			fix: "Return an AsyncIterable of stream.event(...) values, a ReadableStream, or a Response from streaming operations.",
+		},
+	);
+}
+
+function getSseTransport(
+	operation: OperationDefinition,
+): OperationSseTransport | undefined {
+	return operation.transport?.kind === "sse" ? operation.transport : undefined;
+}
+
+function getHttpStreamTransport(
+	operation: OperationDefinition,
+): OperationHttpStreamTransport | undefined {
+	return operation.transport?.kind === "http-stream"
+		? operation.transport
+		: undefined;
 }
 
 function toAuthFlowResponse(
@@ -370,15 +992,57 @@ async function handleOperation(
 	provider: ProviderDefinition,
 	request: OperationRequest,
 	operationId: string,
+	options: ProviderServerOptions = {},
+	proxyTelemetry?: ProxyTelemetryCollector,
 ): Promise<Response | OperationResponse> {
-	const ctx = createProviderContext(provider, request);
-	const result = await executeOperation(
+	const ctx = createProviderContext(
 		provider,
+		request,
 		operationId,
-		ctx,
-		request.input,
+		options,
+		proxyTelemetry,
 	);
-	return toJsonSuccessResponse(result);
+	const operation = provider.operations[operationId];
+	const streaming =
+		operation?.transport?.kind && operation.transport.kind !== "json";
+	let cleanupCalled = false;
+	const cleanup = () => {
+		if (cleanupCalled) return;
+		cleanupCalled = true;
+		ctx.stealth.close?.();
+	};
+	try {
+		const result = await executeOperation(
+			provider,
+			operationId,
+			ctx,
+			request.input,
+		);
+		if (streaming && operation) {
+			return toStreamingResponse(operation, result, cleanup, request.requestId);
+		}
+		return toJsonSuccessResponse(result, ctx);
+	} catch (error) {
+		cleanup();
+		throw error;
+	} finally {
+		if (!streaming) cleanup();
+	}
+}
+
+function responseWithProviderTelemetry(
+	response: Response,
+	proxyTelemetry?: ProxyTelemetryCollector,
+): Response {
+	const headerValue = proxyTelemetry?.toHeaderValue();
+	const headers = new Headers(response.headers);
+	headers.delete(PROVIDER_TELEMETRY_HEADER);
+	if (headerValue) headers.set(PROVIDER_TELEMETRY_HEADER, headerValue);
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText,
+	});
 }
 
 type AuthRoute = "start" | "continue" | "poll" | "abort";
@@ -387,6 +1051,7 @@ async function handleAuthFlow(
 	provider: ProviderDefinition,
 	request: AuthFlowRequest,
 	route: AuthRoute,
+	options: ProviderServerOptions = {},
 ): Promise<Response | AuthFlowResponse> {
 	const flow = provider.auth?.flow;
 	if (!flow) {
@@ -395,22 +1060,29 @@ async function handleAuthFlow(
 		});
 	}
 
-	const { context, getPatch } = createAuthFlowContext(provider, request);
-
-	const result =
-		route === "start"
-			? await flow.start(context)
-			: route === "continue"
-				? await flow.continue(context, request.input ?? {})
-				: route === "poll"
-					? flow.poll
-						? await flow.poll(context)
-						: null
-					: flow.abort
-						? await flow.abort(context)
-						: null;
+	const { context, getPatch } = createAuthFlowContext(
+		provider,
+		request,
+		options,
+	);
+	try {
+		const result =
+			route === "start"
+				? await flow.start(context)
+				: route === "continue"
+					? await flow.continue(context, request.input ?? {})
+					: route === "poll"
+						? flow.poll
+							? await flow.poll(context)
+							: null
+						: flow.abort
+							? await flow.abort(context)
+							: null;
 
-	return toAuthFlowResponse(result, getPatch());
+		return toAuthFlowResponse(result, getPatch());
+	} finally {
+		context.stealth.close?.();
+	}
 }
 
 export function createServerApp(
@@ -443,6 +1115,8 @@ export function createServerApp(
 	app.post("/v1/:operation", async (c) => {
 		let rawBody: unknown;
 		const operation = c.req.param("operation");
+		const proxyTelemetry = new ProxyTelemetryCollector();
+		const requestCost = startRequestCost();
 		try {
 			rawBody = await c.req.raw
 				.clone()
@@ -451,8 +1125,37 @@ export function createServerApp(
 			const body = OperationRequestSchema.parse(rawBody);
 			const requestHeaders = Object.fromEntries(c.req.raw.headers.entries());
 			body.headers = { ...requestHeaders, ...body.headers };
-			const response = await handleOperation(provider, body, operation);
-			return response instanceof Response ? response : c.json(response);
+			const response = await handleOperation(
+				provider,
+				body,
+				operation,
+				options,
+				proxyTelemetry,
+			);
+			if (response instanceof Response) {
+				logProviderSuccess(
+					logger,
+					provider,
+					"operation",
+					operation,
+					body.requestId,
+					response.status,
+					finishRequestCost(requestCost),
+				);
+				return responseWithProviderTelemetry(response, proxyTelemetry);
+			}
+			const telemetryHeader = proxyTelemetry.toHeaderValue();
+			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
+			logProviderSuccess(
+				logger,
+				provider,
+				"operation",
+				operation,
+				body.requestId,
+				200,
+				finishRequestCost(requestCost),
+			);
+			return c.json(response);
 		} catch (error) {
 			const status = toStatusCode(error);
 			const requestId = extractRequestId(rawBody);
@@ -464,20 +1167,33 @@ export function createServerApp(
 				requestId,
 				error,
 				status,
+				finishRequestCost(requestCost),
 			);
+			const telemetryHeader = proxyTelemetry.toHeaderValue();
+			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
 			return c.json(toErrorResponse(error, requestId), status);
 		}
 	});
 
 	app.post("/auth/start", async (c) => {
 		let rawBody: unknown;
+		const requestCost = startRequestCost();
 		try {
 			rawBody = await c.req.raw
 				.clone()
 				.json()
 				.catch(() => undefined);
 			const body = AuthFlowRequestSchema.parse(rawBody);
-			const response = await handleAuthFlow(provider, body, "start");
+			const response = await handleAuthFlow(provider, body, "start", options);
+			logProviderSuccess(
+				logger,
+				provider,
+				"auth",
+				"start",
+				body.requestId,
+				response instanceof Response ? response.status : 200,
+				finishRequestCost(requestCost),
+			);
 			return response instanceof Response ? response : c.json(response);
 		} catch (error) {
 			const status = toStatusCode(error);
@@ -490,6 +1206,7 @@ export function createServerApp(
 				requestId,
 				error,
 				status,
+				finishRequestCost(requestCost),
 			);
 			return c.json(toErrorResponse(error, requestId), status);
 		}
@@ -497,13 +1214,28 @@ export function createServerApp(
 
 	app.post("/auth/continue", async (c) => {
 		let rawBody: unknown;
+		const requestCost = startRequestCost();
 		try {
 			rawBody = await c.req.raw
 				.clone()
 				.json()
 				.catch(() => undefined);
 			const body = AuthFlowRequestSchema.parse(rawBody);
-			const response = await handleAuthFlow(provider, body, "continue");
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"continue",
+				options,
+			);
+			logProviderSuccess(
+				logger,
+				provider,
+				"auth",
+				"continue",
+				body.requestId,
+				response instanceof Response ? response.status : 200,
+				finishRequestCost(requestCost),
+			);
 			return response instanceof Response ? response : c.json(response);
 		} catch (error) {
 			const status = toStatusCode(error);
@@ -516,6 +1248,7 @@ export function createServerApp(
 				requestId,
 				error,
 				status,
+				finishRequestCost(requestCost),
 			);
 			return c.json(toErrorResponse(error, requestId), status);
 		}
@@ -523,13 +1256,23 @@ export function createServerApp(
 
 	app.post("/auth/poll", async (c) => {
 		let rawBody: unknown;
+		const requestCost = startRequestCost();
 		try {
 			rawBody = await c.req.raw
 				.clone()
 				.json()
 				.catch(() => undefined);
 			const body = AuthFlowRequestSchema.parse(rawBody);
-			const response = await handleAuthFlow(provider, body, "poll");
+			const response = await handleAuthFlow(provider, body, "poll", options);
+			logProviderSuccess(
+				logger,
+				provider,
+				"auth",
+				"poll",
+				body.requestId,
+				response instanceof Response ? response.status : 200,
+				finishRequestCost(requestCost),
+			);
 			return response instanceof Response ? response : c.json(response);
 		} catch (error) {
 			const status = toStatusCode(error);
@@ -542,6 +1285,7 @@ export function createServerApp(
 				requestId,
 				error,
 				status,
+				finishRequestCost(requestCost),
 			);
 			return c.json(toErrorResponse(error, requestId), status);
 		}
@@ -549,13 +1293,23 @@ export function createServerApp(
 
 	app.post("/auth/disconnect", async (c) => {
 		let rawBody: unknown;
+		const requestCost = startRequestCost();
 		try {
 			rawBody = await c.req.raw
 				.clone()
 				.json()
 				.catch(() => undefined);
 			const body = AuthFlowRequestSchema.parse(rawBody);
-			const response = await handleAuthFlow(provider, body, "abort");
+			const response = await handleAuthFlow(provider, body, "abort", options);
+			logProviderSuccess(
+				logger,
+				provider,
+				"auth",
+				"disconnect",
+				body.requestId,
+				response instanceof Response ? response.status : 200,
+				finishRequestCost(requestCost),
+			);
 			return response instanceof Response ? response : c.json(response);
 		} catch (error) {
 			const status = toStatusCode(error);
@@ -568,6 +1322,7 @@ export function createServerApp(
 				requestId,
 				error,
 				status,
+				finishRequestCost(requestCost),
 			);
 			return c.json(toErrorResponse(error, requestId), status);
 		}
@@ -622,7 +1377,10 @@ export async function serve(
 		);
 	}
 
-	const app = createServerApp(provider, { logger: options.logger });
+	const app = createServerApp(provider, {
+		logger: options.logger,
+		stt: options.stt,
+	});
 
 	bunRuntime.serve({
 		port: options.port ?? DEFAULT_PORT,