auto-model-router 0.32.0 → 0.33.0

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.32.0",
+    "version": "0.33.0",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.32.0",
+      "version": "0.33.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1426,6 +1426,35 @@ ignored rather than failing the turn. The decision trail records what the
 policy changed (`policy: …`), and `GET /v1/router/catalog?policy=…` shows what a
 policy admits, model by model, without routing a turn.
 
+## Per-turn upstream credentials
+
+The same front door can also send the credentials one turn dispatches with, in
+an `X-Omp-Upstream-Keys` header carrying JSON that maps an upstream id to a
+credential:
+
+```json
+{ "openrouter": "sk-or-v1-…", "azure-eu": "…" }
+```
+
+The ids are the ones the catalog and `/health` use: `openrouter`, `ollama`, or
+a named entry's `id`. An upstream named here dispatches with that credential
+for the whole turn — every retry, same-tier failover and tier escalation
+included — instead of its configured `apiKey`; one not named keeps the
+configured key. An upstream mapped to `""` has **no** credential this turn and
+is excluded from selection rather than dispatched keyless, so a turn that
+carries nothing usable for a provider simply routes elsewhere.
+
+Nothing is stored: the override lives on the parsed request and is read when a
+header is built, so the shared configuration is never written to and concurrent
+turns carrying different callers' keys cannot see each other's. The credential
+is a secret and is treated as one — it is never logged, never recorded in the
+ledger, and never repeated in an error or a decision reason. A malformed header
+is ignored like a malformed `X-Omp-Policy`, leaving the configured keys in
+force.
+
+This is what lets one router serve callers who bring their own keys — the team
+edition's per-user credentials — without a process per credential set.
+
 ## Data governance
 
 Two things an operator with a compliance obligation needs from a router: that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/router/candidates.ts

@@ -214,6 +214,15 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			continue;
 		}
 
+		// A per-turn credential map that names this model's upstream with an
+		// empty string says the turn HAS no key for it: dispatching would 401,
+		// so it is not a candidate this turn (and is a candidate again on the
+		// next turn that does carry one).
+		if (req.upstreamKeys?.[model.provider] === "") {
+			rejected.push({ slug, reason: "no_credential", detail: `upstream ${model.provider} has no credential on this turn` });
+			continue;
+		}
+
 		// Hard-coded denials, before any user configuration.
 		const builtIn = builtInDenial(model);
 		if (builtIn !== null) {

package/src/router/types.ts

@@ -164,6 +164,8 @@ export type RejectionReason =
 	| "free_tier_excluded"
 	| "reasoning_mandatory"
 	| "untrusted"
+	/** The turn's `X-Omp-Upstream-Keys` names this model's upstream with an empty credential: it cannot be dispatched to. */
+	| "no_credential"
 	/** Already failed on this turn; excluded so failover picks a different model. */
 	| "failed_this_turn";
 

package/src/server/http.ts

@@ -918,6 +918,12 @@ export function startServer(cfg: RouterConfig): StartedServer {
 					const snap = catalog.peek();
 					return json({
 						status: "ok",
+						// What a front door may rely on, by name rather than by version: a
+						// team edition that sends per-turn credentials to a router without
+						// `upstream-keys` would have them ignored, and its tenants served on
+						// the deployment's own credential — a silent cross-charge. A name it
+						// can check turns that into a refusal it can explain.
+						features: ["upstream-keys"],
 						apiKeyConfigured: cfg.openrouter.apiKey !== "",
 						// Which upstreams turns can actually be served from: OpenRouter needs
 						// its key; Ollama needs to be on and out of cooldown.

package/src/server/turn.ts

@@ -472,7 +472,9 @@ export async function runTurn(
 		let streamEnded = false;
 
 		try {
-			dispatch = await upstream.dispatch({ body, sessionId: decision.sessionId, signal: attemptSignal });
+			// Inside the attempt loop, so a retry, a same-tier failover and a tier
+			// escalation all dispatch with the same per-turn credentials.
+			dispatch = await upstream.dispatch({ body, sessionId: decision.sessionId, signal: attemptSignal, ...(req.upstreamKeys === undefined ? {} : { upstreamKeys: req.upstreamKeys }) });
 		} catch (err) {
 			streamError = err;
 		}

package/src/upstream/anthropic.ts

@@ -410,13 +410,13 @@ export function createAnthropicClient(cfg: RouterConfig, id: string, fetchImpl:
 		if (caller && timeout) return AbortSignal.any([caller, timeout]);
 		return caller ?? timeout;
 	}
-	async function post(e: UpstreamEntry, body: Record<string, unknown>, signal: AbortSignal | undefined): Promise<Response> {
+	async function post(e: UpstreamEntry, body: Record<string, unknown>, signal: AbortSignal | undefined, apiKey: string = e.apiKey): Promise<Response> {
 		const headers: Record<string, string> = { "content-type": "application/json", "anthropic-version": ANTHROPIC_VERSION, ...e.headers };
 		if (e.auth === "oauth-bearer") {
 			// A Claude Pro/Max subscription token: Bearer auth at the first-party API, with the OAuth beta. No per-token cost is reported.
-			headers["authorization"] = `Bearer ${e.apiKey}`;
+			headers["authorization"] = `Bearer ${apiKey}`;
 			headers["anthropic-beta"] = e.headers["anthropic-beta"] ?? "oauth-2025-04-20,claude-code-20250219";
-		} else if (e.apiKey !== "") headers["x-api-key"] = e.apiKey;
+		} else if (apiKey !== "") headers["x-api-key"] = apiKey;
 		try {
 			return await fetchImpl(`${e.baseUrl.replace(/\/+$/, "")}/v1/messages`, { method: "POST", headers, body: JSON.stringify(body), signal: composeSignal(e, signal) });
 		} catch (err) {
@@ -444,7 +444,8 @@ export function createAnthropicClient(cfg: RouterConfig, id: string, fetchImpl:
 		async dispatch(opts: DispatchOptions): Promise<Dispatch> {
 			const e = entry();
 			const { rendered, servedSlug } = render(e, { ...opts.body, stream: true });
-			const res = await post(e, rendered, opts.signal);
+			// A per-turn credential for this upstream wins for this dispatch only; the shared entry is never touched.
+			const res = await post(e, rendered, opts.signal, opts.upstreamKeys?.[id] ?? e.apiKey);
 			if (!res.ok) throw await httpError(res);
 			if (!res.body) throw new UpstreamError("upstream_error", res.status, "response had no body", true);
 			const translator = createAnthropicTranslator(servedSlug);

package/src/upstream/compat.ts

@@ -113,15 +113,20 @@ function transportError(id: string, err: unknown): UpstreamError {
 	return new UpstreamError("network", 0, err instanceof Error ? err.message : String(err), true);
 }
 
-/** The chat-completions URL and auth for an entry: Azure names the deployment in the path and keys with `api-key`. */
-export function compatEndpoint(entry: UpstreamEntry, modelId: string): { url: string; headers: Record<string, string> } {
+/**
+ * The chat-completions URL and auth for an entry: Azure names the deployment in the path and keys with `api-key`.
+ *
+ * `apiKey` overrides the entry's own credential for one dispatch (a per-turn
+ * key from the front door). The entry itself is never written to.
+ */
+export function compatEndpoint(entry: UpstreamEntry, modelId: string, apiKey: string = entry.apiKey): { url: string; headers: Record<string, string> } {
 	const base = entry.baseUrl.replace(/\/+$/, "");
 	const headers: Record<string, string> = { "content-type": "application/json", ...entry.headers };
 	if (entry.kind === "azure") {
-		if (entry.apiKey !== "") headers["api-key"] = entry.apiKey;
+		if (apiKey !== "") headers["api-key"] = apiKey;
 		return { url: `${base}/openai/deployments/${encodeURIComponent(modelId)}/chat/completions?api-version=${encodeURIComponent(entry.apiVersion)}`, headers };
 	}
-	if (entry.apiKey !== "") headers.authorization = `Bearer ${entry.apiKey}`;
+	if (apiKey !== "") headers.authorization = `Bearer ${apiKey}`;
 	return { url: `${base}/chat/completions`, headers };
 }
 
@@ -195,8 +200,8 @@ export function createCompatClient(cfg: RouterConfig, id: string, fetchImpl: Fet
 		return err;
 	}
 
-	async function post(e: UpstreamEntry, body: Record<string, unknown>, signal: AbortSignal | undefined): Promise<Response> {
-		const { url, headers } = compatEndpoint(e, typeof body.model === "string" ? body.model : "");
+	async function post(e: UpstreamEntry, body: Record<string, unknown>, signal: AbortSignal | undefined, apiKey: string = e.apiKey): Promise<Response> {
+		const { url, headers } = compatEndpoint(e, typeof body.model === "string" ? body.model : "", apiKey);
 		try {
 			return await fetchImpl(url, { method: "POST", headers, body: JSON.stringify(body), signal: composeSignal(e, signal) });
 		} catch (err) {
@@ -212,7 +217,8 @@ export function createCompatClient(cfg: RouterConfig, id: string, fetchImpl: Fet
 
 		async dispatch(opts: DispatchOptions): Promise<Dispatch> {
 			const e = entry();
-			const res = await post(e, toCompatBody(id, { ...opts.body, stream: true }), opts.signal);
+			// A per-turn credential for this upstream wins for this dispatch only; the shared entry is never touched.
+			const res = await post(e, toCompatBody(id, { ...opts.body, stream: true }), opts.signal, opts.upstreamKeys?.[id] ?? e.apiKey);
 			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));

package/src/upstream/ollama.ts

@@ -146,9 +146,9 @@ export function createOllamaClient(cfg: RouterConfig, fetchImpl: FetchLike = fet
 		log.warn("ollama cloud unavailable; routing around it", { kind: err.kind, cooldownMs: ms, message: err.message });
 	};
 
-	function headers(extra: Record<string, string> = {}): Record<string, string> {
+	function headers(extra: Record<string, string> = {}, apiKey: string = o.apiKey): Record<string, string> {
 		const h: Record<string, string> = { "content-type": "application/json", ...extra };
-		if (o.apiKey !== "") h.authorization = `Bearer ${o.apiKey}`;
+		if (apiKey !== "") h.authorization = `Bearer ${apiKey}`;
 		return h;
 	}
 
@@ -195,7 +195,8 @@ export function createOllamaClient(cfg: RouterConfig, fetchImpl: FetchLike = fet
 			try {
 				res = await fetchImpl(`${baseUrl()}/chat/completions`, {
 					method: "POST",
-					headers: headers(),
+					// A per-turn credential wins for this dispatch only; cfg is never written to.
+					headers: headers({}, opts.upstreamKeys?.ollama ?? o.apiKey),
 					body: JSON.stringify(body),
 					signal: composeSignal(opts.signal),
 				});

package/src/upstream/openrouter.ts

@@ -114,14 +114,14 @@ export function createOpenRouterClient(cfg: RouterConfig): UpstreamClient {
 		return caller ?? timeout;
 	}
 
-	function headers(extra: Record<string, string>): Record<string, string> {
+	function headers(extra: Record<string, string>, apiKey: string = cfg.openrouter.apiKey): 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 (apiKey !== "") h.authorization = `Bearer ${apiKey}`;
 		if (cfg.openrouter.referer) h["http-referer"] = cfg.openrouter.referer;
 		return h;
 	}
@@ -139,7 +139,8 @@ export function createOpenRouterClient(cfg: RouterConfig): UpstreamClient {
 			try {
 				res = await fetch(`${baseUrl}/chat/completions`, {
 					method: "POST",
-					headers: headers({ "x-session-id": opts.sessionId }),
+					// A per-turn credential wins for this dispatch only; cfg is never written to.
+					headers: headers({ "x-session-id": opts.sessionId }, opts.upstreamKeys?.openrouter ?? cfg.openrouter.apiKey),
 					body: JSON.stringify(body),
 					signal,
 				});

package/src/upstream/types.ts

@@ -43,6 +43,13 @@ export interface DispatchOptions {
 	body: Record<string, unknown>;
 	/** Forwarded as the `x-session-id` header, mirroring body `session_id`. */
 	sessionId: string;
+	/**
+	 * Per-turn credentials by upstream id (`NormRequest.upstreamKeys`). The
+	 * client dispatching this body prefers its own entry over the configured
+	 * `apiKey`, without ever writing to the shared config: concurrent turns
+	 * carry different tenants' keys over the same `UpstreamEntry`.
+	 */
+	upstreamKeys?: Readonly<Record<string, string>>;
 	signal: AbortSignal;
 }
 

package/src/wire/openai/request.ts

@@ -315,6 +315,31 @@ export function parsePolicyHeader(raw: string | null): RequestPolicy | undefined
 	return Object.keys(out).length === 0 ? undefined : out;
 }
 
+/**
+ * Parses the X-Omp-Upstream-Keys header: `{ "<upstream id>": "<credential>" }`.
+ * Malformed, not an object, or empty ⇒ no overrides, exactly like a malformed
+ * X-Omp-Policy (never a rejected turn — the configured keys still serve).
+ * Non-string values are dropped; `""` is KEPT, meaning "this turn has no
+ * credential for that upstream", which excludes it from selection.
+ */
+export function parseUpstreamKeysHeader(raw: string | null): Record<string, string> | undefined {
+	if (raw === null || raw.trim() === "") return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+	const out: Record<string, string> = {};
+	for (const [id, value] of Object.entries(parsed as Record<string, unknown>)) {
+		// The id is config-shaped, so trim it; the credential is copied verbatim.
+		const key = id.trim();
+		if (key !== "" && typeof value === "string") out[key] = value;
+	}
+	return Object.keys(out).length === 0 ? undefined : out;
+}
+
 export function parseChatRequest(body: unknown, headers: Headers): NormRequest {
 	if (typeof body !== "object" || body === null || Array.isArray(body)) {
 		throw invalidRequest("Request body must be a JSON object");
@@ -352,6 +377,9 @@ export function parseChatRequest(body: unknown, headers: Headers): NormRequest {
 	// Per-request routing policy (team edition): JSON in X-Omp-Policy.
 	const policy = parsePolicyHeader(headers.get("x-omp-policy"));
 
+	// Per-turn upstream credentials (team edition): JSON in X-Omp-Upstream-Keys.
+	const upstreamKeys = parseUpstreamKeysHeader(headers.get("x-omp-upstream-keys"));
+
 	if (typeof b.model !== "string" || b.model.length === 0) {
 		throw invalidRequest("model must be a non-empty string");
 	}
@@ -417,6 +445,7 @@ export function parseChatRequest(body: unknown, headers: Headers): NormRequest {
 		agentdoxOrigin,
 		isSubagent,
 		...(policy === undefined ? {} : { policy }),
+		...(upstreamKeys === undefined ? {} : { upstreamKeys }),
 		requestedModel,
 		requestedModelFull: b.model,
 		messages,

package/src/wire/types.ts

@@ -126,6 +126,21 @@ export interface NormRequest {
 	 * to. Absent ⇒ the configured profile and filters alone.
 	 */
 	policy?: RequestPolicy;
+	/**
+	 * Per-turn upstream credentials from the `X-Omp-Upstream-Keys` header
+	 * (JSON `{ "<upstream id>": "<credential>" }`), set by a front door whose
+	 * callers bring their own keys: one router fleet then serves every tenant
+	 * instead of one process per credential set. Keyed by upstream id —
+	 * `openrouter`, `ollama`, or a named entry's `id`.
+	 *
+	 * An upstream named here dispatches with this credential for the whole
+	 * turn, every retry and failover included; one not named keeps its
+	 * configured `apiKey`; one named with `""` carries no credential and is
+	 * excluded from candidate selection rather than dispatched keyless.
+	 *
+	 * A secret: never logged, recorded, or repeated in an error.
+	 */
+	upstreamKeys?: Readonly<Record<string, string>>;
 	/** Virtual model the client selected, e.g. `auto`, `auto-cheap`, `auto-max`. */
 	requestedModel: string;
 	/**

package/test/failover.test.ts

@@ -703,3 +703,44 @@ describe("400 classification (review 2026-09-05 follow-up)", () => {
 	});
 });
 
+describe("per-turn upstream credentials", () => {
+	test("the turn's credentials reach the first dispatch, the failover retry, and nothing else", async () => {
+		const { router } = mkRouter([mkDecision("moderate", "a/model"), mkDecision("moderate", "b/model")]);
+		const { upstream, calls: dispatches } = mkUpstream([
+			{ kind: "fail", error: new UpstreamError("model_unavailable", 404, "no endpoints found", true) },
+			{ kind: "chunks", chunks: okChunks("b/model") },
+		]);
+		const { ledger, entries } = mkLedger();
+		const { store } = mkConversations();
+		const { sink, errors, finishes } = mkSink();
+		const upstreamKeys = { "up-a": "sk-tenant-secret", "up-b": "sk-other-secret" };
+
+		await runTurn({ ...mkReq(), upstreamKeys }, sink, { config: mkConfig(), router, upstream, ledger, conversations: store, catalog, context: createDisabledBridge() }, new AbortController().signal);
+
+		expect(errors).toHaveLength(0);
+		expect(finishes).toHaveLength(1);
+		// Both attempts carry them: a retry that dropped the credential would 401.
+		expect(dispatches).toHaveLength(2);
+		for (const d of dispatches) expect(d.upstreamKeys).toEqual(upstreamKeys);
+
+		// A secret: it is in no ledger row, no decision reason, and no error text.
+		const recorded = JSON.stringify(entries);
+		expect(recorded).not.toContain("sk-tenant-secret");
+		expect(recorded).not.toContain("sk-other-secret");
+		expect(JSON.stringify(finishes)).not.toContain("sk-tenant-secret");
+	});
+
+	test("a turn without the header dispatches with no override at all", async () => {
+		const { router } = mkRouter([mkDecision("moderate", "a/model")]);
+		const { upstream, calls: dispatches } = mkUpstream([{ kind: "chunks", chunks: okChunks("a/model") }]);
+		const { ledger } = mkLedger();
+		const { store } = mkConversations();
+		const { sink, errors } = mkSink();
+
+		await runTurn(mkReq(), sink, { config: mkConfig(), router, upstream, ledger, conversations: store, catalog, context: createDisabledBridge() }, new AbortController().signal);
+
+		expect(errors).toHaveLength(0);
+		expect("upstreamKeys" in dispatches[0]!).toBe(false);
+	});
+});
+

package/test/upstream-keys.test.ts

@@ -0,0 +1,240 @@
+import { describe, expect, test } from "bun:test";
+
+import { buildUpstreamModels } from "../src/catalog/static-catalog.ts";
+import type { CatalogSnapshot } from "../src/catalog/types.ts";
+import { DEFAULT_CONFIG } from "../src/config/defaults.ts";
+import type { RouterConfig, UpstreamEntry } from "../src/config/types.ts";
+import { completeUpstreamEntry } from "../src/config/upstreams.ts";
+import { buildCandidates } from "../src/router/candidates.ts";
+import { extractFeatures } from "../src/router/features.ts";
+import type { Rejection } from "../src/router/types.ts";
+import { createAnthropicClient } from "../src/upstream/anthropic.ts";
+import { compatEndpoint, createCompatClient } from "../src/upstream/compat.ts";
+import { createOllamaClient } from "../src/upstream/ollama.ts";
+import { createOpenRouterClient } from "../src/upstream/openrouter.ts";
+import { parseMessagesRequest } from "../src/wire/anthropic/messages.ts";
+import { parseChatRequest, parseUpstreamKeysHeader } from "../src/wire/openai/request.ts";
+import { parseResponsesRequest } from "../src/wire/openai/responses.ts";
+
+/**
+ * Per-turn upstream credentials (X-Omp-Upstream-Keys): a front door whose
+ * callers bring their own keys sends the turn's credentials in a header, so one
+ * router fleet serves every tenant instead of one process per credential set.
+ *
+ * The property everything else rests on: the credential belongs to the TURN.
+ * The shared `UpstreamEntry` is never written to, so two concurrent turns
+ * cannot see each other's key.
+ */
+
+const NL = String.fromCharCode(10);
+
+function entry(over: Partial<UpstreamEntry> & { id: string; kind: UpstreamEntry["kind"] }): UpstreamEntry {
+	return completeUpstreamEntry({ baseUrl: "https://api.example/v1", apiKey: "sk-configured", models: [{ id: "m1", input: 1, output: 4 }], ...over });
+}
+
+function cfgWith(upstreams: UpstreamEntry[]): RouterConfig {
+	return { ...structuredClone(DEFAULT_CONFIG), upstreams, logLevel: "silent" };
+}
+
+function sse(frames: string[]): Response {
+	return new Response(
+		new ReadableStream({
+			start: (c) => {
+				for (const f of frames) c.enqueue(new TextEncoder().encode(`${f}${NL}${NL}`));
+				c.close();
+			},
+		}),
+		{ status: 200, headers: { "content-type": "text/event-stream" } },
+	);
+}
+
+/** Drains a dispatch so the fake upstream's stream is consumed like a real turn's. */
+async function drain(d: { chunks: AsyncIterable<unknown> }): Promise<void> {
+	for await (const c of d.chunks) void c;
+}
+
+const OK_FRAMES = [`data: ${JSON.stringify({ id: "gen-1", model: "m1", choices: [{ delta: { content: "hi" } }] })}`, "data: [DONE]"];
+const ANTHROPIC_FRAMES = [
+	`event: message_start${NL}data: ${JSON.stringify({ type: "message_start", message: { id: "msg_1", model: "claude-sonnet-4", usage: { input_tokens: 1, output_tokens: 0 } } })}`,
+	`event: message_stop${NL}data: ${JSON.stringify({ type: "message_stop" })}`,
+];
+
+const SIGNAL = new AbortController().signal;
+
+describe("parseUpstreamKeysHeader", () => {
+	test("accepts an id→credential object, drops junk, and never rejects a turn", async () => {
+		// Same defensive contract as X-Omp-Policy: anything unusable is simply no override.
+		expect(parseUpstreamKeysHeader(null)).toBeUndefined();
+		expect(parseUpstreamKeysHeader("   ")).toBeUndefined();
+		expect(parseUpstreamKeysHeader("not json")).toBeUndefined();
+		expect(parseUpstreamKeysHeader('["sk-x"]')).toBeUndefined();
+		expect(parseUpstreamKeysHeader('"sk-x"')).toBeUndefined();
+		expect(parseUpstreamKeysHeader("{}")).toBeUndefined();
+		// Non-string values are dropped; an empty string is KEPT — it means "no credential this turn".
+		expect(parseUpstreamKeysHeader(JSON.stringify({ openrouter: "sk-or-1", " azure-eu ": "az", bad: 7, worse: null, "": "x", off: "" }))).toEqual({
+			openrouter: "sk-or-1",
+			"azure-eu": "az",
+			off: "",
+		});
+		// The credential is copied verbatim: trimming one would break a key whose bytes matter.
+		expect(parseUpstreamKeysHeader(JSON.stringify({ up: " sk-pad " }))).toEqual({ up: " sk-pad " });
+	});
+
+	test("every wire carries the map, and its absence leaves the property off", async () => {
+		const header = new Headers({ "X-Omp-Upstream-Keys": '{"openrouter":"sk-or-tenant"}' });
+		const chat = parseChatRequest({ model: "auto", messages: [{ role: "user", content: "hi" }] }, header);
+		const messages = parseMessagesRequest({ model: "claude-sonnet-4", messages: [{ role: "user", content: "hi" }], max_tokens: 16 }, header);
+		const responses = parseResponsesRequest({ model: "auto", input: "hi" }, header);
+		for (const req of [chat, messages, responses]) expect(req.upstreamKeys).toEqual({ openrouter: "sk-or-tenant" });
+		expect([chat.protocol, messages.protocol, responses.protocol]).toEqual(["openai-chat", "anthropic-messages", "openai-responses"]);
+		// exactOptionalPropertyTypes: absent means absent, not `undefined`.
+		expect("upstreamKeys" in parseChatRequest({ model: "auto", messages: [{ role: "user", content: "hi" }] }, new Headers())).toBe(false);
+		expect("upstreamKeys" in parseMessagesRequest({ model: "claude-sonnet-4", messages: [{ role: "user", content: "hi" }], max_tokens: 16 }, new Headers())).toBe(false);
+		expect("upstreamKeys" in parseResponsesRequest({ model: "auto", input: "hi" }, new Headers())).toBe(false);
+	});
+});
+
+describe("per-turn credentials at dispatch", () => {
+	test("compatEndpoint prefers the per-turn key without touching the entry", async () => {
+		const e = entry({ id: "openai-direct", kind: "openai" });
+		expect(compatEndpoint(e, "m1").headers.authorization).toBe("Bearer sk-configured");
+		expect(compatEndpoint(e, "m1", "sk-turn").headers.authorization).toBe("Bearer sk-turn");
+		// Azure keys with its own header, and an empty credential sends none at all.
+		const az = entry({ id: "azure-eu", kind: "azure" });
+		expect(compatEndpoint(az, "dep", "az-turn").headers["api-key"]).toBe("az-turn");
+		expect(compatEndpoint(az, "dep", "").headers["api-key"]).toBeUndefined();
+		expect(e.apiKey).toBe("sk-configured");
+	});
+
+	test("an OpenAI-compatible upstream uses the turn's key, else the configured one", async () => {
+		const seen: Array<string | null> = [];
+		const cfg = cfgWith([entry({ id: "openai-direct", kind: "openai" })]);
+		const client = createCompatClient(cfg, "openai-direct", async (_url, init) => {
+			seen.push(new Headers(init?.headers).get("authorization"));
+			return sse(OK_FRAMES);
+		});
+		const body = { model: "openai-direct/m1", messages: [] };
+		await drain(await client.dispatch({ body, sessionId: "s", signal: SIGNAL, upstreamKeys: { "openai-direct": "sk-turn" } }));
+		await drain(await client.dispatch({ body, sessionId: "s", signal: SIGNAL }));
+		// A map that names a DIFFERENT upstream leaves this one on its own key.
+		await drain(await client.dispatch({ body, sessionId: "s", signal: SIGNAL, upstreamKeys: { openrouter: "sk-or" } }));
+		// An empty credential is "none", never a fallback to the configured key.
+		await drain(await client.dispatch({ body, sessionId: "s", signal: SIGNAL, upstreamKeys: { "openai-direct": "" } }));
+		expect(seen).toEqual(["Bearer sk-turn", "Bearer sk-configured", "Bearer sk-configured", null]);
+		expect(cfg.upstreams[0]!.apiKey).toBe("sk-configured");
+	});
+
+	test("an Anthropic upstream uses the turn's key on both auth shapes", async () => {
+		const seen: Array<Record<string, string | null>> = [];
+		const cfg = cfgWith([
+			entry({ id: "anthropic-direct", kind: "anthropic", apiKey: "sk-ant-configured" }),
+			entry({ id: "claude-sub", kind: "anthropic", auth: "oauth-bearer", apiKey: "oauth-configured" }),
+		]);
+		const fetchImpl = async (_url: unknown, init?: RequestInit): Promise<Response> => {
+			const h = new Headers(init?.headers);
+			seen.push({ "x-api-key": h.get("x-api-key"), authorization: h.get("authorization") });
+			return sse(ANTHROPIC_FRAMES);
+		};
+		const direct = createAnthropicClient(cfg, "anthropic-direct", fetchImpl);
+		const sub = createAnthropicClient(cfg, "claude-sub", fetchImpl);
+		await drain(await direct.dispatch({ body: { model: "anthropic-direct/m1", messages: [{ role: "user", content: "hi" }], max_tokens: 16 }, sessionId: "s", signal: SIGNAL, upstreamKeys: { "anthropic-direct": "sk-ant-turn" } }));
+		await drain(await direct.dispatch({ body: { model: "anthropic-direct/m1", messages: [{ role: "user", content: "hi" }], max_tokens: 16 }, sessionId: "s", signal: SIGNAL }));
+		await drain(await sub.dispatch({ body: { model: "claude-sub/m1", messages: [{ role: "user", content: "hi" }], max_tokens: 16 }, sessionId: "s", signal: SIGNAL, upstreamKeys: { "claude-sub": "oauth-turn" } }));
+		expect(seen).toEqual([
+			{ "x-api-key": "sk-ant-turn", authorization: null },
+			{ "x-api-key": "sk-ant-configured", authorization: null },
+			{ "x-api-key": null, authorization: "Bearer oauth-turn" },
+		]);
+		expect(cfg.upstreams.map((u) => u.apiKey)).toEqual(["sk-ant-configured", "oauth-configured"]);
+	});
+
+	test("OpenRouter and Ollama take an override under their own reserved ids", async () => {
+		const cfg = cfgWith([]);
+		cfg.openrouter.apiKey = "sk-or-configured";
+		cfg.ollama = { ...cfg.ollama, apiKey: "sk-ollama-configured" };
+		const seen: Array<string | null> = [];
+		const realFetch = globalThis.fetch;
+		globalThis.fetch = (async (_url: unknown, init?: RequestInit) => {
+			seen.push(new Headers(init?.headers).get("authorization"));
+			return sse(OK_FRAMES);
+		}) as unknown as typeof fetch;
+		try {
+			const or = createOpenRouterClient(cfg);
+			await drain(await or.dispatch({ body: { model: "a/b", messages: [] }, sessionId: "s", signal: SIGNAL, upstreamKeys: { openrouter: "sk-or-turn" } }));
+			await drain(await or.dispatch({ body: { model: "a/b", messages: [] }, sessionId: "s", signal: SIGNAL }));
+		} finally {
+			globalThis.fetch = realFetch;
+		}
+		const ollama = createOllamaClient(cfg, async (_url, init) => {
+			seen.push(new Headers(init?.headers).get("authorization"));
+			return sse(OK_FRAMES);
+		});
+		await drain(await ollama.dispatch({ body: { model: "ollama/m", messages: [] }, sessionId: "s", signal: SIGNAL, upstreamKeys: { ollama: "sk-ollama-turn" } }));
+		await drain(await ollama.dispatch({ body: { model: "ollama/m", messages: [] }, sessionId: "s", signal: SIGNAL }));
+		expect(seen).toEqual(["Bearer sk-or-turn", "Bearer sk-or-configured", "Bearer sk-ollama-turn", "Bearer sk-ollama-configured"]);
+		expect(cfg.openrouter.apiKey).toBe("sk-or-configured");
+		expect(cfg.ollama.apiKey).toBe("sk-ollama-configured");
+	});
+
+	test("two concurrent turns over one entry never see each other's credential", async () => {
+		const cfg = cfgWith([entry({ id: "openai-direct", kind: "openai" })]);
+		let release!: () => void;
+		const gate = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		const seen: Array<string | null> = [];
+		let inFlight = 0;
+		const client = createCompatClient(cfg, "openai-direct", async (_url, init) => {
+			const auth = new Headers(init?.headers).get("authorization");
+			// Hold both requests open at once: a mutation-based implementation
+			// would have overwritten the first turn's key by the time it reads.
+			inFlight++;
+			if (inFlight === 1) await gate;
+			else release();
+			seen.push(auth);
+			return sse(OK_FRAMES);
+		});
+		const turn = async (key: string): Promise<void> => {
+			const d = await client.dispatch({ body: { model: "openai-direct/m1", messages: [] }, sessionId: "s", signal: SIGNAL, upstreamKeys: { "openai-direct": key } });
+			await drain(d);
+		};
+		await Promise.all([turn("sk-tenant-a"), turn("sk-tenant-b")]);
+		expect(seen.sort()).toEqual(["Bearer sk-tenant-a", "Bearer sk-tenant-b"]);
+		// The shared config is exactly as it was configured.
+		expect(cfg.upstreams[0]!.apiKey).toBe("sk-configured");
+	});
+});
+
+describe("candidate selection with per-turn credentials", () => {
+	const twoUpstreams = [
+		...buildUpstreamModels(entry({ id: "up-a", kind: "openai", models: [{ id: "m1", input: 1, output: 4, quality: { coding: 80, intelligence: 80, agentic: 80 } }] }), []),
+		...buildUpstreamModels(entry({ id: "up-b", kind: "openai", models: [{ id: "m1", input: 1, output: 4, quality: { coding: 80, intelligence: 80, agentic: 80 } }] }), []),
+	];
+	const snapshot: CatalogSnapshot = { models: twoUpstreams, fetchedAtMs: Date.now(), keyScoped: true };
+	const cfg: RouterConfig = { ...DEFAULT_CONFIG, adaptiveTierFloors: false, filters: { ...DEFAULT_CONFIG.filters, minTrust: 0 }, tiers: { ...DEFAULT_CONFIG.tiers, moderate: { ...DEFAULT_CONFIG.tiers.moderate, minQuality: 0, maxInputPerMtok: 10 } } };
+
+	function build(keys: Record<string, string> | undefined): { slugs: string[]; rejected: Rejection[] } {
+		const req = parseChatRequest(
+			{ model: "auto", messages: [{ role: "user", content: "hi" }] },
+			new Headers(keys === undefined ? {} : { "x-omp-upstream-keys": JSON.stringify(keys) }),
+		);
+		const { candidates, rejected } = buildCandidates({ req, features: extractFeatures(req, 100), tier: "moderate", task: "chat", snapshot, cfg, expectedCompletionTokens: 128, warmSlug: null });
+		return { slugs: candidates.map((c) => c.model.slug), rejected };
+	}
+
+	test("an upstream with an empty credential is excluded for that turn only", async () => {
+		expect(build(undefined).slugs.sort()).toEqual(["up-a/m1", "up-b/m1"]);
+		// A real credential changes nothing about who may be selected.
+		expect(build({ "up-a": "sk-turn" }).slugs.sort()).toEqual(["up-a/m1", "up-b/m1"]);
+		const off = build({ "up-a": "" });
+		expect(off.slugs).toEqual(["up-b/m1"]);
+		expect(off.rejected).toContainEqual({ slug: "up-a/m1", reason: "no_credential", detail: "upstream up-a has no credential on this turn" });
+		// The next turn, carrying a key, sees it again: nothing was recorded anywhere.
+		expect(build({ "up-a": "sk-turn" }).slugs.sort()).toEqual(["up-a/m1", "up-b/m1"]);
+	});
+
+	test("no rejection reason repeats the credential", async () => {
+		const { rejected } = build({ "up-a": "", "up-b": "sk-secret-value" });
+		expect(JSON.stringify(rejected)).not.toContain("sk-secret-value");
+	});
+});