@alilis/k-hat 0.2.6 → 0.2.8

package/README.md

@@ -1,82 +1,19 @@
-# K-Hat（khat）
+## 停止后台代理
 
-本地 API key 代理管理器，统一管理多个 AI 服务商的密钥并自动轮转。
-
-把 Codex、OpenCode、ZCode 等 Agent Tool 的 API 端点统一指向 khat，之后更换任何 key 都不必再碰这些工具的配置。当一个 key 触发限流（429）、鉴权失败（401）或余额耗尽（402）时，代理自动切换到同 Provider 的其他 key，你的编码工作流不中断。
-
-## 特性
-
-- **单端口双协议**：一个 HTTP 入口同时承载 OpenAI 族与 Anthropic 族协议，按路径区分
-- **模型路由**：按请求中的 `model` 字段路由到目标 Provider，支持 `provider/model` 显式消歧
-- **多 key 加权轮询**：一个 Provider 可配多个 key，按权重平滑分配请求
-- **自动切换**：上游返回 429 / 401 / 402 时标记 key 不可用并换下一个 key 重发（仅首字节前）
-- **加密密钥库**：全部机密（key 明文、访问令牌）存放在 `vault.json` 的加密 payload 中，payload 使用 AES-256-GCM 加密，32 字节主密钥由操作系统绑定（Windows DPAPI）保护，配置文件零机密可安全备份
-- **流式透传**：SSE 逐 chunk 透传，不缓冲、不改写响应内容；客户端断开级联取消上游请求
-- **后台守护与自愈**：`khat start` 在后台启动 supervisor，崩溃后指数退避重启；`khat stop` 优雅停止，`--foreground` 用于诊断
-- **可观测性**：零机密 JSONL 请求日志、按 key 的请求/失败/字节/Token 计数器、`khat log` 与 `/_keys/logs`
-- **本地管理页**：`khat ui` 以 60 秒单次票据打开内嵌 UI，查看状态、日志并恢复不可用 key
-- **零运行时依赖**：纯 Node.js/TypeScript，仅用 Node 内置模块
-
-## 安装
-
-**方式一：从 npm 安装（推荐）**
-
-```bash
-npm install -g @alilis/k-hat
-```
-
-之后任意目录都能直接使用下文的 `khat <命令>`。卸载用 `npm uninstall -g @alilis/k-hat`。
-
-> Windows 下若提示找不到 `khat`，确认 `%APPDATA%\npm` 在 PATH 中（重开终端后生效）。
-
-**方式二：从源码运行**
-
-```bash
-git clone https://github.com/aweirdocc/k-hat
-cd k-hat
-npm install        # 安装依赖的同时会自动编译 TypeScript（prepare 钩子）
+khat stop
 ```
 
-执行 `npm link` 注册全局命令，效果与方式一相同；或者不改动全局环境，停留在仓库目录内，把下文所有的 `khat <命令>` 换成 `npm run khat -- <命令>`：
-
-```bash
-npm run khat -- status
-npm run khat -- tui
-```
+然后在你的工具中把 `base_url` 指向 `http://127.0.0.1:8787/v1`（或 `http://127.0.0.1:8787`，视工具而定），认证令牌填 `khat init` 生成的访问令牌。
 
-## 快速开始
+### 服务化部署（M7）
 
 ```bash
-# 1. 首次初始化：生成加密密钥库 + 访问令牌 + 默认配置
-khat init
-# 输出访问令牌（仅此一次，也可用 khat token show 查看）
-
-# 2. 添加 Provider
-khat provider add deepseek --base-url https://api.deepseek.com --name DeepSeek --protocol openai
-
-# 3. 添加 key（省略 --value 时交互式提示输入；--weight 为该 key 的轮询权重，默认 1）
-khat key add deepseek main --weight 3
-
-# 4. 添加路由：模型名 -> Provider
-khat route add deepseek-v4-pro deepseek
-
-# 5. 后台启动代理（管理变更命令也会在需要时自动启动它）
-khat start
-
-# 6. 查看状态
-khat status
-
-# 7. 打开本地管理页
-khat ui
-
-# 或在终端中打开交互式管理界面
-khat tui
-
-# 8. 停止后台代理
-khat stop
+khat service install          # 注册开机自启（Windows 计划任务 / macOS launchd / Linux systemd --user）
+khat service uninstall        # 取消开机自启
+khat service status           # 查看服务注册状态与守护进程运行状态
 ```
 
-然后在你的工具中把 `base_url` 指向 `http://127.0.0.1:8787/v1`（或 `http://127.0.0.1:8787`，视工具而定），认证令牌填 `khat init` 生成的访问令牌。
+> **注意**：service 安装时会固定 `KHAT_HOME` 为安装时解析的数据目录；`khat stop` 不会卸载服务，下次登录仍自动启动；Windows 上未采用 NSSM（因用户级 DPAPI vault 无法以 LocalSystem 运行）。
 
 ## CLI 命令
 
@@ -97,6 +34,28 @@ khat stop
 
 > Provider、key 和路由的新增、更新、删除与恢复等管理变更通过本地 Admin API 执行；若 daemon 尚未运行，命令会自动启动它。
 
+### 模型列表接口
+
+代理提供带访问令牌认证的只读模型列表接口：
+
+```bash
+TOKEN=$(khat token show)
+curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/models
+```
+
+`GET /models` 和兼容 OpenAI 客户端的 `GET /v1/models` 返回当前配置中启用的 `routes`，不会请求上游 Provider，也不会返回 `upstreamModel`：
+
+```json
+{
+  "object": "list",
+  "data": [
+    { "id": "deepseek-chat", "object": "model", "created": 0, "owned_by": "deepseek" }
+  ]
+}
+```
+
+未配置路由时 `data` 为空；禁用路由不会出现在列表中。请求必须携带 `Authorization: Bearer <access-token>`，否则返回 HTTP 401。
+
 ### 访问令牌
 
 | 命令 | 说明 |
@@ -124,7 +83,7 @@ khat stop
 | `khat key list [<provider>]` | 列出 key（默认脱敏，仅显示尾 4 位） |
 | `khat key remove <provider> <id>` | 删除 key |
 | `khat key enable <provider> <id>` | 将被标记不可用的 key 恢复为可用 |
-| `khat key test <provider> <id> [--model <m>]` | 直连配置的上游发送一次最小请求探活；成功后恢复 key，不会仅因探测返回 401/402/429 就标记 key 不可用 |
+| `khat key test <provider> <id> [--model <m>]` | 直连配置的上游发送一次最小请求探活；成功后自动恢复 key，不会仅因探测返回 401/402/429 就标记 key 不可用 |
 
 ### 路由管理
 
@@ -140,7 +99,7 @@ khat stop
 | 变量 | 说明 |
 |---|---|
 | `KHAT_HOME` | 数据目录（默认 `~/.khat`） |
-| `KHAT_ACCESS_TOKEN` | 覆盖密钥库中的访问令牌（主要供测试） |
+| `KHAT_ACCESS_TOKEN` | 覆盖密钥库中的访问密钥（主要供测试） |
 
 ## 常见异常与处理
 
@@ -162,68 +121,7 @@ khat stop
 | `daemon started but health check failed` | 后台 daemon 启动异常 | `khat start --foreground` 前台运行观察日志 |
 | `--weight must be a positive integer` | 权重不是正整数 | 传入 ≥1 的整数 |
 | `unknown provider: <x>` / `unknown key: <x/y>` | 引用了不存在的 Provider / Key | 用 `khat provider list` / `khat key list` 核对 |
-| `empty value` | 交互输入 key 值时未输入 | 重新输入，或用 `--value <v>` 提供 |
-| 非 TTY 下 `key add` 交互报错 | 无交互终端且未传 `--value` | 用 `--value <v>` 提供 |
-| `Ticket is invalid or expired` | UI 票据已过期或已使用 | 重新运行 `khat ui` |
-| `khat is not running` | 需要 daemon 的命令但未启动 | 先 `khat start` |
-
-### 代理返回的入口错误
-
-| 状态码 | 含义 | 处理 |
-|---|---|---|
-| 400 | 入口路径与 Provider 协议不匹配，或请求体非法 | 检查工具配置的入口路径与 `base_url` |
-| 401 | 访问令牌无效 | 用 `khat token show` 核对工具里配置的令牌 |
-| 404 | 请求的模型没有匹配的路由 | `khat route add <model> <provider>` |
-| 502 | 上游返回错误（如 key 探活失败） | 查看 `khat log` 与 key 状态 |
-
-### 使用注意事项
-
-- **变更命令会自动拉起 daemon**：`provider / key / route` 等管理命令通过本地 Admin API 执行，若后台服务未运行会自动启动（单写者设计），无需手动 `khat start`。
-- **UI 票据单次有效**：`khat ui` 签发的票据 60 秒有效、只能交换一次会话；管理页保持打开不受影响，重新打开需再次 `khat ui`。
-- **密钥库加密描述**：`vault.json` 是合法 JSON 信封，机密载荷经 AES-256-GCM 加密，32 字节主密钥由 Windows DPAPI 保护；文件本身不是整体二进制密文。
-
-## 协议支持
-
-| 入口路径 | 协议 | 认证头 | 服务的工具 |
-|---|---|---|---|
-| `/v1/chat/completions` | OpenAI Chat | `Authorization: Bearer` | OpenCode、Cursor（部分） |
-| `/v1/responses` | OpenAI Responses | `Authorization: Bearer` | Codex |
-| `/v1/messages` | Anthropic Messages | `x-api-key` + `anthropic-version` | ZCode |
-
-采用**同族直通**策略：OpenAI 入口转发到 OpenAI 上游，Anthropic 入口转发到 Anthropic 上游，只重写认证头与目标 URL，不改写请求体。入口路径与 Provider 协议不匹配时返回 400。
-
-## 数据安全
-
-- **密钥库加密落盘**：`vault.json` 是 JSON 信封；其中 `payload` 使用 AES-256-GCM 加密，32 字节主密钥由 Windows DPAPI（CurrentUser 作用域）保护，key 明文仅存在于守护进程内存
-- **配置零机密**：`config.json` 只存 `vaultRef` 引用，可放心进 Git/网盘备份
-- **日志零机密**：不记录 key 明文、请求/响应体、认证头；CLI 展示 key 默认脱敏
-- **入口双重防护**：所有请求校验 256-bit 访问令牌；默认只绑定 loopback，不对局域网暴露
-- **上游强制 HTTPS**：证书校验，不提供禁用开关（仅 loopback 主机允许明文 http）
-
-## 项目结构
-
-```
-src/
-├── server.ts    # HTTP 服务与转发器（双协议、认证头重写、超时、重试）
-├── router.ts    # 模型名 -> Provider 路由
-├── selector.ts  # 平滑加权轮询
-├── store.ts     # config/state/vault 存储层 + CLI 变更操作
-├── vault.ts     # AES-256-GCM 加密密钥库
-├── config.ts    # 配置加载、校验、原子写入
-├── dpapi.ts     # Windows DPAPI 主密钥保护
-├── types.ts     # 类型定义
-└── cli.ts       # CLI 入口
-test/            # 自动化测试（node:test）
-docs/            # 需求、可行性、概要设计、ADR
-```
-
-## 开发
-
-```bash
-npm test                    # 构建 + 运行全部测试
-npm run build               # 仅编译 TypeScript
-npm start                   # 启动代理
-npm run khat -- status      # 源码运行任意 CLI 子命令
-```
-
-当前状态与设计决策见 [CONTEXT.md](./CONTEXT.md) 与 [docs/](./docs/)。
+| `khat service is not installed` | service 注册不存在 | `khat service install` |
+| `could not register the scheduled task` | Windows 计划任务注册失败 | 检查任务调度器权限，运行 `schtasks /Query /TN khat` 确认 |
+| `could not load the launch agent` | macOS launchd 加载失败 | 检查 `~/Library/LaunchAgents/local.khat.plist` 是否被手动删除，运行 `launchctl list local.khat` |
+| `could not enable the service` | Linux systemd 启用失败 | 检查 `~/.config/systemd/user/khat.service` 是否被删除，运行 `systemctl --user is-enabled khat` |

package/dist/{cli.js → cli/cli.js}

@@ -6,14 +6,15 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
-import { saveJsonAtomic, providerUrl, defaultConfig } from './config.js';
-import { createKhatServer } from './server.js';
-import { openStore, maskSecret } from './store.js';
-import { Vault, generateAccessToken, ACCESS_TOKEN_REF } from './vault.js';
-import { createKeyProtector } from './key-protector.js';
-import { exportPortable, importPortable } from './portable-vault.js';
-import { LogWriter } from './logger.js';
-import { runDoctor as inspectDoctor, formatDoctorSuggestion } from './doctor.js';
+import { saveJsonAtomic, providerUrl, defaultConfig } from '../core/config.js';
+import { createKhatServer } from '../network/server.js';
+import { openStore, maskSecret } from '../data/store.js';
+import { Vault, generateAccessToken, ACCESS_TOKEN_REF } from '../data/vault.js';
+import { createKeyProtector } from '../data/key-protector.js';
+import { exportPortable, importPortable } from '../data/portable-vault.js';
+import { LogWriter } from '../core/logger.js';
+import { runDoctor as inspectDoctor, formatDoctorSuggestion } from '../doctor.js';
+import { createServiceManager } from '../service.js';
 const dataDir = process.env.KHAT_HOME ?? join(homedir(), '.khat');
 const configPath = join(dataDir, 'config.json');
 const statePath = join(dataDir, 'state.json');
@@ -30,6 +31,9 @@ Setup
   start [--foreground] [--port <n>]     start the proxy as a background daemon (or foreground with --foreground);
                                         --port <n> changes the persisted listen port
   stop                                  stop the background daemon
+  service install                       register khat to auto-start at logon (Task Scheduler / launchd / systemd --user)
+  service uninstall                     remove the auto-start registration
+  service status                        show the service registration and daemon state
   status                                show providers, keys, routes and key health
   doctor                                detect local Agent Tools and show connection guidance
   log [--tail <n>]                      show recent masked proxy request logs
@@ -195,7 +199,14 @@ function keyStatusLine(store, providerId, keyId) {
     const state = store.states[`${providerId}/${keyId}`];
     if (!state || state.status === 'available')
         return { status: 'available', note: '' };
-    return { status: 'unavailable', note: `  last error: ${state.lastError?.http ?? '?'} at ${state.lastError?.at ?? '?'}` };
+    const lastError = `last error: ${state.lastError?.http ?? '?'} at ${state.lastError?.at ?? '?'}`;
+    if (state.status === 'cooldown') {
+        const remaining = Date.parse(state.cooldownUntil ?? '') - Date.now();
+        if (remaining <= 0)
+            return { status: 'available', note: '' };
+        return { status: 'cooldown', note: `  cooling down, auto-retry in ${Math.ceil(remaining / 1000)}s (${lastError})` };
+    }
+    return { status: 'unavailable', note: `  ${lastError}` };
 }
 function printStatus(store) {
     const token = store.vault.get(ACCESS_TOKEN_REF);
@@ -243,6 +254,28 @@ async function daemonRunning() {
         return false;
     }
 }
+async function readDaemonPid() {
+    if (!(await daemonRunning()))
+        return undefined;
+    try {
+        return Number.parseInt((await readFile(pidPath, 'utf8')).trim(), 10);
+    }
+    catch {
+        return undefined;
+    }
+}
+function printServiceStatus(service, daemonPid) {
+    if (!service.installed) {
+        console.log('khat service is not installed (run khat service install)');
+        return;
+    }
+    const enabled = service.enabled === null ? 'unknown' : service.enabled ? 'on' : 'off';
+    const running = service.running === null ? 'unknown' : service.running ? 'yes' : 'no';
+    console.log('khat service');
+    console.log(`  auto-start:  ${enabled}`);
+    console.log(`  running:     ${running}${service.detail ? ` (${service.detail})` : ''}`);
+    console.log(`  daemon:      ${daemonPid !== undefined ? `running (pid ${daemonPid})` : 'not running'}`);
+}
 async function runForeground() {
     const store = await openInitializedStore();
     const secrets = {};
@@ -368,7 +401,7 @@ async function runTui() {
     if (!token)
         throw new Error('no access token found; run khat init');
     await ensureDaemon();
-    const { runTui: startTui } = await import('./tui-main.js');
+    const { runTui: startTui } = await import('../ui/tui/tui-main.js');
     await startTui(`http://${store.config.bind}:${store.config.port}`, token);
 }
 async function runUi() {
@@ -402,7 +435,7 @@ async function runLog(flags) {
         return;
     }
     for (const entry of entries) {
-        console.log(`${entry.ts}\t${entry.status}\t${entry.provider}/${entry.key.split('/').pop()}\t${entry.model}\t${entry.durationMs}ms\t${entry.tokensIn ?? 0}/${entry.tokensOut ?? 0} tokens`);
+        console.log(`${entry.ts}\t${entry.status}\t${entry.provider}/${entry.key.split('/').pop()}\t${entry.model ?? '(probe)'}\t${entry.durationMs ?? '—'}\t${entry.tokensIn ?? 0}/${entry.tokensOut ?? 0} tokens`);
     }
 }
 async function runDoctor() {
@@ -497,6 +530,25 @@ try {
         case 'stop':
             await runStop();
             break;
+        case 'service': {
+            const action = positionals[0];
+            const manager = createServiceManager(process.platform, { dataDir });
+            if (action === 'install') {
+                await openInitializedStore();
+                console.log(await manager.install({ startNow: !(await daemonRunning()) }));
+            }
+            else if (action === 'uninstall') {
+                console.log(await manager.uninstall());
+            }
+            else if (action === 'status') {
+                printServiceStatus(await manager.status(), await readDaemonPid());
+            }
+            else {
+                console.error('usage: khat service install | uninstall | status');
+                process.exitCode = 1;
+            }
+            break;
+        }
         case 'status':
             printStatus(await openInitializedStore());
             break;
@@ -677,7 +729,7 @@ try {
                     console.log(`${providerId}/${keyId} is available`);
                 }
                 else if ([401, 402, 429].includes(response.status))
-                    console.log('this error marks a key unavailable during proxying; check the key on the provider side');
+                    console.log(response.status === 429 ? 'a 429 during proxying puts the key in cooldown; it revives automatically when the cooldown expires' : 'this error marks a key unavailable during proxying; check the key on the provider side');
             }
             else {
                 console.error('usage: khat key add | list | update | remove | enable | test');

package/dist/{config.js → core/config.js}

@@ -53,6 +53,9 @@ export function validateConfig(config) {
     if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) {
         throw new Error('Invalid config: port must be an integer between 1 and 65535');
     }
+    if (config.revision !== undefined && (!Number.isInteger(config.revision) || config.revision < 0)) {
+        throw new Error('Invalid config: revision must be a non-negative integer');
+    }
     for (const provider of config.providers) {
         if (!provider.id || !provider.baseUrl || (provider.protocol !== 'openai' && provider.protocol !== 'anthropic') || !Array.isArray(provider.keys))
             throw new Error(`Invalid provider: ${provider.id}`);

package/dist/core/probe.js

@@ -0,0 +1,15 @@
+import { providerUrl } from '../core/config.js';
+const ANTHROPIC_VERSION = '2023-06-01';
+/** Minimal one-token ping shared by the Admin probe endpoint and the background prober. */
+export async function probeKey(provider, model, secret) {
+    const path = provider.protocol === 'anthropic' ? '/v1/messages' : '/v1/chat/completions';
+    const headers = provider.protocol === 'anthropic'
+        ? { 'content-type': 'application/json', 'x-api-key': secret, 'anthropic-version': ANTHROPIC_VERSION }
+        : { 'content-type': 'application/json', authorization: `Bearer ${secret}` };
+    const body = provider.protocol === 'anthropic'
+        ? { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }] }
+        : { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }], stream: false };
+    const response = await fetch(providerUrl(provider.baseUrl, path), { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
+    await response.arrayBuffer();
+    return response.status;
+}

package/dist/{key-protector.js → data/key-protector.js}

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
-import { dpapiProtector } from './dpapi.js';
+import { dpapiProtector } from '../data/dpapi.js';
 const SERVICE = 'khat-vault';
 const ACCOUNT = 'khat';
 function run(command, args, input = '') {

package/dist/{portable-vault.js → data/portable-vault.js}

@@ -1,8 +1,8 @@
 import { createCipheriv, createDecipheriv, pbkdf2Sync, randomBytes } from 'node:crypto';
 import { access, mkdir, readFile, rename, rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { saveJsonAtomic, validateConfig, defaultConfig } from './config.js';
-import { Vault } from './vault.js';
+import { saveJsonAtomic, validateConfig, defaultConfig } from '../core/config.js';
+import { Vault } from '../data/vault.js';
 const FORMAT = 'khat-vault-export';
 const VERSION = 1;
 const AAD = 'khat-vault-export-v1';

package/dist/{store.js → data/store.js}

@@ -1,7 +1,7 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { readJsonFile, saveJsonAtomic, loadState, validateConfig, defaultConfig } from './config.js';
-import { Vault } from './vault.js';
+import { readJsonFile, saveJsonAtomic, loadState, validateConfig, defaultConfig } from '../core/config.js';
+import { Vault } from '../data/vault.js';
 /** Ids appear in `provider/model` routing syntax and in vault refs, so they cannot contain `/`. */
 const ID_PATTERN = /^[A-Za-z0-9_-]+$/;
 export function maskSecret(value) {
@@ -43,7 +43,12 @@ export async function openStore(dir, protector) {
                 release();
             }
         },
-        saveConfig: () => saveJsonAtomic(configPath, config),
+        saveConfig: () => {
+            // Monotonic marker: lets the config watcher tell our own writes (and stale reads of them)
+            // apart from genuine external edits.
+            config.revision = Number.isInteger(config.revision) ? config.revision + 1 : 1;
+            return saveJsonAtomic(configPath, config);
+        },
         saveState: () => saveJsonAtomic(statePath, { keys: store.states, counters: store.counters }),
         recordCounter: (keyRef, delta) => {
             const current = store.counters[keyRef] ?? { requests: 0, failed: 0, bytesOut: 0, tokensIn: 0, tokensOut: 0 };
@@ -57,7 +62,9 @@ export async function openStore(dir, protector) {
             if (!stateTimer)
                 stateTimer = setTimeout(() => {
                     stateTimer = undefined;
-                    void store.saveState();
+                    store.saveState().catch((error) => {
+                        console.error(`[khat] failed to persist state: ${error?.message ?? error}`);
+                    });
                 }, 1_000);
             stateTimer.unref();
         }

package/dist/{vault.js → data/vault.js}

@@ -1,6 +1,6 @@
 import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
-import { saveJsonAtomic } from './config.js';
+import { saveJsonAtomic } from '../core/config.js';
 const VAULT_VERSION = 1;
 const AAD = 'khat-vault-v1';
 // Releases before the kay->khat rename wrote their payload under this AAD; files saved that way stay readable and are rewritten under the current AAD on their next save().

package/dist/{admin.js → network/admin.js}

@@ -1,11 +1,13 @@
-import { addProvider, updateProvider, removeProvider, addKey, updateKey, removeKey, enableKey, setKeyEnabled, addRoute, updateRoute, setRouteEnabled, removeRoute, maskSecret } from './store.js';
-import { LogWriter } from './logger.js';
+import { addProvider, updateProvider, removeProvider, addKey, updateKey, removeKey, enableKey, setKeyEnabled, addRoute, updateRoute, setRouteEnabled, removeRoute, maskSecret } from '../data/store.js';
+import { LogWriter } from '../core/logger.js';
 import { join } from 'node:path';
-import { UiSessions, serveUi } from './web-ui.js';
-import { ACCESS_TOKEN_REF, generateAccessToken } from './vault.js';
-import { providerUrl } from './config.js';
-import { findRoute, routeUpstreamModel } from './router.js';
-import { readExport, applyImport } from './portable-vault.js';
+import { UiSessions, serveUi } from '../ui/web-ui.js';
+import { ACCESS_TOKEN_REF, generateAccessToken } from '../data/vault.js';
+import { providerUrl } from '../core/config.js';
+import { findRoute, routeUpstreamModel } from '../core/router.js';
+import { keyBlocked } from './selector.js';
+import { probeKey } from '../core/probe.js';
+import { readExport, applyImport } from '../data/portable-vault.js';
 // Admin API is the daemon's single-writer surface (ADR-0005). It is reachable
 // only from loopback and behind the proxy access token, so a local non-loopback
 // client or a process without the token cannot mutate config/state/vault.
@@ -39,7 +41,7 @@ async function listProviderModels(store, providerId) {
     const provider = store.config.providers.find((item) => item.id === providerId);
     if (!provider)
         throw new Error(`unknown provider: ${providerId}`);
-    const key = provider.keys.find((item) => item.enabled !== false && store.states[`${provider.id}/${item.id}`]?.status !== 'unavailable');
+    const key = provider.keys.find((item) => item.enabled !== false && !keyBlocked(store.states[`${provider.id}/${item.id}`]));
     if (!key)
         throw new Error('provider has no available key');
     const secret = store.vault.get(key.vaultRef);
@@ -67,11 +69,14 @@ function buildStatus(store) {
             keys: provider.keys.map((key) => {
                 const state = store.states[`${provider.id}/${key.id}`];
                 const secret = store.vault.get(key.vaultRef);
+                // An expired cooldown is selectable again, so it must surface as available.
+                const status = keyBlocked(state) ? state.status : 'available';
                 return {
                     id: key.id,
                     weight: key.weight,
                     ...(key.enabled === false ? { enabled: false } : {}),
-                    status: state?.status === 'unavailable' ? 'unavailable' : 'available',
+                    status,
+                    ...(status === 'cooldown' ? { cooldownUntil: state.cooldownUntil } : {}),
                     lastError: state?.lastError,
                     secret: secret ? maskSecret(secret) : null,
                     counters: store.counters[`${provider.id}/${key.id}`] ?? { requests: 0, failed: 0, bytesOut: 0, tokensIn: 0, tokensOut: 0 }
@@ -206,15 +211,10 @@ async function route(req, res, store, sessionAuthorized = false) {
                 : store.config.routes.find((item) => item.provider === provider.id);
             if (!secret || !route || route.provider !== provider.id)
                 throw new Error('a key and route model are required for probing');
-            const model = routeUpstreamModel(route);
-            const path = provider.protocol === 'anthropic' ? '/v1/messages' : '/v1/chat/completions';
-            const headers = upstreamHeaders(provider.protocol, secret, true);
-            const body = provider.protocol === 'anthropic' ? { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }] } : { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }], stream: false };
-            const response = await fetch(providerUrl(provider.baseUrl, path), { method: 'POST', headers: headers, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
-            await response.arrayBuffer();
-            if (response.ok)
+            const status = await probeKey(provider, routeUpstreamModel(route), secret);
+            if (status >= 200 && status < 300)
                 await store.mutate(() => enableKey(store, provider.id, key.id));
-            return json(res, response.ok ? 200 : 502, { ok: response.ok, status: response.status });
+            return json(res, status >= 200 && status < 300 ? 200 : 502, { ok: status >= 200 && status < 300, status });
         }
     }
     if (sub[0] === 'routes') {

package/dist/{selector.js → network/selector.js}

@@ -1,7 +1,19 @@
+/** True when a key must not be selected: permanently unavailable, or still cooling down after a 429. */
+export function keyBlocked(state, now = Date.now()) {
+    if (!state)
+        return false;
+    if (state.status === 'unavailable')
+        return true;
+    if (state.status === 'cooldown') {
+        const until = Date.parse(state.cooldownUntil ?? '');
+        return Number.isNaN(until) || until > now;
+    }
+    return false;
+}
 export class WeightedSelector {
     current = new Map();
     select(providerId, keys, states) {
-        const available = keys.filter((key) => key.enabled !== false && states[`${providerId}/${key.id}`]?.status !== 'unavailable');
+        const available = keys.filter((key) => key.enabled !== false && !keyBlocked(states[`${providerId}/${key.id}`]));
         if (!available.length)
             return undefined;
         let total = 0;