@platless/axom-cli 0.1.0

package/dist/workstation/acp/acpClient.js

@@ -0,0 +1,691 @@
+import { spawn } from 'node:child_process';
+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 {
+}
+/**
+ * A subprocess failed to start, or died before it finished responding to `initialize`.
+ *
+ * 带着子进程的 stderr 尾巴。启动期出事的时候,唯一说得清「到底哪儿不对」的就是子进程自己往 stderr
+ * 上写的那几行 —— npx 的 `npm error code ETARGET`、adapter 的崩溃栈、代理的拒绝。这里以前是
+ * `stdio: 'inherit'`,那几行只落进 daemon.log,调用方拿到的是一句
+ * "exited before responding to initialize (code=1)",服务端那头再转手就成了一条内容为空的
+ * "ACP connection closed" —— 排查的人手上什么都没有。见 {@link isMissingPackageVersion}:那条判定
+ * 需要的是证据,不是从「管子断了」倒推出来的猜测。
+ */
+export class AgentSpawnError extends Error {
+    stderr;
+    constructor(message, stderr = '') {
+        super(message);
+        this.stderr = stderr;
+    }
+}
+/** The agent opened a connection but never answered `initialize` within the allotted time. */
+export class AgentInitializeTimeoutError extends Error {
+    /** 同 {@link AgentSpawnError.stderr}:超时那一刻子进程已经写出来的东西。 */
+    stderr;
+    constructor(message, stderr = '') {
+        super(message);
+        this.stderr = stderr;
+    }
+}
+/**
+ * npm 的 `ETARGET`:**包在,但你点名的那个版本不在**。
+ *
+ * 这是唯一一个能把「registry 把版本钉错了」跟「这台机器上这个 agent 坏了」分开的信号,所以回退只
+ * 认它。npm 会同时打出机器可读的 `npm error code ETARGET` 和人话 `notarget No matching version
+ * found for <spec>`;这里匹配前者 —— 后者的措辞跨 npm 大版本改过,错误码没有。
+ *
+ * 特意**不**认 `E404`(整个包都不存在)和别的任何失败:去掉版本对它们毫无帮助,而每多认一种,
+ * 就等于给一次真实的失败额外加一整轮冷启动。
+ */
+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` 错误码——所以正则只在这一处,两个调用点都直接测字符串,而不是各自维护一份。
+ */
+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.
+ *
+ * ## Why this exists
+ *
+ * Both failure paths that can carry a sign-in — a refused `session/new` and a refused
+ * `session/prompt` — reach us as the SDK's `RequestError`, built from the peer's own
+ * `{code, message, data}` (`jsonrpc.js:844`). Everything downstream used to see only
+ * `errorMessage(err)`, which throws the code away and leaves free text; the server then had no way
+ * to tell `auth_required` from a context window overflow, and drew a login card for both. This is
+ * the one read that keeps the code, and it is placed where the original error object still exists
+ * rather than anywhere that would have to parse the flattened string back.
+ *
+ * ## Why `instanceof`, and why the two guards
+ *
+ * `instanceof RequestError` rather than a structural `typeof err.code === 'number'`: Node's own
+ * errors carry a `code` too (a string, but a duck-typed read invites the next one that does not),
+ * and the SDK class is the only thing in this process that means "a JSON-RPC peer said no".
+ *
+ * `code` is nevertheless whatever the remote agent put in its JSON — the SDK does not validate it —
+ * so it is checked before it can reach a frame. The Kotlin twin of these fields is an `Int`, and a
+ * fractional or out-of-range number does not lose precision on the way: it fails to decode and
+ * takes the **whole frame** with it, which is how `stat().mtimeMs` once cost an entire agent
+ * channel. A malformed code is reported as no code at all, which downgrades to an ordinary error
+ * card — the same thing every pre-v12 peer already gets.
+ */
+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;
+}
+function translateSpawnError(command, error, stderr) {
+    if (error.code === 'ENOENT') {
+        return new AgentSpawnError(`Could not launch '${command}': no such command on PATH. ` +
+            'If this is npx or uvx, make sure it is installed and reachable from this process.', stderr);
+    }
+    return new AgentSpawnError(`Failed to launch '${command}': ${error.message}`, stderr);
+}
+/**
+ * 子进程 stderr 留多少字节。装得下 npm 的整段报错(ETARGET 那几行不到 1KB),又不至于让一个活了
+ * 一整天的 adapter 把日志攒在内存里 —— 这条尾巴在连接建立之后还会继续被写。
+ */
+const STDERR_TAIL_LIMIT = 8_192;
+/**
+ * 子进程退出事件和它 stderr 上最后一段数据,谁先落到事件循环上,Node 不做保证 —— 而 npm 的 ETARGET
+ * 恰恰就在最后那几行里。所以 `'exit'` 之后再给 stderr 一个收尾窗口。
+ *
+ * 有界,是因为孙进程可能攥着这根管子不放(npx 正常路径下就会 spawn 真正的 adapter),那种情况下
+ * `'end'` 永远不来;等不到就带着此刻手上的那份走,而不是把调用方吊死。这段时间只花在**失败**路径上。
+ */
+const STDERR_FLUSH_GRACE_MS = 250;
+/**
+ * 把子进程的 stderr 接出来:一边原样转发到本进程的 stderr,一边留一份有界的尾巴给启动期的报错带上,
+ * 一边逐行喂给 {@link sniffAuthUrl} —— 有的 agent(实测 antigravity)不走 `elicitation/create` 递
+ * 登录链接,而是直接打到 stderr 上(见 `authUrlSniffer.ts` 的文件头注释)。
+ *
+ * 转发这件事是必须补的。这里以前是 `stdio: 'inherit'`,adapter 的诊断输出直接落进守护进程的
+ * stdio(即 daemon.log);改成 `pipe` 之后没人转,那些输出就凭空消失了 —— 修一个可观测性问题的
+ * 过程中砸掉另一个。
+ *
+ * 用 `'data'` 手动写而不是 `pipe(process.stderr)`:pipe 在源 end 时会把目的地一起 end 掉,而这里的
+ * 目的地是守护进程自己的 stderr。一个 adapter 退出就把 daemon.log 的写端关掉,比丢日志糟得多。
+ *
+ * `present` 是可选的,和 Task 3 的 `PresentElicitationUrl` 同一条规矩:没有真实的下游可以展示 URL
+ * 时,不伪造"已经展示"这件事 —— 这里的表现是干脆不嗅、不生成 elicitationId,而不是嗅到了却传给一个
+ * 空调用。嗅到的 URL 没有真实的 `elicitationId`(它压根不是通过 `elicitation/create` 到达的),所以
+ * 这里现造一个,前缀标出它的来源,便于下游区分"这是 stderr 嗅探出来的,不是协议本身的一次请求"。
+ */
+function captureChildStderr(stream, present) {
+    if (!stream)
+        return { text: () => '', flushed: () => Promise.resolve() };
+    let tail = '';
+    let lineBuffer = '';
+    // 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
+    // reader who only ever did one thing. Scoped to this connection's lifetime (a fresh `Set` per
+    // `captureChildStderr` call), not global, so a *different* connection that happens to hit the
+    // same authorize endpoint still gets its own card.
+    const presentedUrls = new Set();
+    const ended = new Promise((resolve) => {
+        stream.once('end', () => resolve());
+        stream.once('close', () => resolve());
+    });
+    const scanForAuthUrl = (text) => {
+        if (!present)
+            return;
+        lineBuffer += text;
+        const lines = lineBuffer.split('\n');
+        // The last element is either '' (the chunk ended on a newline) or a partial line still being
+        // written — either way it is not a complete line yet, so it stays in the buffer for the next
+        // chunk (or for the final scan below, once the stream ends). Capped the same way as `tail`
+        // (`STDERR_TAIL_LIMIT`): a child emitting a long run of `\r`-delimited progress output with no
+        // `\n` must not accumulate unboundedly here while waiting for a line to ever complete.
+        lineBuffer = (lines.pop() ?? '').slice(-STDERR_TAIL_LIMIT);
+        for (const line of lines) {
+            const url = sniffAuthUrl(line);
+            if (!url || presentedUrls.has(url))
+                continue;
+            presentedUrls.add(url);
+            try {
+                present(`stderr-auth-url-${randomUUID()}`, url);
+            }
+            catch (error) {
+                // A caller's `present` must never take the whole daemon down over an unhandled exception
+                // thrown from inside a `'data'` listener — there is no `uncaughtException` handler
+                // anywhere in `src/` (`daemon.ts` registers only `unhandledRejection`), so letting this
+                // escape would kill every session on the workstation over one bad transport write, not
+                // just this login. Same reasoning as `stream.on('error', () => {})` a few lines below,
+                // applied to the injected callback instead of the stream itself.
+                console.error(`[acp] present() threw while surfacing a login url sniffed from stderr: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    };
+    stream.on('data', (chunk) => {
+        const text = chunk.toString();
+        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'));
+    return {
+        text: () => tail,
+        flushed: (ms) => settledWithin(ended, ms).then(() => undefined),
+    };
+}
+/**
+ * 子进程死掉之后,SDK 会用一句 `ACP connection closed` 把还没回来的 `initialize` 拒掉 —— 它是从
+ * stdout 上读到 EOF 推出来的,里面没有一个字说明为什么关。真正的原因在子进程的 stderr 上,由
+ * {@link watchChildLifecycle} 收着;但这两条 reject 谁先到达 `Promise.race` 完全不确定,实测 SDK
+ * 那条几乎总是先到 —— 生产上看到的那句内容为空的 "ACP connection closed" 就是它。
+ *
+ * 所以失败时不认「谁先到」:再等一小会儿,子进程要是确实死了,就换成它那条带 stderr 的错误。上限比
+ * {@link STDERR_FLUSH_GRACE_MS} 宽一点,因为那条错误本身就要等满收尾窗口才发得出来。
+ */
+const CHILD_FAILURE_GRACE_MS = STDERR_FLUSH_GRACE_MS + 100;
+/** `failure` 在 `ms` 之内 reject 出来的那个错误,否则 `undefined`。计时器总会被清掉。 */
+function rejectionWithin(failure, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(undefined), ms);
+        failure.catch((error) => {
+            clearTimeout(timer);
+            resolve(error);
+        });
+    });
+}
+/** 报错正文里只放最后几行;完整尾巴留在 `.stderr` 上给 {@link isMissingPackageVersion} 这类程序读。 */
+function lastStderrLines(text, count) {
+    return text.split('\n').map((line) => line.trim()).filter(Boolean).slice(-count).join(' | ');
+}
+/**
+ * Watches a freshly spawned child for the two ways it can die before answering `initialize`: a
+ * failed spawn (`'error'`, e.g. ENOENT when the launcher binary is missing — the daemon's launchd
+ * environment has a minimal PATH, so this is not hypothetical) and an early exit. Node throws an
+ * unhandled exception if a `ChildProcess` ever emits `'error'` with no listener attached, so this
+ * must be wired up synchronously, right after `spawn()`, before anything else has a chance to await.
+ *
+ * The returned promise is pre-`.catch()`-ed so that when `initialize` or the timeout wins the race
+ * in `connectAgent` instead, a later `'error'`/`'exit'` on this same child does not surface as an
+ * unhandled rejection.
+ *
+ * 退出报错要等 {@link ChildStderr.flushed} 才发出去:一个 `code=1` 的退出码本身什么也没说,把子进程
+ * 死前写在 stderr 上的那几行一起带上,才是这个错误对调用方唯一有价值的部分。
+ */
+function watchChildLifecycle(child, command, stderr) {
+    let onError;
+    let onExit;
+    const failure = new Promise((_, reject) => {
+        onError = (error) => reject(translateSpawnError(command, error, stderr.text()));
+        onExit = (code, signal) => {
+            const summary = `Agent process for '${command}' exited before responding to initialize ` +
+                `(code=${code ?? 'null'}, signal=${signal ?? 'null'}).`;
+            void stderr.flushed(STDERR_FLUSH_GRACE_MS).then(() => {
+                const detail = stderr.text().trim();
+                reject(new AgentSpawnError(detail ? `${summary} stderr: ${lastStderrLines(detail, 6)}` : summary, detail));
+            });
+        };
+        child.once('error', onError);
+        child.once('exit', onExit);
+    });
+    failure.catch(() => { });
+    return {
+        failure,
+        dispose() {
+            child.off('error', onError);
+            child.off('exit', onExit);
+        },
+    };
+}
+/**
+ * How long {@link closeAgentTransport} waits for a signalled child to actually exit, per signal.
+ * SIGTERM's default disposition ends a Node process immediately, so this is only ever spent on an
+ * adapter that installs its own handler — and even then, spending it is the point: the wait is what
+ * keeps our read end attached until the child is gone.
+ */
+const CHILD_EXIT_GRACE_MS = 2_000;
+/** Resolves `true` if `settled` wins the race, `false` if `ms` elapses first. The timer is always cleared, so a fast exit never keeps the event loop alive. */
+function settledWithin(settled, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), ms);
+        void settled.then(() => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+}
+/**
+ * End the agent subprocess **before** tearing the protocol streams down, and exported so a test can
+ * pin that order.
+ *
+ * The order used to be the other way round, and it made a mid-turn close kill the adapter with an
+ * uncaught `EPIPE` (reproduced on a real ACP adapter; closing an idle connection was always clean).
+ * `connection.close()` cancels the reader over the child's stdout, which destroys our end of that
+ * pipe; an adapter still writing its turn then takes `EPIPE` on its next write, has no listener for
+ * it, and dies printing a full Node crash stack. The child's stderr is forwarded verbatim into this
+ * process's own stderr (see `captureChildStderr`) and the daemon's stdio is redirected into
+ * `daemon.log`, so every mid-turn close left a crash stack in the user's log — noise sitting exactly
+ * where someone would look for a real fault.
+ *
+ * Signalling first and *waiting for the exit* is what fixes it: the child is gone before anything
+ * touches the pipe, so there is no broken pipe left to hand it. Signal-then-teardown without the
+ * wait would only narrow the race, not close it — `kill()` returns as soon as the signal is sent.
+ *
+ * Chosen over the other candidate fix (close stdin, let the adapter exit on EOF, then kill after a
+ * grace) because that one pays its grace period on *every* close for any adapter that does not
+ * happen to exit on stdin EOF, and nothing in ACP v1 requires one to. This costs nothing in the
+ * common case: SIGTERM's default disposition is immediate termination, so the wait is already over
+ * by the next tick. Nothing is lost by not shutting down more gently — a crashed adapter's session
+ * still replays in full through `session/load` on reconnect (verified on a real adapter), because
+ * the adapter persists it itself.
+ */
+export async function closeAgentTransport(child, connection, graceMs = CHILD_EXIT_GRACE_MS) {
+    if (child.exitCode === null && child.signalCode === null) {
+        const exited = new Promise((resolve) => {
+            child.once('exit', () => resolve());
+        });
+        child.kill();
+        // SIGKILL for an adapter that traps SIGTERM and lingers: waiting on it forever would hang every
+        // caller of `close()`, and tearing the streams down while it still runs is the defect itself.
+        if (!(await settledWithin(exited, graceMs))) {
+            child.kill('SIGKILL');
+            await settledWithin(exited, graceMs);
+        }
+    }
+    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.
+ */
+export async function connectAgent(spec, env, agentEnv, options = {}) {
+    assertNodeVersionSupported(spec, options.nodeVersion);
+    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 },
+    });
+    const stderrTail = captureChildStderr(child.stderr, options.present);
+    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 app = client({ name: 'axom' });
+    options.configure?.(app);
+    const connection = app.connect(stream);
+    const timeoutMs = options.initializeTimeoutMs ?? DEFAULT_INITIALIZE_TIMEOUT_MS;
+    let timeoutHandle;
+    const timeout = new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => {
+            // 超时也把 stderr 带上:npx 在慢机器上会把整个 initialize 预算耗光之后才让子进程死掉,那时候
+            // 真正的原因(比如 ETARGET)早就写在这里了,只是赢下 race 的是计时器而不是 `'exit'`。
+            const detail = stderrTail.text().trim();
+            reject(new AgentInitializeTimeoutError(`Agent '${spec.command}' did not respond to initialize within ${timeoutMs}ms.` +
+                (detail ? ` Last stderr: ${lastStderrLines(detail, 6)}` : ''), detail));
+        }, timeoutMs);
+    });
+    timeout.catch(() => { });
+    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),
+                    },
+                }),
+            }),
+            lifecycle.failure,
+            timeout,
+        ]);
+    }
+    catch (error) {
+        // 先决定要抛哪一个,**再**动子进程:`child.kill()` 之后 `'exit'` 一样会让 lifecycle reject,
+        // 那时候拿到的"子进程死了"是我们自己造成的,拿它盖掉一个真实的协议错误就是在制造假线索。
+        const failure = error instanceof AgentSpawnError || error instanceof AgentInitializeTimeoutError
+            ? error
+            : ((await rejectionWithin(lifecycle.failure, CHILD_FAILURE_GRACE_MS)) ?? error);
+        connection.close(failure);
+        child.kill();
+        throw failure;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+        lifecycle.dispose();
+    }
+    // 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 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) {
+        // 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 ` +
+            'id/name; ignoring them');
+    }
+    return {
+        capabilities,
+        authMethods,
+        supportsSteering: steeringAdvertised(initResponse._meta),
+        steeringTimings: steeringTimings(initResponse._meta),
+        agentInfo: initResponse.agentInfo ?? undefined,
+        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),
+    };
+}