@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/acp/initializeResponse.js

@@ -0,0 +1,290 @@
+/**
+ * The `initialize` handshake, as data: the params this client sends and what it reads out of the
+ * agent's reply.
+ *
+ * ## Why this is its own module
+ *
+ * Two readers must agree on every byte of this: `connectAgent` (the live SDK path) and the
+ * deterministic ACP processor (`processor/`, spec 2026-10-11 §5.4), which parses the same reply off
+ * the keeper's raw log inside `step`. `step`'s import graph may not reach anything that spawns a
+ * process, reads the clock or draws a random id (`processor/guard.test.ts`), and `acpClient.ts` does
+ * all three — so the pure half lives here and `acpClient.ts` re-exports every name it used to own.
+ * One implementation rather than two kept equal by a test: the equivalence test in
+ * `processor/initialize.test.ts` then guards the processor's *wiring* (the right line, the right
+ * result), not a second copy of these rules.
+ *
+ * The runtime profile in `_meta` is deliberately not read here: it belongs to the connection's
+ * runtime diagnostics, which the processor takes over in Task 17b/17c.
+ */
+import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk';
+import { airCapabilityMeta, asSdkClientCapabilities, AIR_ASYNC_TASKS_CAPABILITY, AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, DRAFT_SUBAGENTS_CAPABILITY, } from './draftSubagents.js';
+import { metaTerminalAuthArgs, terminalLoginSpecOf } from './terminalLoginSpec.js';
+/** The `initialize` params this client sends — the same object on the live path and from the processor. */
+export function initializeRequestParams() {
+    return {
+        protocolVersion: PROTOCOL_VERSION,
+        // Three things are declared here, and they are not interchangeable — see
+        // `draftSubagents.ts` for the tier each one sits in.
+        //
+        // 1. `subagents: {}` is the **canonical** draft field from ACP RFD #1992. Both official
+        //    adapters gate native subagent sessions on it, and both answer with
+        //    `agentCapabilities.sessionCapabilities.subagents` (measured against each).
+        //
+        // 2. The AIR list is sent as well, for two separate reasons. It is the *only* channel for
+        //    `asyncTasks` — nothing canonical exists for background work — and it is the fallback
+        //    for `nativeSubagentSessions`, because a released SDK sitting between us and an agent
+        //    can strip a draft field it has no type for (upstream says so in #1017's compatibility
+        //    note). Declaring both is not belt-and-braces: they cover different failure modes.
+        //
+        // 3. `subagent-transcript: true` stays. It is claude-agent-acp's older vendor key
+        //    (`dist/acp-agent.js:155-158`), and it still governs the **fallback** path taken when
+        //    native subagent sessions are not negotiated — an older adapter, or a stripped
+        //    capability. Without it that path strips every subagent's text and thinking
+        //    (`stripSubagentTextAndThinking`, `:3926`), leaving nothing but tool-call wreckage.
+        //    Adapters that have never heard of any of these keys are required by the spec to
+        //    ignore them.
+        clientCapabilities: asSdkClientCapabilities({
+            [DRAFT_SUBAGENTS_CAPABILITY]: {},
+            // `ClientSessionCapabilities.configOptions` (`types.gen.d.ts:4306`), part of the schema
+            // proper — unlike `subagents` above, this survives the pinned SDK's `zInitializeRequest`
+            // stripping because it's a known field, not a draft one. `{}` for `boolean` tells the
+            // agent it may send `type: "boolean"` entries in `SessionConfigOption` and that this
+            // client will send `session/set_config_option` with a boolean `value`
+            // (`SessionConfigOptionsCapabilities`, `types.gen.d.ts:4333-4353`); without it an agent
+            // with a boolean toggle downgrades it to a two-value select.
+            session: { configOptions: { boolean: {} } },
+            // `ClientCapabilities.elicitation` (`types.gen.d.ts:4479`) is a known field of the schema
+            // proper, not a draft one, so it survives `zInitializeRequest` stripping as-is. `{}` for
+            // `url` (`ElicitationUrlCapabilities`, `:4616`) means the client can put a URL in front of
+            // the user; this is the precondition for the whole device-code login shape to exist at all
+            // — Codex's own `getCodexAuthMethods` gates its `chat-gpt-device-code` auth method on
+            // `clientCapabilities?.elicitation?.url != null`. Without declaring it, Codex never offers
+            // that method and `elicitation/create` with `mode: 'url'` never arrives to answer (see
+            // `permission.ts`'s `handleCreateElicitation`).
+            //
+            // `form` (`ElicitationFormCapabilities`, `types.gen.d.ts:4455`) is what keeps Claude's
+            // AskUserQuestion alive: without it the adapter puts the tool in `disallowedTools`
+            // (`claude-agent-acp/dist/acp-agent.js:5959`), so the model never has it at all — the
+            // symptom is prose questions, not an unrendered card. This is the trigger for the whole
+            // elicitation-standardization plan: everything through Task 17 built the machinery to
+            // answer `elicitation/create` once it arrives; this line is what makes it arrive at all.
+            elicitation: { url: {}, form: {} },
+            _meta: {
+                // The convention Zed introduced and the ACP adapters adopted: an agent may gate its terminal
+                // sign-in methods on this key — claude-agent-acp advertises `claude-ai-login` / `console-login`
+                // (each with a `_meta["terminal-auth"]` naming the pipe-friendly invocation) only when the
+                // client declares it; pi-acp always returns its method but attaches the same block only then.
+                // We DO host those invocations — `terminalLogin.ts` runs them with pipes, sniffs the OAuth URL
+                // out of the output and surfaces it as a login link (spec 2026-09-24 D6/D7/D9) — so declaring
+                // this is a statement of fact, not an aspiration. Same-machine only: a hosted login's
+                // localhost OAuth callback must reach the workstation's own listener, which a browser opened
+                // on another machine cannot do; the standard `authenticate` methods (device-code style) are
+                // unaffected and never needed this key.
+                'terminal-auth': true,
+                terminal_output_delta: true,
+                'subagent-transcript': true,
+                ...airCapabilityMeta(AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, AIR_ASYNC_TASKS_CAPABILITY),
+            },
+        }),
+    };
+}
+/**
+ * Whether a JSON-RPC error code is one a frame may carry: an integer inside the Kotlin twin's `Int`
+ * range. See `acpClient.ts` `jsonRpcErrorCode` for why a malformed code is reported as no code at
+ * all. Split out so the processor, which sees the peer's `{code}` as plain JSON rather than as the
+ * SDK's `RequestError`, applies the identical rule.
+ */
+export function jsonRpcErrorCodeOf(code) {
+    if (typeof code !== 'number' || !Number.isInteger(code))
+        return undefined;
+    return code >= -2_147_483_648 && code <= 2_147_483_647 ? code : undefined;
+}
+/**
+ * Read an `initialize` result exactly the way `connectAgent` always has.
+ *
+ * The protocol version is checked **first** and nothing else is read when it is wrong — Global
+ * Constraint 1 is v1-only and a reply for another version is not ours to interpret. Malformed input
+ * throws where it always threw (a non-array `authMethods`, a non-object result); callers that must
+ * not throw (the processor) catch it themselves, so the live path keeps its exact behaviour.
+ */
+export function parseInitializeResult(initResponse) {
+    if (initResponse.protocolVersion !== PROTOCOL_VERSION) {
+        return { protocolSupported: false, protocolVersion: initResponse.protocolVersion };
+    }
+    const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+    const axomMeta = isRecord(initResponse._meta) && isRecord(initResponse._meta.axom) ? initResponse._meta.axom : undefined;
+    const cachedReconnect = axomMeta?.cachedReconnect === 'resume' ? 'resume' : undefined;
+    const sessionCapabilities = initResponse.agentCapabilities?.sessionCapabilities;
+    const capabilities = {
+        // Capability markers are empty objects (`{ _meta? }`); supplying `{}` means "supported", and
+        // omitting the field (or explicit `null`) means "not supported". A truthiness check reads `{}`
+        // correctly by accident but reads `null`/`undefined` correctly too, which hides the real bug:
+        // this must stay an explicit `!= null`, never `Boolean(...)` or a bare truthy test.
+        list: sessionCapabilities?.list != null,
+        delete: sessionCapabilities?.delete != null,
+        resume: sessionCapabilities?.resume != null,
+        loadSession: initResponse.agentCapabilities?.loadSession === true,
+        logout: initResponse.agentCapabilities?.auth?.logout != null,
+        /**
+         * ACP `PromptCapabilities.image` (`types.gen.d.ts:1601`): "Agent supports
+         * [`ContentBlock::Image`]". Every field of that type is optional, so an agent that says
+         * nothing supports text only -- `=== true` rather than `!== false`.
+         *
+         * Verified against codex-acp 1.7.0, which declares `{embeddedContext: true, image: true}`.
+         * `audio` is deliberately not read: no agent we target declares it, and an unread capability
+         * is a field nobody can act on.
+         */
+        promptImage: initResponse.agentCapabilities?.promptCapabilities?.image === true,
+        mcpHttp: initResponse.agentCapabilities?.mcpCapabilities?.http === true,
+    };
+    // Honour the advertised capability, not what the agent happens to route: some adapters (e.g.
+    // codex-acp routing `session/fork`) implement more than they declare in `agentCapabilities`.
+    // Reading `capabilities` above off `initResponse` — never probing the agent for what it accepts
+    // — is what keeps that distinction intact.
+    const advertisedAuthMethods = initResponse.authMethods ?? [];
+    const authMethods = advertisedAuthMethods
+        .map(toAuthMethodSnapshot)
+        .filter((method) => method !== null);
+    const terminalLogins = [];
+    for (const method of advertisedAuthMethods) {
+        const spec = terminalLoginSpecOf(method);
+        if (spec && typeof method.id === 'string') {
+            // A duplicate id keeps its first position and takes the later spec — exactly `Map.set`.
+            const existing = terminalLogins.findIndex(([id]) => id === method.id);
+            if (existing >= 0)
+                terminalLogins[existing] = [method.id, spec];
+            else
+                terminalLogins.push([method.id, spec]);
+        }
+    }
+    return {
+        protocolSupported: true,
+        ...(cachedReconnect ? { cachedReconnect } : {}),
+        capabilities,
+        authMethods,
+        droppedAuthMethods: advertisedAuthMethods.length - authMethods.length,
+        terminalLogins,
+        ...(initResponse.agentCapabilities?._meta?.['axom/accountRateLimits']?.read === true ? { supportsAccountLimits: true, accountLimitsVersion: initResponse.agentCapabilities?._meta?.['axom/accountRateLimits']?.version ?? 1 } : {}),
+        supportsSteering: steeringAdvertised(initResponse._meta),
+        steeringTimings: steeringTimings(initResponse._meta),
+        agentInfo: initResponse.agentInfo ?? undefined,
+    };
+}
+/**
+ * Whether an `InitializeResponse._meta` advertises the `_session/steering` extension.
+ *
+ * ## `_session/steering` is not ACP
+ *
+ * It is absent from the schema this client is pinned to (`grep steer
+ * node_modules/@agentclientprotocol/sdk/dist/schema/types.gen.d.ts` returns nothing). It is an
+ * extension `claude-agent-acp` implements: the method constant lives at its `acp-agent.js@0.76.0:164`
+ * and its own comment calls it a *"Custom (extension) request method ... Named `_session/steering`
+ * per the agreed ACP steering wire protocol"*. The leading underscore is ACP's extension namespace.
+ *
+ * ## Why the top-level `_meta` specifically
+ *
+ * The adapter advertises it at `InitializeResponse._meta.steering.supported`, a **sibling of
+ * `agentCapabilities`** (`acp-agent.js@0.76.0:944-950`), not a key inside it. `_meta` is typed
+ * `{[key: string]: unknown} | null` (`types.gen.d.ts:1498-1500`), so every hop down has to be
+ * narrowed rather than indexed through a cast.
+ *
+ * Strictly `=== true`. An agent that sends `steering: {}` (the shape ACP uses for its *own*
+ * capability markers) has not said `supported`, and this extension does not define that spelling —
+ * reading it as a yes would be this client inventing a wire contract.
+ */
+export function steeringAdvertised(meta) {
+    if (typeof meta !== 'object' || meta === null)
+        return false;
+    const steering = meta.steering;
+    if (typeof steering !== 'object' || steering === null)
+        return false;
+    return steering.supported === true;
+}
+/**
+ * The delivery timings the `_session/steering` extension defines — when the agent hands an injected
+ * message to the model. `next` is the only lossless one: `now` aborts the running generation and
+ * discards whatever tool calls were still outstanding.
+ */
+export const STEER_TIMINGS = ['now', 'next', 'later'];
+/**
+ * Which delivery timings an `InitializeResponse._meta` says the agent accepts —
+ * `_meta.steering.timings`, the sibling of the `supported` flag {@link steeringAdvertised} reads,
+ * and read from the **top-level** `_meta` for exactly the same reason.
+ *
+ * ## Empty is the answer, not the absence of one
+ *
+ * An agent that declares no timings has told us we may not name one. That is not "assume the
+ * default" — the extension ignores an unrecognised `priority` **silently** (the measurement behind
+ * ruling N4: sending `next` to today's adapters lands as `now`, which throws away the user's
+ * in-flight work). So an empty result must reach the caller as "do not specify a timing at all",
+ * and today — before the upstream PR that makes adapters broadcast this — every agent in the wild
+ * produces exactly that. Steady state, not a bug.
+ *
+ * ## Unknown values are dropped, never rejected
+ *
+ * A timing this build has never heard of is skipped and the known ones beside it survive. This
+ * client is deployed on user machines and can be older than both the agent it launches and the
+ * server it reports to; throwing (or discarding the whole array) on a value from a future version
+ * of the extension would take steering away from an agent that does support it. Non-strings are
+ * dropped the same way: `_meta` is typed `{[key: string]: unknown}`, so nothing here is guaranteed.
+ *
+ * Duplicates collapse — the wire shape is a JSON array but the fact is a set.
+ */
+export function steeringTimings(meta) {
+    if (typeof meta !== 'object' || meta === null)
+        return [];
+    const steering = meta.steering;
+    if (typeof steering !== 'object' || steering === null)
+        return [];
+    const declared = steering.timings;
+    if (!Array.isArray(declared))
+        return [];
+    const known = [];
+    for (const entry of declared) {
+        if (typeof entry !== 'string')
+            continue;
+        if (!STEER_TIMINGS.includes(entry))
+            continue;
+        if (known.includes(entry))
+            continue;
+        known.push(entry);
+    }
+    return known;
+}
+/**
+ * One `initialize` auth method, or `null` when the agent did not advertise a usable one.
+ *
+ * `initResponse` is another process's JSON that arrived over a pipe; `AuthMethod` is what this
+ * client *asked* for, not what it was handed. Both variants of that union make `id` and `name`
+ * required (`@agentclientprotocol/sdk` `types.gen.d.ts:2241-2246` for `AuthMethodTerminal`,
+ * `:2281-2286` for `AuthMethodAgent`), so an agent that omits them is off-spec -- but nothing
+ * between its stdout and here checks, and the snapshot then carries `undefined` in two positions
+ * its own type declares non-optional. That lie does not stay local: `JSON.stringify` erases an
+ * `undefined` value entirely, so the object passes every `typeof x.id` check in this process and
+ * still reaches a peer with the keys missing.
+ *
+ * `agoragentic-acp` advertises exactly `{type: 'terminal', description: '…'}`. Observing it once
+ * put a malformed `AuthMethodInfo` in the roster, which rides in every subsequent
+ * `management_hello`, which the server then cannot decode -- and a hello the server cannot decode
+ * closes the socket with nothing said, so the workstation retried into a permanent OFFLINE.
+ *
+ * Dropping rather than repairing: `id` is the value `authenticate` is called with, so inventing
+ * one would trade a missing sign-in method for a broken one.
+ */
+export function toAuthMethodSnapshot(method) {
+    if (typeof method.id !== 'string' || typeof method.name !== 'string')
+        return null;
+    // Terminal by shape (spec 2026-09-24 D6): a top-level `type: "terminal"`, or a `_meta
+    // ["terminal-auth"]` object from an agent that advertises its terminal login only there.
+    const terminal = terminalLoginSpecOf(method) !== undefined;
+    const args = 'args' in method && Array.isArray(method.args) ? method.args : terminal ? metaTerminalAuthArgs(method) : undefined;
+    return {
+        id: method.id,
+        name: method.name,
+        ...(terminal ? { type: 'terminal' } : {}),
+        ...(method.description != null ? { description: method.description } : {}),
+        // `args` only exists on a terminal method — top-level, or under `_meta["terminal-auth"]` when
+        // that is the only place the agent put it. Never the `_meta` command: see `terminalLogins`.
+        ...(args ? { args } : {}),
+    };
+}

package/dist/workstation/acp/installErrors.js

@@ -16,13 +16,13 @@
  * built.
  *
  * Three shapes, matching the three things a failed install can mean (see `acpClient.ts`'s
- * `isMissingPackageVersion`/`stderrShowsMissingPackageVersion` — the one predicate every ETARGET
+ * `stderrShowsMissingPackageVersion` — the one predicate every ETARGET
  * check in this codebase reuses rather than re-deriving):
  *
  * 1. An ordinary failure with no ETARGET in sight: a network hiccup, a full disk, a missing archive
  *    tool, a timeout. {@link friendlyOrdinaryInstallError}.
  * 2. The registry pins a version that is not published upstream, and the unpinned retry
- *    (`unpinnedFallbackFor`, `registry/launch.ts`) that tries to work around it fails too.
+ *    (`AcpAgents.installPristineWithFallback`) that tries to work around it fails too.
  *    {@link friendlyPinnedVersionUnavailableAndFallbackFailed}.
  * 3. The same missing pin, but the unpinned retry succeeds — not a failure at all, so it produces no
  *    message here. It produces a {@link PinnedVersionUnavailable} fact instead, which
@@ -87,3 +87,13 @@ export function friendlyPinnedVersionUnavailableAndFallbackFailed(agentId, pinne
     return (`The registry pins '${agentId}' to version ${pinned}, which is not published. Installing the ` +
         `latest available version instead failed too: ${shortDetail(fallbackDetail)}.${reassurance(existingVersion)}`);
 }
+/**
+ * A uv-distributed adapter, and `uv` itself is not on this workstation (the spawn failed `ENOENT`). Not a
+ * transient failure, so not "try again in a moment": the reader has to install uv first. Raised only by
+ * an Install that tried to run `uv` — scanning never checks for it.
+ */
+export function friendlyUvMissingError(agentId, existingVersion) {
+    return (`Could not install '${agentId}': uv is not installed on this workstation, and this agent is distributed ` +
+        `as a Python tool installed with uv. Install uv (https://docs.astral.sh/uv/getting-started/installation/) ` +
+        `so the workstation's service can find it on its PATH, then install the agent again.${reassurance(existingVersion)}`);
+}

package/dist/workstation/acp/installProbe.js

@@ -312,7 +312,7 @@ export function installNpxPackage(spec, options = {}) {
     // 都没有时 `npxCacheVersion` 同样是 `undefined` —— 两个 `undefined` 相等,若不单独守住这一条,
     // 一个从未被任何 npx 调用装过的包名,只要没剥版本前先被查过缓存,就会在这里被判定成"已经装好",
     // 一次 npx 都不用起。registry 自己从不发不钉版本的 spec(见 `registry/launch.ts` 的说明),这条分支
-    // 过去因此从没被真正走到过;`unpinnedFallbackFor` 的回退——`AcpAgents.installNpxWithFallback`——
+    // 过去因此从没被真正走到过;旧的 npx 安装期回退——
     // 是第一个会把不带版本的 spec 递进来的调用方,伪装成功比真的失败更糟:界面会说"已安装",磁盘上
     // 其实什么都没有。
     const pinnedVersion = npmPackageVersion(spec);