@yhong91/cpac 0.1.24 → 0.1.25

package/README.md

@@ -47,9 +47,9 @@ cpac uninstall --target codex          # 字节级恢复原配置
 cpac claude                            # Claude Code 走 CPA
 cpac opencode                          # opencode 走 CPA（模型选 cpac/<模型名>）
 
-# 5. 可选：Claude 模型槽位覆盖（持久缓存；默认自动选择已覆盖多数场景，见下文）
-cpac claude-models                     # 查看当前覆盖
-cpac claude-models --haiku             # 下拉选择 haiku 槽模型
+# 5. 可选：Agent 配置向导与模型选择
+cpac codex setup                       # 进入 Codex 配置向导（Subagent 模型多选、最大上下文、Multi-Agent V2）
+cpac claude setup                      # 进入 Claude Code 模型向导（Sonnet、Haiku、Opus 槽位选择）
 
 # 6. 升级（装上新版本后自动 sync 已接入的 agent）
 cpac upgrade
@@ -59,7 +59,7 @@ cpac upgrade
 
 ## Agent 自动化安装指南
 
-本节面向 AI agent：按顺序执行即可完成安装与配置，**全程无交互**。注意：`--v2_models` 复选框和 `claude-models` 不带值的下拉选择是 TTY-only，agent 必须走下方直接写配置 JSON 的路径。
+本节面向 AI agent：按顺序执行即可完成安装与配置，**全程无交互**。注意：`cpac codex --config` 和 `cpac claude --config` 的交互向导是 TTY-only，agent 必须走下方直接写配置 JSON 的路径。
 
 1. **检查前置**：`node --version` ≥ 20；确认用户需要哪些 agent（`codex`/`claude`/`pi`/`kimi`/`opencode` 在 PATH 上）。向用户索取 CPA API key。
 
@@ -72,7 +72,7 @@ source ~/.zshrc
 cpac status   # 验证：CPA_API_KEY 应显示 configured
 ```
 
-3. **写入模型配置**（创建或合并 `~/.config/cpac/config.json`，已有键保留）：
+1. **写入模型配置**（创建或合并 `~/.config/cpac/config.json`，已有键保留）：
 
 ```json
 {
@@ -80,20 +80,23 @@ cpac status   # 验证：CPA_API_KEY 应显示 configured
 }
 ```
 
-   Claude 槽位（opus/sonnet/haiku）通常不用配：cpac 启动时自动选择——同家族 claude 模型优先，否则 gemini → grok → luna → 目录第一个；opus 无匹配则不设。这个链条在常见目录上正好给出理想结果：sonnet 落在 claude-sonnet-*（它同时充当 Auto mode 分类器的替身，避免分类请求失败后回退到昂贵的会话主模型），haiku 落在快的 gemini flash。只有目录奇怪时才用 `cpac claude-models --opus/--sonnet/--haiku <模型>` 显式覆盖。codex spawn subagent 取三个 GPT + gemini + grok 五席（顺序即优先级，Codex 只广告 catalog 前 5）。候选替换：`mimo-v2.5`（haiku）、`grok-4.5`（haiku）。若上述 slug 不在目录中（`curl -s -H "Authorization: Bearer $CPA_API_KEY" "$CPA_BASE_URL/v1/models"` 可查），按家族就近替换。分类器机制细节见 [docs/claude-auto-mode-classifier.md](docs/claude-auto-mode-classifier.md)。
+   Claude 槽位（opus/sonnet/haiku）通常不用配：cpac 启动时自动选择——同家族 claude 模型优先，否则 gemini → grok → luna → 目录第一个；opus 无匹配则不设。这个链条在常见目录上正好给出理想结果：sonnet 落在 claude-sonnet-*（它同时充当 Auto mode 分类器的替身，避免分类请求失败后回退到昂贵的会话主模型），haiku 落在快的 gemini flash。只有目录奇怪时才用 `cpac claude setup` 交互式配置。codex spawn subagent 取三个 GPT + gemini + grok 五席（顺序即优先级，Codex 只广告 catalog 前 5），可通过 `cpac codex setup` 交互式配置。候选替换：`mimo-v2.5`（haiku）、`grok-4.5`（haiku）。若上述 slug 不在目录中（`curl -s -H "Authorization: Bearer $CPA_API_KEY" "$CPA_BASE_URL/v1/models"` 可查），按家族就近替换。分类器机制细节见 [docs/claude-auto-mode-classifier.md](docs/claude-auto-mode-classifier.md)。
 
-4. **持久注入**（只对检测到的目标；codex 会应用步骤 3 的 spawn_models）：
+1. **持久注入**（只对检测到的目标；codex 会应用步骤 3 的 spawn_models）：
 
 ```bash
 cpac install --all
 cpac status   # 验证：各 target 显示 ready/injected
 ```
 
-5. **临时接管类 agent 无需安装**，直接告知用户用 `cpac claude` / `cpac opencode` 启动（步骤 3 的 claude_models 自动生效）。
+1. **统一启动与配置**：
+   - 启动：`cpac <codex|claude|kimi|grok|pi|opencode> [args...]`（所有原生参数如 `-c` 等原样透明传递）
+   - 配置：`cpac <codex|claude> setup`（交互式配置模型与特性）
+   - 还原：`cpac <agent> clear`（还原或重置配置）
 
-6. **已安装后升级**：npm 发布新版本后，等 publish 成功再执行 `cpac upgrade`。它会按需 `npm install -g`，再对已接入的 Codex / Pi / Kimi 做 `sync`。不要拆成 `npm install -g @yhong91/cpac` 再手动 `cpac sync`。只刷新配置、不升 CLI 时才用 `cpac sync`。
+2. **已安装后升级**：npm 发布新版本后，等 publish 成功再执行 `cpac upgrade`。它会按需 `npm install -g`，再对已接入的 Codex / Pi / Kimi / Grok 做 `sync`。不要拆成 `npm install -g @yhong91/cpac` 再手动 `cpac sync`。只刷新配置、不升 CLI 时才用 `cpac sync`。
 
-失败处理：任何一步报错时先跑 `cpac status`；密钥未配置回到步骤 2；注入后异常用 `cpac uninstall --target <id>` 恢复原配置。
+失败处理：任何一步报错时先跑 `cpac status`；密钥未配置回到步骤 2；注入后异常用 `cpac <agent> clear` 或 `cpac restore --target <id>` 恢复原配置。
 
 ## 首次引导
 
@@ -179,34 +182,20 @@ cpac version
 
 ### Claude Code
 
-通过 CPA 启动 Claude Code，后续参数原样传递：
+通过 CPA 启动 Claude Code，后续所有原生参数原样传递（如 `-c` 继续会话、`--model` 等）：
 
 ```bash
 cpac claude
+cpac claude -c                         # 继续上一次对话（原生 -c 原样直通）
 cpac claude --model claude-sonnet-4-5
 cpac claude -- -p "检查当前项目"
 ```
 
-`cpac claude` 会在本地起一个临时 loopback 代理，并为 Claude Code 子进程设置：
+#### 配置与清除
 
-```text
-ANTHROPIC_BASE_URL=http://127.0.0.1:<临时端口>
-ANTHROPIC_AUTH_TOKEN=<CPA_API_KEY>
-CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
-CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1
-```
-
-同时清除可能覆盖网关选择的 `ANTHROPIC_API_KEY` 和 Claude Code 云 provider 环境变量。它不会修改 `~/.claude/`，并原样返回 Claude Code 的退出码。
-
-代理开启 Claude Code 的 gateway model discovery：`/model` 选择器会列出 CPA 目录里的全部模型。claude 系模型直接使用原 id；其它模型以 `claude-cpac--<模型名>` 别名出现（例如 `claude-cpac--gpt-5.6-sol`），请求发出时由代理还原为真实模型名。
-
-启动时还会把模型槽位（`ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU_MODEL` 及 `ANTHROPIC_SMALL_FAST_MODEL`）指向目录里的模型，避免 haiku/subagent 任务打到网关不认识的默认 id。默认自动选择（claude 系优先：按家族名匹配 opus/sonnet/haiku，否则最大窗口给 opus/sonnet、最小窗口给 haiku），可用命令覆盖：
-
-```sh
-cpac claude-models                                            # 查看当前覆盖
-cpac claude-models --opus claude-opus-4-8 --haiku glm-5.3     # 设置/合并
-cpac claude-models --haiku                                    # 不带值：arrow-key 下拉选择
-cpac claude-models --reset                                    # 恢复自动选择
+```bash
+cpac claude setup                      # 交互式依次配置 Sonnet / Haiku / Opus
+cpac claude clear                      # 重置所有覆盖，恢复自动选择
 ```
 
 未设置的槽位启动时自动选择：claude 池内同家族模型优先，否则按 gemini → grok → luna → 目录第一个回退；opus 无匹配则不设。
@@ -223,33 +212,25 @@ Claude Code 的发现协议不携带 context 信息，claude 前缀的未知模
 
 ### Codex
 
-注入 CPA 模型目录：
+启动 Codex，后续所有原生参数原样传递（如 `-c` 动态覆盖配置、`exec` 等）：
 
 ```bash
-cpac inject [--v2_off] [--v2_models] [--max_context] [--config PATH]
+cpac codex                             # 自动确保注入和代理后拉起 Codex
+cpac codex -c model="gpt-5"            # 动态覆盖 Codex 配置（原生 -c 原样直通）
+cpac codex exec "帮我写一个测试"
 ```
 
-查看状态：
+#### 配置与清除
 
 ```bash
-cpac status
+cpac codex setup                       # 交互式配置 Subagent 候选模型、最大上下文和 Multi-Agent V2
+cpac codex clear                       # 还原 Codex 原生配置并关闭代理
 ```
 
-`status` 列出所有支持的 agent 及当前状态：
-
-```text
-codex: injected proxy=http://127.0.0.1:10101/v1 sha256=...
-claude: ready
-pi: ready
-```
-
-- **codex**：`native`（未注入）、`injected`（已注入，附代理地址和配置摘要）、`injected (loopback proxy stopped)` 或 `injected (config missing)`
-- **claude**：`ready`（密钥已配置）或 `not configured`
-- **pi**：`ready`（密钥已配置）或 `not configured`
-
-恢复注入前的原配置：
+#### 传统注入命令
 
 ```bash
+cpac inject [--v2_off] [--v2_models] [--max_context] [--config PATH]
 cpac restore
 ```
 

package/dist/cpac.js

@@ -262,7 +262,13 @@ export async function fetchCatalog(cpaUrl, apiKey) {
 // set auto_compact_token_limit at 90% (Codex's own convention), keeping
 // compaction ahead of the hard ceiling.
 export function liftContextWindows(bytes) {
-    const document = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new CPACError("invalid CPA catalog");
+    }
     for (const model of document.models) {
         const maxWindow = typeof model.max_context_window === "number" && model.max_context_window > 0
             ? Math.floor(model.max_context_window)
@@ -280,7 +286,13 @@ export function liftContextWindows(bytes) {
 // Move `order` slugs to the front of the rich catalog (stable for the rest),
 // so the Codex client's first-5 spawn_agent advertisement picks them.
 export function reorderCatalog(bytes, order) {
-    const document = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new CPACError("invalid CPA catalog");
+    }
     const rank = new Map(order.map((slug, index) => [slug, index]));
     const models = document.models.map((model, index) => ({ model, index }));
     models.sort((left, right) => {
@@ -300,7 +312,13 @@ export function reorderCatalog(bytes, order) {
 export function saveSpawnModels(configPath, models) {
     let document = {};
     if (existsSync(configPath)) {
-        const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(configPath, "utf8"));
+        }
+        catch {
+            throw new CPACError("config must be a valid JSON object");
+        }
         if (!objectValue(parsed))
             throw new CPACError("config must be a JSON object");
         document = parsed;
@@ -356,6 +374,9 @@ async function checkboxPicker(title, items, max) {
                 return;
             }
             if (key === "\r" || key === "\n") {
+                if (max === 1 && selected.size === 0) {
+                    selected.add(cursor);
+                }
                 finish();
                 return;
             }
@@ -388,7 +409,13 @@ export async function pickSpawnModels(config) {
     if (!apiKey)
         throw new CPACError(`environment variable ${config.api_key_env} is not set`);
     const catalog = await fetchCatalog(config.cpa_url, apiKey);
-    const document = JSON.parse(new TextDecoder().decode(catalog.bytes));
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder().decode(catalog.bytes));
+    }
+    catch {
+        throw new CPACError("invalid CPA catalog");
+    }
     const slugs = document.models.map((model) => model.slug);
     const picked = await checkboxPicker("Select spawn_agent models", slugs, MAX_SPAWN_MODELS);
     if (picked.length === 0)
@@ -699,13 +726,18 @@ function responseHeaders(headers) {
     return forwarded;
 }
 function upstreamUrl(cpaUrl, requestUrl) {
-    const incoming = new URL(requestUrl, "http://127.0.0.1");
-    const suffix = incoming.pathname === "/v1"
-        ? ""
-        : incoming.pathname.startsWith("/v1/")
-            ? incoming.pathname.slice(3)
-            : incoming.pathname;
-    return new URL(`${apiBase(cpaUrl)}${suffix}${incoming.search}`);
+    try {
+        const incoming = new URL(requestUrl, "http://127.0.0.1");
+        const suffix = incoming.pathname === "/v1"
+            ? ""
+            : incoming.pathname.startsWith("/v1/")
+                ? incoming.pathname.slice(3)
+                : incoming.pathname;
+        return new URL(`${apiBase(cpaUrl)}${suffix}${incoming.search}`);
+    }
+    catch {
+        throw new CPACError(`invalid upstream request URL: ${requestUrl}`);
+    }
 }
 export async function createLoopbackProxy(cpaUrl, apiKey, proxyId, port) {
     const server = createServer((request, response) => {
@@ -1088,7 +1120,7 @@ async function startProxyProcess(config, apiKey) {
         });
     });
 }
-async function stopProxyProcess(proxy) {
+export async function stopProxyProcess(proxy) {
     if (!(await proxyIsHealthy(proxy)))
         return;
     try {
@@ -1102,7 +1134,7 @@ async function stopProxyProcess(proxy) {
         // The server may close the connection while shutting down.
     }
 }
-function readState(stateDir) {
+export function readState(stateDir) {
     const path = join(stateDir, "state.json");
     if (!existsSync(path))
         return null;
@@ -1148,7 +1180,7 @@ function readState(stateDir) {
     }
     return value;
 }
-function stateProxy(state) {
+export function stateProxy(state) {
     return state.proxy_id && state.proxy_pid && state.proxy_port
         ? { id: state.proxy_id, pid: state.proxy_pid, port: state.proxy_port }
         : null;
@@ -1460,7 +1492,7 @@ export function saveApiKeyExport(profile, name, apiKey) {
     atomicWrite(profile, Buffer.from(content), mode);
 }
 async function guide(config) {
-    console.log(`CPA Companion\n\nCPA: ${config.cpa_url}\nCPA_API_KEY: ${process.env[config.api_key_env]?.trim() ? "configured" : "not configured"}\n\nCommands:\n  cpac claude [args...]  Launch Claude Code through CPA\n  cpac inject            Inject CPA into Codex and start its loopback proxy\n  cpac proxy             Run the injected loopback proxy in the foreground\n  cpac status            Show agent support status (Codex, Claude, Pi, Kimi)\n  cpac restore           Restore the original Codex config\n  cpac pi install        Install CPA provider extension for Pi\n  cpac pi uninstall      Remove the Pi CPA provider extension\n  cpac pi status         Show Pi extension install status\n  cpac kimi install      Write CPA provider config for Kimi Code\n  cpac kimi uninstall    Remove the Kimi Code CPA provider config\n  cpac kimi status       Show Kimi Code config install status\n  cpac detect            Show supported targets and install status\n  cpac install           Install CPA integration into detected targets\n  cpac sync              Refresh installed Codex/Pi/Kimi injections from the current CPA\n  cpac uninstall         Remove CPA integration from installed targets\n  cpac upgrade           Update cpac from npm and sync installed agents\n  cpac --help            Show command usage`);
+    console.log(`CPA Companion\n\nCPA: ${config.cpa_url}\nCPA_API_KEY: ${process.env[config.api_key_env]?.trim() ? "configured" : "not configured"}\n\nCommands:\n  cpac <agent> [args...] Launch an agent (codex, kimi, grok, pi, claude, opencode) through CPA\n  cpac inject            Inject CPA into Codex and start its loopback proxy\n  cpac proxy             Run the injected loopback proxy in the foreground\n  cpac status            Show agent support status (Codex, Claude, Pi, Kimi, Grok)\n  cpac restore           Restore the original Codex config\n  cpac detect            Show supported targets and install status\n  cpac install           Install CPA integration into detected targets\n  cpac sync              Refresh installed Codex/Pi/Kimi/Grok injections from CPA\n  cpac uninstall         Remove CPA integration from installed targets\n  cpac upgrade           Update cpac from npm and sync installed agents\n  cpac --help            Show command usage`);
     if (process.env[config.api_key_env]?.trim())
         return 0;
     const apiKey = await promptSecret(config.api_key_env);
@@ -1481,7 +1513,13 @@ export async function runOpencode(config, args, executable = "opencode") {
     if (!apiKey)
         throw new CPACError(`environment variable ${config.api_key_env} is not set`);
     const catalog = await fetchCatalog(config.cpa_url, apiKey);
-    const document = JSON.parse(new TextDecoder().decode(catalog.bytes));
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder().decode(catalog.bytes));
+    }
+    catch {
+        throw new CPACError("invalid CPA catalog");
+    }
     const models = {};
     for (const row of document.models) {
         const id = catalogModelId(row);
@@ -1523,24 +1561,119 @@ export async function runOpencode(config, args, executable = "opencode") {
         child.once("close", (code) => resolve(code ?? 1));
     });
 }
-export async function runClaudeModels(parsed) {
-    if (parsed.pick.length) {
-        const config = loadConfig(parsed.configPath, true);
-        const apiKey = process.env[config.api_key_env]?.trim();
-        if (!apiKey)
-            throw new CPACError(`environment variable ${config.api_key_env} is not set`);
+export async function runCodexConfig(config, configPath, options = {}) {
+    if (options.reset) {
+        let raw = {};
+        try {
+            const file = JSON.parse(readFileSync(configPath, "utf8"));
+            if (!objectValue(file))
+                throw new CPACError("config must be a JSON object");
+            raw = file;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                if (error instanceof CPACError)
+                    throw error;
+                throw new CPACError(`cannot read config: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        delete raw.spawn_models;
+        atomicWrite(configPath, Buffer.from(`${JSON.stringify(raw, null, 2)}\n`));
+        await runRestore(config, ["codex"], { all: false, dryRun: false });
+        console.log("Codex configuration reset to default");
+        return 0;
+    }
+    if (options.interactive && (!process.stdin.isTTY || !process.stderr.isTTY)) {
+        console.log(config.spawn_models
+            ? JSON.stringify(config.spawn_models, null, 2)
+            : "spawn_models not set");
+        return 0;
+    }
+    let spawnModels = config.spawn_models;
+    let v2Off = options.v2Off ?? false;
+    let maxContext = options.maxContext ?? false;
+    if (options.interactive || options.v2Models) {
+        const picked = await pickSpawnModels(config);
+        if (picked.length > 0) {
+            spawnModels = picked;
+            saveSpawnModels(configPath, picked);
+            console.log(`spawn_models saved to ${configPath}: ${picked.join(", ")}`);
+        }
+        if (options.interactive) {
+            const [maxCtxChoice] = await checkboxPicker("Codex Context Window Size:", [
+                "Standard (default input budget, e.g. 200K~272K)",
+                "Max Context Window (lift to full upper bound, e.g. 921K~1M, 90% auto-compact limit)",
+            ], 1);
+            maxContext = maxCtxChoice?.startsWith("Max Context") ?? false;
+            const [v2Choice] = await checkboxPicker("Codex Multi-Agent V2 mode:", ["Enabled (Default)", "Disabled (--v2_off)"], 1);
+            v2Off = v2Choice === "Disabled (--v2_off)";
+        }
+    }
+    const updatedConfig = { ...config, spawn_models: spawnModels };
+    await runInstall(updatedConfig, ["codex"], {
+        all: false,
+        dryRun: false,
+        force: true,
+        v2Off,
+        maxContext,
+    });
+    console.log("Codex configuration updated and synced.");
+    return 0;
+}
+export async function runClaudeConfig(config, configPath, options = {}) {
+    if (options.reset) {
+        let raw = {};
+        try {
+            const file = JSON.parse(readFileSync(configPath, "utf8"));
+            if (!objectValue(file))
+                throw new CPACError("config must be a JSON object");
+            raw = file;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                if (error instanceof CPACError)
+                    throw error;
+                throw new CPACError(`cannot read config: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        delete raw.claude_models;
+        atomicWrite(configPath, Buffer.from(`${JSON.stringify(raw, null, 2)}\n`));
+        console.log("Claude Code tier models reset to CPA catalog auto-selection");
+        return 0;
+    }
+    if (options.interactive && (!process.stdin.isTTY || !process.stderr.isTTY)) {
+        console.log(config.claude_models
+            ? JSON.stringify(config.claude_models, null, 2)
+            : "claude_models not set; cpac claude auto-picks tier models from the CPA catalog");
+        return 0;
+    }
+    const models = { ...(options.models || {}) };
+    const shouldPick = options.interactive || (options.pick && options.pick.length > 0);
+    if (shouldPick) {
+        const apiKey = await resolveApiKey(config.api_key_env);
         const catalog = await fetchCatalog(config.cpa_url, apiKey);
-        const document = JSON.parse(new TextDecoder().decode(catalog.bytes));
-        const slugs = document.models.map((model) => model.slug);
-        for (const slot of parsed.pick) {
-            const [picked] = await checkboxPicker(`Select ${slot} model`, slugs, 1);
-            if (!picked)
-                throw new CPACError("no model selected");
-            parsed.models[slot] = picked;
+        let document;
+        try {
+            document = JSON.parse(new TextDecoder().decode(catalog.bytes));
+        }
+        catch {
+            throw new CPACError("CPA catalog response is not valid JSON");
+        }
+        const slugs = (document.models ?? [])
+            .map((model) => (typeof model?.slug === "string" ? model.slug : ""))
+            .filter(Boolean);
+        const slotsToPick = options.pick && options.pick.length > 0
+            ? options.pick
+            : ["sonnet", "haiku", "opus"];
+        for (const slot of slotsToPick) {
+            const choices = slot === "sonnet" ? slugs : ["(auto-select from catalog)", ...slugs];
+            const [picked] = await checkboxPicker(`Select Claude Code ${slot.toUpperCase()} tier model:`, choices, 1);
+            if (picked && picked !== "(auto-select from catalog)") {
+                models[slot] = picked;
+            }
         }
     }
-    if (!parsed.reset && !Object.keys(parsed.models).length) {
-        const config = loadConfig(parsed.configPath, true);
+    if (!Object.keys(models).length && !shouldPick) {
         console.log(config.claude_models
             ? JSON.stringify(config.claude_models, null, 2)
             : "claude_models not set; cpac claude auto-picks tier models from the CPA catalog");
@@ -1548,7 +1681,7 @@ export async function runClaudeModels(parsed) {
     }
     let raw = {};
     try {
-        const file = JSON.parse(readFileSync(parsed.configPath, "utf8"));
+        const file = JSON.parse(readFileSync(configPath, "utf8"));
         if (!objectValue(file))
             throw new CPACError("config must be a JSON object");
         raw = file;
@@ -1560,23 +1693,25 @@ export async function runClaudeModels(parsed) {
             throw new CPACError(`cannot read config: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    if (parsed.reset) {
-        delete raw.claude_models;
-    }
-    else {
-        const existing = objectValue(raw.claude_models)
-            ? { ...raw.claude_models }
-            : {};
-        Object.assign(existing, parsed.models);
-        raw.claude_models = existing;
-    }
-    atomicWrite(parsed.configPath, Buffer.from(`${JSON.stringify(raw, null, 2)}\n`));
-    loadConfig(parsed.configPath);
-    console.log(parsed.reset
-        ? "claude_models cleared"
-        : `claude_models updated: ${JSON.stringify(raw.claude_models)}`);
+    const existing = objectValue(raw.claude_models)
+        ? { ...raw.claude_models }
+        : {};
+    Object.assign(existing, models);
+    raw.claude_models = existing;
+    atomicWrite(configPath, Buffer.from(`${JSON.stringify(raw, null, 2)}\n`));
+    loadConfig(configPath);
+    console.log(`Claude Code tier models updated in ${configPath}:\n${JSON.stringify(raw.claude_models, null, 2)}`);
     return 0;
 }
+export async function runClaudeModels(parsed) {
+    const config = loadConfig(parsed.configPath, true);
+    return await runClaudeConfig(config, parsed.configPath, {
+        models: parsed.models,
+        pick: parsed.pick,
+        reset: parsed.reset,
+        interactive: false,
+    });
+}
 export async function runClaude(config, args, executable = "claude") {
     const apiKey = await resolveApiKey(config.api_key_env);
     const proxy = await createClaudeProxy(config.cpa_url, apiKey);
@@ -1653,6 +1788,53 @@ export async function runClaude(config, args, executable = "claude") {
         });
     });
 }
+export async function runTargetLauncher(config, targetId, args, executable = targetId, options = {}) {
+    const target = TARGETS.find((t) => t.id === targetId);
+    if (!target)
+        throw new CPACError(`unknown target: ${targetId}`);
+    if (["kimi", "grok"].includes(targetId)) {
+        const state = readState(config.state_dir);
+        const proxy = state ? stateProxy(state) : null;
+        if (!proxy || !(await proxyIsHealthy(proxy))) {
+            const apiKey = await resolveApiKey(config.api_key_env);
+            const started = await startProxyProcess(config, apiKey);
+            const fingerprint = proxyFingerprint(config, apiKey);
+            const catalog = await fetchCatalog(config.cpa_url, apiKey);
+            const catalogPath = join(config.state_dir, "codex-models.json");
+            mkdirSync(config.state_dir, { recursive: true, mode: 0o700 });
+            atomicWrite(catalogPath, catalog.bytes);
+            const originalMode = existsSync(config.codex_config)
+                ? statSync(config.codex_config).mode & 0o7777
+                : 0o600;
+            atomicWrite(join(config.state_dir, "state.json"), stateBytes(config, state ? state.config_existed : false, state ? state.config_mode : originalMode, started, fingerprint));
+        }
+    }
+    if (target.installed(config)) {
+        try {
+            await runSync(config, [targetId], {
+                all: false,
+                dryRun: false,
+                v2Off: options.v2Off,
+                maxContext: options.maxContext,
+            });
+        }
+        catch (error) {
+            console.warn(`warning: auto-sync failed (${error instanceof Error ? error.message : String(error)}); launching with existing config`);
+        }
+    }
+    else {
+        await target.install(config, false, options.v2Off, options.maxContext);
+    }
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(executable, args, { stdio: "inherit" });
+        child.once("error", (error) => {
+            rejectPromise(new CPACError(error instanceof Error && "code" in error && error.code === "ENOENT"
+                ? `${executable} not found`
+                : `cannot start ${executable}: ${error.message}`));
+        });
+        child.once("close", (code) => resolvePromise(code ?? 1));
+    });
+}
 export async function runProxy(config) {
     const apiKey = await resolveApiKey(config.api_key_env);
     const state = readState(config.state_dir);
@@ -1819,7 +2001,13 @@ function kimiInputHasImage(row) {
 export async function installKimiConfig(config) {
     const apiKey = await resolveApiKey(config.api_key_env);
     const catalog = await fetchCatalog(config.cpa_url, apiKey);
-    const document = JSON.parse(new TextDecoder("utf-8").decode(catalog.bytes));
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder("utf-8").decode(catalog.bytes));
+    }
+    catch {
+        throw new CPACError("invalid CPA catalog");
+    }
     const rows = catalogModelRows(document) ?? [];
     if (rows.length === 0)
         throw new CPACError("CPA catalog contains no models");
@@ -1941,7 +2129,13 @@ function writeGrokBlock(path, block) {
 export async function installGrokConfig(config) {
     const apiKey = await resolveApiKey(config.api_key_env);
     const catalog = await fetchCatalog(config.cpa_url, apiKey);
-    const document = JSON.parse(new TextDecoder("utf-8").decode(catalog.bytes));
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder("utf-8").decode(catalog.bytes));
+    }
+    catch {
+        throw new CPACError("invalid CPA catalog");
+    }
     const rows = catalogModelRows(document) ?? [];
     if (rows.length === 0)
         throw new CPACError("CPA catalog contains no models");
@@ -2207,6 +2401,17 @@ export async function runUninstall(config, requested, options) {
     }
     return 0;
 }
+export async function runRestore(config, requested, options) {
+    if (requested.length > 0 || options.all) {
+        return runUninstall(config, requested, options);
+    }
+    if (options.dryRun) {
+        console.log("would restore the original Codex config");
+        return 0;
+    }
+    await restore(config);
+    return 0;
+}
 function compareVersions(a, b) {
     const left = a.split(".").map(Number);
     const right = b.split(".").map(Number);
@@ -2270,21 +2475,21 @@ export async function runUpgrade(config, checkOnly) {
 function usage() {
     return [
         "Usage: cpac",
+        "       cpac <codex|kimi|grok|pi|claude|opencode> [args...]",
+        "       cpac <codex|claude> setup",
+        "       cpac <codex|claude|kimi|grok|pi> clear",
         "       cpac inject [--v2_off] [--v2_models] [--max_context] [--config PATH]",
-        "       cpac <status|restore> [--config PATH]",
+        "       cpac restore [--target codex,pi,kimi,grok] [--all] [--dry-run] [--config PATH]",
+        "       cpac status [--config PATH]",
         "       cpac proxy [--config PATH]",
-        "       cpac claude [--config PATH] [--] [claude args...]",
-        "       cpac opencode [--config PATH] [--] [opencode args...]",
-        "       cpac claude-models [--opus [M]] [--sonnet [M]] [--haiku [M]] [--reset] [--config PATH]",
         "       cpac detect [--json] [--home PATH]",
         "       cpac install [--target codex,pi,kimi,grok] [--all] [--dry-run] [--force] [--v2_off] [--v2_models] [--max_context] [--home PATH]",
         "       cpac sync [--target codex,pi,kimi,grok] [--all] [--dry-run] [--v2_off] [--v2_models] [--max_context] [--home PATH]",
-        "       cpac uninstall [--target codex,pi,kimi,grok] [--all] [--dry-run] [--home PATH]",
         "       cpac upgrade [--check]",
         "       cpac version",
         "",
-        "install/uninstall manage persistent injections only; claude and opencode are",
-        "ephemeral — launch them with `cpac claude` / `cpac opencode` instead.",
+        "launch an agent directly with `cpac <agent> [args...]` (all args forwarded).",
+        "configure an agent with `cpac <agent> setup` or restore with `cpac <agent> clear`.",
     ].join("\n");
 }
 function parseArgs(args) {
@@ -2295,6 +2500,7 @@ function parseArgs(args) {
         args[0] === "install" ||
         args[0] === "sync" ||
         args[0] === "uninstall" ||
+        args[0] === "restore" ||
         args[0] === "upgrade" ||
         args[0] === "version") {
         const parsed = {
@@ -2358,10 +2564,100 @@ function parseArgs(args) {
         }
         return parsed;
     }
+    if (["codex", "kimi", "grok", "pi", "claude", "opencode"].includes(args[0])) {
+        const targetId = args[0];
+        let configPath = defaultConfigPath();
+        if (args[1] === "clear" || args[1] === "--clear") {
+            for (let i = 2; i < args.length; i++) {
+                if (args[i] === "--config") {
+                    const val = args[++i];
+                    if (val)
+                        configPath = resolve(expandUserPath(val));
+                }
+            }
+            if (targetId === "claude") {
+                return {
+                    command: "claude-config",
+                    configPath,
+                    models: {},
+                    pick: [],
+                    reset: true,
+                    interactive: false,
+                };
+            }
+            return {
+                command: "restore",
+                configPath,
+                json: false,
+                targets: [targetId],
+                all: false,
+                dryRun: false,
+                force: false,
+                check: false,
+                v2Off: false,
+                v2Models: false,
+                maxContext: false,
+            };
+        }
+        if (args[1] === "setup" || args[1] === "--setup") {
+            for (let i = 2; i < args.length; i++) {
+                if (args[i] === "--config") {
+                    const val = args[++i];
+                    if (val)
+                        configPath = resolve(expandUserPath(val));
+                }
+            }
+            if (targetId === "codex") {
+                return {
+                    command: "codex-config",
+                    configPath,
+                    v2Off: false,
+                    v2Models: false,
+                    maxContext: false,
+                    reset: false,
+                    interactive: true,
+                };
+            }
+            if (targetId === "claude") {
+                return {
+                    command: "claude-config",
+                    configPath,
+                    models: {},
+                    pick: [],
+                    reset: false,
+                    interactive: true,
+                };
+            }
+            throw new CPACError(`${targetId} does not require setup (all CPA models are auto-synced). Run 'cpac ${targetId}' or 'cpac install --target ${targetId}'.`);
+        }
+        const passArgs = args.slice(1);
+        if (targetId === "codex") {
+            return {
+                command: "codex",
+                configPath,
+                args: passArgs,
+                v2Off: false,
+                v2Models: false,
+                maxContext: false,
+            };
+        }
+        if (targetId === "claude") {
+            return {
+                command: "claude",
+                configPath,
+                args: passArgs,
+            };
+        }
+        return {
+            command: targetId,
+            configPath,
+            args: passArgs,
+        };
+    }
     if (args[0] === "claude-models") {
         if (args.includes("-h") || args.includes("--help")) {
             console.log([
-                "Usage: cpac claude-models [--opus [M]] [--sonnet [M]] [--haiku [M]] [--reset] [--config PATH]",
+                "Usage: cpac claude --config [--opus [M]] [--sonnet [M]] [--haiku [M]] [--reset] [--config PATH]",
                 "",
                 "Sets the model Claude Code uses per task tier. Saved to the config file",
                 "and applied on every `cpac claude` launch:",
@@ -2410,35 +2706,14 @@ function parseArgs(args) {
                 throw new CPACError(`unknown option: ${arg}`);
             }
         }
-        return { command: "claude-models", configPath, models, pick, reset };
-    }
-    if (args[0] === "claude") {
-        let configPath = defaultConfigPath();
-        let index = 1;
-        if (args[index] === "--config") {
-            const value = args[++index];
-            if (!value)
-                throw new CPACError("--config requires a path");
-            configPath = resolve(expandUserPath(value));
-            index += 1;
-        }
-        if (args[index] === "--")
-            index += 1;
-        return { command: "claude", configPath, args: args.slice(index) };
-    }
-    if (args[0] === "opencode") {
-        let configPath = defaultConfigPath();
-        let index = 1;
-        if (args[index] === "--config") {
-            const value = args[++index];
-            if (!value)
-                throw new CPACError("--config requires a path");
-            configPath = resolve(expandUserPath(value));
-            index += 1;
-        }
-        if (args[index] === "--")
-            index += 1;
-        return { command: "opencode", configPath, args: args.slice(index) };
+        return {
+            command: "claude-config",
+            configPath,
+            models,
+            pick,
+            reset,
+            interactive: !reset && Object.keys(models).length === 0 && pick.length === 0,
+        };
     }
     if (args.includes("-h") || args.includes("--help")) {
         console.log(usage());
@@ -2473,7 +2748,7 @@ function parseArgs(args) {
             positional.push(args[index]);
     }
     if (positional.length !== 1 ||
-        !["inject", "status", "restore", "proxy"].includes(positional[0])) {
+        !["inject", "status", "proxy"].includes(positional[0])) {
         throw new CPACError(usage());
     }
     if (positional[0] !== "inject" && (v2Off || v2Models || maxContext)) {
@@ -2536,8 +2811,8 @@ export async function main(args = process.argv.slice(2)) {
                 maxContext: parsed.maxContext,
             });
         }
-        if (parsed.command === "uninstall")
-            return await runUninstall(config, parsed.targets, {
+        if (parsed.command === "uninstall" || parsed.command === "restore")
+            return await runRestore(config, parsed.targets, {
                 all: parsed.all,
                 dryRun: parsed.dryRun,
             });
@@ -2549,8 +2824,38 @@ export async function main(args = process.argv.slice(2)) {
         }
         if (parsed.command === "claude")
             return await runClaude(config, parsed.args);
+        if (parsed.command === "claude-config")
+            return await runClaudeConfig(config, parsed.configPath, {
+                models: parsed.models,
+                pick: parsed.pick,
+                reset: parsed.reset,
+                interactive: parsed.interactive,
+            });
+        if (parsed.command === "codex-config")
+            return await runCodexConfig(config, parsed.configPath, {
+                v2Off: parsed.v2Off,
+                v2Models: parsed.v2Models,
+                maxContext: parsed.maxContext,
+                reset: parsed.reset,
+                interactive: parsed.interactive,
+            });
         if (parsed.command === "opencode")
             return await runOpencode(config, parsed.args);
+        if (parsed.command === "codex") {
+            let launcherConfig = config;
+            if (parsed.v2Models) {
+                const picked = await pickSpawnModels(config);
+                saveSpawnModels(parsed.configPath, picked);
+                console.log(`spawn_models saved to ${parsed.configPath}: ${picked.join(", ")}`);
+                launcherConfig = { ...config, spawn_models: picked };
+            }
+            return await runTargetLauncher(launcherConfig, "codex", parsed.args, "codex", { v2Off: parsed.v2Off, maxContext: parsed.maxContext });
+        }
+        if (parsed.command === "kimi" ||
+            parsed.command === "grok" ||
+            parsed.command === "pi") {
+            return await runTargetLauncher(config, parsed.command, parsed.args);
+        }
         if (parsed.command === "claude-models")
             return await runClaudeModels(parsed);
         if (parsed.command === "proxy")
@@ -2565,8 +2870,6 @@ export async function main(args = process.argv.slice(2)) {
             }
             await inject(injectConfig, parsed.v2Off, parsed.maxContext);
         }
-        else if (parsed.command === "restore")
-            await restore(config);
         else
             return await status(config);
         return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yhong91/cpac",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Connect Codex and Claude Code to a remote CLIProxyAPI gateway",
   "type": "module",
   "bin": {