ACP: the bridge emits only agent_message_chunk — tool calls and token usage never reach the wire (the SDK already models both)

[chyroc]

Summary

We built a multi-tenant agent platform that runs DSH as its inference backend over ACP, and we have real inference working end to end. This post is about the one gap that cost us the most: the ACP bridge emits exactly one SessionUpdate variant, so an automation client cannot reconstruct what happened during a turn — only the final text.

We read 2026-07-23-acp-automation-only-protocol.md first, and we are not asking to relitigate it. Keeping editor cards, plans, titles, modes and human elicitation out of an automation transport is the right call, and packages/acp/acp/README.md:76-81 registers the consequences honestly.

Our ask is narrower, and we think it is consistent with that decision rather than a reversal of it: tool activity and token usage are not presentation. They are machine-readable control-flow and accounting facts that an automated controller needs, and they are the two things the note's "inspect durable logs or another API" escape hatch cannot deliver for an out-of-process client.

The current surface

One sessionUpdate literal exists in the whole package:

$ grep -n "sessionUpdate" packages/acp/acp/src/index.ts
150:      await conn.sessionUpdate(notification)
235:              update: { sessionUpdate: 'agent_message_chunk', content },

The event handler at packages/acp/acp/src/index.ts:222-252 subscribes to session/event and filters to assistant/message only.

What makes this cheap: the SDK already models all of it

This is the part we want to highlight — none of the following needs a protocol extension or a _meta convention. The pinned @agentclientprotocol/sdk 0.25.1 (packages/acp/acp/package.json:35) already defines the full union at dist/schema/types.gen.d.ts:4623:

export type SessionUpdate =
  | (ContentChunk   & { sessionUpdate: "user_message_chunk" })   // :4624
  | (ContentChunk   & { sessionUpdate: "agent_message_chunk" })  // :4626  <- the only one emitted
  | (ContentChunk   & { sessionUpdate: "agent_thought_chunk" })
  | (ToolCall       & { sessionUpdate: "tool_call" })            // :4630
  | (ToolCallUpdate & { sessionUpdate: "tool_call_update" })     // :4632
  | ... | (UsageUpdate & { sessionUpdate: "usage_update" })      // :4648

And the harness's own internal event map already carries the data, in packages/core/session/src/types.ts:

Internal event	Line	Maps onto
tool/call — { turn, step, callId, name, arguments }	:283	tool_call
tool/result — { turn, step, message, error? }	:295	tool_call_update
user/message — UserMessage	:264	user_message_chunk
assistant/message — { …, usage?: TokenUsage }	:277	usage / usage_update

So the gap is purely projection at the transport boundary. The producers, the schema, and the SDK helpers all exist already.

1. Tool calls are invisible

Tools execute inside DSH and the ACP client sees nothing until the final assistant text. A concrete minimal shape, all fields already in ToolCall (types.gen.d.ts:5231 for ToolCallStatus, :5292 for ToolKind):

// on tool/call
{ "sessionId": "…", "update": {
    "sessionUpdate": "tool_call",
    "toolCallId": "<callId>",     // the existing CallId
    "title": "<tool name>",
    "status": "in_progress",
    "rawInput": { }               // the existing arguments
}}
// on tool/result
{ "sessionId": "…", "update": {
    "sessionUpdate": "tool_call_update",
    "toolCallId": "<callId>",
    "status": "completed",        // or "failed" when error is set
    "rawOutput": { }
}}

title/rawInput alone are enough for automation. Deciding not to synthesize kind or locations (the render-intent concern that 2026-07-04-trim-acp-bridge-unreachable-surface.md deliberately removed) would be entirely consistent — we are asking for the correlation facts, not the cards.

Our workaround: we route every tool through our own MCP facade so we can account for tool calls on our side, and we synthesize the timeline there. That only works because we own the tool surface; it does nothing for DSH-internal tools.

2. No token usage at the ACP boundary

session/prompt returns only { stopReason } (packages/acp/acp/src/index.ts:405, :421-422). The harness has @deepseek-ai/dsh-token-meter and assistant/message already carries usage?: TokenUsage (packages/core/session/src/types.ts:277), but nothing reaches the wire — so metering and billing integrations get zero.

PromptResponse already has a first-class optional usage field (types.gen.d.ts:3730), and the shapes line up almost 1:1:

TokenUsage (packages/llm/llm/src/types.ts:135)	ACP Usage (types.gen.d.ts:5334)
inputTokens	inputTokens
outputTokens	outputTokens
cacheReadTokens?	cachedReadTokens?
cacheWriteTokens?	cachedWriteTokens?
reasoningTokens?	thoughtTokens?

Populating PromptResponse.usage on the turn-end frame looks like the smallest possible change with the highest value, and it adds no new event type at all.

Our workaround: none available in-band. We currently reconcile token cost from our model gateway's billing records instead of from the agent runtime, which means our per-turn attribution is coarser than for our other backends.

3. agent_message_chunk carries no messageId

At packages/acp/acp/src/index.ts:233-236 the notification omits messageId, so a client receiving several chunks cannot group them per assistant message. ContentChunk.messageId is optional in the schema (types.gen.d.ts:903), so this is spec-legal — but Message.id is described as "Stable identity preserved across every representation boundary" (packages/llm/llm/src/message.ts:129-131) and is already in hand at the emit site, so passing it through looks close to free.

Is the omission intentional, given the bridge emits whole committed messages rather than deltas?

4. No turn-state signal

There is no running/idle frame, so clients synthesize turn boundaries from the session/prompt call/return pair. That works for one in-flight prompt per session and we are not asking for a new event type here — noting it only because session_info_update and current_mode_update exist in the union and might already be the intended home.

Why the durable log isn't a substitute

The automation-only note suggests clients "inspect durable logs or another API" for tool traces and usage. For an out-of-process client that boundary is hard to use: the JSONL log is an internal format with no compatibility promise, it requires shared-filesystem access to the agent's persistenceRoot (fine for a subagent on the same host, not for a service consuming DSH over a process boundary), and there is no ACP method to read it — session/load, list and resume are all unsupported. So in practice ACP is the only surface available, and it is the one place the data is missing.

Offer

We are happy to contribute PRs. The projection in ctx.on('session/event', …) is where all four of these land, and we have equivalent mappings working in our own client already. If you would prefer these gated behind an opt-in config so the default automation contract stays minimal, that works for us too — say the word on shape and we will follow it.

Happy to be told we have misread the design intent on any of these.

[denial123789]

The useful distinction here is presentation versus control-plane facts. Omitting plans, modes, titles, and render-oriented cards keeps the automation contract small; correlated tool lifecycle and per-turn usage answer different machine questions: whether policy/cancellation/audit can identify the active action, and whether tenant accounting can reconcile the turn. A minimal projection could preserve the existing callId from tool/call through exactly one terminal tool_call_update, then normalize assistant-message usage into PromptResponse.usage or usage_update. Raw arguments and results need an explicit redaction and retention policy before crossing the process boundary. We added a source-pinned capability ledger, safe workaround guidance, and acceptance gates here: https://sandbaseai.github.io/deepseek-harness-handbook/acp-editor-boundary.html

Disclosure: I contribute to this independent community handbook.