Elevator pitch
What are you proposing to change?ACP v2 should unify
session/load and session/resume into a single
session/resume method. Clients that need replay can set a replayFrom cursor
on session/resume; clients that omit replayFrom get the current resume
behavior without history replay.
Status quo
How do things work today and what problems does this cause? Why would we change things?In v1,
session/load and session/resume are separate methods. They restore
the same existing session context, reconnect MCP servers, and accept the same
workspace parameters. The main behavioral difference is replay:
session/loadreplays previous conversation history before responding.session/resumerestores the session without replaying previous history.
What we propose to do about it
What are you proposing to improve the situation?Remove
session/load from the v2 method surface and keep session/resume.
ResumeSessionRequest gains an optional replayFrom field.
Omitted replayFrom and replayFrom: null are equivalent: the Agent resumes
without replaying previous conversation history.
The initial replay cursor is:
replayFrom: { "type": "start" } means the Agent replays all retained
conversation history through session/update notifications before responding to the
session/resume request.
The schema accepts custom and future cursor types for preservation by
intermediaries. An Agent that does not support the supplied cursor type
MUST reject session/resume with -32602 (Invalid params), rather than
substituting another cursor or resuming without replay. Malformed cursors also
result in -32602.
This does not require the Agent to retain every inserted user message.
Live-only or discarded messages may be absent; retained user messages must
preserve the ID returned on insertion, as defined by the Prompt Lifecycle RFD.
Replay uses the same updates as live delivery. The Agent can send each entity’s updates or only its current state, such as a terminal output snapshot instead of every chunk.
Agents SHOULD preserve agent and thought message IDs, toolCallId, terminalId, and planId across replay when possible, but Clients cannot assume stability across reconnects or Agent restarts. Full replay should rebuild messages, tool calls, terminals, and plans rather than merge them into existing state solely by ID. The empty-content primer for chunked
replay initializes or clears content only under the ID used in that replay;
it does not reconcile messages previously delivered under different IDs.
Replay cursors are inclusive: replay includes the position identified by the
cursor. Future cursors that identify a message would replay that message before
continuing with later history.
Shiny future
How will things play out once this feature exists?Clients always reconnect to existing sessions through
session/resume. They
choose replay behavior by setting or omitting replayFrom, rather than choosing
between two different restore methods.
This leaves room for future replay cursors, such as replaying from a specific
message, checkpoint, or server-provided cursor, without adding more session
restore methods.
Implementation details and plan
Tell me more about your implementation. What is your detailed implementation plan?
- Remove
session/load,LoadSessionRequest, andLoadSessionResponsefrom the v2 schema. - Add
replayFromtoResumeSessionRequestas an optional tagged union. - Add the initial
replayFromvariant{ "type": "start" }.
_meta as a metadata patch, as
live delivery does, and does not reset it. When the Client may already hold
metadata for an entity, the Agent removes stale keys by setting them to null,
or sends _meta: null before the current object.
Frequently asked questions
What questions have arisen over the course of authoring this document or during subsequent discussions?
Is replayFrom required?
No. The field is optional. Omitted and null both mean no history replay.
Why use an object instead of a string?
An object leaves room for future cursor forms that need fields. The initialstart form has no fields beyond type.
Revision history
- 2026-10-28: Replay may send current state instead of every update, and covers tool calls, terminals, and plans, not only messages.
- 2026-10-13: Replay applies top-level
_metaas a key-level patch, per Metadata Patches. - 2026-07-02: Initial draft.