@platless/axom-cli 0.1.0

package/dist/workstation/acp/permission.js

@@ -0,0 +1,327 @@
+/**
+ * ACP's two client-side *requests* that block the agent on a user answer — `session/request_permission`
+ * and `elicitation/create` — plus the one *notification* that pairs with the latter,
+ * `elicitation/complete`. All three are registered onto a `ClientApp` through `connectAgent`'s
+ * `configure` hook (see `acpClient.ts`'s `ConnectAgentOptions.configure` doc comment): `ClientApp.connect()`
+ * copies its handler table at connect time, so a handler added afterwards would compile fine and
+ * simply never fire — this file exists specifically to be wired in before that copy happens.
+ *
+ * ## `session/request_permission`
+ *
+ * This is the plan's single largest risk (see the plan's "审批与提问" section) because it is a real
+ * round trip to a human: the agent process is blocked on `session/prompt` until this resolves, so
+ * every path through {@link handleRequestPermission} must eventually settle it, including the path
+ * where nobody ever answers.
+ *
+ * - **Empty `options` is refused outright**, before anything reaches the user (`validate.ts`'s
+ *   `permission_request` rule: an option-less card parks the session on something with no button to
+ *   answer, leaving Stop as the only way out). This is not a synthesized "allow once" — it is a hard
+ *   no, mirroring the deleted bridge's identical rule.
+ * - Otherwise the agent's own `options` (already `{optionId, name, kind}`, ACP's own vocabulary) are
+ *   passed straight through into the `permission_request` wire event — unlike the deleted Claude
+ *   Code bridge, this client does not invent its own two-option vocabulary, because ACP already hands
+ *   over whatever the agent decided to offer.
+ * - The pending answer is tracked through `AcpSession.registerPendingApproval`/`.answer` — the same
+ *   map `AcpSession.close()` already drains (and `registerPendingApproval` itself refuses to add to,
+ *   resolving immediately instead, once already closed) with an abandonment sentinel for every entry
+ *   still pending, and the connection dying underneath a pending request drains it the same way (Task
+ *   4's contract, extended by this task's review). That sentinel — and any other answer that does not
+ *   name one of the options actually offered — resolves to `{outcome:'rejected'}` here rather than
+ *   being forced into a fabricated selection.
+ * - **Agent-side cancellation** (`ctx.signal` aborting) settles the request as refused and purges the
+ *   pending entry, instead of leaving a card nobody is listening to answer.
+ *
+ * ## `elicitation/create` / `elicitation/complete`
+ *
+ * `elicitation/create`'s `mode` union is **open** (`"form" | "url" | string`, per
+ * `CreateElicitationRequest`'s schema comment: "Custom or future elicitation mode" — a bare `string`
+ * arm, unlike `session/update`'s closed 15-member union). Axom's wire vocabulary now *has* the
+ * `elicitation_request`/`elicitation` pair (Plan B renamed the platform's own interaction events onto
+ * ACP's words). The two names are not in the same state: `elicitation_request` (`InteractionRequested`)
+ * still has no bridge decode path — `TimelineEventWire.decode` has no branch for it, so a bridge
+ * emitting it is rejected outright — but bare `elicitation` (`UserInteractionRequested`) has had a named
+ * decode branch since `TimelineEventWire.kt:127`, and it is answerable end to end: decode rebuilds the
+ * typed event, `CoworkEngine` lands a `USER_INTERACTION` item and parks the turn, and once the user
+ * answers, `ExternalAgentSessionRuntime.execute` forwards the reply through `channel.prompt(runId,
+ * context.userText, ...)`. `'form'` still declines — it ships an arbitrary JSON-Schema
+ * `requestedSchema` (`ElicitationSchema`) that nothing on Axom's wire translates into that fixed Q&A
+ * shape — and the open `default` arm still declines everything else the SDK or a nonstandard agent
+ * might send, for the same reason: neither has anywhere to go yet, and declining is what keeps them
+ * defensible — it never hangs the agent and it never fabricates a user's consent for input nobody was
+ * ever shown.
+ *
+ * `'url'` is different: it is the shape some agents use to hand a sign-in link to the reader (Codex's
+ * device-code flow reaches it through `elicitation/create` once `elicitation.url` is declared in
+ * `acpClient.ts`'s `clientCapabilities` — see that file). {@link handleCreateElicitation} **accepts**
+ * it immediately and hands `elicitationId`/`url` out through the injected `present` callback. Per ACP's
+ * own semantics, `accept` here means "I have put this URL in front of the user", not "the user
+ * finished" — completion is a *separate* event, the agent's own `elicitation/complete` notification
+ * (`CompleteElicitationNotification`), which {@link handleElicitationComplete} turns into a `dismiss`
+ * call. Both callbacks are injected so this module and its tests stay decoupled from whatever transport
+ * carries the URL from the workstation to the server and on to the browser. Today exactly one
+ * caller supplies real ones — `acpAgents.ts`'s `authenticate`, on the throwaway connection it opens
+ * for a single sign-in, where they become the `agent_auth_url` / `agent_auth_url_done` frames. A
+ * session connection deliberately supplies no `present` (see `AcpAgents.open`): a `url` elicitation
+ * raised there belongs to no login, so it is declined rather than shown.
+ *
+ * `dismiss` covers only the provenance the protocol can retract. An agent that printed its URL to
+ * stderr instead never issued the `elicitationId` the workstation invented for it and can never
+ * complete it, so `authenticate` remembers every id it handed out and retracts what is left when
+ * the login settles.
+ */
+import { methods } from '@agentclientprotocol/sdk';
+import { validateWireEvent } from './validate.js';
+/** A value guaranteed not to equal any real `optionId` in `input.options` for a given call — used to purge a pending entry without accidentally supplying a matchable answer. Regenerated per call rather than a fixed literal, for the same anti-collision reasoning as `AcpSession`'s own abandonment sentinel (review finding, task-5 item 6). */
+function unmatchableAnswerFor(options) {
+    let candidate = '__acp_permission_cancelled__';
+    const optionIds = new Set(options.map((o) => o.optionId));
+    while (optionIds.has(candidate))
+        candidate = `${candidate}_`;
+    return candidate;
+}
+/**
+ * ACP's `ToolCallUpdate` (`types.gen.d.ts:140`) verbatim, minus every key the agent left out.
+ *
+ * Absence is load-bearing here in ACP's own terms: everything but `toolCallId` is optional and an
+ * omitted field means "unchanged" (`:135-136`), so writing an explicit `null` in its place would be
+ * a claim the agent never made. `undefined`-valued keys are dropped rather than serialized, matching
+ * `sessionUpdateMapper.ts`'s `compact`.
+ *
+ * `_meta` **is** forwarded, and verbatim, matching `sessionUpdateMapper.ts`'s `tool_call`/
+ * `tool_call_update` handling: it is ACP's own extension slot, and this function copies the object
+ * without reading anything inside it (Global Constraint 3, "transport, not translation"). Claude's
+ * adapter attaches `parentToolUseId` here on a permission request raised by a subagent's tool call
+ * (`acp-agent.js:4160`) — this module has no business knowing that key exists, only that the object
+ * belongs to the call and must survive the trip.
+ */
+function toolCallPayload(toolCall) {
+    const fields = {
+        toolCallId: toolCall.toolCallId,
+        name: toolCall.name ?? undefined,
+        title: toolCall.title ?? undefined,
+        kind: toolCall.kind ?? undefined,
+        status: toolCall.status ?? undefined,
+        content: toolCall.content && toolCall.content.length > 0 ? toolCall.content : undefined,
+        locations: toolCall.locations && toolCall.locations.length > 0 ? toolCall.locations : undefined,
+        rawInput: toolCall.rawInput,
+        rawOutput: toolCall.rawOutput,
+        _meta: toolCall._meta ?? undefined,
+    };
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+/**
+ * ACP `RequestPermissionRequest` (`types.gen.d.ts:108`) on Axom's wire: `{toolCall, options}` plus
+ * `requestId`.
+ *
+ * `requestId` is the one admitted extension — ACP correlates the answer through the JSON-RPC request
+ * id, which lives in the envelope (`ClientRequestContext.requestId`), and an event stream has no
+ * envelope. `sessionId`, ACP's third field (`:112`), is deliberately not carried: the event is
+ * already being delivered on a specific run.
+ *
+ * **`toolCall` is nested, not flattened.** The flattened version lifted the tool's
+ * `name`/`title`/`kind`/`arguments` to the top level, which put `name` (the tool's programmatic name,
+ * `:169`) beside `options[].name` (`PermissionOption.name`, `:604`, the button's label) — one word
+ * meaning two things in one payload, an ambiguity ACP itself does not have. It also had nowhere to
+ * put `ToolCallUpdate.content`, so a permission card for an edit could never show the diff it was
+ * asking about. The synthesized `prompt` went with it: it was a display string computed from
+ * `toolCall.title`, and the renderer computes it from the same field now
+ * (`WorkTimelineInteractions.foldPermission`) instead of storing a second, drifting copy.
+ */
+function buildPermissionRequestedEvent(input) {
+    return {
+        eventName: 'permission_request',
+        payload: {
+            requestId: input.requestId,
+            toolCall: toolCallPayload(input.toolCall),
+            // Passed straight through: ACP's own `{optionId, name, kind}` already matches
+            // `permission_request`'s wire shape field-for-field, so there is no second vocabulary to
+            // invent the way the deleted Claude Code bridge had to for the SDK's plain `canUseTool` boolean.
+            options: input.options.map((option) => ({ optionId: option.optionId, name: option.name, kind: option.kind })),
+        },
+    };
+}
+/**
+ * Resolve one `session/request_permission` round trip to a {@link PermissionDecision}.
+ *
+ * The empty-`options` guard runs before anything is registered or emitted — see the class doc
+ * comment for why this must stay a hard refusal, never a synthesized option. Note this guard alone is
+ * not the only thing standing between an empty-options request and an emitted card: the
+ * `validateWireEvent` check further down independently rejects the same malformed event (belt and
+ * suspenders on the plan's hardest rule — see `permission.test.ts`'s "rejects outright" test for how
+ * the two are told apart).
+ *
+ * **Cancellation** (review finding, task-5 item 5): if `input.signal` is already aborted when this
+ * runs, or aborts before an answer arrives, this settles `'rejected'` and purges the pending entry via
+ * `sink.answer` — the agent gave up on this specific request, so nothing should still expect an
+ * answer for it. Session-level abandonment (the session closing, or the connection dying) is instead
+ * `AcpSession`'s own job (`registerPendingApproval` resolving immediately when already closed, and
+ * `runReadLoop` draining on an aborted connection) — see `acpSession.ts`.
+ *
+ * The eventual answer is whatever string reaches `sink`'s registered resolver: normally one of
+ * `input.options`' own `optionId`s (relayed from the user through `AcpSession.answer`), but both
+ * `AcpSession`'s own abandonment sentinel and this function's cancellation purge use values guaranteed
+ * not to collide with a real `optionId` (review finding, task-5 item 6) precisely so an answer that
+ * does not name one of the options actually offered resolves to `'rejected'` here rather than being
+ * forced into a selection the user never made.
+ */
+export async function handleRequestPermission(input, sink) {
+    if (input.options.length === 0) {
+        return { outcome: 'rejected' };
+    }
+    if (input.signal?.aborted) {
+        // The agent had already cancelled this request before we even got to it — nothing left to
+        // register or emit for.
+        return { outcome: 'rejected' };
+    }
+    const event = buildPermissionRequestedEvent(input);
+    const rejection = validateWireEvent(event);
+    if (rejection) {
+        // Defensive only — every field above is derived from ACP's own required, typed schema, so a
+        // conforming agent can never actually trip this. A misbehaving one must not park the session on
+        // a card the platform itself would drop, so this refuses exactly like the empty-options case
+        // rather than emitting something `validateWireEvent` already knows is broken.
+        console.error(`[acp] refusing to raise a permission card that fails validateWireEvent: ${rejection.reason}`);
+        return { outcome: 'rejected' };
+    }
+    const optionIds = new Set(input.options.map((option) => option.optionId));
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (decision) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(decision);
+        };
+        sink.registerPendingApproval(input.requestId, (outcome) => {
+            settle(optionIds.has(outcome) ? { outcome: 'answered', optionId: outcome } : { outcome: 'rejected' });
+        });
+        input.signal?.addEventListener('abort', () => {
+            settle({ outcome: 'rejected' });
+            // Purge the now-moot pending entry so a stray later answer doesn't linger against a request
+            // the agent already gave up on. The `settle` above has already fixed this promise's outcome
+            // (the `settled` guard makes the resolver this triggers a no-op), so the value passed here
+            // only has to avoid accidentally matching a real option id.
+            sink.answer(input.requestId, unmatchableAnswerFor(input.options));
+        }, { once: true });
+        sink.emitEvent(event);
+    });
+}
+/** `{action: 'decline'}` — a valid `CreateElicitationResponse` under every arm of its action union. */
+function declineElicitation() {
+    return { action: 'decline' };
+}
+/**
+ * Answer `elicitation/create`. `'url'` accepts and hands the URL out through `deps.present` **only
+ * when both hold**: the request itself actually carries a string `elicitationId`/`url` (a
+ * nonconforming agent that omits either gets declined, never `present(undefined, undefined)`), and a
+ * real `deps.present` is wired (see {@link PresentElicitationUrl}'s doc comment — its absence means
+ * declining, not accepting into a void). Every other arm still declines — see the class doc comment
+ * for why. Accepting here does **not** mean the user finished anything; it means "the URL has been put
+ * in front of them", matching ACP's own `accept` semantics for this mode — which is exactly why both
+ * guards exist: an `accept` this module cannot back with a shown URL would make that claim false.
+ *
+ * The `switch` has a real `default`, not just `'form'`/`'url'` cases, because `CreateElicitationRequest['mode']`
+ * is `"form" | "url" | string` — an **open** union (unlike `session/update`'s closed 15-member one).
+ * Falling through with no default would mean the client's response is `undefined` for any mode the SDK
+ * or a nonstandard agent invents next, sending a malformed JSON-RPC result the agent may wait on
+ * forever instead of a clean, immediate decline.
+ */
+export function handleCreateElicitation(request, deps) {
+    switch (request.mode) {
+        case 'form':
+            // No form-rendering UI exists on Axom's wire yet — see the class doc comment.
+            return declineElicitation();
+        case 'url': {
+            const { elicitationId, url } = request;
+            if (typeof elicitationId !== 'string' || typeof url !== 'string') {
+                // A conforming agent's `ElicitationUrlMode` always has both as required strings
+                // (`types.gen.d.ts`) — this is defense against one that does not conform, not the normal
+                // path. The elicitation still gets answered (declined), never left to hang.
+                return declineElicitation();
+            }
+            if (!deps.present) {
+                // Nobody to show it to yet — see `PresentElicitationUrl`'s doc comment. Declining here is
+                // what an agent (or an MCP server proxied through one) raising this mid-turn can actually
+                // act on, unlike an `accept` that then goes nowhere.
+                return declineElicitation();
+            }
+            deps.present(elicitationId, url);
+            return { action: 'accept' };
+        }
+        default:
+            // The open arm: "Custom or future elicitation mode" per the SDK's own schema comment. This is
+            // the branch the plan's "elicitation whose union arm the SDK does not close" requirement is
+            // about — it must stay reachable and must not fall through silently.
+            return declineElicitation();
+    }
+}
+/**
+ * `elicitation/complete` fires only for an elicitation the client previously accepted — now the `'url'`
+ * mode, once the agent considers that round trip finished. This turns it into a `dismiss` call so
+ * whatever is showing the URL knows to stop. It still needs a real handler registered even before any
+ * transport exists to drive `deps.dismiss` meaningfully: `ClientApp` requires one for every
+ * notification method it is asked to route, and an agent sending this must not crash the connection.
+ */
+export function handleElicitationComplete(notification, deps) {
+    deps.dismiss(notification.elicitationId);
+}
+/**
+ * Register this module's three handlers onto `app`. Must run inside `connectAgent`'s `configure`
+ * hook — see the file doc comment for why a post-connect `.onRequest`/`.onNotification` would compile
+ * but never fire.
+ *
+ * `elicitationDeps` is **required, deliberately with no default** (fix round 1 finding): a defaulted
+ * no-op pair would let a call site that forgot to wire real callbacks compile and stay green forever
+ * while quietly accepting-and-dropping every `url` elicitation it sees — `tsc` clean, tests green, no
+ * error anywhere, the same shape as an incident this repo already had from an unlisted case falling
+ * through a silent `else`. Making the argument mandatory turns a missed wiring into a build failure at
+ * the call site instead. Its own `present` may still be omitted (see {@link PresentElicitationUrl}) —
+ * that is `acpAgents.ts`'s session connection saying, on purpose, that a `url` elicitation raised
+ * outside a login has nowhere to go, and it declines rather than accepting into nothing.
+ */
+export function registerPermissionHandlers(app, sink, elicitationDeps) {
+    app
+        .onRequest(methods.client.session.requestPermission, async (ctx) => {
+        const decision = await handleRequestPermission({ requestId: String(ctx.requestId), toolCall: ctx.params.toolCall, options: ctx.params.options, signal: ctx.signal }, sink);
+        return {
+            outcome: decision.outcome === 'answered' ? { outcome: 'selected', optionId: decision.optionId } : { outcome: 'cancelled' },
+        };
+    })
+        .onRequest(methods.client.elicitation.create, (ctx) => handleCreateElicitation(ctx.params, elicitationDeps))
+        .onNotification(methods.client.elicitation.complete, (ctx) => handleElicitationComplete(ctx.params, elicitationDeps));
+}
+/**
+ * A `PermissionSink` that is not available yet — `configure` runs before `AcpConnection` exists,
+ * which is itself before `AcpSession.open()` can run, so there is no real `AcpSession` at the moment
+ * `registerPermissionHandlers` must be called. `bind()` supplies the real one once `AcpSession.open()`
+ * resolves; every call routed through this handle before that happens is a genuine ordering bug (the
+ * agent cannot reference a `sessionId` that does not exist yet, so `session/request_permission` cannot
+ * arrive before `bind()` in a conforming agent) and fails loudly rather than silently dropping a
+ * permission card.
+ */
+export function createDeferredPermissionSink() {
+    let bound = null;
+    function requireBound() {
+        if (!bound)
+            throw new Error('[acp] permission sink used before AcpSession.open() bound one');
+        return bound;
+    }
+    return {
+        sink: {
+            emitEvent: (event) => requireBound().emitEvent(event),
+            registerPendingApproval: (requestId, resolve) => requireBound().registerPendingApproval(requestId, resolve),
+            answer: (requestId, outcome) => requireBound().answer(requestId, outcome),
+        },
+        bind(target) {
+            // Review finding (task-5, item 4): silently replacing an already-bound sink on a second call
+            // is exactly how one connection carrying two sessions would misroute — session A's cards would
+            // start landing in session B's sink. Failing loudly here can't catch every way to violate the
+            // one-connection-per-session invariant (see this file's `PermissionSink` doc comment), but it
+            // catches the one this module can actually see.
+            if (bound) {
+                throw new Error('[acp] createDeferredPermissionSink.bind() called twice on the same handle');
+            }
+            bound = target;
+        },
+    };
+}

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

@@ -0,0 +1,29 @@
+export const AXOM_AGENT_CATALOG = [
+    { registryAgent: 'claude-acp', defaultName: 'claude-agent', defaultLabel: 'Claude Agent' },
+    { registryAgent: 'codex-acp', defaultName: 'codex', defaultLabel: 'Codex' },
+    // `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: 'pi-acp',
+        defaultName: 'pi',
+        defaultLabel: 'Pi',
+        dependency: {
+            check: 'pi',
+            // 不用 `curl -fsSL https://pi.dev/install.sh | sh`：读过那个脚本，它最终跑的就是这一条
+            // （`npm install -g --ignore-scripts @earendil-works/pi-coding-agent`），装出来的是同一个
+            // npm 包 —— pi 没有原生分发。脚本唯一的增值是 Node 不够新时帮你装 Node，而那一步是交互式的
+            // （读 /dev/tty），在 daemon 里会直接打 "No terminal detected" 退出。而 `curl | sh` 与上面
+            // 那条安全约束正面冲突。
+            install: ['npm', 'install', '-g', '@earendil-works/pi-coding-agent'],
+            requiresNode: '>=22.19.0',
+        },
+    },
+];
+const BY_ID = new Map(AXOM_AGENT_CATALOG.map((entry) => [entry.registryAgent, entry]));
+export function catalogEntryFor(registryAgent) {
+    return BY_ID.get(registryAgent);
+}

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

@@ -0,0 +1,128 @@
+import path from 'node:path';
+import { binaryTargetFor, installedBinaryVersion, platformTriple } from '../binaryInstall.js';
+import { npmPackageName } from '../installProbe.js';
+import { uvPackageName, uvToolEntrypoint, uvToolEntrypointFrom } from '../uvxInstall.js';
+export class UnsupportedDistributionError extends Error {
+}
+/** `npx --yes <specifier> [dist args]`,两个调用方共用的一处构造:钉版本的和不钉版本的。 */
+function npxLaunch(specifier, npx, platform) {
+    return {
+        command: platform === 'win32' ? 'npx.cmd' : 'npx',
+        // `--yes` 让首次拉包不停在交互确认上。
+        args: ['--yes', specifier, ...(npx.args ?? [])],
+        env: { ...(npx.env ?? {}) },
+    };
+}
+/**
+ * registry 只给原料,不给命令行 —— 没有 `command` 字段,启动方式要从 `distribution` 推导。
+ *
+ * 三种分发方式现在都支持:`npx`/`uvx` 走各自安装侧维护的缓存/工具目录(见 `installProbe.ts`、
+ * `uvxInstall.ts`),`binary` 走 `binaryInstall.ts`(Task 8)—— 按六个平台三元组挑一个目标、
+ * 从 `adapterRoot` 找已经装好的版本。三条路径共同的规则是:**从不猜**,找不到就抛
+ * `UnsupportedDistributionError`,理由写清楚是"这个平台没有发行版"还是"这台机器还没装",而不是
+ * 笼统的一句"不支持"。
+ */
+export async function resolveLaunch(agent, platform, 
+// 六个平台三元组里的一半;只有 binary 分支用到。
+arch, 
+// `<workstation config dir>/acp-adapters` —— `binaryInstall.ts` 解包落地的根目录,只有 binary
+// 分支用到。npx 走 npm 自己的 `_npx` 缓存,uvx 走 `uv tool dir`,都不需要这个根目录。
+adapterRoot, 
+// 仅测试注入:真实调用永远走 `uvxInstall.ts` 的默认 `uv` 实现。签名上留成可选,两个真实调用点
+// (`acpAgents.ts`)不用跟着改。下面的 `uvTools` 给出时,这个参数被忽略 —— 见它的说明。
+run, 
+// 已经读好的 `uv tool list` 快照(`listUvTools`)。给了就直接查表,不再自己起 `uv` 子进程 ——
+// `AcpAgents.roster` 为整份 39 条 registry 只读一次,把结果传进这里,而不是让每个 uvx agent
+// 在这条路径上各自再起一次 `uv`。真正的启动路径(`resolveLaunchFor`)不传这个参数,继续用
+// `run`/默认实现现读一次,这里的现读对它而言正是期望行为。
+//
+// 这个函数整体是 async 的唯一原因:`uv` 现在是非阻塞调用(`RunUv` 返回 `Promise`,见
+// `uvxInstall.ts`),没有预取快照时这里必须 `await` 它。给了 `uvTools` 的那条路径
+// (`AcpAgents.resolvable`)完全同步、不等待任何东西,包成 `async` 只是让两条路径共用同一个
+// 签名——`Promise.resolve` 包一层同步返回值的开销,跟每次 roster 扫描本来就要付的成本比可以
+// 忽略不计。
+uvTools) {
+    const { npx, uvx, binary } = agent.distribution;
+    // specifier 里已内联精确版本,不会追 latest —— 除非 registry 钉的那个版本 npm 根本没有,
+    // 见 {@link unpinnedFallbackFor}。
+    if (npx)
+        return npxLaunch(npx.package, npx, platform);
+    if (uvx) {
+        // 不走 `uvx <pkg>`:那条路用 uv 自己的临时环境缓存,目录名带哈希,"装没装"读不可靠。
+        // 改成我们自己 `uv tool install`、启动时直接跑装出来的入口点 —— 与 binary 一样,
+        // 落到"我们装的、我们知道装在哪"这一条统一规则上。
+        const outcome = uvTools
+            ? uvToolEntrypointFrom(uvPackageName(uvx.package), uvTools)
+            : await uvToolEntrypoint(uvPackageName(uvx.package), run);
+        if (outcome.ok) {
+            return { command: outcome.path, args: [...(uvx.args ?? [])], env: { ...(uvx.env ?? {}) } };
+        }
+        if (outcome.reason === 'ambiguous') {
+            // 装了,但不敢猜:多个可执行文件里没有一个跟包名同名,uv 的列出顺序又不是文档化契约——
+            // 静默启动错的那个,换来的是一次没人能追回这里的 ACP 握手挂死或失败,比拒绝启动更糟。
+            throw new UnsupportedDistributionError(`Agent '${agent.id}' is distributed through uvx and its tool is installed, but this build ` +
+                `cannot tell which of its executables is the ACP adapter: ${outcome.candidates.join(', ')}.`);
+        }
+        throw new UnsupportedDistributionError(`Agent '${agent.id}' is distributed through uvx but its tool is not installed on this machine.`);
+    }
+    if (binary) {
+        // 六个平台三元组里挑一个;`windows-aarch64` 在实测的 registry 快照上只有 9/18 的覆盖,
+        // "这个平台没有发行版"是常态,不是异常——`installBinary`（`binaryInstall.ts`）在下载前就
+        // 用同一个函数做同一个判断,这里只是启动路径上再问一次同一件事,答案必须一致。
+        const triple = platformTriple(platform, arch);
+        const target = triple ? binaryTargetFor(agent, triple) : undefined;
+        if (!target) {
+            throw new UnsupportedDistributionError(`Agent '${agent.id}' publishes no archive for ${triple ?? `${platform}-${arch}`}.`);
+        }
+        // 装没装是这台机器磁盘上的事实,不是 registry 条目的属性 —— 跟 npx/uvx 分支一样,没装就说
+        // "没装",不是"不支持"。
+        //
+        // `agent.version` 必须传:同一个 agent 的多个版本可以并存(`<root>/<agent>/<version>/`,
+        // 就是为此设计的),`pickInstalledVersion` 的规则是"钉的版本在就取它,否则取最大"。
+        // `AcpAgents.roster` 报告 `adapterVersion` 时传了它,这里不传就会在两个版本并存时报告一个、
+        // 启动另一个 —— 名册说 0.75.0、跑起来是 0.74.0,而且没有任何一处会说出这件事。
+        const version = installedBinaryVersion(agent.id, adapterRoot, agent.version);
+        if (!version) {
+            throw new UnsupportedDistributionError(`Agent '${agent.id}' has no installed adapter on this machine.`);
+        }
+        return {
+            command: path.join(adapterRoot, agent.id, version, target.cmd),
+            args: [...(target.args ?? [])],
+            env: { ...(target.env ?? {}) },
+        };
+    }
+    throw new UnsupportedDistributionError(`Agent '${agent.id}' declares no launchable distribution.`);
+}
+/**
+ * 同一个 agent,但把 registry 钉的版本从 specifier 上剥掉 —— 上游钉了一个 npm 上并不存在的版本时,
+ * 唯一还能把这个 agent 救回来的启动方式。
+ *
+ * ## 为什么需要它
+ *
+ * 2026-09-04 实测:registry 的 `codex-acp` 条目声明
+ * `@agentclientprotocol/codex-acp@1.10.0`,而 npm 上这个包的版本停在 `1.9.0`
+ * (`dist-tags.latest` 也是 `1.9.0`)。于是每一次 codex 启动都是 `npm error code ETARGET`,npx 退出,
+ * 子进程死掉 —— 两台真实工作站同时失去了 codex。这是上游的缺陷;这里能做的是不让它把 agent 砖掉。
+ *
+ * ## 代价,以及为什么仍然值得
+ *
+ * 不钉版本装回来的,是 npm 此刻叫 `latest` 的那一个 —— **registry 从来没有指定过它**。它可能比钉的
+ * 版本新(常见,上游多半正是发版发歪了),也可能是一个协议行为不同、甚至跟这个客户端谈不拢
+ * `initialize` 的版本。所以这条路只在 ETARGET 上走(见 `acpClient.ts` 的 `isMissingPackageVersion`),
+ * 只走一次,而且两条 warn 日志会把「跑的不是 registry 要的那个版本」说穿。
+ *
+ * ## 三种「没有回退可言」的情况,都返回 undefined
+ *
+ * 没有 npx 分发(`uvx` 走的是 uv 自己的缓存,`binary` 这个版本压根不支持)、specifier 本来就不带版本
+ * (剥无可剥,npm 已经在追 latest 了)。剥版本用 `npmPackageName`,它按最后一个 `@` 切,所以
+ * `@scope/name@1.10.0` → `@scope/name`,而前导的 `@` 不会被当成版本分隔符。
+ */
+export function unpinnedFallbackFor(agent, platform) {
+    const npx = agent.distribution.npx;
+    if (!npx)
+        return undefined;
+    const unpinned = npmPackageName(npx.package);
+    if (unpinned === npx.package)
+        return undefined;
+    return { pinned: npx.package, unpinned, launch: npxLaunch(unpinned, npx, platform) };
+}

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

@@ -0,0 +1,160 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/** `latest` is `max-age=300`; a fixed 2026-08 snapshot exists too but registry.ts always tracks `latest`. */
+export const REGISTRY_URL = 'https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json';
+const CACHE_FILE = 'acp-registry-cache.json';
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Validates only what launch and identity depend on (`id`, and that `distribution` has at least
+ * one channel). The envelope itself — and every other per-agent field — is passed through as-is:
+ * the live registry.json does not pass its own schema (`extensions` is baked in by the builder
+ * against an `additionalProperties:false` schema), so strict validation here would empty the whole
+ * agent list in production instead of just ignoring a field this client doesn't use yet.
+ */
+function isRegistryAgent(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    if (typeof candidate.id !== 'string' || candidate.id.length === 0)
+        return false;
+    const distribution = candidate.distribution;
+    if (typeof distribution !== 'object' || distribution === null)
+        return false;
+    const channels = distribution;
+    return channels.npx != null || channels.uvx != null || channels.binary != null;
+}
+function parseAgents(document) {
+    if (typeof document !== 'object' || document === null) {
+        throw new Error('ACP agent registry document is not a JSON object');
+    }
+    const agents = document.agents;
+    if (!Array.isArray(agents)) {
+        throw new Error('ACP agent registry document is missing an "agents" array');
+    }
+    // Silently drop entries that don't even have an id/distribution rather than failing the whole
+    // list: a single malformed entry must not take every other agent down with it.
+    return agents.filter(isRegistryAgent);
+}
+/**
+ * Fetches the ACP agent registry with ETag revalidation and a last-known-good on-disk cache.
+ *
+ * `document.version` ("1.0.0") is a frozen constant, not a content version — freshness is tracked
+ * via the HTTP ETag (`if-none-match` / 304), never by comparing that field.
+ */
+export class RegistryClient {
+    cacheDir;
+    cachePath;
+    fetchImpl;
+    url;
+    requestTimeoutMs;
+    /**
+     * Why the last {@link readCache} produced nothing, when the reason was something other than "there
+     * is no cache yet". Read only by {@link fallbackOrThrow}.
+     *
+     * A corrupt cache and a cold start both degrade to "no cache", which is right — a bad file must not
+     * make the registry unusable. But collapsing them in the *message* sends whoever is debugging to
+     * look for a network problem on a machine whose only actual fault is one unreadable file, which
+     * nothing else on it would ever mention.
+     */
+    cacheDefect = null;
+    constructor(options) {
+        this.cacheDir = options.cacheDir;
+        this.cachePath = path.join(this.cacheDir, CACHE_FILE);
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.url = options.url ?? REGISTRY_URL;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    }
+    /** Cache-first: returns the cached list immediately (if any) and refreshes in the background. */
+    async load() {
+        const cached = await this.readCache();
+        if (cached) {
+            // A stale cache is still useful; a background refresh failure must not surface to a caller
+            // that already got an answer.
+            void this.refresh().catch(() => undefined);
+            return cached.agents;
+        }
+        return this.refresh();
+    }
+    /** Forces a network fetch. Falls back to the cache on any failure; throws only on a cold start. */
+    async refresh() {
+        const cached = await this.readCache();
+        const headers = {};
+        if (cached?.etag)
+            headers['if-none-match'] = cached.etag;
+        let response;
+        try {
+            response = await this.fetchImpl(this.url, { headers, signal: AbortSignal.timeout(this.requestTimeoutMs) });
+        }
+        catch (error) {
+            return this.fallbackOrThrow(cached, errorMessage(error));
+        }
+        if (response.status === 304) {
+            return this.fallbackOrThrow(cached, 'responded 304 Not Modified but no cached copy exists to revalidate against');
+        }
+        if (!response.ok) {
+            return this.fallbackOrThrow(cached, `responded with HTTP ${response.status}`);
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (error) {
+            return this.fallbackOrThrow(cached, `returned a body that could not be parsed as JSON (${errorMessage(error)})`);
+        }
+        const agents = parseAgents(body);
+        const etag = response.headers.get('etag') ?? undefined;
+        await this.writeCache({ agents, etag });
+        return agents;
+    }
+    fallbackOrThrow(cached, reason) {
+        if (cached)
+            return cached.agents;
+        const cacheState = this.cacheDefect ?? 'no cached copy exists on this machine';
+        throw new Error(`ACP agent registry at ${this.url} is unreachable (${reason}) and ${cacheState}`);
+    }
+    async readCache() {
+        this.cacheDefect = null;
+        try {
+            const raw = await fs.readFile(this.cachePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== 'object' || parsed === null)
+                return this.unusableCache('it does not contain a JSON object');
+            const candidate = parsed;
+            if (!Array.isArray(candidate.agents))
+                return this.unusableCache('it has no "agents" array');
+            return {
+                agents: candidate.agents.filter(isRegistryAgent),
+                etag: typeof candidate.etag === 'string' ? candidate.etag : undefined,
+                fetchedAt: typeof candidate.fetchedAt === 'string' ? candidate.fetchedAt : new Date(0).toISOString(),
+            };
+        }
+        catch (error) {
+            // A corrupt or unreadable file degrades to "no cache" exactly like a cold start does — that
+            // part is deliberate. Only the *diagnostic* distinguishes them.
+            if (error.code === 'ENOENT')
+                return null;
+            return this.unusableCache(errorMessage(error));
+        }
+    }
+    /** Records why the cache file could not be used, and degrades to "no cache". */
+    unusableCache(detail) {
+        this.cacheDefect = `the cached copy at ${this.cachePath} could not be used (${detail})`;
+        return null;
+    }
+    async writeCache(data) {
+        await fs.mkdir(this.cacheDir, { recursive: true });
+        const payload = { agents: data.agents, etag: data.etag, fetchedAt: new Date().toISOString() };
+        const temporary = path.join(this.cacheDir, `.${CACHE_FILE}.${process.pid}.${Date.now()}.tmp`);
+        try {
+            await fs.writeFile(temporary, `${JSON.stringify(payload)}\n`, 'utf8');
+            await fs.rename(temporary, this.cachePath);
+        }
+        catch (error) {
+            await fs.rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Shape of the ACP agent registry (`https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`).
+ *
+ * There is no `command` field: how to launch an agent is derived from `distribution` (see
+ * `launch.ts`, Task 2). `version` on the document itself is a frozen constant ("1.0.0"), not a
+ * content version — freshness is tracked via ETag, not this field.
+ */
+export {};