@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/qoderStartup.js

@@ -0,0 +1,45 @@
+import { execFile } from 'node:child_process';
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { buildSessionMcpServers } from './delegationMcp.js';
+export const QODER_MANAGED_VERSION = '1.1.61';
+/** Owned by one process; the bearer is never an argument or environment variable. */
+export async function prepareQoderStartup(launch, lease, cwd, env, agentEnv) {
+    buildSessionMcpServers([], lease);
+    if (launch.args.some((arg) => arg === '--' || /^(--mcp-config|--strict-mcp-config|--settings|--setting-sources)(=|$)/.test(arg))) {
+        throw new Error('Managed Qoder startup has conflicting configuration arguments');
+    }
+    const version = await new Promise((resolve, reject) => {
+        execFile(launch.command, [...launch.args, '--version'], {
+            cwd, env: { ...process.env, ...launch.env, ...env, ...agentEnv },
+            encoding: 'utf8', timeout: 10_000, maxBuffer: 64 * 1024, windowsHide: true,
+        }, (error, stdout) => error ? reject(new Error('Managed Qoder version could not be verified')) : resolve(stdout.trim()));
+    });
+    if (version !== QODER_MANAGED_VERSION)
+        throw new Error('Managed Qoder version is not certified');
+    const dir = await mkdtemp(join(tmpdir(), 'axom-qoder-mcp-'));
+    let disposal;
+    const dispose = () => disposal ??= rm(dir, { recursive: true, force: true });
+    try {
+        await chmod(dir, 0o700);
+        const config = join(dir, 'mcp.json');
+        const authorization = Object.values(lease.headers)[0];
+        await writeFile(config, JSON.stringify({ mcpServers: {
+                'axom-delegation': { type: 'http', url: lease.url, headers: { Authorization: authorization } },
+            } }), { mode: 0o600, flag: 'wx' });
+        // Validate again after the asynchronous version probe; an expired lease cannot start a process.
+        buildSessionMcpServers([], lease);
+        return {
+            launch: { ...launch, args: [...launch.args, '--strict-mcp-config', '--mcp-config', config,
+                    '--setting-sources', '', '--settings', '{"autoMemoryEnabled":false}',
+                    '--disallowed-tools', 'Agent', '--cwd', cwd,
+                    '--append-system-prompt', 'Use the axom-delegation MCP tools for delegation. Native Agent execution is disabled in this session.'] },
+            secrets: [authorization, authorization.slice('Bearer '.length)], dir, dispose,
+        };
+    }
+    catch (error) {
+        await dispose();
+        throw error;
+    }
+}

package/dist/workstation/acp/registry/catalog.js

@@ -1,18 +1,248 @@
+/**
+ * Axom 认证过的 agent 清单 —— 取代 `officialCli.ts`。
+ *
+ * ## 它是什么：Axom 对官方 registry 的本地扩展层
+ *
+ * 一个 agent 在本清单里，就是我们真机验证过（roster 的 `curated`），设置页把它放进展开区；其余官方
+ * 条目进折叠的 "Unverified Agents"。本清单能做的事，各有一节在下面：
+ *
+ * - **推荐**：`recommended` 是静态的，只给愿意向任何一台新机器推荐的（pi）。
+ * - **本地检测**（`detect`，见 `detect.ts`）：PATH 上的命令或固定文件位置，只看文件在不在、不起进程。
+ *   检测到 = 这台机器的用户自己在用它，于是它也进推荐位，原因写"本机在用"。
+ * - **前置依赖**（`prerequisite`）：适配器之外、它起得来所必需的本体（Pi 的 CLI、ZCode 桌面应用），
+ *   同样靠 `detect` 判断在不在；有 `install` 就由 Install 先装，没有就只告诉用户怎么办。
+ * - **补充、取代与钉版本**：`supplement` / `supersedes` / `distribution`，以及 `launchEnv`。
+ *
+ * ## 托管与检测是两件事
+ *
+ * Axom 启动的**一律是 Axom 托管的那份**——`<config dir>/acp-adapters` 里我们（npm、uv、binary 各按版本）
+ * 自己装的、钉了版本的副本，与用户自己的安装隔离、独立升级。`adapterInstalled` 只回答这一份在不在。
+ * 用户 PATH 上的 `kimi`、`command-code` **不算** Axom 已安装，也从不被拿来启动：它只是 `detect` 的
+ * 推荐信号。两份共用数据目录（`~/.kimi-code`、`~/.commandcode`），所以登录是共享的。
+ *
+ * ## 它与被它取代的那张表不是一回事
+ *
+ * `officialCli.ts` 断言的是"这个 agent 的官方 CLI 在不在 PATH"，而那个信号既不决定能否启动
+ * （npx 适配器多数自带引擎），也不决定能否使用（凭据才是），于是它撑起来的 `Installed` 徽章
+ * 是一句没人能负责的话。本清单不做任何这类断言：它只提供**我们自己认证过**的三样东西 ——
+ * 用户友好的默认名字、这个 agent 除适配器之外还需要什么、以及它是否进推荐位；本地检测也只回答
+ * "用户自己装了没有"，从不替 Axom 托管的那份作答。
+ *
+ * ## 为什么不为全部 39 个 agent 建表
+ *
+ * 见 spec §2.3：适配器需不需要本机 vendor CLI 是**版本级**属性，只能靠扒依赖树猜，而且完全
+ * 没有必要 —— 试跑失败时 agent 自己那句话（`Pi needs to be installed. Install it via …`）
+ * 带着确切的安装命令，且永远与它自身版本同步。本清单只覆盖我们真机验证过的少数几个。
+ *
+ * ## `prerequisite.install` 是安全边界
+ *
+ * 它会在工作站上**直接执行**，不弹二次确认。所以它只能是本文件里的字面量参数数组，永远不接受
+ * 来自 registry、agent 响应、网络内容或用户输入的字符串；以 argv 形式交给 execFile，不经 shell。
+ * `catalog.test.ts` 有一条机械守卫盯着这件事。
+ *
+ * ## `distribution` 覆盖 registry 的安装来源
+ *
+ * 这里写下的来源**整个替换** registry 的 `version` 与 `distribution`，id 与展示名仍是 registry 的，
+ * 于是已有的配置条目、roster、安装、启动、更新都不用知道发生过替换（见 {@link withCatalogOverrides}）。
+ * 本文件的 distribution 用于长期策略；Qoder 等临时的钉版本放在
+ * axom-patch/cli/runtime.json，按 registry 版本挑选（`when_registry_version` / `until_registry_version`，
+ * 见 `patchAssets.ts`），registry 一到就自己让位。两者与上面的 `install` 是同一条安全边界：只能是
+ * 随 CLI 发布、钉死版本、由真机验证过的可信配置。
+ *
+ * ## `supplement` 与 `supersedes`：registry 缺的条目、registry 不肯撤的条目
+ *
+ * registry 的 `kimi` 跟的是 `MoonshotAI/kimi-cli`，那个仓库已归档，停在 1.52.0；继任者 Kimi Code
+ * （`MoonshotAI/kimi-code`）的条目 `kimi-code` 还在 registry#458 里等审核。Command Code 与社区的
+ * ZCode 适配器（registry#566、#650）也都还没进 registry。registry 没有「已停止维护」这样的字段
+ * （agent.schema.json 只有 `preview` 渠道），所以由本清单声明：
+ *
+ * - `supplement`：registry 里**没有**这个 id 时由我们补上的整条条目，钉死版本。registry 一收录这个 id
+ *   就用 registry 的，之后的版本由 registry 的机器人每小时跟进，补充条目不再生效。
+ * - `supersedes`：被这个条目取代的 registry id，从列表里隐藏。Kimi Code 装上后会把旧版的数据目录
+ *   迁走，旧适配器从此看不见用户的登录（2026-09-25 实测），两个并列只会让人选错。
+ *
+ * ## `launchEnv`：Axom 启动适配器时带的环境变量
+ *
+ * 经 ACP 适配器拉起的 agent 跑在无头/SDK 模式，它们的默认工具集与用户在终端里交互使用时**不同**，
+ * 而差出来的恰好是我们要的东西。2026-09-30 实测：claude-agent-acp 0.84.0 拉起的 Claude Code 没有
+ * TaskCreate/TaskUpdate/TodoWrite（ToolSearch 答 "No matching deferred tools found"），codex-acp
+ * 2.0.1 拉起的 Codex 0.159.2 没有 `update_plan`（问它自己答 "NO"）——于是这两个 agent 从不发 ACP
+ * `plan`，生产上三天 218 个外部会话一张计划卡都没有。各自打开一个开关后同一段提示词分别发出 14 次与
+ * 4 次 `plan`。
+ *
+ * 这里写下的变量并进 registry 条目的 `distribution.*.env`，所以它是**最底下的一层**：registry
+ * 自己声明的 env、工作站配置、用户按 agent 配的 `agentEnv` 都能覆盖它（见 `connectAgent`）。一个
+ * 用户自己配了 `CODEX_CONFIG` 的 Codex 因此会整份替换掉这里的值——那是显式配置，按它来；要保留计划
+ * 工具，把 `tools.update_plan.enabled` 写进自己那份里。
+ *
+ * 这些开关不是上游文档化的稳定接口，适配器升级时要复核仍然生效（上面那段实测的做法：直接用 ACP
+ * 客户端拉起适配器，问它有没有计划工具）。
+ */
+import { patchOverridesFor } from '../patchAssets.js';
+// Temporary distribution/environment overrides are bundled from axom-patch/cli/runtime.json.
 export const AXOM_AGENT_CATALOG = [
-    { registryAgent: 'claude-acp', defaultName: 'claude-agent', defaultLabel: 'Claude Agent' },
-    { registryAgent: 'codex-acp', defaultName: 'codex', defaultLabel: 'Codex' },
+    {
+        registryAgent: 'claude-acp',
+        defaultName: 'claude-agent',
+        defaultLabel: 'Claude Agent',
+        detect: { commands: ['claude'] },
+        // 钉版本的唯一理由是补丁：claude-account-limits 的配方只核验过 0.90.0（runtime.json 的
+        // package_patches）。不钉的话 registry 一发新版，Install/Update 就装上一个配方不覆盖的包，
+        // 账号配额扩展静默消失——2026-10-14 的 antigravity（registry 已到 1.4.0、native extension
+        // 只认 1.3.0）就是这个缺口的实例。钉住后 scan 的 Update 比对（installedVersion vs 本清单的
+        // version）只在落后于钉住版本时才成立，上游新版要等 nightly 核验移植配方后再 bump。
+        // 周期核验步骤见 axom-patch/cli/nightly-task.md。
+        distribution: { version: '0.90.0', npx: { package: '@agentclientprotocol/claude-agent-acp@0.90.0' } },
+        launchEnv: {
+            // Axom 拉起的 Claude Code——会话进程、配额读的 /usage、auth status 探针、terminalLogin 代跑的
+            // `--cli auth login`——一律使用独立的 OAuth 凭据槽，与用户终端 `claude login` 写进默认槽
+            // （macOS keychain `Claude Code-credentials`）的那份互不轮换。Claude 的 refresh token 单次
+            // 轮换，多进程共享一份凭据时并发刷新会互相作废、进而被 Claude Code 清除（全员登出；
+            // anthropics/claude-code#54443，2026-10 本机实测每日复现）。
+            //
+            // CLAUDE_SECURESTORAGE_CONFIG_DIR 只改槽位命名，不把存储切到目录：macOS 上 keychain 条目变为
+            // `Claude Code-credentials-<sha256(路径)前8位>`，明文回退文件在 <路径>/.credentials.json（仅当
+            // keychain 写入失败时才落）。前导 `~` 由 `registry/launch.ts` 在 launch env 边界展开为绝对路径——
+            // Claude 把这个值按字面路径使用，不展开 `~`。
+            //
+            // **共享/独立凭据的开关收敛在这一个键上**：删除它（或将来的用户开关通过 workstation 配置的
+            // 同名变量覆盖）即回到与终端 CLI 共享默认槽的旧行为，判定点只此一处。路径一旦发布永不改名——
+            // 换字符串等于强制所有人重新登录。
+            CLAUDE_SECURESTORAGE_CONFIG_DIR: '~/.axom/auth/secures/claude',
+        },
+    },
+    {
+        registryAgent: 'codex-acp',
+        defaultName: 'codex',
+        defaultLabel: 'Codex',
+        detect: { commands: ['codex'] },
+        // 与 claude-acp 同一条规则：codex-account-limits 只核验过 2.2.2，钉住直到配方随新版本移植。
+        distribution: { version: '2.2.2', npx: { package: '@agentclientprotocol/codex-acp@2.2.2' } },
+    },
+    {
+        registryAgent: 'qoder',
+        defaultName: 'qoder',
+        defaultLabel: 'Qoder',
+        detect: { commands: ['qodercli'] },
+        // The temporary registry catch-up pin lives in axom-patch/cli/runtime.json so a newer
+        // upstream release can take over without another Axom release.
+    },
     // `gemini` was here and is deliberately gone. `@google/gemini-cli --acp` now refuses `session/new`
     // outright ("This client is no longer supported for Gemini Code Assist for individuals … migrate
     // to the Antigravity suite"), so recommending it puts an agent in the popover's top tier that
     // cannot open a session for whoever takes the recommendation. It stays in the ACP registry and can
     // still be added by hand from the collapsed section; what is withdrawn is Axom's own endorsement,
     // which is the only thing this file publishes.
+    {
+        registryAgent: 'kimi-code',
+        defaultName: 'kimi-code',
+        defaultLabel: 'Kimi Code',
+        // Kimi Code 发布独立二进制（GitHub release，6 平台 tar.gz，各带 `.sha256`；归档根目录就是 `kimi`，
+        // Windows 是 `kimi.exe`），不依赖本机 Node —— npm 包 `@moonshot-ai/kimi-code` 要 Node >= 22.19，
+        // 会把 Node 版本变成又一个"装好了却起不来"的理由。`acp` 子命令是它的 ACP 服务端；凭据在
+        // `~/.kimi-code`，与用户自己装的那份共用——实测把二进制挪到别的目录照样免登录开会话。
+        // 其余字段照 registry#458 的条目写。
+        supplement: {
+            name: 'Kimi Code',
+            version: '2.1.1',
+            description: "Moonshot AI's next-gen coding agent",
+            repository: 'https://github.com/MoonshotAI/kimi-code',
+            website: 'https://moonshotai.github.io/kimi-code/',
+            authors: ['Moonshot AI'],
+            license: 'MIT',
+            icon: 'https://cdn.agentclientprotocol.com/registry/v1/latest/kimi.svg',
+            distribution: {
+                binary: kimiCodeBinary('2.1.1', {
+                    'darwin-aarch64': ['darwin-arm64', '8c3bad99571b16abd113ab5d511a98a36b852c0d5493991842a67b8c2bc4ecd0'],
+                    'darwin-x86_64': ['darwin-x64', 'f6dc0289112c24119d070f9203d44bcd53580e380819db25b58be65643b75bd4'],
+                    'linux-aarch64': ['linux-arm64', '5c68d74b139b47fb3457f3805a159cdfa942a6a98a159ab158a1baf93b024bbd'],
+                    'linux-x86_64': ['linux-x64', 'b66cc3787bc9dfa6a06761305dc8878f98e7a24f79fa4494c00714229a1486e8'],
+                    'windows-aarch64': ['win32-arm64', '72bb17fef0d165a5f61905ede7e57c552791905d605a778967d054fe702873d4'],
+                    'windows-x86_64': ['win32-x64', '87756a53a9bb0915842d884eaf43f69a06b2e404bcbb05d41c519c12d4b410cb'],
+                }),
+            },
+        },
+        supersedes: ['kimi'],
+        // 官方安装器把二进制放在 `~/.kimi-code/bin`，不一定进了 daemon 看得见的 PATH。
+        detect: {
+            commands: ['kimi'],
+            locations: everyPlatform(['~/.kimi-code/bin/kimi'], ['~/.kimi-code/bin/kimi.exe']),
+        },
+    },
+    {
+        registryAgent: 'command-code',
+        defaultName: 'command-code',
+        defaultLabel: 'Command Code',
+        // registry 没有它。1.66.0 还没有 `acp` 子命令，1.74.3 起有、真机试跑通过；2026-10-14 nightly
+        // 升到 1.82.1：`acp` 子命令仍在（四个 bin 不变），commandcode-account-limits 配方已随
+        // generate.py 移植（handler map 换了名字 u/dn→m/hn，锚点已跟）。包里有 `cmd`、`cmdc`、
+        // `commandcode`、`command-code` 四个 bin，npx 挑与包名同名的那个。没有 ACP 登录方法，只有一句
+        // 说明（终端里跑 `cmd login`）；凭据在 `~/.commandcode`，与用户自己装的那份共用。npm 上的许可证
+        // 写的是 UNLICENSED（专有）。
+        supplement: {
+            name: 'Command Code',
+            version: '1.82.1',
+            description: 'Command Code, coding agent that continuously learns your coding taste.',
+            website: 'https://commandcode.ai',
+            authors: ['Command Code'],
+            license: 'UNLICENSED',
+            icon: 'https://commandcode.ai/favicon.ico',
+            distribution: { npx: { package: 'command-code@1.82.1', args: ['acp'] } },
+        },
+        detect: { commands: ['command-code', 'commandcode'] },
+    },
+    {
+        registryAgent: 'zcode-acp',
+        defaultName: 'zcode',
+        defaultLabel: 'ZCode',
+        // 社区适配器（registry#566、#650 都还没合），驱动的是 ZCode 桌面应用自带的 `zcode app-server`,
+        // 所以 ZCode 本体是前置依赖，而且没有一条我们能替用户跑的安装命令 —— 只能告诉他去装。
+        // 凭据：legacy `~/.zcode/v2/config.json`，但 ZCode 桌面 3.14.x 起不再写它；适配器 0.68.1+（上游
+        // #320）在 config.json 缺席时改读加密凭据库 `~/.zcode/v2/credentials.json`（桌面登录时写下）取
+        // individual coding-plan 的 api-key。Linux 上本体没有固定路径，只认 PATH。
+        // 2026-10-13 真机验证（ZCode 桌面 3.14.5 + 0.69.3）：initialize → session/new → 首轮 prompt 通过，
+        // 日志 "serving the coding-plan API key (config.json or store)"。0.63/0.64 那轮不兼容（模型只剩
+        // 无授权的 builtin:bigmodel-coding-plan\GLM-5.3，首轮 CONFIGURATION_ERROR "Model creation failed"，
+        // 2026-10-06 两台机器复现）自 0.68.1 起修复。2026-10-14 nightly 升到 0.69.4：三份配方的目标文件
+        // 与 0.69.3 字节一致（配方 versions 同时覆盖两版），subagent 探针在 0.69.4 补丁副本上通过、
+        // pristine 证实上游仍未原生发出 subagent/async 变体。
+        supplement: {
+            name: 'ZCode',
+            version: '0.69.4',
+            description: 'Community bridge that drives the real ZCode app-server (GLM) over ACP.',
+            repository: 'https://github.com/william0wang/zcode-acp',
+            website: 'https://github.com/william0wang/zcode-acp',
+            authors: ['William Wang'],
+            license: 'Apache-2.0',
+            icon: 'https://raw.githubusercontent.com/william0wang/zcode-acp/main/registry/zcode-acp/icon.svg',
+            distribution: { npx: { package: 'zcode-acp-server@0.69.4' } },
+        },
+        prerequisite: {
+            label: 'ZCode',
+            detect: {
+                commands: ['zcode'],
+                locations: {
+                    'darwin-aarch64': ['/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs'],
+                    'darwin-x86_64': ['/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs'],
+                    'windows-aarch64': ['%LOCALAPPDATA%/Programs/ZCode/resources/glm/zcode.cjs'],
+                    'windows-x86_64': ['%LOCALAPPDATA%/Programs/ZCode/resources/glm/zcode.cjs'],
+                },
+            },
+            hint: 'Install the ZCode desktop app (https://zcode.z.ai) and sign in once.',
+        },
+    },
     {
         registryAgent: 'pi-acp',
         defaultName: 'pi',
         defaultLabel: 'Pi',
-        dependency: {
-            check: 'pi',
+        recommended: true,
+        // pi-steering 与 pi-subagent-subwork 两份配方只核验过 0.0.34。registry 今天也在 0.0.34，
+        // 但那是巧合而不是保护：上游一发 0.0.35，未钉版本的 Install 就会装上一个 steering/子代理
+        // 归一都不生效的包。钉住后版本只随配方移植走（nightly-task.md）。
+        distribution: { version: '0.0.34', npx: { package: 'pi-acp@0.0.34' } },
+        prerequisite: {
+            label: 'Pi',
+            detect: { commands: ['pi'] },
             // 不用 `curl -fsSL https://pi.dev/install.sh | sh`：读过那个脚本，它最终跑的就是这一条
             // （`npm install -g --ignore-scripts @earendil-works/pi-coding-agent`），装出来的是同一个
             // npm 包 —— pi 没有原生分发。脚本唯一的增值是 Node 不够新时帮你装 Node，而那一步是交互式的
@@ -22,8 +252,159 @@ export const AXOM_AGENT_CATALOG = [
             requiresNode: '>=22.19.0',
         },
     },
+    {
+        // 推荐位第二名（pi 之后的第一个）：真机验证记录见 2026-10-13 genius 站验证（scan/verify/会话/审批
+        // 全链路）。hermes 不在公开 ACP registry（41 个 agent 里没有），本条同时是 supplement —— registry
+        // 一旦收录这个 id 就整体让位。PyPI 上的 `hermes-agent`（0.19.0，requires_python <3.14）是过时的
+        // 次要通道，官方分发是 `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`（git
+        // clone + pm bootstrap，写 ~/.local/bin/{hermes,hermes-acp}），所以走 pathLaunch 而不是 uvx：
+        // 启动用户自己装的那份，本机只有一份，与 pi 的本体同款哲学。`hermes-acp` 是官方 wheel/git 都
+        // 声明的 ACP console script；不要用 `hermes-agent`（那是 demo runner）或裸 `hermes`（CLI 主入口，
+        // acp 只是它的子命令 —— 两者都不带 ACP 语义的入口保障）。
+        registryAgent: 'hermes-acp',
+        defaultName: 'hermes',
+        defaultLabel: 'Hermes',
+        recommended: true,
+        detect: {
+            commands: ['hermes'],
+            locations: everyPlatform(['~/.local/bin/hermes-acp'], ['~/.local/bin/hermes-acp.exe']),
+        },
+        pathLaunch: { command: 'hermes-acp', hint: 'Install Hermes Agent with the official installer (curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash), then scan again.' },
+        supplement: {
+            name: 'Hermes',
+            version: '0.21.7',
+            description: "Nous Research's self-improving coding agent — native ACP server (hermes acp).",
+            repository: 'https://github.com/NousResearch/hermes-agent',
+            website: 'https://hermes-agent.nousresearch.com',
+            authors: ['Nous Research'],
+            license: 'Apache-2.0',
+            icon: 'https://hermes-agent.nousresearch.com/favicon.ico',
+            // supplement 必须给一条 distribution 才能在 registry 类型里站得住；hermes 没有任何可安装产物，
+            // 留空 distribution 由 pathLaunch 接管 available（见 acpAgents.ts 的 roster）。
+            distribution: {},
+        },
+    },
+    // registry 自己的条目（binary .par），我们只补名字与本机检测；`agy` 是 Antigravity 装好后放进 PATH 的命令。
+    // distribution 钉住：antigravity 的账号配额靠 native extension（runtime.json
+    // native_extensions，account-limits/antigravity-proxy.mjs），proxy 是 stdio sidecar，只在核验过的
+    // 版本上声明能力。2026-10-14 nightly 升到 1.4.0：真实 1.4.0 .par 经 proxy 拉起，initialize 透传无损、
+    // `axom/accountRateLimits` 能力注入成功（本地实测；配额 READ 属于用户凭据路径，留给真机冒烟）。
+    // 归档 URL 抄自 registry 的 1.4.0 条目；registry 本身不给这个条目发 sha256，这里同样不发，校验语义与
+    // registry 直装一致（binaryInstall：无 sha256 即不校验）。上游发新版时按 nightly-task.md 核验后同升。
+    {
+        registryAgent: 'antigravity-acp',
+        defaultName: 'google-antigravity',
+        defaultLabel: 'Google Antigravity',
+        detect: { commands: ['agy'] },
+        distribution: {
+            version: '1.4.0',
+            binary: {
+                'darwin-aarch64': { archive: 'https://dl.google.com/agy-extensions/releases/macos/agy-acp-server-1.4.0-darwin-arm64.zip', cmd: './agy_acp_server.par' },
+                'darwin-x86_64': { archive: 'https://dl.google.com/agy-extensions/releases/macos/agy-acp-server-1.4.0-darwin-x86_64.zip', cmd: './agy_acp_server.par' },
+                'linux-x86_64': { archive: 'https://dl.google.com/agy-extensions/releases/linux/agy-acp-server-1.4.0-linux-x86_64.zip', cmd: './agy_acp_server.par', args: ['--uid='] },
+                'linux-aarch64': { archive: 'https://dl.google.com/agy-extensions/releases/linux/agy-acp-server-1.4.0-linux-arm64.zip', cmd: './agy_acp_server.par', args: ['--uid='] },
+                'windows-x86_64': { archive: 'https://dl.google.com/agy-extensions/releases/windows/agy-acp-server-1.4.0-windows-x86_64.zip', cmd: './agy_acp_server.exe' },
+                'windows-aarch64': { archive: 'https://dl.google.com/agy-extensions/releases/windows/agy-acp-server-1.4.0-windows-arm64.zip', cmd: './agy_acp_server.exe' },
+            },
+        },
+    },
 ];
+/**
+ * Kimi Code 的六个平台归档：GitHub release `@moonshot-ai/kimi-code@<version>` 下的
+ * `kimi-code-<target>.tar.gz`，`sha256` 抄自同名 `.sha256` 资产。版本升级时三样一起换。
+ */
+function kimiCodeBinary(version, targets) {
+    const release = `https://github.com/MoonshotAI/kimi-code/releases/download/@moonshot-ai/kimi-code@${version}`;
+    return Object.fromEntries(Object.entries(targets).map(([triple, [target, sha256]]) => [triple, {
+            archive: `${release}/kimi-code-${target}.tar.gz`,
+            sha256,
+            cmd: triple.startsWith('windows-') ? './kimi.exe' : './kimi',
+            args: ['acp'],
+        }]));
+}
+/** 同一组位置用于全部平台（Windows 三元组用 `windows` 那组）。 */
+function everyPlatform(unix, windows) {
+    return {
+        'darwin-aarch64': unix, 'darwin-x86_64': unix, 'linux-aarch64': unix, 'linux-x86_64': unix,
+        'windows-aarch64': windows, 'windows-x86_64': windows,
+    };
+}
 const BY_ID = new Map(AXOM_AGENT_CATALOG.map((entry) => [entry.registryAgent, entry]));
+/**
+ * 静态推荐条目的展示序（目录数组序）：推荐层的排序依据，用户可指定（2026-10-13：pi 第一、hermes
+ * 第二）。名册序做不到这件事 —— supplement 追加在 registry 之后，字母序又与本意相反（H < P），
+ * 所以显式带一个序号，roster 经 `recommendedRank` 下发、推荐层按它排。非静态推荐的 detected 卡
+ * （"本机在用"）没有序号，排在静态推荐之后、按 label 字母序。
+ */
+export const RECOMMENDED_RANK = new Map(AXOM_AGENT_CATALOG
+    .map((entry, index) => [entry.registryAgent, index])
+    .filter(([id]) => catalogEntryFor(id)?.recommended === true)
+    .map(([id], rank) => [id, rank]));
 export function catalogEntryFor(registryAgent) {
     return BY_ID.get(registryAgent);
 }
+/** The CLI-owned launch environment for one agent at one registry version: catalog `launchEnv`, then runtime.json `env`. */
+export function catalogLaunchEnv(agentId, registryVersion) {
+    return { ...catalogEntryFor(agentId)?.launchEnv, ...patchOverridesFor(agentId, registryVersion).env };
+}
+export function effectiveEntry(agent, supplemented = false) {
+    const entry = catalogEntryFor(agent.id);
+    const patch = patchOverridesFor(agent.id, agent.version);
+    const pinned = patch.distribution ?? entry?.distribution;
+    const pinnedBy = patch.distribution ? 'runtime-override'
+        : entry?.distribution || supplemented ? 'catalog' : undefined;
+    let effective = agent;
+    if (pinned) {
+        const { version, ...distribution } = pinned;
+        effective = { ...effective, version, distribution };
+    }
+    return {
+        agent: effective,
+        registryVersion: agent.version,
+        launchEnv: { ...entry?.launchEnv, ...patch.env },
+        ...(pinnedBy ? { pinnedBy } : {}),
+    };
+}
+/** {@link withCatalogEntries} then {@link effectiveEntry} over a whole registry document, supplements marked as catalog pins. */
+export function effectiveEntries(agents) {
+    const published = new Set(agents.map((agent) => agent.id));
+    return withCatalogEntries(agents).map((agent) => effectiveEntry(agent, !published.has(agent.id)));
+}
+/**
+ * The registry entry as Axom will actually install and launch it: unchanged unless something
+ * overrides it. A distribution replaces the registry's `version` and `distribution` — a runtime.json
+ * override that applies at this registry version first, else this catalog's own. Launch env is merged
+ * under every distribution's own `env` (the registry's declared variables win over ours). Identity
+ * and the registry's own words never move (see the file header).
+ */
+export function applyCatalogOverrides(agent) {
+    const { agent: effective, launchEnv } = effectiveEntry(agent);
+    if (!Object.keys(launchEnv).length)
+        return effective;
+    return { ...effective, distribution: withLaunchEnv(effective.distribution, launchEnv) };
+}
+/** The registry's list with this catalog's supplements added where the registry lacks them and superseded ids removed. */
+export function withCatalogEntries(agents) {
+    const published = new Set(agents.map((agent) => agent.id));
+    const superseded = new Set(AXOM_AGENT_CATALOG.flatMap((entry) => entry.supersedes ?? []));
+    const supplements = AXOM_AGENT_CATALOG.flatMap((entry) => entry.supplement && !published.has(entry.registryAgent) ? [{ ...entry.supplement, id: entry.registryAgent }] : []);
+    return [...agents.filter((agent) => !superseded.has(agent.id)), ...supplements];
+}
+function withLaunchEnv(distribution, launchEnv) {
+    const under = (target) => ({ ...target, env: { ...launchEnv, ...(target.env ?? {}) } });
+    return {
+        ...distribution,
+        ...(distribution.npx && { npx: under(distribution.npx) }),
+        ...(distribution.uvx && { uvx: under(distribution.uvx) }),
+        ...(distribution.binary && {
+            binary: Object.fromEntries(Object.entries(distribution.binary).map(([platform, target]) => [platform, target && under(target)])),
+        }),
+    };
+}
+/**
+ * {@link withCatalogEntries} then {@link applyCatalogOverrides} over a whole registry. `AcpAgents` reads the registry through this
+ * and nothing else, so roster, install, launch and update all see the same effective entries.
+ */
+export function withCatalogOverrides(registry) {
+    return { load: async () => withCatalogEntries(await registry.load()).map(applyCatalogOverrides) };
+}

package/dist/workstation/acp/registry/detect.js

@@ -0,0 +1,55 @@
+/**
+ * 本地检测：这台机器上**用户自己**有没有装某个 agent（或它的前置依赖）。
+ *
+ * ## 它回答的不是"Axom 装好了没有"
+ *
+ * Axom 启动的一律是自己托管的那份（npx 缓存、`uv tool dir`、`<config dir>/acp-adapters`），
+ * 那是 `acpAgents.ts` 的 `adapterInstalled` 的事。这里看的是用户在终端里用的那份：PATH 上的命令、
+ * 厂商安装器放下的固定文件。它只有两个用途（见 `catalog.ts` 文件头）：
+ *
+ * - **推荐信号**：检测到 = 这台机器的用户在用它，于是设置页把它排进推荐位，原因写"本机在用"。
+ * - **前置依赖**：ZCode、Pi 这类适配器自己不带引擎，检测不到本体就起不来。
+ *
+ * ## 只看文件在不在，不起进程
+ *
+ * 与 `installProbe.ts` 的 `findOnPath` 同一条规矩：roster 一次要对 registry 里全部 agent 回答，
+ * 一个会执行东西的探针就是每次扫描几十个子进程。`--version` 回答的是另一个更贵的问题。
+ */
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { findOnPath } from '../installProbe.js';
+/**
+ * 按 `spec` 在这台机器上找：PATH 上的任一命令，或本机三元组下的任一文件位置。
+ *
+ * `triple` 是 `binaryInstall.ts` 的 `platformTriple` 算出来的本机三元组；落在 registry 六个三元组
+ * 之外的机器传 `undefined`，此时只看 `commands`。
+ */
+export function detected(spec, probe, triple) {
+    if (!spec)
+        return false;
+    if (spec.commands?.some((command) => findOnPath(command, probe) !== undefined))
+        return true;
+    const locations = triple ? spec.locations?.[triple] : undefined;
+    return locations?.some((location) => {
+        const resolved = resolveLocation(location, probe);
+        return resolved !== undefined && isFile(resolved);
+    }) ?? false;
+}
+/** 展开 `~/` 与 `%LOCALAPPDATA%/`；对应的目录未知时返回 `undefined`（这条线索查不了，不是命中）。 */
+export function resolveLocation(location, probe) {
+    if (location.startsWith('~/'))
+        return probe.home ? path.join(probe.home, location.slice(2)) : undefined;
+    if (location.startsWith('%LOCALAPPDATA%/')) {
+        return probe.localAppData ? path.join(probe.localAppData, location.slice('%LOCALAPPDATA%/'.length)) : undefined;
+    }
+    return location;
+}
+// `statSync` 而不是 `lstatSync`：与 `findOnPath` 同理，厂商安装器常放符号链接。
+function isFile(candidate) {
+    try {
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}