new RFD: Create agent_message_clear.md #465
Open
+96
−0
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Problem
The current
agent_message_chunksession update is strictly append-only — the client concatenates all received chunks into the agent's message. However, there is no mechanism to clear or replace already-streamed message content. This creates a significant problem for agents whose underlying content generation is non-monotonic.Why non-monotonic streaming matters
Many AI agent backends do not produce strictly append-only token streams. Real-world scenarios where the streamed content may change non-monotonically include:
Current workaround and its limitations
Without a reset mechanism, agents are currently forced into suboptimal hacks to "correct" the UI:
\n---\n) and then re-send the entire updated text from the beginning.Precedent within ACP
The protocol already has full-replacement semantics for other session update types:
plan: "The client replaces the entire plan with each update" — each plan update contains the complete plan.tool_call_update→content: "Replace the content collection" — the new content array fully replaces the old one.So the concept of "replace what was previously sent" is not foreign to the protocol.
Proposal
Add a new session update type —
agent_message_clear— that instructs the client to clear the accumulated streamed content for the current agent message. Subsequentagent_message_chunkupdates would start appending from empty again.{ "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123", "update": { "sessionUpdate": "agent_message_clear" } } }Alternative designs considered
agent_message_clear(proposed)agent_message_replacewith full textagent_message_chunkwithreplace: trueflagThe
agent_message_clearapproach is the simplest and most consistent with existing ACP patterns:planworks (clear-then-replace is conceptually "send a fresh plan").agent_message_chunksemantics unchanged (always append).Usage pattern
The same pattern applies to
agent_thought_clearif needed, thoughagent_message_clearcovers the primary use case.Impact
This change would:
---into the message stream.fountto push full-state updates safely by simply issuing aclearbefore re-pushing a modified state.SessionUpdatevariant, no changes to existing types.