@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/acpClient.js

@@ -3,10 +3,13 @@ import { randomUUID } from 'node:crypto';
 import { Readable, Writable } from 'node:stream';
 import { client, ndJsonStream, PROTOCOL_VERSION, RequestError } from '@agentclientprotocol/sdk';
 import { sniffAuthUrl } from './authUrlSniffer.js';
-import { airCapabilityMeta, asSdkClientCapabilities, AIR_ASYNC_TASKS_CAPABILITY, AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, DRAFT_SUBAGENTS_CAPABILITY, } from './draftSubagents.js';
-import { interceptDraftUpdates } from './draftInterceptor.js';
-export class UnsupportedNodeVersionError extends Error {
-}
+import { overlayEnvSecrets } from './envSecrets.js';
+import { secretForms } from '../keepers/acp/stderr.js';
+import { initializeRequestParams, jsonRpcErrorCodeOf, parseInitializeResult, } from './initializeResponse.js';
+import { withPathPrefix } from './registry/launch.js';
+// Moved to `initializeResponse.ts` (shared with the deterministic processor); re-exported so every
+// existing importer of these names is unchanged.
+export { STEER_TIMINGS, steeringAdvertised, steeringTimings, toAuthMethodSnapshot, } from './initializeResponse.js';
 /**
  * A subprocess failed to start, or died before it finished responding to `initialize`.
  *
@@ -14,8 +17,7 @@ export class UnsupportedNodeVersionError extends Error {
  * 上写的那几行 —— npx 的 `npm error code ETARGET`、adapter 的崩溃栈、代理的拒绝。这里以前是
  * `stdio: 'inherit'`,那几行只落进 daemon.log,调用方拿到的是一句
  * "exited before responding to initialize (code=1)",服务端那头再转手就成了一条内容为空的
- * "ACP connection closed" —— 排查的人手上什么都没有。见 {@link isMissingPackageVersion}:那条判定
- * 需要的是证据,不是从「管子断了」倒推出来的猜测。
+ * "ACP connection closed" —— 排查的人手上什么都没有。
  */
 export class AgentSpawnError extends Error {
     stderr;
@@ -45,156 +47,15 @@ export class AgentInitializeTimeoutError extends Error {
  */
 const NPM_ETARGET = /(?:^|[^A-Z])ETARGET(?![A-Z])/;
 /**
- * 判定规则本身,脱离 {@link AgentSpawnError}/{@link AgentInitializeTimeoutError} 单独导出 ——
- * `installNpxPackage`(`installProbe.ts`)是这条规则的第二个读者:它下载适配器失败时报的是一段
- * `InstallOutcome.error`/`stderr` 字符串,不是这两个类里的一个实例,没有 `.stderr` 字段可供
- * {@link isMissingPackageVersion} 去 `instanceof` 窄化。两个调用点都要认同一件事——npm 自己打在
- * stderr 上的 `ETARGET` 错误码——所以正则只在这一处,两个调用点都直接测字符串,而不是各自维护一份。
+ * 判定规则本身:npm 自己打在 stderr 上的 `ETARGET` 错误码。读者是安装期的回退
+ * (`AcpAgents.installPristineWithFallback`)——启动期不再有回退,启动从不解析版本(spec 2026-10-11 §6.2)。
  */
 export function stderrShowsMissingPackageVersion(stderr) {
     return NPM_ETARGET.test(stderr);
 }
-/**
- * 这次启动失败,是不是因为 registry 钉的版本 npm 根本没有。
- *
- * 只看 {@link AgentSpawnError.stderr} / {@link AgentInitializeTimeoutError.stderr} 里的原始文本 ——
- * 超时也算进来是因为实测过:npx 在一台慢机器上可以把 20s 的 initialize 预算耗光之后才让子进程死掉,
- * 那时候 ETARGET 早就写在 stderr 上了,只是赢下 race 的是计时器。
- */
-export function isMissingPackageVersion(error) {
-    if (!(error instanceof AgentSpawnError) && !(error instanceof AgentInitializeTimeoutError))
-        return false;
-    return stderrShowsMissingPackageVersion(error.stderr);
-}
 /** The agent negotiated a protocol version this client does not speak. */
 export class UnsupportedProtocolVersionError extends Error {
 }
-/**
- * Minimum Node.js major version a known agent package requires, keyed by its npx package name
- * (unversioned — matched against both a bare specifier and a version-pinned one; see
- * `argMatchesPackage`).
- *
- * The registry has no field for this — verified fact, not an oversight to fix here. The only place
- * a Node requirement is declared is the agent package's own `package.json#engines`, and `npx` does
- * not enforce it: it just runs the package under whatever `node` is already on PATH. Getting this
- * wrong means the user sees a subprocess crash stack instead of an actionable message (ruling R7),
- * so this table exists to catch the one adapter known, as of 2026-08-21, to need it.
- */
-const KNOWN_MIN_NODE_MAJOR = [
-    { packageName: '@agentclientprotocol/claude-agent-acp', minMajor: 22 },
-];
-/**
- * True when `arg` is exactly `packageName`, or `packageName` followed by an `@version` suffix.
- * `arg.startsWith(packageName)` alone would also match an unrelated package that merely shares a
- * prefix (e.g. `@agentclientprotocol/claude-agent-acp-extra`); anchoring on an exact match or an
- * `@` boundary rules that out while still matching ruling R3's user-supplied, unpinned
- * `command`/`args` override, which has no version suffix to key off at all.
- */
-function argMatchesPackage(arg, packageName) {
-    return arg === packageName || arg.startsWith(`${packageName}@`);
-}
-/** Exported for tests: derives the minimum Node major version a launch spec requires, if known. */
-export function requiredNodeMajorFor(spec) {
-    const match = KNOWN_MIN_NODE_MAJOR.find((entry) => spec.args.some((arg) => argMatchesPackage(arg, entry.packageName)));
-    return match?.minMajor;
-}
-/**
- * Throws a message a user can act on when this machine's Node is older than a known agent
- * requires. `nodeVersion` defaults to the real running Node; it takes an explicit override so tests
- * can exercise both sides of the gate without depending on the host's actual Node version —
- * `process.versions.node` is a frozen property and cannot be stubbed.
- */
-export function assertNodeVersionSupported(spec, nodeVersion = process.versions.node) {
-    const required = requiredNodeMajorFor(spec);
-    if (required === undefined)
-        return;
-    const currentMajor = Number.parseInt(nodeVersion.split('.')[0] ?? '', 10);
-    if (Number.isNaN(currentMajor) || currentMajor < required) {
-        throw new UnsupportedNodeVersionError(`This agent requires Node.js >= ${required}, but this machine is running Node.js ${nodeVersion}. ` +
-            'Install a newer Node.js and try again.');
-    }
-}
-/**
- * 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;
-}
 /**
  * The JSON-RPC error code an agent answered with, or `undefined` when the failure was not one an
  * agent answered at all.
@@ -225,10 +86,7 @@ export function steeringTimings(meta) {
 export function jsonRpcErrorCode(error) {
     if (!(error instanceof RequestError))
         return undefined;
-    const { code } = error;
-    if (!Number.isInteger(code))
-        return undefined;
-    return code >= -2_147_483_648 && code <= 2_147_483_647 ? code : undefined;
+    return jsonRpcErrorCodeOf(error.code);
 }
 function translateSpawnError(command, error, stderr) {
     if (error.code === 'ENOENT') {
@@ -251,7 +109,7 @@ const STDERR_TAIL_LIMIT = 8_192;
  */
 const STDERR_FLUSH_GRACE_MS = 250;
 /**
- * 把子进程的 stderr 接出来:一边原样转发到本进程的 stderr,一边留一份有界的尾巴给启动期的报错带上,
+ * 把子进程的 stderr 接出来:普通连接原样转发,托管 MCP 请求后的输出逐行脱敏,并留一份有界的安全尾巴给报错带上,
  * 一边逐行喂给 {@link sniffAuthUrl} —— 有的 agent(实测 antigravity)不走 `elicitation/create` 递
  * 登录链接,而是直接打到 stderr 上(见 `authUrlSniffer.ts` 的文件头注释)。
  *
@@ -269,9 +127,41 @@ const STDERR_FLUSH_GRACE_MS = 250;
  */
 function captureChildStderr(stream, present) {
     if (!stream)
-        return { text: () => '', flushed: () => Promise.resolve() };
+        return { text: () => '', flushed: () => Promise.resolve(), redactValue: () => { } };
     let tail = '';
     let lineBuffer = '';
+    let protectedLine = '';
+    let droppingLongLine = false;
+    /** {@link ChildStderr.redactValue}'s forms. */
+    const quiet = new Set();
+    const redactAll = (text) => {
+        let safe = text;
+        for (const secret of quiet)
+            safe = safe.replaceAll(secret, '[REDACTED]');
+        return safe;
+    };
+    const forward = (value) => {
+        tail = (tail + value).slice(-STDERR_TAIL_LIMIT);
+        process.stderr.write(value);
+    };
+    const forwardProtected = (value) => {
+        protectedLine += value;
+        let newline;
+        while ((newline = protectedLine.indexOf('\n')) >= 0) {
+            if (droppingLongLine) {
+                droppingLongLine = false;
+            }
+            else {
+                forward(redactAll(protectedLine.slice(0, newline + 1)));
+            }
+            protectedLine = protectedLine.slice(newline + 1);
+        }
+        if (protectedLine.length > STDERR_TAIL_LIMIT) {
+            protectedLine = '';
+            droppingLongLine = true;
+            forward('[acp] child stderr line omitted\n');
+        }
+    };
     // One login can print its own URL more than once — the ordinary shape of an OAuth CLI is "here's
     // the link" immediately followed by "if your browser didn't open, here it is again", verbatim
     // the same URL. Without this, that becomes two permanent, identical, un-retractable cards for a
@@ -315,19 +205,36 @@ function captureChildStderr(stream, present) {
     };
     stream.on('data', (chunk) => {
         const text = chunk.toString();
-        tail = (tail + text).slice(-STDERR_TAIL_LIMIT);
-        process.stderr.write(chunk);
-        scanForAuthUrl(text);
+        if (quiet.size > 0) {
+            forwardProtected(text);
+            scanForAuthUrl(text);
+        }
+        else {
+            tail = (tail + text).slice(-STDERR_TAIL_LIMIT);
+            process.stderr.write(chunk);
+            scanForAuthUrl(text);
+        }
     });
     // 读端出错(SIGKILL 掉子进程时管子会断)没有谁需要处理,但一个没有监听器的 `'error'` 会把整个
     // 守护进程掀翻 —— 这行不是防御性代码,是 EventEmitter 的硬性要求。
     stream.on('error', () => { });
     // A final unterminated line (no trailing `\n` before the process exits) is still a real line —
     // scan whatever is left in the buffer once the stream itself says there is no more coming.
-    void ended.then(() => scanForAuthUrl('\n'));
+    void ended.then(() => {
+        if (protectedLine && !droppingLongLine)
+            forward(redactAll(protectedLine));
+        scanForAuthUrl('\n');
+    });
     return {
         text: () => tail,
         flushed: (ms) => settledWithin(ended, ms).then(() => undefined),
+        redactValue: (value) => {
+            // Longest first, so a form containing another is removed whole (Set order is insertion order).
+            const all = [...quiet, ...secretForms(value)].sort((a, b) => b.length - a.length);
+            quiet.clear();
+            for (const form of all)
+                quiet.add(form);
+        },
     };
 }
 /**
@@ -350,7 +257,7 @@ function rejectionWithin(failure, ms) {
         });
     });
 }
-/** 报错正文里只放最后几行;完整尾巴留在 `.stderr` 上给 {@link isMissingPackageVersion} 这类程序读。 */
+/** 报错正文里只放最后几行;完整尾巴留在 `.stderr` 上给程序读。 */
 function lastStderrLines(text, count) {
     return text.split('\n').map((line) => line.trim()).filter(Boolean).slice(-count).join(' | ');
 }
@@ -451,94 +358,41 @@ export async function closeAgentTransport(child, connection, graceMs = CHILD_EXI
     connection.close();
     await connection.closed.catch(() => { });
 }
-/**
- * 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.
- */
-function toAuthMethodSnapshot(method) {
-    if (typeof method.id !== 'string' || typeof method.name !== 'string')
-        return null;
-    return {
-        id: method.id,
-        name: method.name,
-        ...('type' in method && method.type === 'terminal' ? { type: 'terminal' } : {}),
-        ...(method.description != null ? { description: method.description } : {}),
-        // `args` only exists on `AuthMethodTerminal` — an `agent`-type method has no such field, and
-        // `'args' in method` is false for it, which is exactly "nothing to show" (see `AgentAuthMethod`).
-        ...('args' in method && Array.isArray(method.args) ? { args: method.args } : {}),
-    };
-}
 const DEFAULT_INITIALIZE_TIMEOUT_MS = 30_000;
 /**
  * Spawns an ACP agent subprocess, connects to it over ndjson stdio, and negotiates capabilities
  * via `initialize`. `env` and `agentEnv` are overlay layers on top of the current process
  * environment, not full environments (existing contract carried over from the deleted bridge
  * transport): if `PATH` is present in either, it has already been resolved by the caller and must
- * not be prefixed with anything else here.
+ * not be prefixed with anything else here — except the spec's own `pathPrefix` (a build's
+ * `node_modules/.bin`), which the adapter needs whatever `PATH` it is given.
  */
 export async function connectAgent(spec, env, agentEnv, options = {}) {
-    assertNodeVersionSupported(spec, options.nodeVersion);
+    // No Node gate here any more: a build's `engines.node` is checked against the Node that runs it when
+    // the spec is made (`launchForBuild`, `builds/nodeGate.ts`); a config `command` override is the user's own.
+    // A build's own PATH prefix (`node_modules/.bin`) must survive a server- or agent-supplied PATH.
+    const processEnv = withPathPrefix({ ...process.env, ...spec.env, ...env, ...agentEnv }, spec.pathPrefix);
     const child = spawn(spec.command, spec.args, {
         // stderr 是 `pipe` 而不是 `inherit`,而且**依然不接进协议流** —— 它被 `captureChildStderr`
         // 单独读走:原样转发到 daemon.log(`inherit` 以前免费提供的那件事),同时留一份尾巴给启动期的
         // 报错。启动失败时 npm 写在这里的文字是唯一的一手证据。
         stdio: ['pipe', 'pipe', 'pipe'],
-        env: { ...process.env, ...spec.env, ...env, ...agentEnv },
+        env: processEnv,
     });
     const stderrTail = captureChildStderr(child.stderr, options.present);
+    for (const value of overlayEnvSecrets({ env, agentEnv }))
+        stderrTail.redactValue(value);
     const lifecycle = watchChildLifecycle(child, spec.command, stderrTail);
     // Argument order reads backwards from what the names suggest: argument 1 is the child's stdin
     // (we write to it), argument 2 is the child's stdout (we read from it). Swapping them still
     // compiles and still "connects" — the initialize request just never arrives, so the failure mode
     // is a hang, not an error.
-    // Filled in by `bindDraftUpdates` once a session exists. Held in closure variables rather than
-    // passed in, because the interceptor has to be in place before `initialize` — the agent may send
-    // its first update before anyone has had a chance to register anything.
-    let ownSessionId = null;
-    let draftSink = null;
-    // Sessions this connection handles by some route other than an `AcpSession` — today only
-    // adoption's replay. Kept beside `ownSessionId` rather than folded into it because they mean
-    // different things: one is "the session we drive", these are "sessions someone else on this
-    // connection is already reading".
-    const knownSessionIds = new Set();
-    const stream = ndJsonStream(Writable.toWeb(child.stdin), 
-    // The child's stdout, minus the notifications the pinned SDK cannot deliver. Everything else
-    // reaches it byte-for-byte; see `draftInterceptor.ts` for the measurements behind this.
-    interceptDraftUpdates(Readable.toWeb(child.stdout), {
-        // Unbound means unknown, and unknown must not be claimed as ours: treating a session we have
-        // not been told about as our own would send its frames to the SDK, which drops them silently.
-        // Diverting is the recoverable direction — the sink can decide, and it can log.
-        isOwnSession: (sessionId) => (ownSessionId !== null && sessionId === ownSessionId) || knownSessionIds.has(sessionId),
-        onDiverted: (update) => {
-            if (draftSink) {
-                draftSink(update);
-                return;
-            }
-            // No sink yet: say so once per update rather than dropping in silence. This is reachable
-            // only before the session is bound, which is before any prompt, so it should stay rare —
-            // and if it stops being rare, that is worth seeing.
-            console.warn(`[acp] dropped a ${update.reason} session/update for '${update.sessionId}': ` +
-                'no session is bound to this connection yet');
-        },
-    }));
+    const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
     const app = client({ name: 'axom' });
-    options.configure?.(app);
+    // This adapter process's generation: the scope `permission.ts`'s `permissionRequestId` derives card ids in (a sign-in's
+    // connection registers the permission handlers).
+    const generation = randomUUID();
+    options.configure?.(app, { generation });
     const connection = app.connect(stream);
     const timeoutMs = options.initializeTimeoutMs ?? DEFAULT_INITIALIZE_TIMEOUT_MS;
     let timeoutHandle;
@@ -555,53 +409,7 @@ export async function connectAgent(spec, env, agentEnv, options = {}) {
     let initResponse;
     try {
         initResponse = await Promise.race([
-            connection.agent.request('initialize', {
-                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`).
-                    elicitation: { url: {} },
-                    _meta: {
-                        'subagent-transcript': true,
-                        ...airCapabilityMeta(AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, AIR_ASYNC_TASKS_CAPABILITY),
-                    },
-                }),
-            }),
+            connection.agent.request('initialize', initializeRequestParams()),
             lifecycle.failure,
             timeout,
         ]);
@@ -622,68 +430,37 @@ export async function connectAgent(spec, env, agentEnv, options = {}) {
     }
     // Global Constraint 1 is v1-only; the schema calls for disconnecting when the agent didn't
     // accept the version this client sent.
-    if (initResponse.protocolVersion !== PROTOCOL_VERSION) {
+    const reading = parseInitializeResult(initResponse);
+    if (!reading.protocolSupported) {
         const error = new UnsupportedProtocolVersionError(`Agent '${spec.command}' negotiated protocol version ${initResponse.protocolVersion}, ` +
             `but this client only supports version ${PROTOCOL_VERSION}.`);
         connection.close(error);
         child.kill();
         throw error;
     }
-    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,
-        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,
-    };
-    // 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);
-    if (authMethods.length !== advertisedAuthMethods.length) {
+    // Capabilities, auth methods and steering are read in `initializeResponse.ts`, the one reading the
+    // deterministic processor shares — see that file for the rules.
+    const { capabilities, authMethods, droppedAuthMethods } = reading;
+    const terminalLogins = new Map(reading.terminalLogins);
+    if (droppedAuthMethods > 0) {
         // Named and counted rather than dropped in silence: the user loses a sign-in method they can
         // see advertised in the agent's own docs, and the only honest answer to "why" is which agent
         // sent what. `agentInfo.name` first because most agents launch through `npx`/`uvx` and
         // `spec.command` would then name the launcher, which identifies none of the ~40 registry
         // entries. See `toAuthMethodSnapshot` for what accepting these costs instead.
         console.warn(`[acp] agent '${initResponse.agentInfo?.name ?? spec.command}' advertised ` +
-            `${advertisedAuthMethods.length - authMethods.length} auth method(s) without the required ` +
+            `${droppedAuthMethods} auth method(s) without the required ` +
             'id/name; ignoring them');
     }
     return {
         capabilities,
         authMethods,
-        supportsSteering: steeringAdvertised(initResponse._meta),
-        steeringTimings: steeringTimings(initResponse._meta),
-        agentInfo: initResponse.agentInfo ?? undefined,
+        terminalLogins,
+        supportsAccountLimits: reading.supportsAccountLimits,
+        supportsSteering: reading.supportsSteering,
+        steeringTimings: reading.steeringTimings,
+        agentInfo: reading.agentInfo,
         connection,
-        agentProcessAlive: () => child.exitCode === null && child.signalCode === null,
-        bindDraftUpdates(sessionId, sink) {
-            ownSessionId = sessionId;
-            draftSink = sink;
-        },
-        markSessionKnown(sessionId) {
-            knownSessionIds.add(sessionId);
-            return () => knownSessionIds.delete(sessionId);
-        },
         // Child first, streams second — see `closeAgentTransport` for why that order is the fix and not
         // an incidental detail.
         close: () => closeAgentTransport(child, connection),

package/dist/workstation/acp/activityBusy.js

@@ -0,0 +1,43 @@
+/**
+ * 「这条会话的 agent 自己说它在忙吗」——一个**弱**判据，不是归一化器。
+ *
+ * 真正的 vendor 原文 → 规范三态只发生在服务端 `axom-core` 的 `agentActivityOf`
+ * （前序 spec 裁决 L1：归一化只在一处）。这里要回答的问题窄得多，答案只有两种，
+ * 而且两边对「读不懂」的处置是同一条推理：服务端答 `null`（保留上一个已知状态，不写库），
+ * 这里答 `false`（本来源不主张忙碌，判据退回 `liveness.turnRunning`）。两边都不把未知
+ * 伪装成已知——答 `true` 会造出一个永不消失的假忙碌，正是本轮要消灭的东西。
+ *
+ * 两个键分属两套词汇表（claude 的 `state`、codex 的 `type`），**不做或运算**：
+ * `state` 在就只看 `state`。混读等于承认一份原文可以同时是两种方言。
+ */
+export function activityIsBusy(raw) {
+    if (!raw)
+        return false;
+    if (typeof raw.state === 'string')
+        return raw.state === 'running' || raw.state === 'requires_action';
+    if (typeof raw.type === 'string')
+        return raw.type === 'active' && !codexBlockedOnHumanOnly(raw);
+    return false;
+}
+/**
+ * codex 的 `activeFlags` 里表示「agent 正被人挡住、没有在算」的标记。
+ *
+ * **和会话状态问的不是同一个问题。** 服务端的 `agentActivityOf` 要答「vendor 说它在干什么」，
+ * 这里要答「排干时有没有在途工作会被重启破坏」。一条停在审批卡或提问上的会话，两个答案不同：
+ * 它确实处在 vendor 说的 `active`，但**没有任何在途工作**，重启它不损失什么。把这种会话算成忙，
+ * 会让一次优雅更新白等满 30 分钟排干再报 BUSY —— 正是本分支要消灭的那个形状，只是换了个入口。
+ * 2026-09-21 在真机上抓到的第一条 codex 原文就是这一种：
+ * `{"type":"active","activeFlags":["waitingOnUserInput"]}`。
+ *
+ * 值域的取证、证据等级，以及「不认识的标记为什么保持忙」的理由，见 `axom-core` 的
+ * `AgentActivityMapping.kt` 里 `CODEX_BLOCKED_ON_HUMAN_FLAGS` 的 KDoc —— 那里是权威说明，
+ * 这两处必须同时改，所以判据故意写成同一个形状（非空 + 每一项都认得）。
+ */
+const CODEX_BLOCKED_ON_HUMAN_FLAGS = new Set(['waitingOnApproval', 'waitingOnUserInput']);
+/** `activeFlags` 非空**且每一项**都在 {@link CODEX_BLOCKED_ON_HUMAN_FLAGS} 里。 */
+function codexBlockedOnHumanOnly(raw) {
+    const flags = raw.activeFlags;
+    if (!Array.isArray(flags) || flags.length === 0)
+        return false;
+    return flags.every((flag) => typeof flag === 'string' && CODEX_BLOCKED_ON_HUMAN_FLAGS.has(flag));
+}

package/dist/workstation/acp/activityReporting.js

@@ -0,0 +1,54 @@
+/**
+ * 两条厂商特定的活动状态采集路径。**只做搬运，不做归一化**——vendor→规范三态的映射
+ * 只发生在服务端 ingest 一处（裁决 L1：normalise in one place, server ingest）。
+ *
+ * 判 agent 用 `InitializeResponse.agentInfo.name`：ACP 的 `Implementation.name` 文档自述
+ * "intended for programmatic or logical use"，而且用户改不了它（`agentName` 是工作站配置里的
+ * 条目名，随时可以改）。
+ */
+const CLAUDE_AGENT = '@agentclientprotocol/claude-agent-acp';
+const CODEX_AGENT = '@agentclientprotocol/codex-acp';
+/** 这个 agent 有没有配套的活动状态采集器；按 InitializeResponse.agentInfo.name 判。 */
+export function reportsActivity(agentName) {
+    return agentName === CLAUDE_AGENT || agentName === CODEX_AGENT;
+}
+/** Certified AIR task-stop compatibility, independent of activity collection. These adapters
+ * implement `_session/async_task/stop`; this is NOT a native child-session cancel declaration.
+ * Keep this separate even while the certified provider sets happen to coincide.
+ */
+export function supportsAsyncTaskStop(agentName) {
+    return agentName === CLAUDE_AGENT || agentName === CODEX_AGENT;
+}
+/**
+ * claude-agent-acp 的 `emitRawSDKMessages`（`acp-agent.d.ts:645`，0.75.1 起存在）：
+ * 命中过滤器的原始 SDK 消息会以 `extNotification("_claude/sdkMessage", …)` 推回来。
+ * 只要状态那一种——过滤器是 `SDKMessageFilter { type, subtype? }`（`:609`）。
+ */
+export function newSessionMetaFor(agentName) {
+    if (agentName !== CLAUDE_AGENT)
+        return undefined;
+    return { claudeCode: { emitRawSDKMessages: [{ type: 'system', subtype: 'session_state_changed' }] } };
+}
+function asObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** claude：把 _claude/sdkMessage 的 params 提成 vendor 原文，非状态消息返回 null。 */
+export function claudeActivityRaw(params) {
+    const message = asObject(params?.message);
+    if (!message)
+        return null;
+    if (message.type !== 'system' || message.subtype !== 'session_state_changed')
+        return null;
+    // 整条消息原样带走，不挑字段：服务端要的是证据，而将来 SDK 给这条消息加字段时
+    // 这里不该是需要改的地方。
+    return message;
+}
+/** codex：把 session_info_update 的 _meta 提成 vendor 原文，没有状态返回 null。 */
+export function codexActivityRaw(meta) {
+    const codex = asObject(meta?.codex);
+    if (!codex)
+        return null;
+    return asObject(codex.threadStatus);
+}