auto-model-router 0.33.0 → 0.35.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.33.0",
+    "version": "0.35.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.33.0",
+      "version": "0.35.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1192,6 +1192,16 @@ it lands on the other (`cache: keeping warm …`), and a replica that has served
 nothing refuses with `402 budget_exceeded` once the shared spend is past its
 cap — where the same cap against an empty store serves.
 
+On Postgres the `ledger` table is partitioned by UTC day
+(`PARTITION BY RANGE (created_at_ms)`), so `ledger.retentionDays` drops whole
+days as partitions instead of deleting rows — at the write rates a shared store
+is for, a bulk `DELETE` competes for I/O with the inserts it is making room
+for. Partitions are provisioned a few days ahead on every boot and created on
+demand if a turn arrives for a day nobody provisioned, so a write never fails
+for a missing partition. A Postgres ledger created before this is left exactly
+as it is (Postgres cannot convert a populated table in place) and logs how to
+convert; see [Data governance](docs/data-governance.md).
+
 A SQLite deployment is unchanged: the file is still migrated in place through
 the nineteen shipped versions, and both halves live in the one file.
 

package/docs/data-governance.md

@@ -166,7 +166,12 @@ one a library default should make for them. (Before v0.21.0 the default was
    because the subquery needs the rows that are about to be deleted.
 2. `ollama_meter_samples` past the cutoff. They only calibrate the ledger's own
    Ollama estimate, so they age out with the rows they calibrate.
-3. `ledger` rows past the cutoff.
+3. `ledger` rows past the cutoff. On Postgres the ledger is partitioned by UTC
+   day, so every day the cutoff covers *completely* is dropped as a partition —
+   a metadata operation — and only the boundary day the cutoff falls inside is
+   deleted row by row. `deleted` still counts ROWS: each partition is counted
+   before it is dropped, so the number means turns, not tables. SQLite has no
+   declarative partitioning and deletes rows as it always has.
 
 Then, when anything was deleted, `PRAGMA incremental_vacuum` hands freed pages
 back to the filesystem and `PRAGMA wal_checkpoint(TRUNCATE)` folds the WAL so
@@ -182,6 +187,42 @@ behaviour and is fine.
 honest answer to "how far back does this ledger go now", which is what the
 question was actually about, and it is reported even when nothing was deleted.
 
+### Partitions, on Postgres
+
+A ledger row is ~2.6 kB, and a thousand-tenant deployment writes 33-165 GB a
+day at 440-2200 writes a second. Deleting that competes for I/O with the
+inserts it is trying to make room for, and leaves bloat autovacuum has to
+chase. So on Postgres `ledger` is `PARTITION BY RANGE (created_at_ms)`, one
+partition per UTC day, and retention becomes a `DROP TABLE` per day.
+
+The bounds are the ms-epoch integers the column already holds, not a derived
+timestamp, so every existing query (`created_at_ms >= ?`) prunes partitions on
+its own: no read — export, spend, the caps, the decision trail — knows the
+table is partitioned. The one visible consequence is the primary key, which a
+partitioned table requires to include the partition key: it is
+`(id, created_at_ms)` there. Ids are per-row UUIDs and a re-recorded entry
+carries the same instant, so the `ON CONFLICT DO NOTHING` guard still collapses
+a duplicate write.
+
+`migrateStore` provisions yesterday through three days ahead on every boot. A
+row for a day nobody provisioned is not an error either: the insert is retried
+once after `ensureLedgerPartitions` creates that day (and the next few), so a
+turn is never lost because a partition was late.
+
+A Postgres ledger created before this shipped **stays exactly as it is**.
+Postgres cannot convert a populated table to a partitioned one in place, and
+copying a billing table at boot is not a failure mode a ledger can have — there
+is no second copy of it. The router logs one line saying retention will keep
+deleting rows there, with the conversion an operator can run deliberately, with
+the router stopped:
+
+```sql
+ALTER TABLE ledger RENAME TO ledger_legacy;      -- then start the router:
+                                                 -- boot recreates it partitioned
+INSERT INTO ledger SELECT * FROM ledger_legacy;  -- verify the counts, then
+DROP TABLE ledger_legacy;
+```
+
 ### The schedule, and the route
 
 `createRetentionRunner` (`src/cost/retention.ts`) owns the once-an-hour floor.

package/omp-extension/router-toast.ts

@@ -27,7 +27,8 @@
 
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 
-import { routerAuthHeaders, routerBaseUrl } from "./router-url.ts";
+import { routerAuthHeaders, routerBaseUrl, routerHome } from "./router-url.ts";
+import { readRemoteRouter } from "./remote-logic.ts";
 import { newestId, selectToasts, type ToastDecision } from "./toast-logic.ts";
 
 /** Raw router config.yml, or null when there is none to read. */
@@ -35,8 +36,12 @@ import { newestId, selectToasts, type ToastDecision } from "./toast-logic.ts";
 /** Absolute path of the shared embed port file (main session writes it). */
 
 // This harness's id, matching the X-Omp-Harness header the router records.
-// Empty ⇒ toast every harness (single-harness default).
-const HARNESS_ID = process.env.OMP_HARNESS_ID ?? "";
+// In remote (team) mode the team rewrites that header to the member id from
+// the key, so remote.json's userId is the same fact — and the only way to
+// keep OTHER members' task toasts out, because task turns carry their own
+// session id and cannot be scoped by session. Empty ⇒ toast every harness
+// (single-harness default).
+const HARNESS_ID = process.env.OMP_HARNESS_ID ?? readRemoteRouter(routerHome())?.userId ?? "";
 const POLL_MS = 2_000;
 // The toast explains the choice by default: model, tier, cost, why it was picked
 // and what it was handed. `AUTO_MODEL_ROUTER_TOAST=compact` restores the one-liner.
@@ -47,6 +52,11 @@ export default function (pi: ExtensionAPI): void {
 
 	// The newest ledger entry already toasted. Ledger is `created_at_ms DESC`.
 	let lastSeenId: string | null = null;
+	// Task session → the model the task last toasted. Task turns belong to
+	// their own session ids, so this — not the session filter — is what keeps
+	// a task's forty same-model dispatches down to one toast, and surfaces the
+	// mid-task model change when an escalation switches the model.
+	const taskModels = new Map<string, string | null>();
 
 	pi.on("session_start", (_event, ctx) => {
 		// Headless/print/subagent sessions have no UI to toast into; skip the
@@ -94,7 +104,7 @@ export default function (pi: ExtensionAPI): void {
 				const entries = body.entries;
 				if (!Array.isArray(entries) || entries.length === 0) return;
 
-				for (const t of selectToasts(entries, lastSeenId, HARNESS_ID, sessionId, VERBOSE)) {
+				for (const t of selectToasts(entries, lastSeenId, HARNESS_ID, sessionId, VERBOSE, taskModels)) {
 					ctx.ui.notify(t.text, "info");
 				}
 				lastSeenId = newestId(entries) ?? lastSeenId;

package/omp-extension/toast-logic.ts

@@ -91,7 +91,7 @@ export interface ToastDecision {
 	/** The router's own decision trail, already written for people. */
 	reasons?: string[];
 	/** Classifier inputs; only a few are worth surfacing. */
-	features?: { promptTokens?: number; toolCount?: number; turnDepth?: number; isToolResultContinuation?: boolean } | null;
+	features?: { promptTokens?: number; toolCount?: number; turnDepth?: number; isToolResultContinuation?: boolean; isSubagent?: boolean } | null;
 	/** Attempt index within the turn; >0 means this served after an escalation. */
 	attempt?: number;
 	/** Prompt tokens compaction removed before dispatch. */
@@ -172,6 +172,7 @@ const tokens = (n: number): string => (n >= 1000 ? `${Math.round(n / 100) / 10}k
 export function factsOf(d: ToastDecision): string[] {
 	const out: string[] = [];
 	const f = d.features ?? undefined;
+	if (f?.isSubagent === true) out.push("task");
 	if (f?.promptTokens !== undefined && f.promptTokens > 0) out.push(`${tokens(f.promptTokens)} prompt`);
 	if (d.promptTokensSaved !== undefined && d.promptTokensSaved > 0) out.push(`${tokens(d.promptTokensSaved)} compacted`);
 	if (f?.toolCount !== undefined && f.toolCount > 0) out.push(`${f.toolCount} tools`);
@@ -215,6 +216,14 @@ export function toToastText(d: ToastDecision, verbose = true): string {
  *
  * When `harnessId` is non-empty, only entries from that harness are toasted,
  * so multiple harnesses sharing one router don't spam each other's toasts.
+ *
+ * `ompSessionId` scopes the toast to this interactive session's own turns.
+ * Subagent (task) turns carry their OWN session id — the subagent process's —
+ * so they never match it and would otherwise be invisible. They are admitted
+ * whenever the harness matches, deduplicated per task session on the served
+ * model through `subModels` (the caller holds the map across ticks): the
+ * first dispatch of a task toasts, a mid-task model change (an escalation)
+ * toasts again, and the forty same-model dispatches after it toast nothing.
  */
 export function selectToasts(
 	entries: ToastDecision[],
@@ -222,6 +231,7 @@ export function selectToasts(
 	harnessId = "",
 	ompSessionId = "",
 	verbose = true,
+	subModels?: Map<string, string | null>,
 ): ToastMessage[] {
 	if (lastSeenId === null) return [];
 	// `entries` is newest-first. Entries strictly newer than lastSeenId are the
@@ -235,7 +245,15 @@ export function selectToasts(
 		if (d === undefined) continue;
 		if (d.wasted) continue;
 		if (harnessId !== "" && d.harnessId !== harnessId) continue;
-		if (ompSessionId !== "" && d.ompSessionId !== ompSessionId) continue;
+		const isTask = d.features?.isSubagent === true;
+		if (!isTask && ompSessionId !== "" && d.ompSessionId !== ompSessionId) continue;
+		if (isTask && subModels !== undefined) {
+			const session = d.ompSessionId ?? "";
+			const model = d.servedSlug ?? d.slug;
+			// Same task, same model as last toasted: not a change, not news.
+			if (subModels.get(session) === model) continue;
+			subModels.set(session, model);
+		}
 		out.push({ model: d.servedSlug ?? d.slug, tier: d.tier, costUsd: d.reportedUsd, text: toToastText(d, verbose) });
 	}
 	return out;

package/package.json

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

package/src/catalog/composite.ts

@@ -21,6 +21,7 @@
 
 import type { OllamaAvailability } from "../upstream/ollama.ts";
 import { effectiveOllamaBias, NO_USAGE, type OllamaUsageSource } from "../upstream/ollama-usage.ts";
+import { openRouterServing, type OpenRouterCredits } from "../upstream/openrouter-usage.ts";
 import { mergeSnapshots, type OllamaCatalogSource } from "./ollama-catalog.ts";
 import type { CatalogModel, CatalogShrink, CatalogSnapshot, CatalogSource } from "./types.ts";
 
@@ -34,6 +35,10 @@ export interface CompositeBias {
 	live?: () => { costBias: number; biasUntilUsage: number };
 	/** False when OpenRouter cannot dispatch (no key): its models are listed for metadata only, never served. Default true. */
 	serveOpenRouter?: () => boolean;
+	/** Last known OpenRouter credit balance (USD), or null when never fetched. Read every combine, no network. */
+	openRouterCredits?: () => OpenRouterCredits | null;
+	/** Balance at or below which OpenRouter stops serving. 0 disables the gate. */
+	minCreditsUsd?: number;
 	/** Named upstreams' models, built from the OpenRouter models (twins) and filtered by each upstream's breaker. */
 	named?: {
 		models(openrouter: readonly CatalogModel[]): readonly CatalogModel[];
@@ -69,7 +74,7 @@ export function createCompositeCatalog(
 
 	function combine(base: CatalogSnapshot, models: readonly CatalogModel[]): CatalogSnapshot {
 		const available = availability.available();
-		const serveBase = bias.serveOpenRouter?.() ?? true;
+		const serveBase = (bias.serveOpenRouter?.() ?? true) && openRouterServing(bias.openRouterCredits?.() ?? null, bias.minCreditsUsd ?? 0);
 		const providerBias = currentBias();
 		// Named upstreams: every enabled entry's models, minus those of an upstream in cooldown.
 		const namedAll = bias.named?.models(base.models) ?? NO_NAMED;

package/src/cli/config-wizard.ts

@@ -128,6 +128,8 @@ export const WIZARD_SECTIONS: readonly SectionSpec[] = [
 			{ path: "openrouter.timeoutMs", label: "Request timeout", kind: "number", min: 1, hint: "ms" },
 			{ path: "openrouter.catalogTtlMs", label: "Catalog TTL", kind: "number", min: 1, hint: "ms" },
 			{ path: "openrouter.catalogRefreshMs", label: "Catalog refresh", kind: "number", min: 0, hint: "ms, 0=off" },
+			{ path: "openrouter.minCreditsUsd", label: "Credit floor USD", kind: "number", min: 0, hint: "0=serve regardless of balance" },
+			{ path: "openrouter.usagePollMs", label: "Credits poll", kind: "number", min: 0, hint: "ms, 0=off" },
 		],
 	},
 	{

package/src/config/defaults.ts

@@ -32,6 +32,11 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		// Refetch the key-scoped catalog every 5 minutes in the background so
 		// guardrail changes are picked up without waiting for traffic + TTL.
 		catalogRefreshMs: 5 * 60 * 1000,
+		// Stop serving OpenRouter at/below this balance (USD); top up to rejoin.
+		// 0 disables the gate. Mirrors ollama.blockBelowUsage's intent.
+		minCreditsUsd: 5,
+		// Balance moves slowly; 10 minutes matches the Ollama usage poll.
+		usagePollMs: 10 * 60 * 1000,
 	},
 	ollama: {
 		// Off: a second upstream changes what every turn can route to.

package/src/config/schema.ts

@@ -33,6 +33,8 @@ const openrouter = z.strictObject({
 	timeoutMs: z.number().positive().optional(),
 	catalogTtlMs: z.number().positive().optional(),
 	catalogRefreshMs: z.number().nonnegative().optional(),
+	minCreditsUsd: z.number().nonnegative().optional(),
+	usagePollMs: z.number().nonnegative().optional(),
 });
 
 const ollamaRate = z.strictObject({

package/src/config/types.ts

@@ -70,6 +70,15 @@ export interface OpenRouterConfig {
 	catalogTtlMs: number;
 	/** Background catalog refresh cadence, ms. 0 disables the periodic refresh. */
 	catalogRefreshMs: number;
+	/**
+	 * Balance (USD, `total_credits − total_usage`) at or below which OpenRouter
+	 * stops serving: its models drop from the catalog until the account is
+	 * topped up. 0 disables the gate — the 402 breaker still catches the real
+	 * thing. Default 5.
+	 */
+	minCreditsUsd: number;
+	/** Credits poll interval, ms. 0 disables the poll (and the gate never fires). */
+	usagePollMs: number;
 }
 
 /**

package/src/cost/ledger-sql.ts

@@ -22,6 +22,7 @@
 import type { CatalogModel } from "../catalog/types.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { consumePendingEstimate } from "../tokens/estimate.ts";
+import { droppableLedgerPartitions, ensureLedgerPartitions } from "../util/schema.ts";
 import { jsonParam, jsonValue, num, numOrNull, type SqlDb } from "../util/sql.ts";
 import { foldBlendSamples, type BlendSample } from "./blended.ts";
 import { computeCost } from "./forecast.ts";
@@ -290,7 +291,12 @@ export function createSqlLedger(db: SqlDb, cfg: RouterConfig, deps: LedgerDeps):
 				deps.findModel(entry.slug) ??
 				null;
 			const breakdown = model !== null ? computeCost(model, entry.usage) : null;
-			await sql`
+			// No conflict target: on Postgres the ledger is partitioned by day, so
+			// its unique index has to include `created_at_ms` and `(id)` alone is
+			// not an arbiter. A re-recorded entry carries the same instant, which
+			// is the case this guard exists for.
+			const insert = async (): Promise<void> => {
+				await sql`
 				INSERT INTO ledger (
 					id, created_at_ms, conversation_key, session_id, turn, requested_model, harness_id, omp_session_id,
 					slug, served_slug, tier, classification_source, reasons, predicted_usd, reported_usd, usage,
@@ -309,7 +315,22 @@ export function createSqlLedger(db: SqlDb, cfg: RouterConfig, deps: LedgerDeps):
 					${entry.promptTokensSaved},
 					${entry.scope === undefined || entry.scope === "" ? null : entry.scope}, ${entry.redactions ?? null}
 				)
-				ON CONFLICT (id) DO NOTHING`;
+				ON CONFLICT DO NOTHING`;
+			};
+			try {
+				await insert();
+			} catch (err) {
+				// A day nobody provisioned: Postgres refuses the row with 23514
+				// ("no partition of relation ledger found for row"). The ledger has
+				// no CHECK constraints of its own, so on this statement that code
+				// can only mean partition routing. Create the day — and the next
+				// few, so this happens once rather than daily — and write again. A
+				// turn is never lost because a partition was late.
+				const code = err !== null && typeof err === "object" && "errno" in err ? String(err.errno) : "";
+				if (code !== "23514") throw err;
+				await ensureLedgerPartitions(db, entry.createdAtMs);
+				await insert();
+			}
 			// Always consume the pending estimate, even when the turn failed, so a
 			// dead turn's bytes can never pair with a later turn's tokens.
 			const pending = consumePendingEstimate(entry.conversationKey);
@@ -520,8 +541,25 @@ export function createSqlLedger(db: SqlDb, cfg: RouterConfig, deps: LedgerDeps):
 			// swept up too.
 			await sql`DELETE FROM feedback WHERE created_at_ms < ${cutoff} OR ledger_id IN (SELECT id FROM ledger WHERE created_at_ms < ${cutoff})`;
 			await sql`DELETE FROM ollama_meter_samples WHERE at_ms < ${cutoff}`;
+			// Whole days the cutoff covers go as metadata: a DROP of a day's
+			// partition is O(1) where deleting its rows is hours of I/O competing
+			// with the inserts it is making room for. Counted before the drop, so
+			// `deleted` still means rows, not partitions.
+			//
+			// ponytail: an exact COUNT(*) scans each doomed day once — a fraction of
+			// what deleting it costs, but not free. If that scan ever matters, read
+			// pg_class.reltuples instead and report the count as an estimate.
+			let dropped = 0;
+			for (const partition of await droppableLedgerPartitions(db, cutoff)) {
+				const rows = (await sql.unsafe(`SELECT COUNT(*) AS n FROM ${partition}`)) as { n: unknown }[];
+				dropped += num(rows[0]?.n);
+				await sql.unsafe(`DROP TABLE ${partition}`);
+			}
+			// What the drops could not cover: the boundary day the cutoff falls
+			// inside (a partial day, so row-wise), anything in a partition whose
+			// bounds could not be read, and every row on SQLite.
 			const deleted = (await sql`DELETE FROM ledger WHERE created_at_ms < ${cutoff} RETURNING id`) as { id: string }[];
-			return { deleted: deleted.length, oldestKeptMs: await oldest() };
+			return { deleted: dropped + deleted.length, oldestKeptMs: await oldest() };
 		},
 
 		async markWasted(id: string): Promise<void> {

package/src/server/http.ts

@@ -282,7 +282,7 @@ export function startServer(cfg: RouterConfig): StartedServer {
 	// A Postgres store has no bootstrap of its own to run synchronously, so the
 	// shape is created on the way up and every entry point waits for it once.
 	// Resolved already on SQLite, where `openDb` just did it.
-	const storeReady = postgres ? migrateStore(sqlDb) : Promise.resolve();
+	const storeReady = postgres ? migrateStore(sqlDb, log) : Promise.resolve();
 	// The ledger reads and writes through the engine-agnostic handle. `findModel`
 	// closes over the catalog built just below: a shared store has no catalog
 	// cache of its own to price a row from.

package/src/server/providers.ts

@@ -19,6 +19,7 @@ import { createOllamaClient, type OllamaClient } from "../upstream/ollama.ts";
 import { setKnownUpstreamIds } from "../cost/report.ts";
 import { createOllamaUsageSource, type OllamaUsageSource } from "../upstream/ollama-usage.ts";
 import { createOpenRouterClient } from "../upstream/openrouter.ts";
+import { createOpenRouterUsageSource } from "../upstream/openrouter-usage.ts";
 import type { UpstreamClient } from "../upstream/types.ts";
 import { createLogger, type Logger } from "../util/log.ts";
 
@@ -75,6 +76,15 @@ export function createProviders(
 		// estimate can be scaled to what ollama.com actually bills.
 		calibration: { db: sqlDb, ledgerUsd: ollamaLedgerUsd, planCreditsOverrideUsd: cfg.ollama.planCreditsUsd },
 	});
+	// OpenRouter's credit balance on the same slow cadence: at/below
+	// `openrouter.minCreditsUsd` its models drop from the catalog until the
+	// account is topped up (a 402 trip only blocks for the rate-limit minute).
+	const openrouterUsage = createOpenRouterUsageSource({
+		apiKey: () => cfg.openrouter.apiKey,
+		pollMs: cfg.openrouter.usagePollMs,
+		timeoutMs: 15_000,
+		log,
+	});
 	// Named upstreams (OpenAI, Azure, Anthropic, vLLM…): a client per id, built when
 	// first needed and kept — its breaker state must survive config reloads — while
 	// the entry it reads is looked up live, so a changed key or URL applies at once.
@@ -105,6 +115,8 @@ export function createProviders(
 			usage: ollamaUsage,
 			live: () => ({ costBias: cfg.ollama.costBias, biasUntilUsage: cfg.ollama.biasUntilUsage }),
 			serveOpenRouter: () => cfg.openrouter.apiKey !== "",
+			openRouterCredits: () => openrouterUsage.peek(),
+			minCreditsUsd: cfg.openrouter.minCreditsUsd,
 			named: { models: (base) => staticCatalog.get(base), serving: namedServingOne, bias: (id) => cfg.upstreams.find((u) => u.id === id)?.costBias ?? 1 },
 		}),
 		ollama,

package/src/upstream/anthropic.ts

@@ -340,6 +340,7 @@ export function classifyAnthropicStatus(id: string, status: number, body: unknow
 	const message = typeof msg === "string" && msg !== "" ? msg : `${id} 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);
+	if (status === 402) return fail("quota", true);
 	if (status === 404) return fail("model_unavailable", true);
 	if (status === 413) return fail("context_length", false);
 	if (status === 429) return fail("rate_limit", true);
@@ -431,7 +432,7 @@ export function createAnthropicClient(cfg: RouterConfig, id: string, fetchImpl:
 			/* status alone */
 		}
 		const err = classifyAnthropicStatus(id, res.status, body);
-		if (err.kind === "rate_limit" || res.status === 529) breaker.trip(err);
+		if (err.kind === "rate_limit" || err.kind === "quota" || res.status === 529) breaker.trip(err);
 		return err;
 	}
 

package/src/upstream/compat.ts

@@ -94,8 +94,10 @@ export function classifyCompatStatus(id: string, status: number, body: unknown):
 	if (status === 401) return fail("auth", false);
 	if (status === 402) return fail("quota", true);
 	if (status === 403) return /credit|quota|plan|limit|billing/i.test(message) ? fail("quota", true) : fail("moderation", true);
-	// OpenAI reports an exhausted balance as a 429 with insufficient_quota: the account, not the moment.
-	if (status === 429) return /insufficient_quota|exceeded your current quota/i.test(`${code} ${message}`) ? fail("quota", true) : fail("rate_limit", true);
+	// OpenAI reports an exhausted balance as a 429 with insufficient_quota; Kimi
+	// ("exceed your available credits given your current in-flight requests") says
+	// credits. Both are the account, not the moment.
+	if (status === 429) return /insufficient_quota|exceeded your current quota|available credits|in-flight requests/i.test(`${code} ${message}`) ? fail("quota", true) : fail("rate_limit", true);
 	if (status === 404) return fail("model_unavailable", true);
 	if (status === 400 || status === 413 || status === 422) {
 		if (/context|too many tokens|token limit|maximum context|too long/i.test(message)) return fail("context_length", false);

package/src/upstream/openrouter-usage.ts

@@ -0,0 +1,120 @@
+/**
+ * OpenRouter credit balance, polled on a slow interval and read without
+ * network on every routing decision (`GET /api/v1/credits`: management-key
+ * scope, `data.total_credits - data.total_usage` = the balance that gates a
+ * dispatch — OpenRouter reserves credits per in-flight request, so the
+ * UNRESERVED balance is what a 402 means).
+ *
+ * Mirrors the Ollama usage source: a key that is empty now may be set from
+ * the dashboard later, so the reader stays live and idles until it is not.
+ * A failed or unparseable poll keeps the last reading — the balance moves
+ * slowly, and hiding a provider on a poll glitch would route around it for
+ * nothing.
+ */
+
+import type { Logger } from "../util/log.ts";
+
+/** Minimal fetch surface, injectable for tests. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface OpenRouterCredits {
+	/** Balance in USD: total_credits − total_usage. Null when the payload lacks it. */
+	remainingUsd: number | null;
+	/** Lifetime credits bought and used, for the dashboard. */
+	totalCreditsUsd: number | null;
+	totalUsageUsd: number | null;
+	fetchedAtMs: number;
+}
+
+export interface OpenRouterUsageSource {
+	/** Latest reading, refreshed when older than the poll interval; last good value on failure. */
+	get(): Promise<OpenRouterCredits | null>;
+	/** Last fetched value without touching the network. */
+	peek(): OpenRouterCredits | null;
+}
+
+export const NO_OPENROUTER_USAGE: OpenRouterUsageSource = { get: async () => null, peek: () => null };
+
+function parseCredits(json: unknown): OpenRouterCredits | null {
+	if (typeof json !== "object" || json === null || !("data" in json)) return null;
+	const data: unknown = json.data;
+	if (typeof data !== "object" || data === null) return null;
+	const d = data as Record<string, unknown>; // narrowed above; cast names the wire shape once
+	const total = typeof d.total_credits === "number" ? d.total_credits : null;
+	const used = typeof d.total_usage === "number" ? d.total_usage : null;
+	if (total === null || used === null) return null;
+	return { remainingUsd: total - used, totalCreditsUsd: total, totalUsageUsd: used, fetchedAtMs: Date.now() };
+}
+
+export function createOpenRouterUsageSource(opts: {
+	apiKey: () => string;
+	pollMs: number;
+	timeoutMs: number;
+	log: Logger;
+	fetchImpl?: FetchLike;
+	root?: string;
+}): OpenRouterUsageSource {
+	if (opts.pollMs <= 0) return NO_OPENROUTER_USAGE;
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const root = (opts.root ?? "https://openrouter.ai/api/v1").replace(/\/+$/, "");
+	let current: OpenRouterCredits | null = null;
+	let checkedAtMs = 0;
+	let inflight: Promise<OpenRouterCredits | null> | null = null;
+	let warned = false;
+
+	async function refresh(): Promise<OpenRouterCredits | null> {
+		try {
+			const res = await fetchImpl(`${root}/credits`, {
+				headers: { authorization: `Bearer ${opts.apiKey()}` },
+				signal: AbortSignal.timeout(opts.timeoutMs),
+			});
+			if (res.ok) {
+				const parsed = parseCredits(await res.json());
+				if (parsed !== null) {
+					current = parsed;
+					warned = false;
+				} else if (!warned) {
+					warned = true;
+					opts.log.warn("openrouter credits payload had no recognisable fields; credit gate keeps its last reading");
+				}
+			} else if (!warned) {
+				warned = true;
+				opts.log.warn("openrouter credits endpoint unavailable; credit gate keeps its last reading", { status: res.status });
+			}
+		} catch (err) {
+			if (!warned) {
+				warned = true;
+				opts.log.warn("openrouter credits fetch failed; credit gate keeps its last reading", {
+					error: err instanceof Error ? err.message : String(err),
+				});
+			}
+		}
+		checkedAtMs = Date.now();
+		return current;
+	}
+
+	return {
+		async get() {
+			if (opts.apiKey() === "") return null;
+			if (Date.now() - checkedAtMs < opts.pollMs) return current;
+			inflight ??= refresh().finally(() => {
+				inflight = null;
+			});
+			return inflight;
+		},
+		peek: () => current,
+	};
+}
+
+/**
+ * True while OpenRouter may serve: the balance is strictly above the floor, or
+ * unknown (a poll that has not landed yet, no key for the endpoint, a payload
+ * change). Hiding on unknown would take a provider down for a dashboard's
+ * missing field — fail open instead; the 402 breaker still catches the real
+ * thing.
+ */
+export function openRouterServing(credits: OpenRouterCredits | null, minCreditsUsd: number): boolean {
+	if (minCreditsUsd <= 0) return true;
+	if (credits === null || credits.remainingUsd === null) return true;
+	return credits.remainingUsd > minCreditsUsd;
+}

package/src/upstream/openrouter.ts

@@ -55,7 +55,12 @@ function classifyStatus(status: number, body: unknown): UpstreamError {
 	// retrying is pointless.
 	if (status === 401) return fail("auth", false);
 	// 402 = out of credits; retrying changes nothing, only topping up does.
-	if (status === 402) return fail("auth", false);
+	// EXCEPT the concurrency shape: OpenRouter reserves credits for in-flight
+	// requests, so a burst can exhaust the UNRESERVED balance on an account
+	// with plenty left ("would exceed your available credits given your
+	// current in-flight requests"). That clears when the streams settle —
+	// a moment, not an account state — so fail over like a rate limit.
+	if (status === 402) return /in-flight requests/i.test(message) ? fail("rate_limit", true) : fail("auth", false);
 	// 403 = provider content-moderation or per-model policy gate (prompt-injection
 	// block, age/data-policy confirmation). This indicts the model/provider, NOT
 	// the key: siblings routinely serve the same content. Retryable so the turn