auto-model-router 0.1.0

package/src/server/turn.ts

@@ -0,0 +1,393 @@
+/**
+ * Turn orchestrator — where money is actually spent.
+ *
+ * One turn = up to `escalation.maxAttempts` dispatches. Each attempt routes,
+ * dispatches, and runs the guarded probe. The probe holds output until the
+ * generation proves itself; on rejection the attempt is aborted (so no further
+ * tokens bill), recorded as wasted, and retried one tier up. Once a single
+ * byte reaches the client the attempt is committed and NEVER retried.
+ */
+
+import type { CatalogSource } from "../catalog/types.ts";
+import type { RouterConfig } from "../config/types.ts";
+import { EMPTY_USAGE, type Ledger, type UsageCounts } from "../cost/types.ts";
+import { createProbe, type Probe } from "../router/escalate.ts";
+import {
+	TIER_ORDER,
+	type ConversationStore,
+	type Decision,
+	type ProbeVerdict,
+	type Router,
+	type Tier,
+} from "../router/types.ts";
+import { UpstreamError, type Dispatch, type UpstreamClient } from "../upstream/types.ts";
+import { createLogger } from "../util/log.ts";
+import type { NormRequest, ResponseSink, TurnSummary, UpstreamChunk } from "../wire/types.ts";
+
+/**
+ * Same-tier failovers allowed per turn. A retryable upstream error (404
+ * model_unavailable, 429 rate_limit, 5xx upstream_error) indicts the slug,
+ * not the tier, so a failed model is first swapped for a sibling. Bounded
+ * because an exhausted tier must escalate rather than spin through the whole
+ * catalog while the client waits; `escalation.maxAttempts` caps total
+ * attempts regardless.
+ */
+const MAX_SAME_TIER_FAILOVERS = 2;
+
+export interface TurnDeps {
+	config: RouterConfig;
+	router: Router;
+	upstream: UpstreamClient;
+	ledger: Ledger;
+	conversations: ConversationStore;
+	catalog: CatalogSource;
+}
+
+/** A dead client connection surfaces as the sink throwing mid-stream. */
+class SinkError extends Error {
+	constructor(cause: unknown) {
+		super(cause instanceof Error ? cause.message : String(cause));
+		this.name = "SinkError";
+	}
+}
+
+export async function runTurn(
+	req: NormRequest,
+	sink: ResponseSink,
+	deps: TurnDeps,
+	signal: AbortSignal,
+): Promise<void> {
+	const { config, router, upstream, ledger, conversations } = deps;
+	const log = createLogger(config.logLevel);
+	const state = conversations.load(req.conversationKey);
+	const turnNumber = state.turn + 1;
+
+	// The trigger list is the source of truth for enabled signals, except
+	// length_stop, which rides on its own toggle (escalation.escalateOnLengthStop).
+	const triggers = new Set(config.escalation.triggers);
+	if (config.escalation.escalateOnLengthStop) triggers.add("length_stop");
+	else triggers.delete("length_stop");
+
+	const maxAttempts = Math.max(1, config.escalation.maxAttempts);
+	let escalateFrom: Tier | undefined;
+	let escalations = 0;
+	// Slugs that returned a retryable upstream error on THIS turn, fed back
+	// into routing as excludeSlugs so a failover retry cannot re-pick the
+	// model that just failed.
+	const failedSlugs: string[] = [];
+	let sameTierFailovers = 0;
+	// A failover decision already routed inside onUpstreamError; the next
+	// loop iteration dispatches it instead of routing again.
+	let pendingDecision: Decision | null = null;
+
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		// Client disconnected before anything was dispatched: spend nothing.
+		if (signal.aborted) return;
+
+		let decision: Decision;
+		if (pendingDecision !== null) {
+			decision = pendingDecision;
+			pendingDecision = null;
+		} else {
+			try {
+				const opts: { attempt: number; escalateFrom?: Tier; excludeSlugs?: readonly string[] } = { attempt };
+				if (escalateFrom !== undefined) opts.escalateFrom = escalateFrom;
+				if (failedSlugs.length > 0) opts.excludeSlugs = failedSlugs;
+				decision = await router.route(req, opts);
+			} catch (err) {
+				await sink.error({ status: 500, code: "router_error", message: err instanceof Error ? err.message : String(err) });
+				return;
+			}
+		}
+
+		const body = req.renderUpstreamBody({
+			slug: decision.slug,
+			fallbacks: decision.fallbacks,
+			sessionId: decision.sessionId,
+			cacheBreakpointMessageIndices: decision.cacheBreakpointMessageIndices,
+			reasoning: decision.reasoning,
+			maxTokens: decision.maxTokens,
+			stripAssistantReasoning: decision.stripAssistantReasoning,
+		});
+
+		// Our own abort composes with the client's: escalation teardown and
+		// client disconnect both kill the upstream connection.
+		const attemptAbort = new AbortController();
+		const attemptSignal = AbortSignal.any([signal, attemptAbort.signal]);
+		const startedAt = Date.now();
+		let usage: UsageCounts = { ...EMPTY_USAGE };
+		let reportedUsd: number | null = null;
+		let servedSlug: string | null = null;
+		let finishReason: string | null = null;
+		let ttftMs: number | null = null;
+		let committed = false;
+		let dispatch: Dispatch | null = null;
+		let probe: Probe | null = null;
+		let generationId: string | null = null;
+
+		const writeEntry = async (fields: {
+			wasted: boolean;
+			escalationSignal: string | null;
+			error: string | null;
+		}): Promise<void> => {
+			if (generationId === null && dispatch !== null) {
+				generationId = await dispatch.generationId().catch(() => null);
+			}
+			ledger.record({
+				id: crypto.randomUUID(),
+				createdAtMs: Date.now(),
+				conversationKey: req.conversationKey,
+				sessionId: decision.sessionId,
+				turn: turnNumber,
+				requestedModel: req.requestedModel,
+				harnessId: req.harnessId,
+				slug: decision.slug,
+				servedSlug,
+				tier: decision.tier,
+				classificationSource: decision.classification.source,
+				reasons: decision.reasons,
+				predictedUsd: decision.forecast.expectedUsd,
+				reportedUsd,
+				usage,
+				attempt,
+				escalationSignal: fields.escalationSignal,
+				latencyMs: Date.now() - startedAt,
+				ttftMs,
+				finishReason,
+				wasted: fields.wasted,
+				upstreamGenerationId: generationId,
+				error: fields.error,
+			});
+		};
+
+		// "retry" re-enters the attempt loop; "done" means the turn is settled
+		// (client told, or client gone) and runTurn must return.
+		const onUpstreamError = async (err: unknown): Promise<"retry" | "done"> => {
+			const uerr =
+				err instanceof UpstreamError
+					? err
+					: new UpstreamError("network", 0, err instanceof Error ? err.message : String(err), true);
+			if (uerr.kind === "aborted" || signal.aborted) {
+				// Client is gone; nothing to retry and no one to notify. Record the
+				// spend so far so the ledger stays honest.
+				await writeEntry({ wasted: !committed, escalationSignal: null, error: uerr.message });
+				return "done";
+			}
+			if (committed) {
+				// Bytes already reached the client: retrying is impossible. Report
+				// the failure; never sink.finish a truncated stream.
+				await writeEntry({ wasted: false, escalationSignal: null, error: `${uerr.kind}: ${uerr.message}` });
+				await sink.error(uerr.toWireError());
+				return "done";
+			}
+			if (uerr.retryable && attempt + 1 < maxAttempts) {
+				failedSlugs.push(decision.slug);
+				if (sameTierFailovers < MAX_SAME_TIER_FAILOVERS) {
+					// Before jumping a tier, try a DIFFERENT model in the same
+					// tier: a 404/429/5xx indicts the slug, not the tier.
+					let failover: Decision | null = null;
+					try {
+						failover = await router.route(req, { attempt: attempt + 1, excludeSlugs: failedSlugs });
+					} catch {
+						// A routing failure here must not kill the turn; tier
+						// escalation below may still find a model.
+						failover = null;
+					}
+					if (failover !== null && failover.tier === decision.tier && !failedSlugs.includes(failover.slug)) {
+						sameTierFailovers++;
+						failover.reasons = [
+							...failover.reasons,
+							`failover: ${decision.slug} returned ${uerr.kind}; retrying ${failover.slug} in ${failover.tier}`,
+						];
+						pendingDecision = failover;
+						await writeEntry({ wasted: true, escalationSignal: null, error: `${uerr.kind}: ${uerr.message}` });
+						return "retry";
+					}
+					// No different candidate at this tier — the router widened on
+					// its own or only the failed slug qualifies. Fall through to
+					// tier escalation.
+				}
+				const topTier = TIER_ORDER[TIER_ORDER.length - 1];
+				if (decision.tier !== topTier) {
+					escalations++;
+					escalateFrom = decision.tier;
+					await writeEntry({
+						wasted: true,
+						escalationSignal: "upstream_error",
+						error: `${uerr.kind}: ${uerr.message}`,
+					});
+					return "retry";
+				}
+			}
+			// Non-retryable, or out of runway: fail the turn openly.
+			await writeEntry({ wasted: false, escalationSignal: null, error: `${uerr.kind}: ${uerr.message}` });
+			await sink.error(uerr.toWireError());
+			return "done";
+		};
+
+		let escalateVerdict: Extract<ProbeVerdict, { action: "escalate" }> | null = null;
+		let streamError: unknown = null;
+		let sinkDied = false;
+
+		try {
+			dispatch = await upstream.dispatch({ body, sessionId: decision.sessionId, signal: attemptSignal });
+		} catch (err) {
+			streamError = err;
+		}
+
+		if (dispatch !== null) {
+			probe = createProbe(decision.probe, req, triggers);
+			const emit = async (chunk: UpstreamChunk): Promise<void> => {
+				try {
+					await sink.chunk(chunk);
+				} catch (err) {
+					throw new SinkError(err);
+				}
+			};
+			try {
+				for await (const chunk of dispatch.chunks) {
+					for (const ev of chunk.events) {
+						switch (ev.type) {
+							case "start":
+								servedSlug = ev.servedSlug;
+								if (ev.generationId !== null) generationId = ev.generationId;
+								break;
+							case "text":
+							case "reasoning":
+								if (ttftMs === null) ttftMs = Date.now() - startedAt;
+								break;
+							case "finish":
+								finishReason = ev.reason;
+								break;
+							case "usage":
+								usage = ev.usage;
+								reportedUsd = ev.reportedCostUsd;
+								break;
+							default:
+								break;
+						}
+					}
+					if (committed) {
+						await emit(chunk);
+						continue;
+					}
+					const verdict = probe.observe(chunk);
+					if (verdict === null) continue;
+					if (verdict.action === "commit") {
+						committed = true;
+						for (const heldChunk of probe.held()) await emit(heldChunk);
+						continue;
+					}
+					// Abort BEFORE breaking so the pending upstream read rejects and
+					// no further tokens bill while we tear down.
+					escalateVerdict = verdict;
+					attemptAbort.abort();
+					break;
+				}
+				if (!committed && escalateVerdict === null) {
+					const verdict = probe.verdictOnEnd();
+					if (verdict.action === "commit") {
+						committed = true;
+						for (const heldChunk of probe.held()) await emit(heldChunk);
+					} else {
+						escalateVerdict = verdict;
+						attemptAbort.abort();
+					}
+				}
+			} catch (err) {
+				if (escalateVerdict !== null || attemptAbort.signal.aborted) {
+					// Teardown noise from our own abort; the escalate path owns the outcome.
+				} else if (err instanceof SinkError) {
+					sinkDied = true;
+				} else {
+					streamError = err;
+				}
+			} finally {
+				// Never leak the upstream connection, whatever happened above.
+				attemptAbort.abort();
+			}
+		}
+
+		if (sinkDied) {
+			await writeEntry({ wasted: !committed, escalationSignal: null, error: "client connection lost" });
+			return;
+		}
+		if (streamError !== null) {
+			if ((await onUpstreamError(streamError)) === "retry") continue;
+			return;
+		}
+
+		if (escalateVerdict !== null) {
+			const hasRunway = attempt + 1 < maxAttempts && decision.probe.escalateTo !== null;
+			if (hasRunway) {
+				escalations++;
+				escalateFrom = decision.tier;
+				await writeEntry({ wasted: true, escalationSignal: escalateVerdict.signal, error: null });
+				log.info("escalating turn", {
+					signal: escalateVerdict.signal,
+					reason: escalateVerdict.reason,
+					from: decision.tier,
+					attempt,
+				});
+				continue;
+			}
+			// No higher tier or no attempts left: commit what was held. A mediocre
+			// answer beats an error.
+			if (probe !== null) {
+				committed = true;
+				for (const heldChunk of probe.held()) await sink.chunk(heldChunk);
+			}
+		}
+
+		await writeEntry({ wasted: false, escalationSignal: null, error: null });
+
+		state.turn = turnNumber;
+		state.currentSlug = servedSlug ?? decision.slug;
+		// Capture the previously-served tier BEFORE overwriting it, so the
+		// hysteresis re-arm below can tell whether this turn changed tier.
+		const prevTier = state.currentTier;
+		state.currentTier = decision.tier;
+		state.escalations += escalations;
+		// Hysteresis window. Only re-arm when the served tier actually changed
+		// (or this turn escalated). Re-arming on EVERY turn — even a trivial one
+		// served by a held hard model — extends the lock forever: the classifier
+		// keeps saying trivial, but the window keeps getting pushed out, so the
+		// router never downgrades. A stable tier needs no new hold; let the
+		// existing window expire so the router can move down when the work is
+		// actually easy.
+		const tierChanged = prevTier !== decision.tier;
+		if (tierChanged || escalations > 0) {
+			state.stickyUntilTurn =
+				turnNumber + (escalations > 0 ? config.hysteresis.holdTurnsAfterEscalation : config.hysteresis.holdTurns);
+		}
+		// Reported cost is authoritative; fall back to the forecast so the
+		// budget guard still works when the provider omits cost.
+		state.spentUsd += reportedUsd ?? decision.forecast.expectedUsd;
+		state.lastPromptTokens = usage.promptTokens;
+		if (usage.cachedTokens > 0 || usage.cacheWriteTokens > 0) {
+			// Non-zero cache traffic is direct evidence the upstream cache exists.
+			state.cacheWarmSlug = servedSlug ?? decision.slug;
+			state.cacheWarmAtMs = Date.now();
+		}
+		state.updatedAtMs = Date.now();
+		conversations.save(state);
+
+		const summary: TurnSummary = {
+			servedSlug: servedSlug ?? decision.slug,
+			tier: decision.tier,
+			attempts: attempt + 1,
+			predictedUsd: decision.forecast.expectedUsd,
+			reportedUsd,
+			usage,
+			reasons: decision.reasons,
+			escalated: escalations > 0,
+		};
+		await sink.finish(summary);
+		return;
+	}
+
+	// Every attempt looped without settling; the retry paths above always
+	// continue or return, so reaching here means maxAttempts was 0-guarded and
+	// the first iteration never ran. Fail openly rather than silently.
+	await sink.error({ status: 502, code: "attempts_exhausted", message: "all routing attempts exhausted" });
+}

package/src/tokens/estimate.ts

@@ -0,0 +1,74 @@
+/**
+ * Token estimation: bytes → tokens without a tokenizer. The ratio is
+ * self-calibrating: `estimatePromptTokens` remembers the bytes it estimated
+ * from (keyed by conversation), and the ledger folds those bytes against the
+ * ACTUAL billed prompt tokens when the turn is recorded, converging
+ * `token_calibration` per tokenizer family on measurement.
+ */
+
+import type { Ledger } from "../cost/types.ts";
+import type { NormRequest } from "../wire/types.ts";
+
+/** Chars-per-token when nothing better is known. Conservative-ish for mixed prose+code. */
+export const DEFAULT_BYTES_PER_TOKEN = 3.6;
+
+/**
+ * Flat per-image allowance. Vision encoders tile images; a typical tile budget
+ * lands around 1100 tokens per image across OpenAI/Anthropic/Gemini.
+ */
+export const IMAGE_TOKEN_ALLOWANCE = 1100;
+
+/**
+ * Per-family defaults, keyed by lowercased `architecture.tokenizer`. DeepSeek
+ * traffic is code-dominant, and BPE tokenizers emit more tokens per character
+ * on code than on prose, so its ratio sits below the prose-oriented default.
+ */
+const FAMILY_BYTES_PER_TOKEN: Record<string, number> = {
+	claude: 3.6,
+	gpt: 3.6,
+	gemini: 3.6,
+	llama: 3.6,
+	qwen: 3.6,
+	qwen3: 3.6,
+	grok: 3.6,
+	mistral: 3.6,
+	deepseek: 3.4,
+};
+
+function familyKey(tokenizer: string): string {
+	return tokenizer.trim().toLowerCase();
+}
+
+export function estimateTokens(bytes: number, tokenizer: string, ledger: Ledger | null): number {
+	const ratio = ledger?.tokenRatio(tokenizer) ?? FAMILY_BYTES_PER_TOKEN[familyKey(tokenizer)] ?? DEFAULT_BYTES_PER_TOKEN;
+	return Math.max(0, Math.ceil(bytes / ratio));
+}
+
+/**
+ * Pending estimates, keyed by conversation. The router estimates before
+ * dispatch; the ledger consumes the estimate when recording the turn, pairing
+ * estimated bytes with actual billed tokens for calibration. In-memory only:
+ * the data is statistical, so a restart losing it costs nothing.
+ */
+const PENDING_CAP = 1024;
+const pendingEstimates = new Map<string, { tokenizer: string; bytes: number }>();
+
+export function estimatePromptTokens(req: NormRequest, tokenizer: string, ledger: Ledger | null): number {
+	let images = 0;
+	for (const message of req.messages) images += message.images;
+	const tokens = estimateTokens(req.promptBytes, tokenizer, ledger) + images * IMAGE_TOKEN_ALLOWANCE;
+	if (pendingEstimates.size >= PENDING_CAP && !pendingEstimates.has(req.conversationKey)) {
+		// Map iteration order is insertion order: drop the eldest.
+		const eldest = pendingEstimates.keys().next();
+		if (!eldest.done) pendingEstimates.delete(eldest.value);
+	}
+	pendingEstimates.set(req.conversationKey, { tokenizer, bytes: req.promptBytes });
+	return tokens;
+}
+
+/** Internal: called by cost/ledger.ts when recording a turn. */
+export function consumePendingEstimate(conversationKey: string): { tokenizer: string; bytes: number } | null {
+	const pending = pendingEstimates.get(conversationKey) ?? null;
+	pendingEstimates.delete(conversationKey);
+	return pending;
+}

package/src/upstream/openrouter.ts

@@ -0,0 +1,221 @@
+/**
+ * OpenRouter transport.
+ *
+ * Deliberately thin: POSTs the body the wire rendered, decodes SSE via
+ * `sse-parse.ts`, and classifies failures into `UpstreamErrorKind`s the turn
+ * orchestrator can act on. No routing policy lives here.
+ */
+
+import type { RouterConfig } from "../config/types.ts";
+import { createLogger } from "../util/log.ts";
+import type { UpstreamChunk } from "../wire/types.ts";
+import { parseSse } from "./sse-parse.ts";
+import {
+	UpstreamError,
+	type Dispatch,
+	type DispatchOptions,
+	type UpstreamClient,
+	type UpstreamErrorKind,
+} from "./types.ts";
+
+// OpenRouter reports context overflow as a 400 with a human message; the
+// message is the only signal, so match the phrasings providers actually send.
+const CONTEXT_LENGTH_RE =
+	/context[ _-]?length|context[ _-]?window|maximum context|too many tokens|reduce (?:the |your )?(?:length|prompt)|prompt is too long|token limit/i;
+
+function asRec(v: unknown): Record<string, unknown> | null {
+	return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+function classifyStatus(status: number, body: unknown): UpstreamError {
+	const rec = asRec(body);
+	const errRec = rec ? asRec(rec.error) : null;
+	const msg = errRec?.message ?? rec?.message;
+	const message = typeof msg === "string" && msg !== "" ? msg : `OpenRouter HTTP ${status}`;
+	const fail = (kind: UpstreamErrorKind, retryable: boolean): UpstreamError =>
+		new UpstreamError(kind, status, message, retryable, body);
+	if (status === 401 || status === 403) return fail("auth", false);
+	// 402 = out of credits; retrying changes nothing, only topping up does.
+	if (status === 402) return fail("auth", false);
+	if (status === 429) return fail("rate_limit", true);
+	if (status === 400) {
+		return CONTEXT_LENGTH_RE.test(message) ? fail("context_length", false) : fail("invalid_request", false);
+	}
+	// Provider routing may recover a missing model on the next attempt.
+	if (status === 404) return fail("model_unavailable", true);
+	if (status >= 500) return fail("upstream_error", true);
+	return fail("upstream_error", status === 408);
+}
+
+async function httpError(res: Response): Promise<UpstreamError> {
+	let body: unknown = null;
+	try {
+		body = await res.json();
+	} catch {
+		// Non-JSON error body — the status alone drives classification.
+	}
+	return classifyStatus(res.status, body);
+}
+
+// Mid-stream failure arrives as an SSE payload: {"error": {message, code}}.
+function streamError(raw: unknown): UpstreamError {
+	const rec = asRec(raw) ?? {};
+	const message = typeof rec.message === "string" && rec.message !== "" ? rec.message : "OpenRouter stream error";
+	const code = rec.code;
+	const status = typeof code === "number" && Number.isFinite(code) ? code : 0;
+	if (status === 0) return new UpstreamError("upstream_error", 0, message, true, raw);
+	return classifyStatus(status, raw);
+}
+
+// Transport-level rejection: timeout, caller abort, or a socket failure.
+function transportError(err: unknown): UpstreamError {
+	if (err instanceof UpstreamError) return err;
+	const name = err instanceof Error ? err.name : "";
+	if (name === "TimeoutError") return new UpstreamError("timeout", 0, "OpenRouter request timed out", true);
+	if (name === "AbortError") return new UpstreamError("aborted", 0, "request aborted", false);
+	return new UpstreamError("network", 0, err instanceof Error ? err.message : String(err), true);
+}
+
+export function createOpenRouterClient(cfg: RouterConfig): UpstreamClient {
+	const baseUrl = cfg.openrouter.baseUrl.replace(/\/+$/, "");
+	const log = createLogger(cfg.logLevel);
+
+	// Compose the per-request timeout with the caller's cancellation.
+	function composeSignal(caller: AbortSignal | undefined): AbortSignal | null {
+		const timeout = cfg.openrouter.timeoutMs > 0 ? AbortSignal.timeout(cfg.openrouter.timeoutMs) : null;
+		if (caller && timeout) return AbortSignal.any([caller, timeout]);
+		return caller ?? timeout;
+	}
+
+	function headers(extra: Record<string, string>): Record<string, string> {
+		const h: Record<string, string> = {
+			"content-type": "application/json",
+			"x-title": cfg.openrouter.title,
+			...extra,
+		};
+		// /models is public; an empty key must not produce a broken Bearer header.
+		if (cfg.openrouter.apiKey !== "") h.authorization = `Bearer ${cfg.openrouter.apiKey}`;
+		if (cfg.openrouter.referer) h["http-referer"] = cfg.openrouter.referer;
+		return h;
+	}
+
+	return {
+		async dispatch(opts: DispatchOptions): Promise<Dispatch> {
+			const signal = composeSignal(opts.signal);
+			// session_id pins provider stickiness so prompt caches stay warm across
+			// turns. No `usage` flag: OpenRouter now returns full cost and cache
+			// accounting on every response, and the old opt-in is a no-op.
+			// The wire's rendered body wins on conflicts, except the two invariants
+			// this client owns: streaming and session id.
+			const body = { ...opts.body, stream: true, session_id: opts.sessionId };
+			let res: Response;
+			try {
+				res = await fetch(`${baseUrl}/chat/completions`, {
+					method: "POST",
+					headers: headers({ "x-session-id": opts.sessionId }),
+					body: JSON.stringify(body),
+					signal,
+				});
+			} catch (err) {
+				throw transportError(err);
+			}
+			if (!res.ok) throw await httpError(res);
+			if (!res.body) throw new UpstreamError("upstream_error", res.status, "response had no body", true);
+
+			const parsed = parseSse(res.body, (msg, fields) => log.warn(msg, fields));
+			let resolveId!: (id: string | null) => void;
+			const idPromise = new Promise<string | null>((resolve) => {
+				resolveId = resolve;
+			});
+			let idResolved = false;
+			const resolveOnce = (id: string | null): void => {
+				if (!idResolved) {
+					idResolved = true;
+					resolveId(id);
+				}
+			};
+
+			const chunks = (async function* (): AsyncGenerator<UpstreamChunk> {
+				try {
+					for await (const chunk of parsed) {
+						// OpenRouter can fail mid-stream as an SSE payload instead of an
+						// HTTP status; reclassify it so callers see one error shape.
+						const errPayload = chunk.raw.error;
+						if (errPayload !== undefined && errPayload !== null) throw streamError(errPayload);
+						if (!idResolved && typeof chunk.raw.id === "string") resolveOnce(chunk.raw.id);
+						yield chunk;
+					}
+				} catch (err) {
+					throw transportError(err);
+				} finally {
+					// generationId() must never hang, even if the consumer abandons
+					// the stream before the first chunk.
+					resolveOnce(null);
+				}
+			})();
+
+			return { chunks, generationId: () => idPromise };
+		},
+
+		async complete(
+			body: Record<string, unknown>,
+			signal: AbortSignal,
+		): Promise<{ text: string; costUsd: number | null }> {
+			// Single attempt by design: this feeds the classifier adjudicator,
+			// where a retry would double adjudication cost on ambiguous turns.
+			let res: Response;
+			try {
+				res = await fetch(`${baseUrl}/chat/completions`, {
+					method: "POST",
+					headers: headers({}),
+					body: JSON.stringify({ ...body, stream: false }),
+					signal: composeSignal(signal),
+				});
+			} catch (err) {
+				throw transportError(err);
+			}
+			if (!res.ok) throw await httpError(res);
+			const json = asRec(await res.json());
+			const choices = json?.choices;
+			const choice0 = Array.isArray(choices) && choices.length > 0 ? asRec(choices[0]) : null;
+			const message = choice0 ? asRec(choice0.message) : null;
+			const content = message?.content;
+			const usage = json ? asRec(json.usage) : null;
+			const cost = usage?.cost;
+			return {
+				text: typeof content === "string" ? content : "",
+				costUsd: typeof cost === "number" && Number.isFinite(cost) ? cost : null,
+			};
+		},
+
+		async fetchModels(signal?: AbortSignal): Promise<unknown[]> {
+			let res: Response;
+			try {
+				res = await fetch(`${baseUrl}/models`, { headers: headers({}), signal: composeSignal(signal) });
+			} catch (err) {
+				throw transportError(err);
+			}
+			if (!res.ok) throw await httpError(res);
+			const data = asRec(await res.json())?.data;
+			if (!Array.isArray(data)) {
+				throw new UpstreamError("upstream_error", res.status, "models payload had no data array", true);
+			}
+			return data;
+		},
+
+		async fetchModelsForUser(signal?: AbortSignal): Promise<unknown[]> {
+			let res: Response;
+			try {
+				res = await fetch(`${baseUrl}/models/user`, { headers: headers({}), signal: composeSignal(signal) });
+			} catch (err) {
+				throw transportError(err);
+			}
+			if (!res.ok) throw await httpError(res);
+			const data = asRec(await res.json())?.data;
+			if (!Array.isArray(data)) {
+				throw new UpstreamError("upstream_error", res.status, "models/user payload had no data array", true);
+			}
+			return data;
+		},
+	};
+}