@platless/axom-cli 0.1.0

package/dist/workstation/acp/sessionUpdateMapper.js

@@ -0,0 +1,602 @@
+/**
+ * One session's memory, and the reason this file is no longer stateless: **what this session has
+ * already been told**, for the two branches that cannot answer a frame from the frame alone.
+ *
+ * It holds two unrelated facts, and they are together only because they have the same lifetime and
+ * the same owner (`AcpSession`, one per session, handed to every `mapSessionUpdate` call):
+ *
+ * 1. `toolCallId → name`, because ACP's `tool_call_update` is a delta (below);
+ * 2. the last agent queue depth reported to the server, because `pi-acp` re-states its depth on
+ *    frames that are not queue events at all (see {@link SessionMapperState.reportsQueueDepth}).
+ *
+ * ## 1. `toolCallId → name`
+ *
+ * ACP's `tool_call_update` is a **delta**, keyed by `toolCallId`. Its `name` is optional, and the
+ * schema says exactly what leaving it out means (`types.gen.d.ts:164-165`):
+ *
+ * > "This field is optional. Omitting it or sending `null` both mean that the existing name is
+ * > left unchanged."
+ *
+ * "Unchanged" is a statement about a name the consumer is expected to still be holding — so a
+ * consumer that holds nothing has no way to honour it. The previous version of this file wrote the
+ * literal `'unknown'` there instead, which does not mean "unchanged": it is a different, false
+ * claim, and it went into the durable `item` row for every terminal update a bridged agent ever
+ * produced. The settings page's "Ready to launch" defect was the same shape — a value nobody had
+ * established, rendered as one that had been.
+ *
+ * Held per session and passed in, rather than kept in module state, so two concurrent sessions
+ * cannot see each other's tool calls. It grows by one short string pair per tool call for the
+ * session's lifetime; a session long enough for that to matter has far larger per-call costs
+ * already (every call's `rawInput`/`rawOutput` is journaled), so there is no eviction here.
+ */
+export class SessionMapperState {
+    byId = new Map();
+    /**
+     * The agent queue depth this session has already reported to the server.
+     *
+     * **Starts at 0, and that initial value is load-bearing, not a placeholder**: a session begins with
+     * an empty agent queue, so a first frame saying "0 waiting" is not news — it is the state the
+     * reader already assumes. Seeding it to `-1` (or `null`) would let the very first frame through,
+     * which on `pi-acp` is `startTurn`'s, i.e. the defect this field exists to prevent.
+     */
+    lastReportedQueueDepth = 0;
+    /**
+     * Is `depth` news? Records it if so. **This is the whole fix for a defect that shipped in the
+     * previous commit**, so the reasoning is written out rather than summarised.
+     *
+     * `pi-acp@0.0.33` emits `_meta.piAcp.{queueDepth,running}` from **five** sites (read first-hand
+     * from the package pinned on this machine, `pi-acp/dist/index.js`, `package.json` version
+     * `0.0.33`), and **the two that fire most are not queue events**:
+     *
+     * | line | when | payload with nothing queued |
+     * |---|---|---|
+     * | `:845` | `prompt()` while a turn is running — a real enqueue | `{n≥1, true}` |
+     * | `:864` | `cancel()` cleared a non-empty queue — a real drain | `{0, …}` |
+     * | **`:925`** | **`startTurn()` — every turn, queue or no queue** | **`{0, true}`** |
+     * | `:940` | the turn's prompt rejected | `{depth, false}` |
+     * | **`:1228`** | **`agent_settled` with an empty queue — every turn end** | **`{0, false}`** |
+     *
+     * (`:1267` carries `piAcp.notify` and no depth; `agentQueueNotice`'s shape check drops it.)
+     *
+     * Because a `step` is a durable item and `foldStep` never merges adjacent ones, emitting on every
+     * frame gave **every pi session two permanent "0 messages waiting" cards per turn, from its first
+     * turn**. The previous commit's premise — that pi publishes on queue changes — was simply wrong,
+     * and nobody had read the package.
+     *
+     * ## Why "the depth changed", and not the two alternatives
+     *
+     * **De-duplicating consecutive identical `{depth, running}` pairs does not fix it.** The two
+     * every-turn frames are `{0,true}` and `{0,false}`: they differ in `running` and they *alternate*,
+     * so they are never consecutive-identical and every single one would still be published. A test
+     * below is written to fail under exactly that implementation.
+     *
+     * **Suppressing `queueDepth === 0` outright eats the news the reader most wants**: the drain. A
+     * queue going 2 → 1 → 0 ends on a zero, and that zero is the whole point.
+     *
+     * Comparing against the last depth *we reported* keeps the drain (`0 ≠ 2`), kills the every-turn
+     * noise (`0 === 0`), and self-heals: once a queue has drained, the session goes quiet again.
+     *
+     * ## Why `running` does not take part in the decision
+     *
+     * **The decisive reason is the measurement above, not a principle**: `running` is exactly the field
+     * that *alternates* across the two every-turn frames (`{0,true}` then `{0,false}`). Any 判据 that
+     * reads it therefore publishes on every turn boundary — which is the defect. It is disqualified by
+     * what it does, and that is checkable: the pair-dedup test below fails if this ever changes.
+     *
+     * A secondary reason to be comfortable with that: the subject of this observation is the depth, and
+     * "is the agent running" is a fact Axom already owns from its own turn state, which invariant II
+     * would rather not have a second independent writer for. That argument is real but it is not what
+     * settles it — a field could be redundant with Axom's own state and still be worth reacting to.
+     *
+     * `running` still rides along inside the sentence, where it is an attribution ("the agent
+     * reports…") rather than a second account of the same fact.
+     */
+    reportsQueueDepth(depth) {
+        if (depth === this.lastReportedQueueDepth)
+            return false;
+        this.lastReportedQueueDepth = depth;
+        return true;
+    }
+    /** Remember what this call is called. Later updates that carry no `name` fall back to it. */
+    record(toolCallId, name) {
+        if (name)
+            this.byId.set(toolCallId, name);
+    }
+    /**
+     * The name to report for one update, in ACP's own order of authority: an explicit `name` on the
+     * update *is* a rename and wins (and is remembered); otherwise the remembered name is what
+     * "unchanged" refers to; `title` is the last resort, matching what `toolCallCreatedEvent` would
+     * have used had `name` been absent at creation. `'unknown'` survives only for a call this mapper
+     * genuinely never saw created — a mid-stream reconnect, or an agent updating an id it never
+     * opened.
+     */
+    resolve(toolCallId, name, title) {
+        if (name) {
+            this.byId.set(toolCallId, name);
+            return name;
+        }
+        return this.byId.get(toolCallId) ?? title ?? 'unknown';
+    }
+}
+/**
+ * Identity, by construction: every ACP `ToolKind` member is a wire value. `delete`, `move` and
+ * `switch_mode` used to be flattened to `'other'` here, which destroyed the only signal the card
+ * renderer has for telling "removed a file" apart from "did something unclassified" — and the
+ * flattening was lossy at the boundary, so no consumer could recover it.
+ *
+ * The only non-identity case left is ACP reporting no kind at all: `ToolCall.kind` is
+ * `ToolKind | null | undefined`, and absent is not a tenth kind — it means "unclassified", which is
+ * exactly what `'other'` already spells.
+ */
+function mapToolKind(kind) {
+    return kind ?? 'other';
+}
+/** Drop `undefined`-valued keys so optional wire fields are genuinely absent, not `null`/`undefined` literals. */
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+/**
+ * `ToolCall.locations` → the wire `tool_call.locations` shape; omitted entirely when there are none.
+ *
+ * An identity copy of ACP's `ToolCallLocation` (`types.gen.d.ts:581`), which is `{path, line?}` —
+ * `line` is `number | null | undefined` (`:586-589`) and used to be dropped here, which cost the
+ * "follow along" feature the only signal telling *where* in the file the agent is working. Absent
+ * stays absent rather than becoming a `null`: `compact` is applied per location, not just to the
+ * enclosing payload.
+ */
+function mapLocations(locations) {
+    if (!locations || locations.length === 0)
+        return undefined;
+    return locations.map((location) => compact({ path: location.path, line: location.line ?? undefined }));
+}
+function toolCallCreatedEvent(update, state) {
+    // Recorded here rather than in `mapToolCallEvents` so the one place that decides what a call is
+    // called is also the one place that remembers it: the two can never drift apart.
+    state.record(update.toolCallId, update.name ?? update.title);
+    return {
+        eventName: 'tool_call',
+        // Every field is now an identity copy of ACP's own `ToolCall` (`types.gen.d.ts:3479`): the wire
+        // vocabulary took ACP's `toolCallId`/`name`/`title`/`rawInput`/`kind`/`locations`/`_meta` names
+        // verbatim.
+        payload: compact({
+            // ACP's `ToolCall.name` is the programmatic name and is optional and UNSTABLE (`:3488-3500`);
+            // on a *creation* its absence means "no tool name is available" (`:3495-3496`) — not the
+            // "left unchanged" that the same-named field on `ToolCallUpdate` means (`:164-165`) — so
+            // there is nothing earlier to fall back to and `title` (always present, `:3484-3487`) is the
+            // only field guaranteed to give the card a name.
+            name: update.name ?? update.title,
+            toolCallId: update.toolCallId,
+            rawInput: update.rawInput,
+            kind: mapToolKind(update.kind),
+            title: update.title,
+            locations: mapLocations(update.locations),
+            // `_meta` is ACP's own extension slot, present on every request/notification shape
+            // (`types.gen.d.ts`). This mapper copies it verbatim and reads nothing inside it — Global
+            // Constraint 3 ("transport, not translation"): claude-agent-acp puts `parentToolUseId` here to
+            // thread a subagent's tool calls back to the `Task` call that spawned it, and other agents put
+            // other vendor-private shapes there; this file has no business knowing either.
+            _meta: update._meta ?? undefined,
+        }),
+    };
+}
+/**
+ * ACP `tool_call_update` (`types.gen.d.ts:140`) — a tool call's **entire** remaining life under one
+ * event name, increments and answer alike, with ACP's own `status` (`ToolCallStatus`, `:217`:
+ * `pending | in_progress | completed | failed`) saying which this one is.
+ *
+ * There used to be two events here. `tool_call_progress` carried the increments and `tool_call_result`
+ * the terminal ones — but `tool_call_progress` *also* carried `status`, so the event name and the field
+ * were two spellings of one fact, and ACP has only the field. The two names cost real data on the way
+ * out of this file: `extractDiff` kept `content.find(type === 'diff')`, the **first** diff and no other,
+ * so a multi-file edit silently lost every diff after the first; `extractOutputChunk`/
+ * `flattenContentForResult` flattened content blocks to free text, so a `terminal` reference became a
+ * string no consumer could resolve back to a terminal. Carrying ACP's `content` array verbatim ends
+ * both losses, and `ToolCallContent` (`:226`, the three-member `content`/`diff`/`terminal` union) is
+ * already the wire shape the server decodes (`AcpToolCallContent.fromWire`).
+ *
+ * `executeStatus` went with the event name it belonged to. It was Axom's `success | failure | running`
+ * riding alongside ACP's `status` — same question, two fields, disjoint value domains, and a consumer
+ * reading one under the other's meaning would call every failure a success. The server maps
+ * `ExecuteResult`'s values into ACP's four rather than keeping a second field.
+ *
+ * Every key emitted here is a key the server's `decodeToolUpdate` reads (`TimelineEventWire.kt`:
+ * name/toolCallId/kind/title/status/content/locations/rawInput/rawOutput/`_meta`): a key this
+ * function does not send has no other source, so it simply is not on the timeline. `name` is the one
+ * whose absence is fatal rather than lossy — the server's branch is `?: return null`, dropping the
+ * whole update silently.
+ *
+ * `_meta` is forwarded verbatim: it is ACP's own extension slot, and this mapper copies the object
+ * without reading anything inside it (Global Constraint 3, "transport, not translation").
+ * `decodeToolUpdate` reads it too — also verbatim, straight onto the event payload — so the slot is
+ * a live end-to-end channel now, not an additive one waiting for a consumer.
+ *
+ * **`stream` is deliberately absent, and it is no longer a concept without a home.** `stdout` vs
+ * `stderr` has nowhere to live in ACP's typed `content`, and the card renders the two separately.
+ * The marker now travels as `_meta.axom.stream` (alongside `_meta.axom.delta`) — `_meta.axom` is the
+ * one namespace the platform writes into ACP's extension slot, and `WorkTimelineTools`'
+ * `effectiveStream()` reads it first, falling back to the old top-level `stream` only for rows
+ * written before that move. What this mapper still does not do is *invent* one: an ACP agent never
+ * says which stream a content block came from, and `_meta.axom` is the platform's namespace, not
+ * something to synthesize on an agent's behalf. So the key stays omitted — ACP's "unchanged", which
+ * is the truthful thing to say when the agent never told us.
+ *
+ * Everything but the id is optional on `ToolCallUpdate` and absent means "leave it unchanged"
+ * (`:140-143`), so `compact` dropping the `undefined`s is load-bearing rather than cosmetic. `kind`
+ * in particular does **not** get `mapToolKind`'s `?? 'other'` fallback: that fallback is right on a
+ * *creation*, where absent means "unclassified", and wrong here, where it would overwrite the kind
+ * the `tool_call` established with a claim the agent never made.
+ */
+function toolCallUpdateEvent(update, state) {
+    return {
+        eventName: 'tool_call_update',
+        payload: compact({
+            // Neither `name` nor `title` is guaranteed on an update that only changed `status`, and ACP
+            // defines that absence as "unchanged" (`types.gen.d.ts:164-165`) rather than "unknown" — see
+            // {@link SessionMapperState}. The emitted key is ACP's own `name` (`ToolCallUpdate.name`, `:169`);
+            // `toolName` was a synonym of it.
+            name: state.resolve(update.toolCallId, update.name, update.title),
+            toolCallId: update.toolCallId,
+            title: update.title ?? undefined,
+            kind: update.kind ?? undefined,
+            status: update.status ?? undefined,
+            // An empty array is omitted rather than sent, and the behaviour is deliberate now that the
+            // card's fold *does* honour ACP's "replace the content collection": `applyChunks` treats an
+            // empty chunk list as "unchanged" at every call site, never as a clear. So an empty array
+            // carries nothing either way — and the server drops it on the way back out anyway
+            // (`TimelineEvent.ToolCallUpdated.payload` only writes `content` when it is non-empty), which
+            // is why sending one could not express a clear even if a consumer wanted to act on it.
+            content: update.content && update.content.length > 0 ? update.content : undefined,
+            locations: mapLocations(update.locations),
+            rawInput: update.rawInput,
+            rawOutput: update.rawOutput,
+            // See the doc comment above: ACP's extension slot, copied verbatim and read by nothing *here*
+            // (the server's `decodeToolUpdate` does read it, also verbatim).
+            _meta: update._meta ?? undefined,
+        }),
+    };
+}
+function mapToolCallEvents(update, state) {
+    const events = [toolCallCreatedEvent(update, state)];
+    // ACP permits a `tool_call` to arrive already finished — the agent reporting a call it both
+    // started and completed in one notification, with no separate `tool_call_update` at all. A card
+    // only ever leaves "Running" on an update reporting a non-pending status
+    // (`WorkTimelineTools.foldToolUpdate`'s outcome branch), and the creation event carries no status,
+    // so without this second event an already-terminal call would render as permanently "Running".
+    //
+    // `ToolCall` is structurally a `ToolCallUpdate` (every field of the latter, with `title` and `kind`
+    // merely narrower), so the same function emits both — the two cannot drift into disagreeing about
+    // what a terminal update looks like.
+    if (update.status === 'completed' || update.status === 'failed') {
+        events.push(toolCallUpdateEvent(update, state));
+    }
+    return events;
+}
+function summarizePlanEntries(entries) {
+    if (entries.length === 0)
+        return 'No plan entries.';
+    return entries.map((entry) => `[${entry.status}] ${entry.content}`).join('\n');
+}
+function summarizePlanUpdateContent(plan) {
+    switch (plan.type) {
+        case 'items':
+            return summarizePlanEntries(plan.entries);
+        case 'file':
+            return `Plan file: ${plan.uri}`;
+        case 'markdown':
+            return plan.content;
+        default:
+            // `PlanUpdateContent` is marked UNSTABLE in the SDK itself, unlike the outer `SessionUpdate`
+            // union this file's exhaustiveness check guards — tolerating a shape this switch doesn't
+            // recognize (rather than failing the build over an experimental type) matches how the deleted
+            // bridges already treat everything the spec marks unstable.
+            return 'Plan updated.';
+    }
+}
+/**
+ * Generic catch-all wire event — the same `{title, message}` shape the deleted `codex/events.ts`
+ * used for its own "no dedicated card" `ThreadItem` variants.
+ *
+ * **Exactly one branch below still calls this, and that is now the whole story of `step` in this
+ * file.** `summarizeAvailableCommands` / `summarizeConfigOptions` / `summarizeCompaction` and the
+ * `blockText` flattening for `compaction_summary_chunk` are gone with the branches that used them:
+ * each of those five variants publishes ACP's own structure under its own event name. What is left
+ * is `plan_update`, and its reason is written at that branch.
+ */
+function stepEvent(title, message) {
+    return { eventName: 'step', payload: { title, message } };
+}
+/** The `step` line's title, exported so the test asserts the same string the mapper writes. */
+export const AGENT_QUEUE_NOTICE_TITLE = 'Agent queue';
+/**
+ * `session_info_update._meta.piAcp.{queueDepth,running}` → a `step` line — ruling N11.
+ *
+ * `pi-acp@0.0.33` publishes its own queue depth under `_meta.piAcp`, and this branch used to read
+ * only `title`/`updatedAt`, so the numbers were dropped on the floor. They are worth showing: on
+ * that adapter a mid-turn `session/prompt` waits for `agent_settled`, and until now nothing on the
+ * reader's screen said the agent was holding anything at all.
+ *
+ * **Most of those frames say nothing, and skipping them is not an optimisation — it is the
+ * correctness fix for a defect the previous commit shipped.** `pi-acp` re-states the depth when a
+ * turn *starts* and when it *settles*, not only when the queue moves; the full site table, the
+ * measurement it came from, and why the two obvious alternatives are wrong are at
+ * {@link SessionMapperState.reportsQueueDepth}, which owns that decision.
+ *
+ * **They describe a different set from Axom's queue, and the normalisation is presentational on
+ * purpose (ruling N11: "相加即错").** `pi-acp`'s queue holds prompts *that adapter* has accepted and
+ * not yet run; Axom's `session_message_queue` holds messages the *server* decided to hold
+ * (spec §4.1) — and today Axom never sends a second `session/prompt` into a running turn at all
+ * (ruling N1), so the two can never be summed into anything meaningful. That is enforced by shape,
+ * not by discipline: `step` is the generic notice event whose payload is four strings
+ * (`WorkTimelinePayload.Step`: `message`/`title`/`detail`/`tone`). The depth survives only as a word
+ * inside a sentence, so no future reader can add it to a queue length, gate a delivery on it, or
+ * render the queue bar from it without first re-parsing prose — which is a thing nobody does by
+ * accident. Publishing `{queueDepth, running}` as structured fields under a name of its own would
+ * have left exactly that door open.
+ *
+ * **Reading a vendor key is not vendor branching.** `_meta` is ACP's extension slot, and `piAcp` is
+ * where this agent puts the observation; there is no vendor-neutral spelling to read instead, and
+ * nothing here changes *behaviour* based on who the agent is (ruling L2's actual prohibition) — a
+ * frame without the key simply says nothing. Shape checks are strict for the same reason every
+ * other branch here checks: `_meta` is `{[key: string]: unknown}` in the SDK (`types.gen.d.ts:3912`),
+ * so anything at all can arrive under it.
+ *
+ * **`queueDepth` is required, `running` is not.** A frame carrying only `running` would be a second
+ * spelling of a fact Axom already owns from its own turn state, which invariant II forbids having
+ * two writers for; as part of a sentence *about the agent's own queue* it is an attribution
+ * ("the agent reports"), which is a different claim and one only the agent can make.
+ */
+function agentQueueNotice(meta, state) {
+    const piAcp = meta?.piAcp;
+    if (typeof piAcp !== 'object' || piAcp === null)
+        return null;
+    const { queueDepth, running } = piAcp;
+    if (typeof queueDepth !== 'number' || !Number.isInteger(queueDepth) || queueDepth < 0)
+        return null;
+    // The shape check comes first on purpose: a malformed frame must not be able to move the
+    // watermark this session compares against, or one bad frame silences the next real change.
+    if (!state.reportsQueueDepth(queueDepth))
+        return null;
+    const waiting = queueDepth === 1 ? '1 message waiting' : `${queueDepth} messages waiting`;
+    const runState = typeof running === 'boolean'
+        ? `, and that it is ${running ? 'running' : 'idle'}`
+        : '';
+    return stepEvent(AGENT_QUEUE_NOTICE_TITLE, `The agent reports ${waiting} in its own queue${runState}. ` +
+        `This is the agent's queue, not Axom's.`);
+}
+/**
+ * Map one ACP `session/update` payload to zero or more wire events.
+ *
+ * Carries no state of its own: everything it needs to remember across updates lives in the
+ * {@link SessionMapperState} its caller owns and passes in. That parameter is **required**, not
+ * optional, on purpose — an optional one would let a future call site forget it and silently
+ * reintroduce *both* failures that class exists to prevent (`name: 'unknown'`, and a queue notice on
+ * every turn boundary), which is exactly the shape of failure a default value hides. `AcpSession` is
+ * the caller with a session's lifetime, and it is where the rest of the cross-update state already
+ * lives: `agent_message` synthesis and `user_message_chunk` folding both stay there rather than here
+ * (see the file doc comment).
+ */
+export function mapSessionUpdate(update, state) {
+    switch (update.sessionUpdate) {
+        case 'user_message_chunk':
+            // identity mapping, same as the two assistant chunk kinds below: `messageId` is the grouping
+            // key ACP defines on `ContentChunk` (`types.gen.d.ts:3456`) and the server folds on it, so it
+            // must survive the hop. Dropping it here would make every chunk look like a separate message.
+            // `_meta` (ACP's own extension slot, `ContentChunk`, `types.gen.d.ts:3460`) is forwarded
+            // verbatim, same as on `tool_call`/`tool_call_update` above and for the same reason (Task 8):
+            // claude-agent-acp stamps `_meta.claudeCode.parentToolUseId` on chunks belonging to a
+            // subagent (`acp-agent.js:6392-6404`; its own comment at `:1271-1274` says subagent-attributed
+            // chunks are recognizable by exactly that stamp), and P2's routing needs it to reach a chunk,
+            // not just a tool call. This mapper reads nothing inside it — Global Constraint
+            // "transport, not translation".
+            return [{ eventName: 'user_message_chunk', payload: compact({ content: update.content, messageId: update.messageId ?? undefined, _meta: update._meta ?? undefined }) }];
+        case 'agent_message_chunk':
+            // identity mapping since the ACP rename: the server event is now called `agent_message_chunk` too
+            return [{ eventName: 'agent_message_chunk', payload: compact({ content: update.content, messageId: update.messageId ?? undefined, _meta: update._meta ?? undefined }) }];
+        case 'agent_thought_chunk':
+            // identity mapping since the ACP rename: the server event is now called `agent_thought_chunk` too
+            return [{ eventName: 'agent_thought_chunk', payload: compact({ content: update.content, messageId: update.messageId ?? undefined, _meta: update._meta ?? undefined }) }];
+        case 'tool_call':
+            // existing events: tool_call, plus a tool_call_update when ACP reports it already finished — see mapToolCallEvents
+            return mapToolCallEvents(update, state);
+        case 'tool_call_update':
+            // identity mapping since the merge: one wire event per ACP update, whatever its status — see toolCallUpdateEvent
+            return [toolCallUpdateEvent(update, state)];
+        case 'plan':
+            // identity mapping: the server event is now called `plan` too, and it carries ACP's own
+            // `entries` (`types.gen.d.ts:3594`) rather than a summary of them.
+            //
+            // This used to be `stepEvent('Plan', summarizePlanEntries(update.entries))` — a free-text
+            // line per entry, joined into one string. Measured on real hardware, claude-agent-acp emits
+            // fully structured plans (`dist/acp-agent.js:6489` from Claude Code's TodoWrite, `:6678` from
+            // its own Task subagent tools), each entry `{content, status, priority}`. The structure was
+            // being destroyed *here*, in Axom's own code, not withheld by the adapter — which is why an
+            // external session's plan card was always empty while the built-in agent had one.
+            //
+            // The entries go over the wire verbatim, `_meta` and all: `TimelineEventWire`'s `plan`
+            // decoder rebuilds a typed `AcpPlanEntry` and keeps only ACP's three fields, so nothing
+            // unrecognized reaches the database. An empty `entries` is still emitted rather than
+            // swallowed — ACP allows it (TodoWrite clearing its list), and the *server* owns the ruling
+            // that an empty plan writes no plan; dropping it here would hide that the agent sent one.
+            return [{ eventName: 'plan', payload: { entries: update.entries } }];
+        case 'plan_update':
+            // existing event: step. Deliberately NOT mapped onto `plan`: `PlanUpdate` (`:3738`) is the
+            // id-addressed family the SDK marks UNSTABLE/@experimental, its content is a three-way union
+            // (`items` | `file` | `markdown`), and it is gated by a client capability Axom does not
+            // advertise. `summarizePlanEntries` therefore survives for this branch alone.
+            return [stepEvent('Plan updated', summarizePlanUpdateContent(update.plan))];
+        case 'plan_removed':
+            // identity mapping: the server event is now called `plan_removed` too, carrying ACP's own
+            // `planId` (`:3763`). Also UNSTABLE in the SDK, and also id-addressed — but unlike
+            // `plan_update` the platform has a real action for it (cancel the session's live plan), and
+            // dropping the id into a `step` line left that action impossible to take.
+            return [{ eventName: 'plan_removed', payload: { planId: update.planId } }];
+        case 'available_commands_update':
+            // identity mapping: the server event is now called `available_commands_update` too, and it
+            // carries ACP's own `AvailableCommand[]` (`types.gen.d.ts:3782`) rather than a comma-joined
+            // list of names. Each command's `description` and `input.hint` (`:3813`) were being destroyed
+            // *here* — the adapter sends them; nothing downstream ever saw them.
+            //
+            // An empty list is still emitted rather than swallowed: "the agent now offers no commands" is
+            // a real transition, and dropping it would hide that the agent said anything at all.
+            return [{ eventName: 'available_commands_update', payload: { availableCommands: update.availableCommands } }];
+        case 'current_mode_update':
+            // identity mapping: the server event is now called `current_mode_update` too, carrying ACP's
+            // own `currentModeId` (`SessionModeId`, `types.gen.d.ts:3855`) instead of a prose line that
+            // spelled the id inside a sentence no consumer could parse back out.
+            return [{ eventName: 'current_mode_update', payload: { currentModeId: update.currentModeId } }];
+        case 'config_option_update':
+            // identity mapping: the server event is now called `config_option_update` too, carrying ACP's
+            // own `SessionConfigOption[]` (`:2617`) verbatim — union member, `currentValue` and all. The
+            // old `options.map(o => o.name).join(', ')` made "configuration updated" a notice that could
+            // not say what changed or what it changed to.
+            return [{ eventName: 'config_option_update', payload: { configOptions: update.configOptions } }];
+        case 'session_info_update': {
+            // identity mapping since the ACP rename: the server event is now called `session_info_update`
+            // too (it was `title_suggested`), reusing the bridge-title-sync path the deleted claudeCode
+            // bridge used for its own native session titles.
+            //
+            // **The shape is no longer narrowed.** `SessionInfoUpdate` (`types.gen.d.ts:3896`) is
+            // `{title?, updatedAt?}` with both fields `string | null`, and the doc comment says a null
+            // clears. That is three states, and this branch used to collapse them to one: anything but a
+            // non-empty string emitted nothing, so an explicit clear and a title-less "the session moved"
+            // both vanished here. `'title' in update` is what tells absent from null — the server's
+            // decoder makes the same distinction with `containsKey`.
+            //
+            // A wholly empty update is still dropped: the server drops it too, and emitting it would only
+            // push the bridge watermark past a frame nobody can act on. "Wholly empty" is about ACP's own
+            // two fields; `_meta` is read separately below and can carry an update of its own.
+            const payload = {};
+            if ('title' in update)
+                payload.title = update.title ?? null;
+            if (update.updatedAt != null)
+                payload.updatedAt = update.updatedAt;
+            const events = Object.keys(payload).length > 0
+                ? [{ eventName: 'session_info_update', payload }]
+                : [];
+            const queueNotice = agentQueueNotice(update._meta, state);
+            if (queueNotice)
+                events.push(queueNotice);
+            return events;
+        }
+        case 'usage_update':
+            // existing event: usage_update — context occupancy/cost, same wire shape the deleted bridges already emit
+            // An identity copy of ACP's `UsageUpdate` (`types.gen.d.ts:3942`): `used` (`:3946`), `size`
+            // (`:3950`) and `cost` (`:3954`, a `Cost` of `{amount, currency}` — `:3919-3927`). The wire
+            // used to spell these `contextTokens`/`totalCostUsd`, and the latter's baked-in currency is
+            // why a non-USD cost had to be dropped rather than mislabeled. Carrying ACP's own `cost`
+            // object carries the currency with it, so there is nothing left to drop.
+            return [{ eventName: 'usage_update', payload: compact({ used: update.used, size: update.size, cost: update.cost ?? undefined }) }];
+        case 'compaction_update':
+            // identity mapping: the server event is now called `compaction_update` too, carrying ACP's own
+            // `{compactionId, status, summary?, error?}` (`types.gen.d.ts:4003`, status at `:3985`). The
+            // server's own compaction audit record moved onto this same name and shape — one concept, one
+            // name across both agents, with Axom's engine watermarks riding along as extensions ACP has no
+            // field for.
+            //
+            // `summary` and `error` have **patch semantics** (`:4003`: omission leaves the stored value
+            // unchanged, null clears it), so `compact` dropping the undefineds is load-bearing: an omitted
+            // key is "unchanged", which is the truthful thing to say when the agent said nothing. A
+            // literal null is a different claim and is not one absence is entitled to make.
+            return [{
+                    eventName: 'compaction_update',
+                    payload: compact({
+                        compactionId: update.compactionId,
+                        status: update.status,
+                        summary: update.summary ?? undefined,
+                        error: update.error ?? undefined,
+                    }),
+                }];
+        case 'compaction_summary_chunk':
+            // identity mapping: the server event is now called `compaction_summary_chunk` too, carrying
+            // ACP's `{compactionId, content}` (`:4039`). This used to flatten the block to free text and
+            // drop the id entirely, so a non-text block became `[image]` and no consumer could attach the
+            // chunk back to the compaction it belongs to.
+            return [{
+                    eventName: 'compaction_summary_chunk',
+                    payload: { compactionId: update.compactionId, content: update.content },
+                }];
+        // --- draft ACP (RFD #1992) and the AIR async-task extension; shapes in `draftSubagents.ts` ---
+        //
+        // All five are identity mappings, for the same reason every other branch here is transport
+        // rather than translation: the normalisation point is server ingest, one place, so that a
+        // workstation running a version behind cannot put a second shape in the database. The names are
+        // ACP's (or, for the async-task trio, the ecosystem's), so there is nothing to rename.
+        case 'subagent_spawned':
+            return [{
+                    eventName: 'subagent_spawned',
+                    payload: compact({
+                        subagentSessionId: update.subagentSessionId,
+                        name: update.name,
+                        task: update.task,
+                        capabilities: update.capabilities,
+                        _meta: update._meta ?? undefined,
+                    }),
+                }];
+        case 'subagent_state_update':
+            return [{
+                    eventName: 'subagent_state_update',
+                    payload: compact({
+                        subagentSessionId: update.subagentSessionId,
+                        state: update.state,
+                        _meta: update._meta ?? undefined,
+                    }),
+                }];
+        case 'async_task_spawned':
+            // `toolCallId` is optional here **because it is genuinely absent** on this frame in practice —
+            // it arrives on the next `async_task_progress`. `compact` dropping it is what lets the server
+            // treat "not said yet" as different from "said to be nothing".
+            return [{
+                    eventName: 'async_task_spawned',
+                    payload: compact({
+                        asyncTaskId: update.asyncTaskId,
+                        name: update.name,
+                        taskType: update.taskType,
+                        description: update.description,
+                        showInTranscript: update.showInTranscript,
+                        canStop: update.canStop,
+                        outputFilePath: update.outputFilePath ?? undefined,
+                        toolCallId: update.toolCallId ?? undefined,
+                        _meta: update._meta ?? undefined,
+                    }),
+                }];
+        case 'async_task_progress':
+            return [{
+                    eventName: 'async_task_progress',
+                    payload: compact({
+                        asyncTaskId: update.asyncTaskId,
+                        description: update.description ?? undefined,
+                        summary: update.summary ?? undefined,
+                        lastToolName: update.lastToolName ?? undefined,
+                        usage: update.usage ?? undefined,
+                        outputFilePath: update.outputFilePath ?? undefined,
+                        toolCallId: update.toolCallId ?? undefined,
+                        _meta: update._meta ?? undefined,
+                    }),
+                }];
+        case 'async_task_state_update':
+            return [{
+                    eventName: 'async_task_state_update',
+                    payload: compact({
+                        asyncTaskId: update.asyncTaskId,
+                        state: update.state,
+                        summary: update.summary ?? undefined,
+                        outputFilePath: update.outputFilePath ?? undefined,
+                        toolCallId: update.toolCallId ?? undefined,
+                        _meta: update._meta ?? undefined,
+                    }),
+                }];
+        default: {
+            // Exhaustiveness guard (plan requirement): if the SDK ever adds a 16th `SessionUpdate` variant,
+            // `update` stops being assignable to `never` here and this file fails to *compile* — not just a
+            // test going red. The hardcoded value list in the test file is a second, weaker net.
+            //
+            // Widening the parameter to `IncomingSessionUpdate` does **not** weaken this: the five draft
+            // variants are named cases above, so they are subtracted from the union before it reaches
+            // here, and anything genuinely unknown still fails the assignment. Adding a draft variant to
+            // `draftSubagents.ts` without a branch here is therefore also a compile error, which is the
+            // property that keeps the two files from drifting apart.
+            const _exhaustive = update;
+            throw new Error(`unmapped sessionUpdate variant: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}