@platless/axom-cli 0.1.0

package/dist/workstation/acp/test/fakeAgent.js

@@ -0,0 +1,435 @@
+// @ts-nocheck
+// Deliberately valid JavaScript, not a module TypeScript needs to type-check: `acpClient.test.ts`
+// runs this fixture as a real, separate OS process that speaks ACP over ndjson stdio, through a
+// Node 20-safe `node -e` bootstrap: `eval(readFileSync(process.argv[1], 'utf8'))`. (The trick was
+// borrowed from the Codex app-server fake, `src/test/fakeAppServer.ts`, which Task 8 deleted along
+// with the native bridges — the path is history, not somewhere to look.) That bootstrap evaluates
+// this file's raw source as plain JavaScript — it never goes through `tsc`, so top-level `import`/
+// `export` syntax would be a SyntaxError here. `require()` reaches Node builtins; the ACP SDK is
+// ESM-only (no CJS build), so it is reached with a dynamic `import()`, which works from CJS too.
+//
+// This is a REAL ACP agent built on the SDK's own `agent()` builder — not a hand-rolled stand-in
+// for our own client. The contract suite (a later task) depends on that being true, and depends on
+// this fixture being able to present different capability sets so tests can cover both "advertises
+// X" and "does not advertise X" without forking the file. Everything an agent would normally decide
+// for itself (capabilities, authMethods, the session id `session/new` hands back, and the
+// `session/update` notifications `session/prompt` sends before it stops) is instead read from a
+// JSON config on argv[2], so callers configure behavior without touching this file.
+//
+// Config shape (all fields optional):
+//   {
+//     agentCapabilities?: AgentCapabilities,   // passed through verbatim into InitializeResponse
+//     authMethods?: AuthMethod[],              // passed through verbatim into InitializeResponse
+//     agentInfo?: Implementation,
+//     initializeMeta?: object,                 // passed through verbatim as InitializeResponse._meta
+//                                               // — the TOP-LEVEL one, a sibling of
+//                                               // agentCapabilities. That is where the steering
+//                                               // extension advertises itself
+//                                               // (`claude-agent-acp` `acp-agent.js@0.76.0:944-950`),
+//                                               // so a test can present `{steering:{supported:true}}`
+//                                               // and, just as importantly, an agent that says
+//                                               // nothing at all
+//     sessionId?: string,                      // default 'fake-session'
+//     updates?: SessionUpdate[],               // sent as session/update notifications during prompt
+//     stopReason?: StopReason,                 // default 'end_turn'
+//     protocolVersionSink?: string,            // if set, the received initialize().protocolVersion
+//                                               // is written to this file path (test-only escape
+//                                               // hatch: InitializeResponse doesn't have to echo it,
+//                                               // so this is how a test observes what was sent)
+//     clientCapabilitiesSink?: string,         // if set, the received initialize().clientCapabilities
+//                                               // is written to this file path as JSON (same escape
+//                                               // hatch as protocolVersionSink — InitializeResponse
+//                                               // has nowhere to echo what the client sent)
+//     protocolVersionOverride?: number,        // if set, returned as initialize().protocolVersion
+//                                               // instead of the SDK's real PROTOCOL_VERSION —
+//                                               // lets a test simulate an agent that negotiated a
+//                                               // version this client should refuse
+//     hangOnInitialize?: boolean,              // if true, initialize() never resolves — simulates
+//                                               // an agent that opened stdio but never speaks, for
+//                                               // exercising connectAgent's initialize timeout
+//     exitMarkerPath?: string,                 // if set, a file this process writes right before
+//                                               // exiting on SIGTERM — lets a test confirm the
+//                                               // process actually died after `child.kill()`
+//     cancelSink?: string,                     // if set, a file this process writes (the JSON
+//                                               // `session/cancel` params) the moment it receives
+//                                               // that notification — lets a test prove
+//                                               // `AcpSession.interrupt()` really sent
+//                                               // `session/cancel` and not, say, an aborted request
+//     hangUntilCancel?: boolean,               // if true, session/prompt sends its `updates` and
+//                                               // then waits for a `session/cancel` notification
+//                                               // before returning, instead of returning right away
+//                                               // — gives a test a real in-flight turn to interrupt
+//     stopReasonAfterCancel?: StopReason,      // stopReason returned once hangUntilCancel's wait is
+//                                               // over; default 'end_turn' — deliberately NOT
+//                                               // 'cancelled', so a test can prove AcpSession forces
+//                                               // status 'interrupted' off its own interrupted flag
+//                                               // rather than merely relaying the agent's stopReason
+//     pingDuringInitialize?: boolean,          // if true, initialize() first calls the client-side
+//                                               // custom method `_test/ping` and writes the
+//                                               // response to pingResultSink before returning —
+//                                               // this is how a test proves a `connectAgent`
+//                                               // `configure` hook actually registered a handler
+//                                               // before `.connect()`, since it only works if the
+//                                               // handler exists in time to answer this call
+//     pingResultSink?: string,
+//     requestPermissionDuringPrompt?: { toolCall: ToolCallUpdate, options: PermissionOption[] },
+//                                               // if set, session/prompt calls the client's
+//                                               // session/request_permission with this payload
+//                                               // before returning, and writes the raw response to
+//                                               // requestPermissionResultSink — Task 5's proof that
+//                                               // its handler is reachable through connectAgent's
+//                                               // `configure` hook from a real separate process.
+//     requestPermissionResultSink?: string,
+//     createElicitationDuringPrompt?: object,  // if set, session/prompt calls the client's
+//                                               // elicitation/create with this payload verbatim
+//                                               // before returning, and writes the raw response to
+//                                               // createElicitationResultSink.
+//     createElicitationResultSink?: string,
+//     authenticateSink?: string,               // if set, a file this process writes (the raw JSON
+//                                               // `authenticate` params, i.e. `{ methodId }`) the
+//                                               // moment it receives that request — lets a test
+//                                               // prove `AcpAuth.authenticate` really sent the
+//                                               // request (vs. refusing before ever reaching the
+//                                               // agent for an unadvertised or terminal methodId)
+//     authenticateRejectsWith?: string,        // if set, the authenticate handler throws an Error
+//                                               // with this message instead of succeeding — lets a
+//                                               // test prove a real agent-side rejection surfaces as
+//                                               // a rejected promise
+//     hangOnAuthenticate?: boolean,            // if true, `authenticate` never resolves — the shape
+//                                               // measured on a real agent that opens a browser and
+//                                               // waits for its callback (spec §6.2: antigravity's
+//                                               // authenticate had not returned after 25s). Lets a
+//                                               // test prove a login is NOT cut off at the probe
+//                                               // budget the way `hangOnSessionNew` proves a probe is
+//     createElicitationDuringAuthenticate?: object,
+//                                               // if set, the `authenticate` handler calls the
+//                                               // client's `elicitation/create` with this payload
+//                                               // verbatim before returning, and writes the raw
+//                                               // response to createElicitationDuringAuthenticateResultSink.
+//                                               // This is the device-code login shape (Codex), and
+//                                               // the only way to prove the client registered its
+//                                               // elicitation handlers on the connection
+//                                               // `authenticate` actually runs on — a session
+//                                               // connection's handlers are unreachable from here.
+//     createElicitationDuringAuthenticateResultSink?: string,
+//     completeElicitationAfterAuthenticate?: string,
+//                                               // if set, the `authenticate` handler sends
+//                                               // `elicitation/complete` for this elicitationId
+//                                               // right after the elicitation above is answered —
+//                                               // the agent retiring its own URL, which is the only
+//                                               // provenance that can ever be retracted by the
+//                                               // protocol itself.
+//     stderrLines?: string[],                  // written to this process's stderr (one line each)
+//                                               // before it speaks any protocol at all — the
+//                                               // stderr-only login shape (antigravity), and it
+//                                               // starts at spawn on purpose, which is exactly the
+//                                               // window `ConnectAgentOptions.present` warns about.
+//     hangOnSessionNew?: boolean,              // if true, session/new never resolves — the agent
+//                                               // answered initialize and then went quiet on the
+//                                               // very next request. Distinct from hangOnInitialize:
+//                                               // that one is caught by connectAgent's own
+//                                               // initializeTimeoutMs, this one is past it, so only
+//                                               // a deadline the CALLER imposes (AcpAgents.verify's
+//                                               // withDeadline) can end it. Task 10a's review
+//                                               // measured this path with a temporary flag and then
+//                                               // reverted it; Task 11 made it permanent.
+//     newSessionRejectsWith?: string,          // if set, the session/new handler throws an Error with
+//                                               // this message instead of returning a sessionId —
+//                                               // the shape a real agent takes when it needs
+//                                               // credentials it does not have. Task 10a uses it to
+//                                               // prove a failed verification reports what happened
+//                                               // WITHOUT claiming the agent is unauthenticated,
+//                                               // which ACP v1 gives nobody the means to know.
+//     newSessionCommands?: AvailableCommand[][], // 每个元素是一次 available_commands_update 推送,
+//                                               // 在 session/new 回包之后按序发出(真适配器就是
+//                                               // 这么干的:setTimeout 0,见 acp-agent.js:756)。
+//                                               // 用数组的数组是因为「推几次」本身就是被测行为:
+//                                               // claude 会推两次(70 → 68),codex 只推一次。
+//     newSessionCommandsDelayMs?: number,       // 每次推送之间的间隔,默认 0。让测试能把一条晚到的
+//                                               // 推送放在 settle 窗口的里面或外面。
+//     sessions?: SessionInfo[],                 // session/list's response `sessions` array; default []
+//     nextCursor?: string,                      // session/list's response `nextCursor`
+//     sessionListSink?: string,                 // if set, a file this process writes (the raw JSON
+//                                                // session/list params, i.e. `{cwd, cursor}`) the
+//                                                // moment it receives that request — Task 7's proof
+//                                                // that listNativeSessions really sent cwd/cursor
+//     loadUpdates?: SessionUpdate[],            // Task 7 (adoption.ts): sent as session/update
+//                                                // notifications during session/load, before it
+//                                                // returns — this is the replay mechanism ACP v1
+//                                                // actually uses (session/resume does NOT replay
+//                                                // history; see adoption.ts's file doc comment)
+//     loadSessionRejectsWith?: string,          // if set, the session/load handler throws an Error with
+//                                                // this message instead of replaying and succeeding —
+//                                                // lets a test prove a client falls back to session/new
+//                                                // when an advertised load is refused (a stale id)
+//     promptRejectsWith?: string,                // if set, the session/prompt handler throws an Error with
+//                                                // this message instead of returning a stopReason — the
+//                                                // only way to exercise a rejected prompt against a real
+//                                                // agent (the SDK masks the text as "Internal error",
+//                                                // and the code as JSON-RPC -32603)
+//     promptRejectsWithAuthRequired?: boolean,   // if set, session/prompt answers with ACP's own
+//                                                // `RequestError.authRequired()` (-32000) instead —
+//                                                // the shape credentials expiring mid-conversation
+//                                                // actually takes, and the only failure the login
+//                                                // card may be drawn for
+//     promptSink?: string,                       // if set, a file this process overwrites with the raw
+//                                                // JSON session/prompt params on every prompt — the
+//                                                // only way to observe WHICH sessionId a prompt was
+//                                                // addressed to, which is the whole point of attaching
+//                                                // to a loaded session rather than opening a new one
+//     loadSessionResponse?: LoadSessionResponse, // session/load's response; default {}
+//     loadSessionSink?: string,                 // if set, a file this process writes (the raw JSON
+//                                                // session/load params) the moment it receives that
+//                                                // request — lets a test prove the right
+//                                                // sessionId/cwd were sent, and (by NOT configuring
+//                                                // this and asserting the file never appears) that
+//                                                // adoption.ts never calls session/load when the
+//                                                // capability isn't advertised
+//     resumeSessionResponse?: ResumeSessionResponse, // session/resume's response; default {}
+//     resumeSessionSink?: string,                // same idea as loadSessionSink, for session/resume
+//                                                // — Task 7's proof that adoption.ts NEVER calls
+//                                                // session/resume for replay (see adoption.ts's file
+//                                                // doc comment for why), even when the agent
+//                                                // advertises and answers it
+//     steerSink?: string,                        // if set, a file this process writes (the raw JSON
+//                                                // `_session/steering` params) the moment it receives
+//                                                // that request. `_session/steering` is an EXTENSION,
+//                                                // not ACP (`claude-agent-acp`
+//                                                // `acp-agent.js@0.76.0:164`),
+//                                                // which is why it is routed here by its literal
+//                                                // method name rather than through `methods.agent.*`
+//     steerOutcome?: 'injected'|'startedNewTurn'|'promptRequired',
+//                                                // the outcome `_session/steering` answers with;
+//                                                // default 'injected'. `startedNewTurn` is the shape
+//                                                // a contract-breaking agent takes — it is what an
+//                                                // agent returns to a client that did NOT opt into
+//                                                // `promptRequired`, so seeing it back means the
+//                                                // agent ignored the opt-in we always send
+//     steerRejectsWith?: string,                 // if set, the handler throws with this message
+//     newSessionConfigOptions?: SessionConfigOption[], // returned verbatim on session/new (types.gen.d.ts:2546)
+//     newSessionModes?: SessionModeState,              // returned verbatim on session/new (:2542)
+//     setConfigOptionSink?: string,                    // file receiving the JSON params of each session/set_config_option
+//     setConfigOptionRejectsWith?: string,             // if set, session/set_config_option throws
+//     setConfigOptionConfigOptions?: SessionConfigOption[], // if set, session/set_config_option answers with
+//                                                // exactly this list instead of echoing
+//                                                // `newSessionConfigOptions` with the value applied —
+//                                                // for the case where the agent's reply carries a
+//                                                // *different* set of options than the open did
+//     setModeSink?: string,                            // file receiving the JSON params of each session/set_mode
+//   }
+//
+// session/list, session/load and session/resume are ALWAYS routed (see the unconditional onRequest
+// calls below), independent of whether `agentCapabilities.sessionCapabilities.list`/`.resume` or
+// `agentCapabilities.loadSession` are advertised. That mirrors the real-world case this task exists
+// to guard against — codex-acp routes session/fork without declaring it — and gives callers a
+// fixture that can prove "honour the advertised capability, not the router" end to end, not just
+// assert a boolean.
+async function main() {
+    const { writeFileSync } = require('node:fs');
+    // Parsed and wired up before the (slow, cold-start) dynamic import below, so a caller that kills
+    // this process almost immediately after spawning it (exercising connectAgent's initialize
+    // timeout with a short deadline) still gets a SIGTERM handler in place. Registering this only
+    // after the SDK import resolved raced the timeout in practice.
+    const config = JSON.parse(process.argv[2] ?? '{}');
+    // Before the SDK import, deliberately: an agent that only ever prints its login URL does it while
+    // it is still starting up, and the client's sniffer is armed from `spawn()` for that reason.
+    for (const line of config.stderrLines ?? [])
+        process.stderr.write(`${line}\n`);
+    if (config.exitMarkerPath) {
+        process.on('SIGTERM', () => {
+            try {
+                writeFileSync(config.exitMarkerPath, 'killed');
+            }
+            finally {
+                process.exit(1);
+            }
+        });
+    }
+    const { agent, methods, PROTOCOL_VERSION, ndJsonStream, RequestError } = await import('@agentclientprotocol/sdk');
+    const { Readable, Writable } = require('node:stream');
+    const sessionId = config.sessionId ?? 'fake-session';
+    const updates = config.updates ?? [];
+    const stopReason = config.stopReason ?? 'end_turn';
+    let resolveCancelled;
+    const cancelled = new Promise((resolve) => {
+        resolveCancelled = resolve;
+    });
+    const app = agent({ name: 'fake-agent' })
+        .onRequest(methods.agent.initialize, async (ctx) => {
+        if (config.protocolVersionSink) {
+            writeFileSync(config.protocolVersionSink, String(ctx.params.protocolVersion));
+        }
+        if (config.clientCapabilitiesSink) {
+            writeFileSync(config.clientCapabilitiesSink, JSON.stringify(ctx.params.clientCapabilities ?? {}));
+        }
+        if (config.pingDuringInitialize) {
+            const pong = await ctx.client.request('_test/ping', { echo: 'hi' });
+            writeFileSync(config.pingResultSink, JSON.stringify(pong));
+        }
+        if (config.hangOnInitialize) {
+            return new Promise(() => { }); // never resolves
+        }
+        return {
+            protocolVersion: config.protocolVersionOverride ?? PROTOCOL_VERSION,
+            agentCapabilities: config.agentCapabilities ?? {},
+            authMethods: config.authMethods ?? [],
+            ...(config.agentInfo ? { agentInfo: config.agentInfo } : {}),
+            ...(config.initializeMeta ? { _meta: config.initializeMeta } : {}),
+        };
+    })
+        .onRequest(methods.agent.authenticate, async (ctx) => {
+        if (config.authenticateSink)
+            writeFileSync(config.authenticateSink, JSON.stringify(ctx.params));
+        if (config.authenticateRejectsWith)
+            throw new Error(config.authenticateRejectsWith);
+        if (config.createElicitationDuringAuthenticate) {
+            // `requestId` is filled in here rather than in the config: a login elicitation is
+            // request-scoped (ACP's `ElicitationRequestScope` — "tied to a specific JSON-RPC request
+            // outside of a session, e.g. during auth phases before any session is started"), and only
+            // this handler knows the id of the `authenticate` it is answering.
+            const result = await ctx.client.request(methods.client.elicitation.create, {
+                requestId: ctx.requestId,
+                ...config.createElicitationDuringAuthenticate,
+            });
+            if (config.createElicitationDuringAuthenticateResultSink) {
+                writeFileSync(config.createElicitationDuringAuthenticateResultSink, JSON.stringify(result));
+            }
+            if (config.completeElicitationAfterAuthenticate) {
+                await ctx.client.notify(methods.client.elicitation.complete, {
+                    elicitationId: config.completeElicitationAfterAuthenticate,
+                });
+            }
+        }
+        // Last, so the flags above are independently exercisable: a login that hangs may well have
+        // handed out its URL first, which is precisely the case this fixture has to be able to model.
+        if (config.hangOnAuthenticate)
+            return new Promise(() => { });
+        return {};
+    })
+        .onRequest(methods.agent.session.new, async (ctx) => {
+        if (config.newSessionRejectsWith)
+            throw new Error(config.newSessionRejectsWith);
+        // Checked after the rejection so the two flags stay independently exercisable; a promise that
+        // never settles is the only faithful way to model an agent that simply stops answering.
+        if (config.hangOnSessionNew)
+            return new Promise(() => { });
+        // Pushed AFTER this handler returns, not before: the real adapter schedules its first
+        // `available_commands_update` on a `setTimeout(…, 0)` that runs once `session/new` has been
+        // answered (`acp-agent.js:752-757`). Sending them inline would let a client that only reads
+        // updates *before* the reply still pass, which is the bug this fixture exists to catch.
+        const pushes = config.newSessionCommands ?? [];
+        if (pushes.length > 0) {
+            void (async () => {
+                for (const availableCommands of pushes) {
+                    await new Promise((r) => setTimeout(r, config.newSessionCommandsDelayMs ?? 0));
+                    await ctx.client.notify(methods.client.session.update, {
+                        sessionId,
+                        update: { sessionUpdate: 'available_commands_update', availableCommands },
+                    });
+                }
+            })();
+        }
+        return {
+            sessionId,
+            ...(config.newSessionConfigOptions ? { configOptions: config.newSessionConfigOptions } : {}),
+            ...(config.newSessionModes ? { modes: config.newSessionModes } : {}),
+        };
+    })
+        .onRequest(methods.agent.session.list, (ctx) => {
+        if (config.sessionListSink)
+            writeFileSync(config.sessionListSink, JSON.stringify(ctx.params));
+        return { sessions: config.sessions ?? [], ...(config.nextCursor ? { nextCursor: config.nextCursor } : {}) };
+    })
+        .onRequest(methods.agent.session.load, async (ctx) => {
+        if (config.loadSessionSink)
+            writeFileSync(config.loadSessionSink, JSON.stringify(ctx.params));
+        if (config.loadSessionRejectsWith)
+            throw new Error(config.loadSessionRejectsWith);
+        for (const update of config.loadUpdates ?? []) {
+            await ctx.client.notify(methods.client.session.update, { sessionId: ctx.params.sessionId, update });
+        }
+        return config.loadSessionResponse ?? {};
+    })
+        .onRequest(methods.agent.session.resume, async (ctx) => {
+        if (config.resumeSessionSink)
+            writeFileSync(config.resumeSessionSink, JSON.stringify(ctx.params));
+        return config.resumeSessionResponse ?? {};
+    })
+        .onRequest(methods.agent.session.setConfigOption, (ctx) => {
+        if (config.setConfigOptionSink)
+            writeFileSync(config.setConfigOptionSink, JSON.stringify(ctx.params));
+        if (config.setConfigOptionRejectsWith)
+            throw new Error(config.setConfigOptionRejectsWith);
+        if (config.setConfigOptionConfigOptions)
+            return { configOptions: config.setConfigOptionConfigOptions };
+        // Echo the snapshot with the requested value applied — the real adapters answer the full set
+        // (SetSessionConfigOptionResponse.configOptions, types.gen.d.ts:2953).
+        const next = (config.newSessionConfigOptions ?? []).map((o) => o.id === ctx.params.configId ? { ...o, currentValue: ctx.params.value } : o);
+        return { configOptions: next };
+    })
+        .onRequest(methods.agent.session.setMode, (ctx) => {
+        if (config.setModeSink)
+            writeFileSync(config.setModeSink, JSON.stringify(ctx.params));
+        return {};
+    })
+        .onNotification(methods.agent.session.cancel, (ctx) => {
+        if (config.cancelSink)
+            writeFileSync(config.cancelSink, JSON.stringify(ctx.params));
+        resolveCancelled();
+    })
+        .onRequest('_session/steering', (params) => params, (ctx) => {
+        if (config.steerSink)
+            writeFileSync(config.steerSink, JSON.stringify(ctx.params));
+        if (config.steerRejectsWith)
+            throw new Error(config.steerRejectsWith);
+        const outcome = config.steerOutcome ?? 'injected';
+        return outcome === 'promptRequired' ? { outcome, reason: 'noRunningTurn' } : { outcome };
+    })
+        .onRequest(methods.agent.session.prompt, async (ctx) => {
+        if (config.promptSink)
+            writeFileSync(config.promptSink, JSON.stringify(ctx.params));
+        // A plain Error is masked by the SDK as JSON-RPC -32603; `RequestError.authRequired()` is
+        // the real thing an agent whose credentials expired answers with (-32000). The two shapes are
+        // what the login card has to tell apart, and only a real agent process on a real wire proves
+        // the code survives the trip.
+        if (config.promptRejectsWithAuthRequired)
+            throw RequestError.authRequired();
+        if (config.promptRejectsWith)
+            throw new Error(config.promptRejectsWith);
+        for (const update of updates) {
+            await ctx.client.notify(methods.client.session.update, { sessionId: ctx.params.sessionId, update });
+        }
+        // Task 5 (permission.ts): if configured, calls the client's `session/request_permission`
+        // handler mid-turn and writes the raw response to a sink file — this is how a test proves the
+        // handler registered via `connectAgent`'s `configure` hook is really reachable from a separate
+        // OS process speaking real ACP, not just callable in-process.
+        if (config.requestPermissionDuringPrompt) {
+            const result = await ctx.client.request(methods.client.session.requestPermission, {
+                sessionId: ctx.params.sessionId,
+                toolCall: config.requestPermissionDuringPrompt.toolCall,
+                options: config.requestPermissionDuringPrompt.options,
+            });
+            writeFileSync(config.requestPermissionResultSink, JSON.stringify(result));
+        }
+        // Same idea for `elicitation/create`.
+        if (config.createElicitationDuringPrompt) {
+            const result = await ctx.client.request(methods.client.elicitation.create, config.createElicitationDuringPrompt);
+            writeFileSync(config.createElicitationResultSink, JSON.stringify(result));
+        }
+        if (config.hangUntilCancel) {
+            await cancelled;
+            return { stopReason: config.stopReasonAfterCancel ?? 'end_turn' };
+        }
+        return { stopReason };
+    });
+    // Mirrors the SDK's own `dist/examples/agent.js`: the agent's outgoing JSON-RPC traffic goes out
+    // over its own stdout, and it reads incoming traffic from its own stdin — the opposite way round
+    // from the client side of the same pipe pair.
+    const stream = ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin));
+    app.connect(stream);
+}
+main().catch((err) => {
+    process.stderr.write(`fake-agent crashed: ${(err && err.stack) || err}\n`);
+    process.exit(1);
+});
+export {};

package/dist/workstation/acp/test/sessionUpdateFixtures.js

@@ -0,0 +1,165 @@
+/**
+ * ACP's fifteen `SessionUpdate` variants, and one minimal (plus one "rich") input per variant.
+ *
+ * **This file exists because a hand-copied list of variants is exactly the guard that cannot
+ * fail.** The list used to live inline in `sessionUpdateMapper.test.ts` as a `const [...] as const`
+ * — its own comment said it was "the second, weaker net" — and `adoption.test.ts` shipped a stale
+ * copy of a different vocabulary list for a whole phase without anything noticing. So the list here
+ * is checked against the SDK's own type declaration ({@link acpVariantsFromSdk}) by
+ * `acpVocabulary.test.ts`, and its shape is pinned by the compiler as well:
+ * {@link MINIMAL} is a `Record` keyed on the SDK's own union, so adding, removing or misspelling a
+ * variant is a **compile** error before it is ever a test failure.
+ *
+ * Three suites share it — `sessionUpdateMapper.test.ts`, `acpVocabulary.test.ts` and
+ * `wireContract.test.ts` — so there is exactly one place where "what does ACP send" is written
+ * down, and it is the place the SDK is diffed against.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const TEXT_CONTENT = { type: 'text', text: 'hello' };
+/**
+ * The minimal fields each variant's own type requires.
+ *
+ * A `Record` over the SDK's union rather than a `switch`: a `switch` with a missing case is only a
+ * problem if some caller happens to hit it, while a `Record` with a missing key does not compile.
+ */
+const MINIMAL = {
+    user_message_chunk: { content: TEXT_CONTENT },
+    agent_message_chunk: { content: TEXT_CONTENT },
+    agent_thought_chunk: { content: TEXT_CONTENT },
+    tool_call: { toolCallId: 'call-1', title: 'Reading a file' },
+    tool_call_update: { toolCallId: 'call-1' },
+    plan: { entries: [] },
+    plan_update: { plan: { type: 'markdown', planId: 'plan-1', content: '- step one' } },
+    plan_removed: { planId: 'plan-1' },
+    available_commands_update: { availableCommands: [] },
+    current_mode_update: { currentModeId: 'default' },
+    config_option_update: { configOptions: [] },
+    session_info_update: {},
+    usage_update: { used: 100, size: 1000 },
+    compaction_update: { compactionId: 'compaction-1', status: 'in_progress' },
+    compaction_summary_chunk: { compactionId: 'compaction-1', content: TEXT_CONTENT },
+};
+/** Every ACP `SessionUpdate` variant, in the SDK's own declaration order. */
+export const ALL_SESSION_UPDATE_VARIANTS = Object.keys(MINIMAL);
+export function minimalFor(variant) {
+    return MINIMAL[variant];
+}
+/**
+ * "Rich" inputs for the two tool variants, whose mapping is the one place a `status` changes how
+ * many events come out: an already-terminal `tool_call` emits a second `tool_call_update` beside
+ * the creation, while a `tool_call_update` is always exactly one event whatever its status says
+ * (see `sessionUpdateMapper.ts`'s `toolCallUpdateEvent`). Kept separate from {@link minimalFor} so
+ * a sweep exercises both the pending/in_progress path and the completed/failed path for those two.
+ */
+export function richFor(variant) {
+    if (variant === 'tool_call') {
+        return [
+            { toolCallId: 'call-1', title: 'Reading a file', status: 'completed', content: [{ type: 'content', content: TEXT_CONTENT }] },
+            { toolCallId: 'call-1', title: 'Reading a file', status: 'failed', content: [{ type: 'content', content: TEXT_CONTENT }] },
+        ];
+    }
+    if (variant === 'tool_call_update') {
+        return [
+            { toolCallId: 'call-1', status: 'completed', content: [{ type: 'diff', path: '/repo/a.ts', newText: 'new' }] },
+            { toolCallId: 'call-1', status: 'failed', content: [{ type: 'content', content: TEXT_CONTENT }] },
+        ];
+    }
+    return [minimalFor(variant)];
+}
+/**
+ * Every field the SDK declares on each variant, filled in — used by the wire-contract guard, whose
+ * question is "which keys can the mapper ever emit for this variant", not "does the minimal input
+ * work". A minimal input answers the second question only, and every optional field it leaves out
+ * is a key the guard would then never see.
+ *
+ * Hand-written rather than derived: the SDK ships `.d.ts`, not a runtime schema, so there is
+ * nothing to enumerate at runtime. What keeps it honest is the guard that consumes it — a key the
+ * mapper emits from a field missing here simply never appears, and the *other* direction (a Kotlin
+ * decoder reading a key nothing here produces) is what that guard reports.
+ */
+export function saturatedFor(variant) {
+    switch (variant) {
+        case 'user_message_chunk':
+        case 'agent_message_chunk':
+        case 'agent_thought_chunk':
+            // Task 8: `_meta` now rides all three chunk kinds too (`sessionUpdateMapper.ts`'s
+            // `mapSessionUpdate`), so the wire-contract guard (`wireContract.test.ts`) needs to see it
+            // emitted here or it flags `<event>._meta` as a key the server reads that the CLI never
+            // sends — a false "silent frame drop" for a key that is, in fact, sent.
+            return { content: TEXT_CONTENT, messageId: 'm-1', _meta: { claudeCode: { parentToolUseId: 'toolu_01' } } };
+        case 'tool_call':
+            // `tool_call` now has a named `TimelineEventWire.decodeToolCall` branch and its typed
+            // `WorkTimelinePayload.ToolCall` consumer preserves ACP's extension slot. Include `_meta`
+            // here so the cross-language guard exercises the actual transport contract rather than a
+            // pre-decoder fallback shape.
+            return {
+                toolCallId: 'call-1',
+                title: 'Reading a file',
+                name: 'read_file',
+                kind: 'read',
+                status: 'completed',
+                content: [{ type: 'content', content: TEXT_CONTENT }],
+                locations: [{ path: '/repo/a.ts', line: 3 }],
+                rawInput: { path: '/repo/a.ts' },
+                rawOutput: 'contents',
+                _meta: { claudeCode: { parentToolUseId: 'toolu_01' } },
+            };
+        case 'tool_call_update':
+            return {
+                toolCallId: 'call-1',
+                title: 'Reading a file',
+                name: 'read_file',
+                kind: 'read',
+                status: 'completed',
+                content: [{ type: 'content', content: TEXT_CONTENT }],
+                locations: [{ path: '/repo/a.ts', line: 3 }],
+                rawInput: { path: '/repo/a.ts' },
+                rawOutput: 'contents',
+                _meta: { claudeCode: { parentToolUseId: 'toolu_01' } },
+            };
+        case 'plan':
+            return { entries: [{ content: 'write the test', priority: 'medium', status: 'pending' }] };
+        case 'plan_update':
+            return { planId: 'plan-1', plan: { type: 'markdown', planId: 'plan-1', content: '- step one' } };
+        case 'plan_removed':
+            return { planId: 'plan-1' };
+        case 'available_commands_update':
+            return { availableCommands: [{ name: 'plan', description: 'Draft a plan', input: { hint: 'goal' } }] };
+        case 'current_mode_update':
+            return { currentModeId: 'default' };
+        case 'config_option_update':
+            return { configOptions: [{ id: 'model', name: 'Model', type: 'select', currentValue: 'opus', options: [] }] };
+        case 'session_info_update':
+            return { title: 'A session', updatedAt: '2026-08-24T00:00:00Z' };
+        case 'usage_update':
+            return { used: 100, size: 1000, cost: { amount: 0.5, currency: 'USD' } };
+        case 'compaction_update':
+            return { compactionId: 'compaction-1', status: 'failed', summary: [TEXT_CONTENT], error: 'out of budget' };
+        case 'compaction_summary_chunk':
+            return { compactionId: 'compaction-1', content: TEXT_CONTENT };
+    }
+}
+const SDK_TYPES = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../node_modules/@agentclientprotocol/sdk/dist/schema/types.gen.d.ts');
+/**
+ * The variant tags the SDK itself declares, read out of `types.gen.d.ts`'s `SessionUpdate` union.
+ *
+ * Strict on purpose, in three places, because every one of them is a way for this to quietly stop
+ * comparing anything: the `export type SessionUpdate =` line must be found, the union must
+ * terminate on a `;`, and at least one tag must come out. A regex that silently matches nothing is
+ * precisely the unfalsifiable guard this whole file exists to replace.
+ */
+export function acpVariantsFromSdk() {
+    const source = readFileSync(SDK_TYPES, 'utf8');
+    const start = source.indexOf('export type SessionUpdate =');
+    if (start < 0)
+        throw new Error(`no \`export type SessionUpdate =\` in ${SDK_TYPES}`);
+    const end = source.indexOf('\n};', start);
+    if (end < 0)
+        throw new Error(`\`SessionUpdate\` union in ${SDK_TYPES} has no terminating \`\\n};\``);
+    const tags = [...source.slice(start, end).matchAll(/sessionUpdate:\s*"([^"]+)"/g)].map((m) => m[1]);
+    if (tags.length === 0)
+        throw new Error(`no \`sessionUpdate: "..."\` tags in ${SDK_TYPES}'s SessionUpdate union`);
+    return tags;
+}