@alilis/k-hat 0.2.7 → 0.2.9

package/README.md

@@ -1,82 +1,46 @@
-# K-Hat（khat）
+# K-Hat
 
-本地 API key 代理管理器，统一管理多个 AI 服务商的密钥并自动轮转。
+本地 API key 代理管理器，统一管理多个 AI 服务商的密钥并自动轮转。K-Hat 在本机提供兼容 OpenAI 的 API 入口，将请求按模型路由到已配置的 Provider，并在 key 不可用时自动切换。
 
-把 Codex、OpenCode、ZCode 等 Agent Tool 的 API 端点统一指向 khat，之后更换任何 key 都不必再碰这些工具的配置。当一个 key 触发限流（429）、鉴权失败（401）或余额耗尽（402）时，代理自动切换到同 Provider 的其他 key，你的编码工作流不中断。
+## 安装与首次运行
 
-## 特性
+要求 Node.js 20 或更高版本。
 
-- **单端口双协议**：一个 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 内置模块
-
-## 安装
+```bash
+npm install
+npm link
+khat init
+khat start
+```
 
-**方式一：从 npm 安装（推荐）**
+如果不希望创建全局命令，也可以在仓库内运行：
 
 ```bash
-npm install -g @alilis/k-hat
+npm run khat -- init
+npm run khat -- start
 ```
 
-之后任意目录都能直接使用下文的 `khat <命令>`。卸载用 `npm uninstall -g @alilis/k-hat`。
-
-> Windows 下若提示找不到 `khat`，确认 `%APPDATA%\npm` 在 PATH 中（重开终端后生效）。
+初始化后，使用 Provider、Key 和 Route 命令完成配置。访问令牌可通过 `khat token show` 查看，建议仅在需要配置客户端时使用。
 
-**方式二：从源码运行**
+## 接入客户端
 
-```bash
-git clone https://github.com/aweirdocc/k-hat
-cd k-hat
-npm install        # 安装依赖的同时会自动编译 TypeScript（prepare 钩子）
-```
+将客户端的 `base_url` 指向 `http://127.0.0.1:8787/v1`（或 `http://127.0.0.1:8787`，视工具而定），认证令牌填入 `khat init` 生成的访问令牌。
 
-执行 `npm link` 注册全局命令，效果与方式一相同；或者不改动全局环境，停留在仓库目录内，把下文所有的 `khat <命令>` 换成 `npm run khat -- <命令>`：
+## 停止后台代理
 
 ```bash
-npm run khat -- status
-npm run khat -- tui
+khat stop
 ```
 
-## 快速开始
+### 服务化部署（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 +61,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 +110,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 +126,7 @@ khat stop
 | 变量 | 说明 |
 |---|---|
 | `KHAT_HOME` | 数据目录（默认 `~/.khat`） |
-| `KHAT_ACCESS_TOKEN` | 覆盖密钥库中的访问令牌（主要供测试） |
+| `KHAT_ACCESS_TOKEN` | 覆盖密钥库中的访问密钥（主要供测试） |
 
 ## 常见异常与处理
 
@@ -162,68 +148,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
@@ -250,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 = {};
@@ -375,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() {
@@ -504,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;

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

@@ -1,4 +1,4 @@
-import { providerUrl } from './config.js';
+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) {

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) {

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,13 +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 { 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 './probe.js';
-import { readExport, applyImport } from './portable-vault.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.

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

@@ -1,14 +1,14 @@
 import { createServer } from 'node:http';
 import { watch } from 'node:fs';
-import { readJsonFile, saveJsonAtomic, validateConfig, providerUrl, defaultTimeouts } from './config.js';
-import { LogWriter } from './logger.js';
+import { readJsonFile, saveJsonAtomic, validateConfig, providerUrl, defaultTimeouts } from '../core/config.js';
+import { LogWriter } from '../core/logger.js';
 import { join, basename } from 'node:path';
-import { findRoute, routeUpstreamModel, resolveProvider, isRouteDisabled } from './router.js';
+import { findRoute, routeUpstreamModel, resolveProvider, isRouteDisabled } from '../core/router.js';
 import { WeightedSelector } from './selector.js';
-import { handleAdmin } from './admin.js';
-import { enableKey } from './store.js';
-import { probeKey } from './probe.js';
-import { ACCESS_TOKEN_REF } from './vault.js';
+import { handleAdmin } from '../network/admin.js';
+import { enableKey } from '../data/store.js';
+import { probeKey } from '../core/probe.js';
+import { ACCESS_TOKEN_REF } from '../data/vault.js';
 const RETRYABLE = new Set([401, 402, 429]);
 const HOP_BY_HOP = new Set(['content-length', 'transfer-encoding', 'connection']);
 const ANTHROPIC_VERSION = '2023-06-01';
@@ -27,6 +27,13 @@ const ENDPOINTS = {
     '/v1/responses': 'openai',
     '/v1/messages': 'anthropic'
 };
+function modelList(config) {
+    const seen = new Set();
+    const data = config.routes
+        .filter((route) => route.enabled !== false && !seen.has(route.model) && seen.add(route.model))
+        .map((route) => ({ id: route.model, object: 'model', created: 0, owned_by: route.provider }));
+    return { object: 'list', data };
+}
 /** Rewrite the client-facing auth into the upstream auth convention for the target protocol. */
 function upstreamHeaders(protocol, secret, accept) {
     if (protocol === 'anthropic')
@@ -132,11 +139,14 @@ export function createKhatServer(options) {
                 return;
             }
             const currentAccessToken = options.store?.vault.get(ACCESS_TOKEN_REF) ?? options.accessToken;
-            if (currentAccessToken && req.headers.authorization !== `Bearer ${currentAccessToken}`)
+            if (!currentAccessToken || req.headers.authorization !== `Bearer ${currentAccessToken}`)
                 return json(res, 401, { error: { message: 'Unauthorized' } });
-            if (req.method !== 'POST' || !(req.url in ENDPOINTS))
+            const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+            if (req.method === 'GET' && (pathname === '/models' || pathname === '/v1/models'))
+                return json(res, 200, modelList(options.config));
+            if (req.method !== 'POST' || !(pathname in ENDPOINTS))
                 return json(res, 404, { error: { message: 'Not found' } });
-            const protocol = ENDPOINTS[req.url];
+            const protocol = ENDPOINTS[pathname];
             const body = await readBody(req, options.config.requestBodyLimitMB * 1024 * 1024);
             let parsed;
             try {
@@ -180,7 +190,7 @@ export function createKhatServer(options) {
                 const headerTimer = setTimeout(() => upstreamAbort(abort, 'upstream response header timeout'), timeouts().headerMs);
                 let upstream;
                 try {
-                    upstream = await fetch(providerUrl(provider.baseUrl, req.url), { method: 'POST', headers: upstreamHeaders(protocol, secret, req.headers.accept), body: upstreamBody, signal: abort.signal });
+                    upstream = await fetch(providerUrl(provider.baseUrl, pathname), { method: 'POST', headers: upstreamHeaders(protocol, secret, req.headers.accept), body: upstreamBody, signal: abort.signal });
                 }
                 catch (error) {
                     if (error?.upstreamTimeout)

package/dist/service.js

@@ -0,0 +1,283 @@
+import { execFile } from 'node:child_process';
+import { access, mkdir, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const WINDOWS_TASK_NAME = 'khat';
+const LAUNCHD_LABEL = 'local.khat';
+const SYSTEMD_UNIT = 'khat';
+async function defaultRunner(command, args) {
+    try {
+        const { stdout, stderr } = await execFileAsync(command, args, { windowsHide: true, timeout: 30_000 });
+        return { code: 0, stdout: String(stdout), stderr: String(stderr) };
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return { code: null, stdout: '', stderr: `${command} is not available` };
+        return { code: typeof error?.code === 'number' ? error.code : null, stdout: String(error?.stdout ?? ''), stderr: String(error?.stderr ?? error?.message ?? 'command failed') };
+    }
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function xmlEscape(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+function resolveOptions(options) {
+    const home = options.homeDir ?? homedir();
+    return {
+        runner: options.run ?? defaultRunner,
+        homeDir: home,
+        dataDir: options.dataDir ?? process.env.KHAT_HOME ?? join(home, '.khat'),
+        distDir: options.distDir ?? dirname(fileURLToPath(new URL('./supervisor.js', import.meta.url))),
+        execPath: options.execPath ?? process.execPath,
+        userId: options.userId ?? (process.env.USERDOMAIN && process.env.USERNAME ? `${process.env.USERDOMAIN}\\${process.env.USERNAME}` : undefined),
+        uid: options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : undefined)
+    };
+}
+function commandFailure(result, action) {
+    return `${action}: ${(result.stderr || result.stdout).trim() || `command exited with code ${result.code}`}`;
+}
+export function buildTaskXml(options) {
+    const triggerUser = options.userId ? `\n      <UserId>${xmlEscape(options.userId)}</UserId>` : '';
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>Khat proxy supervisor; starts the khat daemon when you log on</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>${triggerUser}
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${xmlEscape(options.command)}</Command>
+      <Arguments>${xmlEscape(options.arguments)}</Arguments>
+    </Exec>
+  </Actions>
+</Task>`;
+}
+export function buildLaunchdPlist(options) {
+    const programArgs = options.programArgs.map((arg) => `    <string>${xmlEscape(arg)}</string>`).join('\n');
+    const env = Object.entries(options.env).map(([key, value]) => `    <key>${xmlEscape(key)}</key>\n    <string>${xmlEscape(value)}</string>`).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(options.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(options.program)}</string>
+${programArgs}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(options.workDir)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(options.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(options.logPath)}</string>
+</dict>
+</plist>`;
+}
+export function buildSystemdUnit(options) {
+    const execStart = options.execStart.map((part) => `"${part}"`).join(' ');
+    const env = Object.entries(options.env).map(([key, value]) => `Environment="${key}=${value}"`).join('\n');
+    return `[Unit]
+Description=Khat proxy supervisor
+
+[Service]
+ExecStart=${execStart}
+WorkingDirectory="${options.workDir}"
+${env}
+Restart=no
+
+[Install]
+WantedBy=default.target
+`;
+}
+// Windows: a scheduled task with an interactive token, not an NSSM service —
+// the vault master key is protected with user-scope DPAPI (ADR 0004), which
+// LocalSystem cannot decrypt, and NSSM cannot run as the current user without
+// that user's password.
+function windowsManager(options) {
+    const { runner, dataDir, distDir, execPath, userId } = resolveOptions(options);
+    const supervisorPath = join(distDir, 'supervisor.js');
+    async function install({ startNow = true } = {}) {
+        await mkdir(dataDir, { recursive: true });
+        const xmlPath = join(dataDir, 'service-task.xml');
+        // The task XML cannot set environment variables, so a cmd wrapper pins
+        // KHAT_HOME; the quoted `set` form avoids trailing-space capture.
+        const arguments_ = `/c set "KHAT_HOME=${dataDir}" && "${execPath}" "${supervisorPath}"`;
+        const xml = buildTaskXml({ userId, command: 'cmd.exe', arguments: arguments_ });
+        await writeFile(xmlPath, Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(xml, 'utf16le')]));
+        const created = await runner('schtasks', ['/Create', '/F', '/TN', WINDOWS_TASK_NAME, '/XML', xmlPath]);
+        if (created.code !== 0)
+            throw new Error(`${commandFailure(created, 'could not register the scheduled task')} (definition kept at ${xmlPath})`);
+        await unlink(xmlPath).catch(() => undefined);
+        if (!startNow)
+            return `scheduled task '${WINDOWS_TASK_NAME}' registered; it auto-starts the daemon at your next logon`;
+        const started = await runner('schtasks', ['/Run', '/TN', WINDOWS_TASK_NAME]);
+        if (started.code !== 0)
+            throw new Error(commandFailure(started, 'task registered but could not be started'));
+        return `scheduled task '${WINDOWS_TASK_NAME}' registered and running; it auto-starts at logon`;
+    }
+    async function uninstall() {
+        const query = await runner('schtasks', ['/Query', '/TN', WINDOWS_TASK_NAME]);
+        if (query.code !== 0)
+            return 'khat service is not installed';
+        const removed = await runner('schtasks', ['/Delete', '/F', '/TN', WINDOWS_TASK_NAME]);
+        if (removed.code !== 0)
+            throw new Error(commandFailure(removed, 'could not remove the scheduled task'));
+        return `scheduled task '${WINDOWS_TASK_NAME}' removed`;
+    }
+    async function status() {
+        const query = await runner('schtasks', ['/Query', '/TN', WINDOWS_TASK_NAME]);
+        if (query.code !== 0)
+            return { installed: false, enabled: null, running: null, detail: '' };
+        // schtasks /Query status text is localized; PowerShell's StateEnum is not.
+        const state = await runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-ScheduledTask -TaskName '${WINDOWS_TASK_NAME}' -ErrorAction SilentlyContinue).State`]);
+        const value = Number.parseInt(state.stdout.trim(), 10);
+        if (!Number.isInteger(value))
+            return { installed: true, enabled: null, running: null, detail: 'task state could not be read' };
+        return {
+            installed: true,
+            enabled: value !== 1,
+            running: value === 4,
+            detail: value === 4 ? 'task running' : value === 3 ? 'task ready (not running)' : value === 1 ? 'task disabled' : `task state ${value}`
+        };
+    }
+    return { install, uninstall, status };
+}
+// macOS: launchd user agent. RunAtLoad starts it at login; KeepAlive stays off
+// so the supervisor's own crash circuit breaker is the only restart authority.
+function darwinManager(options) {
+    const { runner, homeDir, dataDir, distDir, execPath, uid } = resolveOptions(options);
+    const supervisorPath = join(distDir, 'supervisor.js');
+    const plistPath = join(homeDir, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+    const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+    async function install({ startNow = true } = {}) {
+        if (uid === undefined)
+            throw new Error('could not determine the user id for launchctl');
+        await mkdir(dirname(plistPath), { recursive: true });
+        await mkdir(dataDir, { recursive: true });
+        const plist = buildLaunchdPlist({
+            label: LAUNCHD_LABEL,
+            program: execPath,
+            programArgs: [supervisorPath],
+            workDir: distDir,
+            env: { KHAT_HOME: dataDir },
+            logPath: join(dataDir, 'service.log')
+        });
+        await writeFile(plistPath, plist, 'utf8');
+        if (!startNow)
+            return `launch agent ${LAUNCHD_LABEL} installed; it auto-starts the daemon at your next logon`;
+        await runner('launchctl', ['bootout', target]);
+        const boot = await runner('launchctl', ['bootstrap', `gui/${uid}`, plistPath]);
+        if (boot.code !== 0)
+            throw new Error(commandFailure(boot, 'could not load the launch agent'));
+        return `launch agent ${LAUNCHD_LABEL} installed and running; it auto-starts at logon`;
+    }
+    async function uninstall() {
+        if (!(await fileExists(plistPath)))
+            return 'khat service is not installed';
+        await runner('launchctl', ['bootout', target]);
+        await unlink(plistPath).catch(() => undefined);
+        return `launch agent ${LAUNCHD_LABEL} removed`;
+    }
+    async function status() {
+        if (!(await fileExists(plistPath)))
+            return { installed: false, enabled: null, running: null, detail: '' };
+        const printed = await runner('launchctl', ['print', target]);
+        if (printed.code !== 0)
+            return { installed: true, enabled: true, running: false, detail: 'not loaded; starts at next logon' };
+        const state = printed.stdout.match(/state\s*=\s*(\S+)/)?.[1] ?? 'unknown';
+        return { installed: true, enabled: true, running: state === 'running', detail: state === 'running' ? 'agent running' : `agent state: ${state}` };
+    }
+    return { install, uninstall, status };
+}
+// Linux: systemd user unit. Restart=no — the supervisor owns crash backoff;
+// the unit only has to launch it once per login/boot.
+function linuxManager(options) {
+    const { runner, homeDir, dataDir, distDir, execPath } = resolveOptions(options);
+    const supervisorPath = join(distDir, 'supervisor.js');
+    const unitPath = join(homeDir, '.config', 'systemd', 'user', `${SYSTEMD_UNIT}.service`);
+    async function install({ startNow = true } = {}) {
+        await mkdir(dirname(unitPath), { recursive: true });
+        const unit = buildSystemdUnit({ execStart: [execPath, supervisorPath], workDir: distDir, env: { KHAT_HOME: dataDir } });
+        await writeFile(unitPath, unit, 'utf8');
+        const reloaded = await runner('systemctl', ['--user', 'daemon-reload']);
+        if (reloaded.code !== 0)
+            throw new Error(commandFailure(reloaded, 'could not reload the systemd user units'));
+        const enable = await runner('systemctl', ['--user', ...(startNow ? ['enable', '--now'] : ['enable']), SYSTEMD_UNIT]);
+        if (enable.code !== 0)
+            throw new Error(commandFailure(enable, 'could not enable the service'));
+        // Without lingering, user units only run while the user is logged in.
+        const linger = await runner('loginctl', ['enable-linger']);
+        const lingerNote = linger.code === 0 ? '' : ' (warning: could not enable lingering, so the service starts at login rather than at boot)';
+        return `systemd user service ${SYSTEMD_UNIT} installed${startNow ? ' and running' : ''}; it auto-starts at login${lingerNote}`;
+    }
+    async function uninstall() {
+        if (!(await fileExists(unitPath)))
+            return 'khat service is not installed';
+        await runner('systemctl', ['--user', 'disable', '--now', SYSTEMD_UNIT]);
+        await unlink(unitPath).catch(() => undefined);
+        await runner('systemctl', ['--user', 'daemon-reload']);
+        return `systemd user service ${SYSTEMD_UNIT} removed`;
+    }
+    async function status() {
+        if (!(await fileExists(unitPath)))
+            return { installed: false, enabled: null, running: null, detail: '' };
+        const enabledResult = await runner('systemctl', ['--user', 'is-enabled', SYSTEMD_UNIT]);
+        const activeResult = await runner('systemctl', ['--user', 'is-active', SYSTEMD_UNIT]);
+        const enabledText = enabledResult.stdout.trim();
+        const activeText = activeResult.stdout.trim();
+        return {
+            installed: true,
+            enabled: enabledText === 'enabled' ? true : enabledText === 'disabled' ? false : null,
+            running: activeText === 'active',
+            detail: activeText === 'active' ? 'unit active' : `unit ${activeText || 'unknown'}`
+        };
+    }
+    return { install, uninstall, status };
+}
+export function createServiceManager(platform, options = {}) {
+    if (platform === 'win32')
+        return windowsManager(options);
+    if (platform === 'darwin')
+        return darwinManager(options);
+    if (platform === 'linux')
+        return linuxManager(options);
+    throw new Error(`unsupported platform '${platform}': khat service requires Windows Task Scheduler, macOS launchd, or Linux systemd`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alilis/k-hat",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "publishConfig": {
     "access": "public"
   },
@@ -8,7 +8,7 @@
   "license": "MIT",
   "type": "module",
   "bin": {
-    "khat": "dist/cli.js"
+    "khat": "dist/cli/cli.js"
   },
   "files": [
     "dist"
@@ -36,8 +36,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepare": "npm run build",
-    "start": "node dist/cli.js start",
-    "khat": "node dist/cli.js",
+    "start": "node dist/cli/cli.js start",
+    "khat": "node dist/cli/cli.js",
     "test": "npm run build && node --test test/**/*.test.js",
     "bench": "node bench/bench.js"
   },