pi-multikey 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-keypool contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# pi-multikey
+
+[中文](./README.zh.md)
+
+A pi extension that bundles multiple API keys into a single **key pool**, exposing only **one provider** to pi.
+
+It solves three pain points:
+
+1. **No more copying your provider config per key** — models (contextWindow / modalities / thinkingLevelMap / compat) are configured once; swapping or adding keys never touches the model definitions.
+2. **Automatic 429 key rotation** — on a failed request it immediately retries with the next key, and the failed key goes into cooldown (honoring `retry-after`). No manual provider switching.
+3. **Concurrent subagents share keys automatically** — every in-flight request holds a key lease, picked by "fewest in use + least recently used", so when the main agent spawns multiple subagents they naturally land on different keys.
+
+## Installation
+
+```bash
+# Option 1: git (recommended, no npm account needed)
+pi install git:github.com/kslamph/multikey@v1.2.0
+
+# Option 2: npm
+pi install npm:pi-multikey
+
+# Option 3: local directory
+pi install /path/to/multikey
+```
+
+## Quick start (B.AI preset)
+
+```
+/multikey → Add pool… → Preset: B.AI → paste keys one per line (blank line to finish)
+```
+
+After picking the preset, the endpoint, compat, and all 6 model definitions are wired up automatically. Models are available directly as `bai/<model-id>`, e.g. `bai/deepseek-v4-flash`.
+
+## Presets
+
+Built-in presets decouple "model settings" from "keys". The data comes from b.ai model cards and DeepSeek / Tencent / Xiaomi official docs, with each thinking level probed empirically; unsupported levels are written as `null` so the UI hides them.
+
+| Model | ctx / max-out | Modalities | Supported thinking levels |
+|---|---|---|---|
+| deepseek-v4-flash | 1M / 384K | text | off · low · high · max |
+| deepseek-v4-flash-vision-exp | 1M / 384K | text+image | off · low · high · max |
+| hy3 | 256K / 128K | text | off · low · high |
+| mimo-v2.5 | 1M / 128K | text+image | off · high (official: low/medium/high behave identically) |
+| qwen3.8-flash | 1M / 131K | text+image | off · low · medium · xhigh |
+| glm-5.3-flash | 1M / 131K | text+image | low · high · max (always thinks, no off) |
+
+> Why `null` must be explicit: pi's `getSupportedThinkingLevels` treats `mapped === null` as unsupported and hides that level, but **omitting** it is treated as supported and the level name is sent to the API verbatim; `xhigh` / `max` additionally require an explicit non-null value to be usable.
+
+To add a preset: append one entry to the `PRESETS` array in `presets.ts`.
+
+## Configuration
+
+`~/.pi/agent/multikey.json`. On first run it auto-discovers mergeable pools from `~/.pi/agent/models.json` (≥2 providers sharing a baseUrl = you copying the provider per key), and also picks up providers pointing at `api.b.ai`; if nothing is found it generates an empty config.
+
+```jsonc
+{
+  "pools": [
+    {
+      "id": "bai",                          // provider id in pi → bai/deepseek-v4-flash
+      "name": "B.AI (Key Pool)",
+      "baseUrl": "https://api.b.ai/v1",
+      "api": "openai-completions",
+      "auth": "bearer",                     // optional: "bearer" (default) or "api-key" (x-api-key header)
+      "compat": { ... },                    // provider-level defaults, merged into every model
+      "cooldownMs": 20000,                  // 429 cooldown
+      "invalidKeyCooldownMs": 600000,       // 401/403 cooldown
+      "keys": [
+        { "key": "sk-...", "label": "key-1", "enabled": true },
+        { "key": "sk-...", "label": "key-2", "enabled": true }
+      ],
+      "models": [ "…preset or hand-configured model definitions…" ]
+    }
+  ]
+}
+```
+
+To add nvidia / opencode etc. later: `/multikey` → `Add pool…` (Custom), or edit the JSON directly and `Reload config from disk`.
+
+### Adding a custom pool (no questions about API types)
+
+The custom wizard only asks for the essentials — **provider id, base URL, key(s)**. It then probes the endpoint:
+
+1. It fetches `<baseUrl>/models` (and `<baseUrl>/v1/models` as a fallback) with `Authorization: Bearer`; on 401/403 it retries with `x-api-key`.
+2. `/models` is public on some gateways, so it also sends a tiny 1-token chat request to verify the key. If both header styles are rejected there but a dummy key passes, the endpoint simply doesn't check keys (open endpoint) and the pool is saved with the default Bearer auth.
+3. You multi-select the models to add straight from the server's list. Context window / input modes / max output found in the model metadata are adopted; everything else gets safe defaults (128k context, text input, 16k max output, zero cost).
+4. Optionally tune the common params (context size, input modes, max output) per model — or skip and edit them later via the Models menu. Anything advanced (thinking maps, compat, cost) you edit in `multikey.json` and hit *Reload config from disk*.
+
+The detected header style is stored as `"auth": "api-key"` only when the endpoint proved to want `x-api-key`; the default is Bearer. The pool is saved **only after** this completes, so a cancelled wizard never leaves a half-configured provider behind.
+
+## Management UI
+
+```
+/multikey
+├─ Status                     live status: in-flight / cooldown / 429 count per key
+├─ Manage pools…              pools with an unknown api type are marked ⚠ broken; incomplete pools (incomplete)
+│  ├─ Keys…                   add keys one per line; delete / edit / disable
+│  ├─ Models…                 fetch from /models (multi-select) or add manually; edit contextWindow,
+│  │                         maxTokens, modalities, reasoning, thinkingLevelMap, compat, cost
+│  ├─ Endpoint & settings…   baseUrl, api type, auth style, cooldown durations, headers
+│  └─ Delete pool
+├─ Add pool…
+│  ├─ Preset: B.AI           all model settings preloaded; paste keys (verified by a probe) and you're done
+│  └─ Custom…                id + base URL + keys, then auto-probe, model multi-select, safe defaults
+└─ Reload config from disk
+```
+
+Changes take effect immediately (the provider is re-registered) — no restart needed.
+
+## Pointing subagents at the pool
+
+Set `agentOverrides` in `settings.json` to the pool provider:
+
+```json
+"subagents": {
+  "agentOverrides": {
+    "oracle":   { "model": "bai/glm-5.3-flash" },
+    "scout":    { "model": "bai/hy3" },
+    "worker":   { "model": "bai/mimo-v2.5" }
+  }
+}
+```
+
+`defaultProvider: "bai"` works the same way.
+
+## How it works
+
+- The extension registers a provider via `pi.registerProvider()` with a custom `streamSimple`.
+- Each request leases one key from the pool (`options.apiKey` overrides), and once the HTTP response headers arrive:
+  - 429 → that key is cooled down (default 20s, honoring `retry-after`) and the request immediately retries with the next key (no duplicated output);
+  - 401/403 → that key gets a long cooldown (default 10 minutes) and the request retries with the next key;
+  - other errors → handed back to pi's own retry mechanism.
+- Only when every key is exhausted does it surface the 429 upward, letting pi's own backoff retry as a safety net (by then the earliest cooldown has usually expired).
+
+## Releasing to npm
+
+A GitHub Action (`.github/workflows/release.yml`) auto-publishes to npm on tag push.
+
+1. Bump the version in `package.json` (and commit).
+2. Tag the commit — the tag must match the version, e.g. `v1.0.1`:
+
+   ```bash
+   git tag v1.0.1
+   git push origin v1.0.1
+   ```
+
+3. The workflow verifies tag/version match, dry-runs `npm pack`, then publishes with
+   [npm provenance](https://docs.npmjs.com/generating-provenance-statements).
+
+Setup (once):
+
+- Add an npm **automation** token with `publish` scope as the `NPM_TOKEN` secret
+  in the repo's GitHub **Settings → Secrets and variables → Actions**.
+  (An automation token, not your login token, so 2FA never blocks the action.)
+- The repo and package must be **public** for provenance to work.
+- Pre-release tags like `v1.0.1-beta.1` publish to the `next` dist-tag instead of `latest`.
+
+## Security note
+
+Keys are stored in plaintext at `~/.pi/agent/multikey.json`; recommended:
+
+```bash
+chmod 600 ~/.pi/agent/multikey.json
+```

package/README.zh.md

@@ -0,0 +1,146 @@
+# pi-multikey
+
+一个 pi 扩展：把多个 API key 组成一个"密钥池"，对外只暴露**一个 provider**。
+
+解决三个痛点：
+
+1. **不用为每个 key 复制一份 provider 配置** —— 模型（contextWindow / 模态 / thinkingLevelMap / compat）只配置一次，换 key、加 key 都不动模型定义。
+2. **429 自动换 key** —— 请求失败立刻用下一个 key 重试，失败的 key 进入冷却（尊重 `retry-after`），无需手工切换 provider。
+3. **并发 subagent 自动分摊 key** —— 每个进行中的请求持有一个 key lease，选择策略是"在用数最少 + 最久未用"，所以主 agent 同时开多个 subagent 时，它们天然落在不同的 key 上。
+
+## 安装
+
+```bash
+# 方式一：git（推荐，无需 npm 账号）
+pi install git:github.com/kslamph/multikey@v1.2.0
+
+# 方式二：npm（scoped 包，发布时始终带 --access public）
+pi install npm:pi-multikey
+
+# 方式三：本地目录
+pi install /path/to/multikey
+```
+
+## 快速开始（B.AI preset）
+
+```
+/multikey → Add pool… → Preset: B.AI → 逐行粘贴 key（一行一个，留空结束）
+```
+
+选 preset 后 endpoint、compat、6 个模型的全部设定自动就位，模型通过
+`bai/<model-id>` 直接可用，例如 `bai/deepseek-v4-flash`。
+
+## Presets
+
+内置 preset 把"模型设定"与"密钥"解耦。数据来自 b.ai model cards、
+DeepSeek / Tencent / 小米官方文档，并对每个 thinking 档位做过实测探测；
+不支持的档位写为 `null`，UI 不显示。
+
+| 模型 | ctx / max-out | 模态 | 生效 thinking 档位 |
+|---|---|---|---|
+| deepseek-v4-flash | 1M / 384K | text | off · low · high · max |
+| deepseek-v4-flash-vision-exp | 1M / 384K | text+image | off · low · high · max |
+| hy3 | 256K / 128K | text | off · low · high |
+| mimo-v2.5 | 1M / 128K | text+image | off · high（官方：low/medium/high 行为相同） |
+| qwen3.8-flash | 1M / 131K | text+image | off · low · medium · xhigh |
+| glm-5.3-flash | 1M / 131K | text+image | low · high · max（始终思考，无 off） |
+
+> 为什么必须显式写 `null`：pi 的 `getSupportedThinkingLevels` 把 `mapped === null`
+> 视为不支持并隐藏该档，但**省略**会被当作支持并把档名原样发给 API；
+> `xhigh` / `max` 还要求显式给出非 null 值才可用。
+
+新增 preset：在 `presets.ts` 的 `PRESETS` 数组里加一项即可。
+
+## 配置
+
+`~/.pi/agent/multikey.json`。首次运行时会从 `~/.pi/agent/models.json` 自动发现
+可合并的池（同一 baseUrl 出现 ≥2 个 provider = 你在按 key 复制 provider），
+也会收录指向 `api.b.ai` 的 provider；什么都没发现则生成空配置。
+
+```jsonc
+{
+  "pools": [
+    {
+      "id": "bai",                          // pi 里的 provider id → bai/deepseek-v4-flash
+      "name": "B.AI (Key Pool)",
+      "baseUrl": "https://api.b.ai/v1",
+      "api": "openai-completions",
+      "auth": "bearer",                       // 可选："bearer"（默认）或 "api-key"（x-api-key 头）
+      "compat": { ... },                    // provider 级默认，合并进每个模型
+      "cooldownMs": 20000,                  // 429 冷却
+      "invalidKeyCooldownMs": 600000,       // 401/403 冷却
+      "keys": [
+        { "key": "sk-...", "label": "key-1", "enabled": true },
+        { "key": "sk-...", "label": "key-2", "enabled": true }
+      ],
+      "models": [ "…preset 或手动配置的模型定义…" ]
+    }
+  ]
+}
+```
+
+以后要加 nvidia / opencode 等：`/multikey` → `Add pool…`（Custom），或直接编辑
+JSON 后 `Reload config from disk`。
+
+### 添加自定义池（不再询问 API 类型）
+
+自定义向导只问最基本的三项：**provider id、Base URL、key**。随后自动探测端点：
+
+1. 用 `Authorization: Bearer` 请求 `<baseUrl>/models`（会自动尝试 `<baseUrl>/v1/models`），若返回 401/403 再换 `x-api-key` 重试。
+2. 有些网关的 `/models` 是公开的，因此还会发一个 1 token 的迷你 chat 请求验证 key。若两种头都被拒但假 key 能通过，说明是免鉴权的开放端点，按默认 Bearer 保存。
+3. 直接从服务端返回的模型列表中**多选**要添加的模型。元数据里的上下文长度 / 输入模态 / 最大输出会被采用，其余一律安全默认值（128k 上下文、text 输入、16k 最大输出、成本 0）。
+4. 可选：逐模型微调常用参数（上下文、输入模态、最大输出），或跳过以后在 Models 菜单里改。高级字段（thinking 映射、compat、cost）直接编辑 `multikey.json` 后 `Reload config from disk`。
+
+探测出的认证头风格只在端点确实要求 `x-api-key` 时才会存为 `"auth": "api-key"`，默认 Bearer。整池**最后一次性写入**，中途取消不会留下半成品 provider。
+
+## 管理界面
+
+```
+/multikey
+├─ Status                    实时状态：每把 key 的 in-flight / 冷却 / 429 计数
+├─ Manage pools…             api 类型非法的池会标 ⚠ broken；未完成的池标 (incomplete)
+│  ├─ Keys…                  一行一个添加 key；删 / 改 / 禁用
+│  ├─ Models…                从 /models 拉取多选添加，或手动添加；编辑 contextWindow、
+│  │                         maxTokens、模态、reasoning、thinkingLevelMap、compat、cost
+│  ├─ Endpoint & settings…   baseUrl、api 类型、认证风格、冷却时长、headers
+│  └─ Delete pool
+├─ Add pool…
+│  ├─ Preset: B.AI           预置全部模型设定，粘贴 key（自动校验）即可用
+│  └─ Custom…                只填 id + Base URL + key，随后自动探测、多选模型、安全默认值
+└─ Reload config from disk
+```
+
+改动即时生效（重新注册 provider），无需重启。
+
+## 让 subagent 用上池
+
+`settings.json` 的 agentOverrides 改成池 provider：
+
+```json
+"subagents": {
+  "agentOverrides": {
+    "oracle":   { "model": "bai/glm-5.3-flash" },
+    "scout":    { "model": "bai/hy3" },
+    "worker":   { "model": "bai/mimo-v2.5" }
+  }
+}
+```
+
+`defaultProvider: "bai"` 同理。
+
+## 工作原理
+
+- 扩展通过 `pi.registerProvider()` 注册 provider，并提供自定义 `streamSimple`。
+- 每次请求从池中取一把 key（`options.apiKey` 覆盖），收到 HTTP 响应头后：
+  - 429 → 该 key 冷却（默认 20s，尊重 `retry-after`），立即换 key 重试（不产生任何重复输出）；
+  - 401/403 → 该 key 长冷却（默认 10 分钟），换 key 重试；
+  - 其他错误 → 原样交给 pi 的重试机制。
+- 所有 key 都耗尽时才向上抛 429，由 pi 自身的 backoff 重试兜底（此时最早的冷却多半已结束）。
+
+## 安全提示
+
+key 明文保存在 `~/.pi/agent/multikey.json`，建议：
+
+```bash
+chmod 600 ~/.pi/agent/multikey.json
+```

package/config.ts

@@ -0,0 +1,341 @@
+/**
+ * multikey config: load / save / normalize / seed
+ *
+ * Config lives at ~/.pi/agent/multikey.json. Each "pool" becomes one pi provider
+ * whose requests are spread across multiple API keys with automatic 429 rotation.
+ * (Pools created before the rename live in keypool.json and are migrated once.)
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { AuthStyle } from "./probe.ts";
+
+/** Safe model defaults applied when a spec doesn't say otherwise (edit in multikey.json). */
+export const DEFAULT_CONTEXT_WINDOW = 128_000;
+export const DEFAULT_MAX_TOKENS = 16_384;
+export const DEFAULT_INPUT: ("text" | "image")[] = ["text"];
+
+export const KNOWN_API_TYPES = [
+	"openai-completions",
+	"openai-responses",
+	"anthropic-messages",
+	"google-generative-ai",
+	"mistral-conversations",
+	"openai-codex-responses",
+	"azure-openai-responses",
+	"google-vertex",
+	"bedrock-converse-stream",
+	"pi-messages",
+] as const;
+
+export interface PoolKeyConfig {
+	/** The literal API key. */
+	key: string;
+	/** Optional human label, e.g. "main", "spare-1". */
+	label?: string;
+	/** Disabled keys are never selected. Default: true. */
+	enabled?: boolean;
+}
+
+export interface PoolModelConfig {
+	id: string;
+	name?: string;
+	api?: string;
+	baseUrl?: string;
+	reasoning?: boolean;
+	thinkingLevelMap?: Record<string, string | null>;
+	input?: ("text" | "image")[];
+	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	contextWindow?: number;
+	maxTokens?: number;
+	compat?: Record<string, unknown>;
+	headers?: Record<string, string>;
+}
+
+export interface PoolConfig {
+	/** Provider id in pi, e.g. "bai". Model refs become "<id>/<modelId>". */
+	id: string;
+	name?: string;
+	baseUrl: string;
+	/** Streaming API type, e.g. "openai-completions". Default: openai-completions. */
+	api?: string;
+	/** Auth header style. Default: bearer (Authorization: Bearer). "api-key" sends x-api-key instead. */
+	auth?: AuthStyle;
+	/** Provider-level compat defaults merged into every model. */
+	compat?: Record<string, unknown>;
+	headers?: Record<string, string>;
+	/** Cooldown after a 429 on a key. Default 20000ms. */
+	cooldownMs?: number;
+	/** Cooldown after a 401/403 (bad key). Default 600000ms. */
+	invalidKeyCooldownMs?: number;
+	keys: PoolKeyConfig[];
+	models: PoolModelConfig[];
+}
+
+export interface KeypoolConfig {
+	pools: PoolConfig[];
+}
+
+export function configPath(): string {
+	return process.env.MULTIKEY_CONFIG ?? process.env.KEYPOOL_CONFIG ?? join(homedir(), ".pi", "agent", "multikey.json");
+}
+
+/** Pre-rename default location; only consulted for migration when no env override is set. */
+function legacyConfigPath(): string | undefined {
+	if (process.env.MULTIKEY_CONFIG || process.env.KEYPOOL_CONFIG) return undefined;
+	return join(homedir(), ".pi", "agent", "keypool.json");
+}
+
+const DEFAULT_COOLDOWN_MS = 20_000;
+const DEFAULT_INVALID_KEY_COOLDOWN_MS = 600_000;
+/**
+ * First-run seed: discover pools from ~/.pi/agent/models.json instead of shipping
+ * any baked-in credentials. A pool is created for every group of providers that
+ * share one baseUrl (the "I duplicated a provider per key" pattern) plus any
+ * provider already pointing at api.b.ai.
+ */
+
+/** Builtin provider ids we must not shadow with a pool registration. */
+const BUILTIN_ID_DENYLIST = new Set([
+	"anthropic",
+	"openai",
+	"openai-codex",
+	"azure-openai",
+	"google",
+	"google-vertex",
+	"amazon-bedrock",
+	"mistral",
+	"groq",
+	"openrouter",
+	"xai",
+	"deepseek",
+	"moonshot",
+	"zai",
+	"minimax",
+	"github-copilot",
+]);
+
+interface RawModelJsonProvider {
+	baseUrl?: string;
+	apiKey?: string;
+	api?: string;
+	name?: string;
+	compat?: Record<string, unknown>;
+	headers?: Record<string, string>;
+	models?: PoolModelConfig[];
+}
+
+function hostOf(url: string): string {
+	try {
+		return new URL(url).host.toLowerCase();
+	} catch {
+		return "";
+	}
+}
+
+/** Resolve a models.json config value: literal or $ENV/${ENV}. Skips `!command` (never shell out during seed). */
+function resolveConfigValue(value: string): string | undefined {
+	if (value.startsWith("!")) return undefined;
+	const names: string[] = [];
+	const pattern = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+	let match = pattern.exec(value);
+	while (match) {
+		names.push(match[1] ?? match[2]!);
+		match = pattern.exec(value);
+	}
+	if (names.length === 0) return value.trim() || undefined;
+	let resolved = value;
+	for (const name of names) {
+		const envValue = process.env[name];
+		if (!envValue) return undefined;
+		resolved = resolved.replace(new RegExp(`\\$\\{?${name}\\}?`, "g"), envValue);
+	}
+	return resolved.trim() || undefined;
+}
+
+function mergeModel(base: PoolModelConfig | undefined, extra: PoolModelConfig): PoolModelConfig {
+	if (!base) return { ...extra };
+	const merged: PoolModelConfig = { ...base };
+	for (const [key, value] of Object.entries(extra)) {
+		if (value === undefined) continue;
+		const current = (base as unknown as Record<string, unknown>)[key];
+		if (current === undefined || current === null) (merged as unknown as Record<string, unknown>)[key] = value;
+	}
+	// Prefer a definition that actually declares the sizing fields over a stub.
+	if (base.contextWindow === undefined && extra.contextWindow !== undefined) merged.contextWindow = extra.contextWindow;
+	if (base.maxTokens === undefined && extra.maxTokens !== undefined) merged.maxTokens = extra.maxTokens;
+	return merged;
+}
+
+function discoverPools(): PoolConfig[] {
+	const modelsPath = join(homedir(), ".pi", "agent", "models.json");
+	if (!existsSync(modelsPath)) return [];
+
+	let providers: Record<string, RawModelJsonProvider>;
+	try {
+		const parsed = JSON.parse(readFileSync(modelsPath, "utf-8")) as {
+			providers?: Record<string, RawModelJsonProvider>;
+		};
+		providers = parsed.providers ?? {};
+	} catch {
+		return [];
+	}
+
+	// Group by baseUrl.
+	const groups = new Map<string, { id: string; cfg: RawModelJsonProvider }[]>();
+	for (const [id, cfg] of Object.entries(providers)) {
+		if (!cfg || typeof cfg.baseUrl !== "string" || !cfg.baseUrl.trim()) continue;
+		const key = cfg.baseUrl.trim();
+		const bucket = groups.get(key) ?? [];
+		bucket.push({ id, cfg });
+		groups.set(key, bucket);
+	}
+
+	const pools: PoolConfig[] = [];
+	for (const [baseUrl, bucket] of groups) {
+		const isBai = hostOf(baseUrl) === "api.b.ai";
+		if (!isBai && bucket.length < 2) continue;
+
+		// Collect distinct keys.
+		const keys: PoolKeyConfig[] = [];
+		const seenKeys = new Set<string>();
+		for (const entry of bucket) {
+			if (typeof entry.cfg.apiKey !== "string") continue;
+			const resolved = resolveConfigValue(entry.cfg.apiKey);
+			if (!resolved || seenKeys.has(resolved)) continue;
+			seenKeys.add(resolved);
+			keys.push({ key: resolved, label: `${entry.id}`, enabled: true });
+		}
+		if (keys.length === 0) continue;
+
+		// Union of models across the duplicated providers.
+		const modelById = new Map<string, PoolModelConfig>();
+		for (const entry of bucket) {
+			for (const model of entry.cfg.models ?? []) {
+				if (!model || typeof model.id !== "string") continue;
+				modelById.set(model.id, mergeModel(modelById.get(model.id), model));
+			}
+		}
+
+		const primary = bucket[0]!;
+		let poolId = primary.id;
+		if (BUILTIN_ID_DENYLIST.has(poolId.toLowerCase())) poolId = `${poolId}-pool`;
+		if (pools.some((p) => p.id === poolId)) poolId = `${poolId}-2`;
+
+		pools.push({
+			id: poolId,
+			name: `${primary.cfg.name ?? primary.id} (Key Pool)`,
+			baseUrl,
+			api: bucket.find((entry) => entry.cfg.api)?.cfg.api ?? "openai-completions",
+			compat: primary.cfg.compat,
+			headers: primary.cfg.headers,
+			cooldownMs: DEFAULT_COOLDOWN_MS,
+			invalidKeyCooldownMs: DEFAULT_INVALID_KEY_COOLDOWN_MS,
+			keys,
+			models: [...modelById.values()],
+		});
+	}
+	return pools;
+}
+
+function seedConfig(): KeypoolConfig {
+	return { pools: discoverPools() };
+}
+
+export function loadConfig(): { config: KeypoolConfig; created: boolean; migratedFrom?: string } {
+	const path = configPath();
+	if (!existsSync(path)) {
+		const legacy = legacyConfigPath();
+		if (legacy && existsSync(legacy)) {
+			// One-time rename migration: adopt the old keypool.json as-is.
+			const raw = JSON.parse(readFileSync(legacy, "utf-8")) as KeypoolConfig;
+			const config = normalize(raw);
+			saveConfig(config);
+			return { config, created: false, migratedFrom: legacy };
+		}
+		const config = seedConfig();
+		saveConfig(config);
+		return { config, created: true };
+	}
+	const raw = JSON.parse(readFileSync(path, "utf-8")) as KeypoolConfig;
+	return { config: normalize(raw), created: false };
+}
+
+export function saveConfig(config: KeypoolConfig): void {
+	const path = configPath();
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+export function normalize(config: KeypoolConfig): KeypoolConfig {
+	const pools = Array.isArray(config.pools) ? config.pools : [];
+	const normalized: PoolConfig[] = [];
+	for (const pool of pools) {
+		if (!pool || typeof pool.id !== "string" || !pool.id.trim()) continue;
+		if (!pool.baseUrl || typeof pool.baseUrl !== "string") continue;
+		normalized.push(normalizePool(pool));
+	}
+	return { pools: normalized };
+}
+
+function normalizePool(pool: PoolConfig): PoolConfig {
+	const keys = (Array.isArray(pool.keys) ? pool.keys : [])
+		.filter((k) => k && typeof k.key === "string" && k.key.trim())
+		.map((k) => ({
+			key: k.key.trim(),
+			label: typeof k.label === "string" && k.label.trim() ? k.label.trim() : undefined,
+			enabled: k.enabled !== false,
+		}));
+	const models = (Array.isArray(pool.models) ? pool.models : []).filter((m) => m && typeof m.id === "string" && m.id.trim());
+	return {
+		id: pool.id.trim(),
+		name: pool.name ?? pool.id,
+		baseUrl: pool.baseUrl,
+		api: pool.api ?? "openai-completions",
+		auth: pool.auth === "api-key" ? "api-key" : undefined,
+		compat: pool.compat,
+		headers: pool.headers,
+		cooldownMs: typeof pool.cooldownMs === "number" && pool.cooldownMs >= 0 ? pool.cooldownMs : DEFAULT_COOLDOWN_MS,
+		invalidKeyCooldownMs:
+			typeof pool.invalidKeyCooldownMs === "number" && pool.invalidKeyCooldownMs >= 0
+				? pool.invalidKeyCooldownMs
+				: DEFAULT_INVALID_KEY_COOLDOWN_MS,
+		keys,
+		models,
+	};
+}
+
+/** Convert a pool config into pi ProviderModelConfig-style definitions (provider-level compat merged in). */
+export function toProviderModels(pool: PoolConfig): ProviderModelConfig[] {
+	return pool.models.map(
+		(m): ProviderModelConfig => ({
+			id: m.id,
+			name: m.name ?? m.id,
+			api: m.api,
+			baseUrl: m.baseUrl,
+			reasoning: m.reasoning ?? true,
+			thinkingLevelMap: m.thinkingLevelMap as ProviderModelConfig["thinkingLevelMap"],
+			input: m.input ?? DEFAULT_INPUT,
+			cost: m.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: m.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+			maxTokens: m.maxTokens ?? DEFAULT_MAX_TOKENS,
+			compat: mergeCompat(pool.compat, m.compat) as ProviderModelConfig["compat"],
+		}),
+	);
+}
+
+function mergeCompat(
+	base: Record<string, unknown> | undefined,
+	override: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+	if (!base && !override) return undefined;
+	return { ...(base ?? {}), ...(override ?? {}) };
+}
+
+/** Mask a key for display: sk-1234…abcd */
+export function maskKey(key: string): string {
+	if (key.length <= 10) return "…";
+	return `${key.slice(0, 6)}…${key.slice(-4)}`;
+}