ACP Server Notifications

These are ACP-compatible JSON-RPC notifications projected from Diminuendo gateway events. Fabric stream, conversation, and presentation events are the canonical internal model.

Thread Events

Notification	When
`thread/started`	Thread created and agent spawned
`thread/updated`	Thread metadata changed (name, settings)
`thread/archived`	Thread archived
`thread/tokenUsage/updated`	Token usage stats updated

Turn Events

Notification	When
`turn/started`	Agent started processing a turn
`turn/completed`	Agent finished processing
`turn/diff/updated`	File diff produced by agent
`turn/plan/updated`	Agent plan updated

Item Events (Streaming)

Notification	When
`item/started`	New content item started
`item/completed`	Content item finished
`item/agentMessage/delta`	Text content delta (streaming token)
`item/toolCall/started`	Agent started a tool call
`item/toolCall/completed`	Tool call finished
`item/terminalCommand/started`	Terminal command started
`item/terminalCommand/output`	Terminal output chunk
`item/terminalCommand/completed`	Terminal command finished
`item/fileChange/started`	File change started
`item/fileChange/completed`	File change applied

Server Requests (Gateway → Client)

These require a response from the client:

Method	Description
`item/commandExecution/requestApproval`	Request approval for a shell command
`item/fileChange/requestApproval`	Request approval for a file edit
`item/tool/requestUserInput`	Request user input (API key, choice, etc.)
`item/permissions/requestApproval`	Request additional permissions

DeltaCoalescer

High-frequency item/agentMessage/delta notifications are batched by the DeltaCoalescer:

10ms interval or 4KB threshold — whichever comes first
Reduces broadcast pressure without perceptible latency
Clients receive coalesced text deltas instead of individual tokens

Example: Complete Turn

// 1. Turn starts
{"jsonrpc":"2.0","method":"turn/started","params":{"turnId":"turn_1"}}

// 2. Agent message item starts
{"jsonrpc":"2.0","method":"item/started","params":{"itemId":"item_1","type":"agentMessage"}}

// 3. Streaming text deltas
{"jsonrpc":"2.0","method":"item/agentMessage/delta","params":{"itemId":"item_1","text":"Here "}}
{"jsonrpc":"2.0","method":"item/agentMessage/delta","params":{"itemId":"item_1","text":"is the fix..."}}

// 4. Tool call
{"jsonrpc":"2.0","method":"item/toolCall/started","params":{"itemId":"item_2","name":"edit_file"}}
{"jsonrpc":"2.0","method":"item/fileChange/started","params":{"path":"src/auth.ts"}}
{"jsonrpc":"2.0","method":"item/fileChange/completed","params":{"path":"src/auth.ts","diff":"..."}}
{"jsonrpc":"2.0","method":"item/toolCall/completed","params":{"itemId":"item_2"}}

// 5. Item and turn complete
{"jsonrpc":"2.0","method":"item/completed","params":{"itemId":"item_1"}}
{"jsonrpc":"2.0","method":"turn/completed","params":{"turnId":"turn_1","tokenUsage":{...}}}