diff --git a/docs/docs.json b/docs/docs.json index be358463..8d57c16f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -114,7 +114,6 @@ "pages": [ "rfds/session-fork", "rfds/request-cancellation", - "rfds/session-resume", "rfds/meta-propagation", "rfds/agent-telemetry-export", "rfds/proxy-chains", @@ -136,7 +135,7 @@ }, { "group": "Preview", - "pages": [] + "pages": ["rfds/session-resume"] }, { "group": "Completed", diff --git a/docs/protocol/draft/schema.mdx b/docs/protocol/draft/schema.mdx index c93ba7f4..39586404 100644 --- a/docs/protocol/draft/schema.mdx +++ b/docs/protocol/draft/schema.mdx @@ -1205,7 +1205,7 @@ This capability is not part of the spec yet, and may be removed or changed at an Resumes an existing session without returning previous messages. -This method is only available if the agent advertises the `session.resume` capability. +This method is only available if the agent advertises the `sessionCapabilities.resume` capability. The agent should resume the session context, allowing the conversation to continue without replaying the message history (unlike `session/load`). @@ -1221,7 +1221,7 @@ Request parameters for resuming an existing session. Resumes an existing session without returning previous messages (unlike `session/load`). This is useful for agents that can resume sessions but don't implement full session loading. -Only available if the Agent supports the `session.resume` capability. +Only available if the Agent supports the `sessionCapabilities.resume` capability. **Type:** Object diff --git a/docs/protocol/draft/session-setup.mdx b/docs/protocol/draft/session-setup.mdx index 0e19536a..8360bba2 100644 --- a/docs/protocol/draft/session-setup.mdx +++ b/docs/protocol/draft/session-setup.mdx @@ -30,6 +30,11 @@ sequenceDiagram Agent->>Client: session/update Note over Agent,Client: All content streamed Agent-->>Client: session/load response + else + Client->>Agent: session/resume (sessionId) + Note over Agent: Restore session context + Note over Agent: Connect to MCP servers + Agent-->>Client: session/resume response end Note over Client,Agent: Ready for prompts @@ -77,7 +82,7 @@ The Agent **MUST** respond with a unique [Session ID](#session-id) that identifi ## Loading Sessions -Agents that support the `loadSession` capability allow Clients to resume previous conversations. This feature enables persistence across restarts and sharing sessions between different Client instances. +Agents that support the `loadSession` capability allow Clients to resume previous conversations with history replay. This feature enables persistence across restarts and sharing sessions between different Client instances. ### Checking Support @@ -166,17 +171,102 @@ Followed by the agent's response: } ``` -When **all** the conversation entries have been streamed to the Client, the Agent **MUST** respond to the original `session/load` request. +When **all** the conversation entries have been streamed to the Client, the +Agent **MUST** respond to the original `session/load` request. ```json { "jsonrpc": "2.0", "id": 1, - "result": null + "result": {} +} +``` + +The response **MAY** also include initial mode, model, or session configuration +state when those features are supported by the Agent. + +The Client can then continue sending prompts as if the session was never +interrupted. + +## Resuming Sessions + + + This section describes the preview `session/resume` method. Clients MUST gate + usage on the `sessionCapabilities.resume` capability being present during + initialization. + + +Agents that advertise `sessionCapabilities.resume` allow Clients to reconnect to +an existing session without replaying the conversation history. + +### Checking Support + +Before attempting to resume a session, Clients **MUST** verify that the Agent +supports this capability by checking for the `sessionCapabilities.resume` field +in the `initialize` response: + +```json highlight={8-10} +{ + "jsonrpc": "2.0", + "id": 0, + "result": { + "protocolVersion": 1, + "agentCapabilities": { + "sessionCapabilities": { + "resume": {} + } + } + } +} +``` + +If `sessionCapabilities.resume` is not present, the Agent does not support +resuming sessions and Clients **MUST NOT** attempt to call `session/resume`. + +### Resuming a Session + +To resume an existing session without replaying prior messages, Clients +**MUST** call the `session/resume` method with: + +- The [Session ID](#session-id) to resume +- [MCP servers](#mcp-servers) to connect to +- The [working directory](#working-directory) + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "session/resume", + "params": { + "sessionId": "sess_789xyz", + "cwd": "/home/user/project", + "mcpServers": [ + { + "name": "filesystem", + "command": "/path/to/mcp-server", + "args": ["--mode", "filesystem"], + "env": [] + } + ] + } +} +``` + +Unlike `session/load`, the Agent **MUST NOT** replay the conversation history +via `session/update` notifications before responding. Instead, it restores the +session context, reconnects to the requested MCP servers, and returns once the +session is ready to continue. + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": {} } ``` -The Client can then continue sending prompts as if the session was never interrupted. +The response **MAY** also include initial mode, model, or session configuration +state when those features are supported by the Agent. ## Additional Workspace Roots @@ -214,7 +304,7 @@ When present, `additionalDirectories` has the following behavior: - `cwd` remains the primary working directory and the base for relative paths - each `additionalDirectories` entry **MUST** be an absolute path - omitting the field or providing an empty array activates no additional roots for the resulting session -- on `session/load`, Clients must send the full intended additional-root list again because omitting the field or providing an empty array does not restore stored roots implicitly +- on `session/load` and `session/resume`, Clients must send the full intended additional-root list again because omitting the field or providing an empty array does not restore stored roots implicitly ## Session ID @@ -225,6 +315,7 @@ Clients use this ID to: - Send prompt requests via `session/prompt` - Cancel ongoing operations via `session/cancel` - Load previous sessions via `session/load` (if the Agent supports the `loadSession` capability) +- Resume previous sessions via `session/resume` (if the Agent supports the preview `sessionCapabilities.resume` capability) ## Working Directory diff --git a/docs/rfds/session-resume.mdx b/docs/rfds/session-resume.mdx index f3c07d27..309af6e5 100644 --- a/docs/rfds/session-resume.mdx +++ b/docs/rfds/session-resume.mdx @@ -28,7 +28,8 @@ could be used as a mechanism for proxies and adapter libraries to emulate "sessi > What are you proposing to improve the situation? -Add a "session/resume" command and a capability `{ session: { resume: {} }`. +Add a "session/resume" command and a capability +`{ sessionCapabilities: { resume: {} } }`. ## Shiny future @@ -82,4 +83,5 @@ This argues "session/resume" is the basic primitive which "session/load" builds ## Revision history +- 2026-04-14: Update capability shape to `sessionCapabilities.resume` - 2025-11-24: Update FAQ to mention session/resume vs session/load diff --git a/docs/rfds/updates.mdx b/docs/rfds/updates.mdx index 19d325c4..7f4ade70 100644 --- a/docs/rfds/updates.mdx +++ b/docs/rfds/updates.mdx @@ -6,6 +6,13 @@ rss: true This page tracks lifecycle changes for ACP Requests for Dialog. For broader ACP announcements, see [Updates](/updates). + +## session/resume RFD moves to Preview stage + +The RFD for adding a `session/resume` method to the protocol has been moved to Preview stage. Please review the [RFD](/rfds/session-resume) for more information on the current proposal and provide feedback before the feature is stabilized. + + + ## Custom LLM Endpoint RFD moves to Draft stage diff --git a/schema/schema.unstable.json b/schema/schema.unstable.json index b1c12adc..919bbbbc 100644 --- a/schema/schema.unstable.json +++ b/schema/schema.unstable.json @@ -1176,7 +1176,7 @@ "$ref": "#/$defs/ResumeSessionRequest" } ], - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `session.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `sessionCapabilities.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", "title": "ResumeSessionRequest" }, { @@ -4989,7 +4989,7 @@ "type": "object" }, "ResumeSessionRequest": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `session.resume` capability.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `sessionCapabilities.resume` capability.", "properties": { "_meta": { "additionalProperties": true, diff --git a/src/agent.rs b/src/agent.rs index 8166c4a6..d864ace2 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -1428,7 +1428,7 @@ impl ForkSessionResponse { /// Resumes an existing session without returning previous messages (unlike `session/load`). /// This is useful for agents that can resume sessions but don't implement full session loading. /// -/// Only available if the Agent supports the `session.resume` capability. +/// Only available if the Agent supports the `sessionCapabilities.resume` capability. #[cfg(feature = "unstable_session_resume")] #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] #[schemars(extend("x-side" = "agent", "x-method" = SESSION_RESUME_METHOD_NAME))] @@ -4202,7 +4202,7 @@ pub enum ClientRequest { /// /// Resumes an existing session without returning previous messages. /// - /// This method is only available if the agent advertises the `session.resume` capability. + /// This method is only available if the agent advertises the `sessionCapabilities.resume` capability. /// /// The agent should resume the session context, allowing the conversation to continue /// without replaying the message history (unlike `session/load`).