pi-keyrouter 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# 🔑 pi-keyrouter
+
+**API key rotation for [pi-coding-agent](https://github.com/nicobailon/pi-coding-agent).**
+
+Multiple keys per provider · automatic 429/401 fallback · recursion-safe.
+
+```bash
+pi install npm:pi-keyrouter
+# create ~/.pi/keyrouter.json with your keys
+/reload
+```
+
+When your model returns 429 (rate-limited) or 401 (unauthorized), the next key is picked automatically. pi sees a single successful response — retries are transparent.
+
+---
+
+## ⚡ Install
+
+```bash
+pi install npm:pi-keyrouter
+```
+
+Add your provider config to `~/.pi/keyrouter.json`:
+
+```json
+{
+  "providers": [
+    {
+      "name": "z-ai",
+      "match": ["api.z.ai", "z.ai"],
+      "keys": [
+        { "name": "primary", "value": "key-1-..." },
+        { "name": "backup",  "value": "key-2-..." }
+      ]
+    }
+  ],
+  "maxRetries": 3,
+  "cooldownMs": 60000
+}
+```
+
+`/reload` — extension wraps `globalThis.fetch` and rotates on 429/401.
+
+---
+
+## 🎯 How it works
+
+1. **Install** — extension loads, reads config, wraps `fetch`.
+2. **Request** — URL matches a provider → key picked, `Authorization: Bearer <key>` set.
+3. **On 429 / 401** — current key marked bad (cooldown `cooldownMs`), next key tried.
+4. **On 200** — response returned, key marked OK.
+5. **After `maxRetries`** — last failed response returned (so pi sees the real error).
+
+Recursion is bounded by `maxRetries` (default 3). No infinite loops.
+
+### What gets rotated
+
+| Status | Action |
+|---|---|
+| 200 | Return response, mark key OK |
+| 429 | Mark key `rate-limited` (cooldown), try next |
+| 401 / 403 | Mark key `unauthorized` (cooldown), try next |
+| 5xx / network | Don't mark key bad — try next, but no cooldown |
+| `maxRetries` exhausted | Return last failed response |
+
+---
+
+## 📊 Visibility
+
+The `/keyrouter` command shows live state:
+
+```bash
+/keyrouter
+```
+
+```
+🔑 keyrouter: active
+  z-ai (current: backup)
+    • primary  uses=12 fails=2 status=rate-limited ⏱ 47s
+    • backup   uses=2  fails=0 status=ok
+```
+
+Subcommands:
+
+- `/keyrouter status` — show snapshot (default)
+- `/keyrouter enable` — re-activate (if disabled)
+- `/keyrouter disable` — restore original fetch, stop rotating
+- `/keyrouter reload` — re-read config
+
+Every key switch notifies the user with a Box widget:
+
+> 🔑 keyrouter: z-ai — primary → backup (HTTP 429, attempt 1)
+
+---
+
+## 🔧 Config
+
+`~/.pi/keyrouter.json` (or `<cwd>/.soly/keyrouter.json`, `<cwd>/.pi/keyrouter.json`).
+
+```json5
+{
+  "providers": [
+    {
+      "name": "display-name",          // for logs (any string)
+      "match": ["api.z.ai", "z.ai"],   // URL substrings (case-insensitive)
+      "keys": [
+        { "name": "primary", "value": "key-1..." },
+        { "name": "backup",  "value": "key-2..." }
+      ]
+    }
+  ],
+  "maxRetries": 3,         // total retries per request across all keys
+  "cooldownMs": 60000      // how long a bad key stays marked bad (1 min default)
+}
+```
+
+### Multi-provider
+
+```json
+{
+  "providers": [
+    { "name": "z-ai",       "match": ["api.z.ai"], "keys": [...] },
+    { "name": "openrouter", "match": ["openrouter.ai"], "keys": [...] }
+  ]
+}
+```
+
+Each provider rotates independently. Cross-provider URLs are not intercepted.
+
+---
+
+## 🛡️ Security
+
+API keys live in plain text in `keyrouter.json`. **Don't commit it.** Options:
+
+- Add `keyrouter.json` to `.gitignore`
+- Use `chmod 600` on the file
+- (Future) env var interpolation `$ENV_VAR` — not yet implemented
+
+---
+
+## 🛠 Development
+
+```bash
+bun test          # 34 tests
+bun run typecheck # tsc --noEmit
+```
+
+Monorepo layout:
+
+```
+packages/pi-keyrouter/
+├── index.ts          — extension entry point
+├── rotation.ts       — pure key-pick logic
+├── fetch-wrapper.ts  — fetch interceptor with retry
+├── config.ts         — config loader
+├── types.ts          — shared types
+└── tests/
+    ├── rotation.test.ts      — pure logic
+    ├── fetch-wrapper.test.ts — integration with mocked fetch
+    ├── config.test.ts        — config loader
+    └── smoke.test.ts         — load-time smoke test
+```
+
+---
+
+## 📜 License
+
+MIT — same as [pi-soly](https://github.com/lowern1ght/pi-soly).

package/config.ts

@@ -0,0 +1,83 @@
+// =============================================================================
+// config.ts — load key router config from disk
+// =============================================================================
+//
+// Looks in this order (first hit wins):
+// 1. <cwd>/.pi/keyrouter.json      — project override
+// 2. <cwd>/.soly/keyrouter.json    — soly convention
+// 3. ~/.pi/keyrouter.json          — user-level default
+//
+// Schema:
+// {
+//   "providers": [
+//     {
+//       "name": "z-ai",
+//       "match": ["api.z.ai", "z.ai"],
+//       "keys": [
+//         { "name": "primary", "value": "key-1..." },
+//         { "name": "backup",  "value": "key-2..." }
+//       ]
+//     }
+//   ],
+//   "maxRetries": 3,
+//   "cooldownMs": 60000
+// }
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { KeyRouterConfig } from "./types.ts";
+
+const CONFIG_FILENAMES = ["keyrouter.json"];
+
+export function defaultConfig(): KeyRouterConfig {
+	return {
+		providers: [],
+		maxRetries: 3,
+		cooldownMs: 60_000,
+	};
+}
+
+export function loadConfig(cwd: string, home?: string): KeyRouterConfig {
+	const homeDir = home ?? os.homedir();
+	const candidates: string[] = [];
+	for (const dir of [
+		path.join(cwd, ".soly"),
+		path.join(cwd, ".pi"),
+		cwd,
+		path.join(homeDir, ".soly"),
+		path.join(homeDir, ".pi"),
+		homeDir,
+	]) {
+		for (const name of CONFIG_FILENAMES) {
+			candidates.push(path.join(dir, name));
+		}
+	}
+	for (const file of candidates) {
+		if (fs.existsSync(file)) {
+			try {
+				const raw = fs.readFileSync(file, "utf-8");
+				const parsed = JSON.parse(raw) as Partial<KeyRouterConfig>;
+				return normalize(parsed);
+			} catch {
+				// bad config — fall through to default
+			}
+		}
+	}
+	return defaultConfig();
+}
+
+function normalize(input: Partial<KeyRouterConfig>): KeyRouterConfig {
+	const providers = (input.providers ?? []).filter(
+		(p): p is { name: string; match: string[]; keys: { name: string; value: string }[] } =>
+			typeof p?.name === "string" &&
+			Array.isArray(p.match) &&
+			Array.isArray(p.keys) &&
+			p.keys.every((k) => typeof k?.name === "string" && typeof k?.value === "string"),
+	);
+	return {
+		providers,
+		maxRetries: typeof input.maxRetries === "number" ? input.maxRetries : 3,
+		cooldownMs: typeof input.cooldownMs === "number" ? input.cooldownMs : 60_000,
+	};
+}

package/fetch-wrapper.ts

@@ -0,0 +1,228 @@
+// =============================================================================
+// fetch-wrapper.ts — wraps global fetch with key-rotation logic
+// =============================================================================
+//
+// Replaces `globalThis.fetch` with a function that:
+// 1. Intercepts requests whose URL matches a configured provider.
+// 2. Picks the best available key (rotation logic in rotation.ts).
+// 3. Sets the Authorization header.
+// 4. On 429/401, marks the key as bad and retries with the next key
+//    (up to maxRetries).
+// 5. Calls onRotate on every key switch.
+//
+// On failure, the original response is returned (not a synthetic one) so
+// pi sees the real error if all retries fail.
+
+import {
+	initKeyStates,
+	isAvailable,
+	markBad,
+	markOk,
+	matchProvider,
+	pickNextKey,
+	recordUse,
+	waitForNextKey,
+} from "./rotation.ts";
+import type {
+	KeyRouterConfig,
+	KeyState,
+	ProviderConfig,
+	RotationEvent,
+} from "./types.ts";
+
+/** State tracked per provider. */
+interface ProviderState {
+	config: ProviderConfig;
+	keys: KeyState[];
+	preferredIndex: number;
+}
+
+export interface KeyRouterHandle {
+	/** Restore the original fetch and stop intercepting. */
+	disable: () => void;
+	/** Snapshot of current state (for /keyrouter status command). */
+	getSnapshot: () => KeyRouterSnapshot[];
+}
+
+export interface KeyRouterSnapshot {
+	provider: string;
+	current: string;
+	keys: Array<{
+		name: string;
+		uses: number;
+		failures: number;
+		lastStatus: string;
+		cooldownRemainingMs: number;
+	}>;
+}
+
+/**
+ * Install the fetch wrapper. Returns a handle for disable / inspection.
+ *
+ * @param config — key router config
+ * @param onRotate — called on every key switch (for UI notification)
+ */
+export function installKeyRouter(
+	config: KeyRouterConfig,
+	onRotate: (event: RotationEvent) => void,
+): KeyRouterHandle {
+	// Capture original fetch BEFORE wrapping
+	const originalFetch = globalThis.fetch.bind(globalThis);
+
+	// Build per-provider state
+	const providerStates = new Map<string, ProviderState>();
+	for (const p of config.providers) {
+		providerStates.set(p.name, {
+			config: p,
+			keys: initKeyStates(p.keys),
+			preferredIndex: 0,
+		});
+	}
+
+	async function wrappedFetch(
+		input: string | URL | Request,
+		init?: RequestInit,
+	): Promise<Response> {
+		const url =
+			typeof input === "string"
+				? input
+				: input instanceof URL
+					? input.toString()
+					: input.url;
+		const matched = matchProvider(
+			Array.from(providerStates.values()).map((s) => s.config),
+			url,
+		);
+		if (!matched) {
+			return originalFetch(input, init);
+		}
+		const state = providerStates.get(matched.name);
+		if (!state || state.keys.length === 0) {
+			return originalFetch(input, init);
+		}
+
+		const now = Date.now();
+		const maxRetries = Math.max(1, config.maxRetries);
+		let attempt = 0;
+		let lastResponse: Response | undefined;
+		let lastError: unknown;
+		let lastPreferred = state.preferredIndex;
+
+		while (attempt < maxRetries) {
+			attempt += 1;
+			const idx = pickNextKey(state.keys, lastPreferred, now);
+			if (idx < 0) break;
+			const key = state.keys[idx];
+			if (!key) break;
+
+			// If the chosen key is on cooldown, wait briefly
+			if (!isAvailable(key, now)) {
+				const wait = waitForNextKey(state.keys, now);
+				if (wait > 0 && wait < 2000) {
+					await new Promise((r) => setTimeout(r, wait));
+				}
+			}
+
+			recordUse(key);
+			const initCopy = { ...(init ?? {}) };
+			const headers = new Headers(initCopy.headers ?? {});
+			headers.set("Authorization", `Bearer ${key.value}`);
+			initCopy.headers = headers;
+
+			let response: Response;
+			try {
+				response = await originalFetch(input, initCopy);
+			} catch (e) {
+				lastError = e;
+				// Network errors don't consume a retry budget
+				// (we'll loop back and try again)
+				lastPreferred = (idx + 1) % state.keys.length;
+				continue;
+			}
+
+			if (response.status === 429) {
+				markBad(key, "rate-limited", config.cooldownMs, Date.now());
+				lastResponse = response;
+				if (attempt >= maxRetries) break;
+				const nextIdx = pickNextKey(state.keys, idx + 1, Date.now());
+				if (nextIdx === idx) break;
+				const nextKey = state.keys[nextIdx];
+				if (nextKey) {
+					onRotate({
+						provider: matched.name,
+						fromKey: key.name,
+						toKey: nextKey.name,
+						reason: "rate-limited",
+						status: 429,
+						attempt,
+					});
+				}
+				state.preferredIndex = nextIdx;
+				lastPreferred = nextIdx;
+				continue;
+			}
+
+			if (response.status === 401 || response.status === 403) {
+				markBad(key, "unauthorized", config.cooldownMs, Date.now());
+				lastResponse = response;
+				if (attempt >= maxRetries) break;
+				const nextIdx = pickNextKey(state.keys, idx + 1, Date.now());
+				if (nextIdx === idx) break;
+				const nextKey = state.keys[nextIdx];
+				if (nextKey) {
+					onRotate({
+						provider: matched.name,
+						fromKey: key.name,
+						toKey: nextKey.name,
+						reason: "unauthorized",
+						status: response.status,
+						attempt,
+					});
+				}
+				state.preferredIndex = nextIdx;
+				lastPreferred = nextIdx;
+				continue;
+			}
+
+			// Success — mark ok and return
+			markOk(key);
+			state.preferredIndex = idx;
+			return response;
+		}
+
+		// All retries exhausted — return the last response if we have one
+		if (lastResponse) return lastResponse;
+		// Or re-throw the last network error
+		if (lastError !== undefined) throw lastError;
+		// Or fall through to original fetch
+		return originalFetch(input, init);
+	}
+
+	// Install wrapper
+	(globalThis as { fetch: typeof fetch }).fetch = wrappedFetch as typeof fetch;
+
+	function getSnapshot(): KeyRouterSnapshot[] {
+		const now = Date.now();
+		return Array.from(providerStates.values()).map((s) => {
+			const current = s.keys[s.preferredIndex];
+			return {
+				provider: s.config.name,
+				current: current?.name ?? "(none)",
+				keys: s.keys.map((k) => ({
+					name: k.name,
+					uses: k.uses,
+					failures: k.failures,
+					lastStatus: k.lastStatus,
+					cooldownRemainingMs:
+						k.cooldownUntil > now ? k.cooldownUntil - now : 0,
+				})),
+			};
+		});
+	}
+
+	function disable(): void {
+		(globalThis as { fetch: typeof fetch }).fetch = originalFetch;
+	}
+
+	return { disable, getSnapshot };
+}

package/index.ts

@@ -0,0 +1,122 @@
+// =============================================================================
+// index.ts — pi-keyrouter extension entry point
+// =============================================================================
+//
+// Usage:
+//   pi install npm:pi-keyrouter
+//   # create ~/.pi/keyrouter.json with your provider keys
+//   /reload
+//
+// On load:
+// 1. Reads keyrouter config (project or user-level)
+// 2. Wraps globalThis.fetch with rotation logic
+// 3. On 429/401, retries with next key up to maxRetries
+// 4. Notifies user on every key switch via Box widget
+//
+// Provides /keyrouter command for status / disable / enable.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "./config.ts";
+import { installKeyRouter, type KeyRouterHandle } from "./fetch-wrapper.ts";
+
+export default function keyRouterExtension(pi: ExtensionAPI): void {
+	let handle: KeyRouterHandle | undefined;
+	let enabled = true;
+	let currentCwd = "";
+
+	function activate(cwd: string, notify: (text: string, level: string) => void): void {
+		if (handle) return;
+		const config = loadConfig(cwd);
+		if (config.providers.length === 0) {
+			return; // nothing to do
+		}
+		handle = installKeyRouter(config, (event) => {
+			notify(
+				`🔑 keyrouter: ${event.provider} — ${event.fromKey} → ${event.toKey} ` +
+					`(HTTP ${event.status}, attempt ${event.attempt})`,
+				"warning",
+			);
+		});
+	}
+
+	function deactivate(): void {
+		if (handle) {
+			handle.disable();
+			handle = undefined;
+		}
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		currentCwd = ctx.cwd;
+		activate(ctx.cwd, (text, level) =>
+			(ctx.ui.notify as (t: string, l?: string) => void)(text, level),
+		);
+		if (handle) {
+			ctx.ui.notify(
+				`🔑 keyrouter: active (${loadConfig(ctx.cwd).providers.length} provider(s))`,
+				"info",
+			);
+		}
+	});
+
+	pi.on("session_shutdown", () => {
+		deactivate();
+	});
+
+	pi.registerCommand("keyrouter", {
+		description: "manage key rotation (status, enable, disable, reload)",
+		handler: async (args, ctx) => {
+			const sub = args.trim().split(/\s+/)[0] ?? "status";
+			if (sub === "status") {
+				if (!handle) {
+					ctx.ui.notify("🔑 keyrouter: not active", "info");
+					return;
+				}
+				const snap = handle.getSnapshot();
+				const lines: string[] = [`🔑 keyrouter: ${enabled ? "active" : "disabled"}`];
+				for (const p of snap) {
+					lines.push(``);
+					lines.push(`  ${p.provider} (current: ${p.current})`);
+					for (const k of p.keys) {
+						const cooldown = k.cooldownRemainingMs > 0
+							? ` ⏱ ${Math.ceil(k.cooldownRemainingMs / 1000)}s`
+							: "";
+						lines.push(
+							`    • ${k.name}  uses=${k.uses} fails=${k.failures} status=${k.lastStatus}${cooldown}`,
+						);
+					}
+				}
+				ctx.ui.notify(lines.join("\n"), "info");
+				return;
+			}
+			if (sub === "enable") {
+				if (!handle) {
+					activate(currentCwd, (text, level) =>
+						(ctx.ui.notify as (t: string, l?: string) => void)(text, level),
+					);
+				}
+				enabled = true;
+				ctx.ui.notify("🔑 keyrouter: enabled", "info");
+				return;
+			}
+			if (sub === "disable") {
+				deactivate();
+				enabled = false;
+				ctx.ui.notify("🔑 keyrouter: disabled (fetch restored)", "info");
+				return;
+			}
+			if (sub === "reload") {
+				deactivate();
+				activate(currentCwd, (text, level) =>
+					(ctx.ui.notify as (t: string, l?: string) => void)(text, level),
+				);
+				ctx.ui.notify("🔑 keyrouter: reloaded", "info");
+				return;
+			}
+			ctx.ui.notify(
+				"Usage: /keyrouter [status|enable|disable|reload]",
+				"info",
+			);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-keyrouter",
+  "version": "0.1.0",
+  "description": "API key rotation for pi-coding-agent. Multiple keys per provider, automatic 429/401 fallback, max-retries guard.",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun x tsc --noEmit"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.78.1",
+    "@types/node": "^25.9.1",
+    "bun-types": "^1.3.14",
+    "typescript": "^6.0.3"
+  },
+  "files": [
+    "README.md",
+    "index.ts",
+    "config.ts",
+    "rotation.ts",
+    "fetch-wrapper.ts",
+    "types.ts"
+  ],
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "api-key",
+    "key-rotation",
+    "rate-limit",
+    "fallback",
+    "ai-coding"
+  ],
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "homepage": "https://github.com/lowern1ght/pi-soly#readme",
+  "bugs": {
+    "url": "https://github.com/lowern1ght/pi-soly/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lowern1ght/pi-soly.git",
+    "directory": "packages/pi-keyrouter"
+  }
+}

package/rotation.ts

@@ -0,0 +1,132 @@
+// =============================================================================
+// rotation.ts — pure key-rotation logic
+// =============================================================================
+//
+// Decides which key to use next. No side effects, no I/O. Given a list of
+// keys + their state, picks the best available one.
+//
+// Strategy:
+// 1. Start with the first key (most recent working key takes priority).
+// 2. If it's on cooldown, find the next available key.
+// 3. If all keys are on cooldown, return the one that becomes available
+//    soonest (may need to wait).
+// 4. If there are no keys, return null.
+
+import type { KeyState, RotationReason } from "./types.ts";
+
+/** Build initial state from a list of key values. */
+export function initKeyStates(
+  keys: ReadonlyArray<{ name: string; value: string }>,
+): KeyState[] {
+  return keys.map((k) => ({
+    name: k.name,
+    value: k.value,
+    lastStatus: "untried",
+    cooldownUntil: 0,
+    uses: 0,
+    failures: 0,
+  }));
+}
+
+/** Returns true if the key is currently available (past cooldown). */
+export function isAvailable(state: KeyState, now: number): boolean {
+  return state.cooldownUntil === 0 || state.cooldownUntil <= now;
+}
+
+/** Mark a key as bad for `cooldownMs`. */
+export function markBad(
+  state: KeyState,
+  reason: RotationReason,
+  cooldownMs: number,
+  now: number,
+): void {
+  state.lastStatus = reason === "rate-limited" ? "rate-limited" : "unauthorized";
+  state.cooldownUntil = now + cooldownMs;
+  state.failures += 1;
+}
+
+/** Mark a key as used successfully. Clears any cooldown. */
+export function markOk(state: KeyState): void {
+  state.lastStatus = "ok";
+  state.cooldownUntil = 0;
+}
+
+/** Record that a key was attempted (regardless of outcome). */
+export function recordUse(state: KeyState): void {
+  state.uses += 1;
+}
+
+/**
+ * Pick the next key to try.
+ *
+ * Priority:
+ * 1. The key at `preferredIndex` if available (used to "stick" with a key
+ *    that was working — pi doesn't change keys across requests in the same
+ *    turn unless we rotate).
+ * 2. The next available key in rotation order.
+ * 3. If all on cooldown, the one that becomes available soonest.
+ *
+ * Returns the picked index, or -1 if no keys.
+ */
+export function pickNextKey(
+  states: KeyState[],
+  preferredIndex: number,
+  now: number,
+): number {
+  if (states.length === 0) return -1;
+
+  // 1. Preferred if available
+  const preferred = states[preferredIndex];
+  if (preferred && isAvailable(preferred, now)) {
+    return preferredIndex;
+  }
+
+  // 2. Next available in rotation order (start from preferred + 1)
+  for (let offset = 1; offset <= states.length; offset++) {
+    const idx = (preferredIndex + offset) % states.length;
+    const s = states[idx];
+    if (s && isAvailable(s, now)) {
+      return idx;
+    }
+  }
+
+  // 3. All on cooldown — pick the one that becomes available soonest
+  let bestIdx = 0;
+  let bestUntil = states[0]?.cooldownUntil ?? 0;
+  for (let i = 1; i < states.length; i++) {
+    const u = states[i]?.cooldownUntil ?? 0;
+    if (u < bestUntil) {
+      bestUntil = u;
+      bestIdx = i;
+    }
+  }
+  return bestIdx;
+}
+
+/** Find the provider config whose `match` substrings hit the URL. */
+export function matchProvider<T extends { name: string; match: string[] }>(
+  providers: T[],
+  url: string,
+): T | undefined {
+  const lower = url.toLowerCase();
+  for (const p of providers) {
+    for (const m of p.match) {
+      if (lower.includes(m.toLowerCase())) return p;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Compute the delay (ms) to wait before the soonest key becomes available.
+ * Returns 0 if at least one key is available now.
+ */
+export function waitForNextKey(states: KeyState[], now: number): number {
+  let minWait = Number.POSITIVE_INFINITY;
+  for (const s of states) {
+    if (isAvailable(s, now)) return 0;
+    const wait = s.cooldownUntil - now;
+    if (wait < minWait) minWait = wait;
+  }
+  return minWait === Number.POSITIVE_INFINITY ? 0 : minWait;
+}

package/types.ts

@@ -0,0 +1,56 @@
+// =============================================================================
+// types.ts — shared types for pi-keyrouter
+// =============================================================================
+
+/** A single API key entry. `name` is for logging; `value` is the literal key. */
+export interface ApiKey {
+  name: string;
+  value: string;
+}
+
+/** Configuration for a single provider. */
+export interface ProviderConfig {
+  /** Display name (e.g. "z-ai", "openrouter"). For logging. */
+  name: string;
+  /** URL substrings to match. If request URL contains any of these, the
+   *  wrapper handles it. Match is case-insensitive. */
+  match: string[];
+  /** Ordered list of keys. First key used by default; on 429/401, rotate. */
+  keys: ApiKey[];
+}
+
+/** Top-level config. */
+export interface KeyRouterConfig {
+  providers: ProviderConfig[];
+  /** Max number of retries across all keys per request. Default 3. */
+  maxRetries: number;
+  /** How long a key is marked bad after 429 (ms). Default 60_000. */
+  cooldownMs: number;
+}
+
+/** Internal state for a key (not user-configurable). */
+export interface KeyState {
+  name: string;
+  value: string;
+  /** Last status we saw from this key. */
+  lastStatus: "ok" | "rate-limited" | "unauthorized" | "untried";
+  /** Epoch ms when this key's bad-status expires. 0 = available. */
+  cooldownUntil: number;
+  /** How many times this key has been used (for diagnostics). */
+  uses: number;
+  /** How many times this key has returned 429/401. */
+  failures: number;
+}
+
+/** Reason we rotated to a new key. */
+export type RotationReason = "rate-limited" | "unauthorized";
+
+/** Event payload for `onRotate` callback. */
+export interface RotationEvent {
+  provider: string;
+  fromKey: string;
+  toKey: string;
+  reason: RotationReason;
+  status: number;
+  attempt: number;
+}