[Feature] ACP mode should report context usage (usage_update)

[AndriyPytel]

Affected area

Coding agent and CLI (ACP mode)

What is the problem?

ACP mode reports no usage information at all, so an ACP client cannot show how much of the context window a session has consumed. The number exists — the TUI renders it as the context bar — but nothing in src/modes/acp/ references usage or the context window, so over ACP it is invisible.

That matters most in exactly the setting ACP is for: a long driven session where the user cannot see the TUI and has no signal that compaction is approaching.

Proposed solution

Emit ACP's standard usage_update session update:

{ "sessionUpdate": "usage_update", "used": 20846, "size": 1000000 }

• used / size come from AgentConnectionState.contextUsage, the same ContextUsage the TUI bar renders, so the two cannot disagree.
• Emit after a completed assistant message and after compaction. Those are the only moments the reading can change (usage is costed when a response completes; compaction replaces the transcript), so a streaming turn does not cost a getState() round trip per delta.
• Skip the update while the reading is unknown — the window between a compaction and the next costed response, where tokens is null — rather than reporting zero.

usage_update is a first-class SessionUpdate variant in @agentclientprotocol/sdk, so nothing goes into _meta and a vanilla client gets this for free.

Alternatives considered

Putting the number in the Prime Agent _meta envelope: rejected, since only a Prime-Agent-aware client would read it, and ACP already has the standard field.

Polling usage on every session event: rejected, since it costs a round trip per streamed delta to report an unchanged number.

Additional context

A patch is up as #1351, with a test in test/suite/acp-mode.test.ts that drives a real ACP client over an in-memory duplex and asserts 0 < used < size (reverting the source change fails it); npm run check passes, and it is verified against a live prime-agent --mode acp process.

Opening this Discussion because the new contribution process routes intake here — this one has no Issue behind it, so treat the PR as a proposal rather than as accepted work.

[AndriyPytel]

@sethkarten flagging this one to you as well, as the author of ACP mode.

Where this comes from: I run Prime Agent through ACP rather than the TUI, and the context bar is the one thing I genuinely miss. Over ACP there is no signal at all that a session is filling up until compaction happens, which is a strange gap given that the number already exists and ACP has a standard field for it.

Captured from a real prime-agent --mode acp process, one initialize / session/new / session/prompt round, logging every session/update:

before (main)                                   after (#1351)
[0.86s] <- initialize                           [0.74s] <- initialize
[0.86s] <- session/new                          [0.74s] <- session/new
[0.87s] update  available_commands_update       [0.76s] update  available_commands_update
[2.78s] update  agent_message_chunk             [2.99s] update  agent_message_chunk
                                                [3.06s] update  usage_update  {"used":20851,"size":1000000}
[2.84s] <- session/prompt  {"end_turn"}         [3.08s] <- session/prompt  {"end_turn"}

(available_commands_update shows in both columns because I also run #1308 locally; on stock main that line is absent too.)

The patch is #1351. It reads the same ContextUsage the TUI bar renders, so the two cannot drift apart, and it only polls where the reading can actually change — a completed assistant message, or a compaction — rather than on every streamed delta.

If you would rather this rode in _meta, or waited until ACP marks the field stable, that is a reasonable call and I will close the PR. Worth noting that UsageUpdate itself is a plain SessionUpdate variant in the SDK; it is Usage (the per-turn token breakdown) that carries the UNSTABLE marker, and this change does not touch that.