diff --git a/docs/docs.json b/docs/docs.json index 8d57c16f..9a063d65 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -127,7 +127,6 @@ "rfds/diff-delete", "rfds/boolean-config-option", "rfds/elicitation", - "rfds/session-close", "rfds/next-edit-suggestions", "rfds/additional-directories", "rfds/custom-llm-endpoint" @@ -135,7 +134,7 @@ }, { "group": "Preview", - "pages": ["rfds/session-resume"] + "pages": ["rfds/session-close", "rfds/session-resume"] }, { "group": "Completed", diff --git a/docs/protocol/draft/schema.mdx b/docs/protocol/draft/schema.mdx index 30d5c3b2..76f259a7 100644 --- a/docs/protocol/draft/schema.mdx +++ b/docs/protocol/draft/schema.mdx @@ -845,7 +845,7 @@ This capability is not part of the spec yet, and may be removed or changed at an Closes an active session and frees up any resources associated with it. -This method is only available if the agent advertises the `session.close` capability. +This method is only available if the agent advertises the `sessionCapabilities.close` capability. The agent must cancel any ongoing work (as if `session/cancel` was called) and then free up any resources associated with the session. @@ -862,7 +862,7 @@ If supported, the agent **must** cancel any ongoing work related to the session (treat it as if `session/cancel` was called) and then free up any resources associated with the session. -Only available if the Agent supports the `session.close` capability. +Only available if the Agent supports the `sessionCapabilities.close` capability. **Type:** Object diff --git a/docs/protocol/draft/session-setup.mdx b/docs/protocol/draft/session-setup.mdx index 8360bba2..e8e3ac51 100644 --- a/docs/protocol/draft/session-setup.mdx +++ b/docs/protocol/draft/session-setup.mdx @@ -268,6 +268,79 @@ session is ready to continue. The response **MAY** also include initial mode, model, or session configuration state when those features are supported by the Agent. +## Closing Active Sessions + + + This section describes the preview `sessionCapabilities.close` capability. + Clients MUST gate usage on that capability being present during + initialization. + + +When advertised, Clients MAY call `session/close` to tell the Agent to cancel +any ongoing work for a session and free any resources associated with that +active session. + +### Checking Support + +Before attempting to close a session, Clients **MUST** verify that the Agent +supports this capability by checking the `sessionCapabilities.close` field in +the `initialize` response: + +```json highlight={8-10} +{ + "jsonrpc": "2.0", + "id": 0, + "result": { + "protocolVersion": 1, + "agentCapabilities": { + "sessionCapabilities": { + "close": {} + } + } + } +} +``` + +If `sessionCapabilities.close` is not present, the Agent does not support +closing sessions and Clients **MUST NOT** attempt to call `session/close`. + +### Closing a Session + +To close an active session, Clients **MUST** call the `session/close` method +with the session ID: + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "session/close", + "params": { + "sessionId": "sess_789xyz" + } +} +``` + + + The ID of the active session to close. + + +The Agent **MUST** cancel any ongoing work for that session as if +[`session/cancel`](../prompt-turn#cancellation) had been called, then free the +resources associated with the session. + +On success, the Agent responds with an empty result object: + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": {} +} +``` + +Agents MAY return an error if the session does not exist or is not currently +active. + ## Additional Workspace Roots diff --git a/docs/rfds/session-close.mdx b/docs/rfds/session-close.mdx index 211eea5c..1e43e913 100644 --- a/docs/rfds/session-close.mdx +++ b/docs/rfds/session-close.mdx @@ -44,8 +44,8 @@ Clients can track what sessions are actively used by a user and automatically cl > Tell me more about your implementation. What is your detailed implementation plan? We propose to add a new `"session/close"` method. Agents must declare this option is -available by returning `session: { close : {} }` in their capabilities. The object is reserved -to declare future capabilities. +available by returning `sessionCapabilities: { close: {} }` in their capabilities. The object is +reserved to declare future capabilities. Then the client would be able to close a specific session with: @@ -76,5 +76,6 @@ seems like a good idea. ## Revision history +2026-04-14: Move to preview and update capability docs to `sessionCapabilities.close` 2026-03-09: Rename from session/stop to session/close 2026-02-24: Initial draft diff --git a/docs/rfds/updates.mdx b/docs/rfds/updates.mdx index 7f4ade70..954c04b6 100644 --- a/docs/rfds/updates.mdx +++ b/docs/rfds/updates.mdx @@ -13,6 +13,13 @@ The RFD for adding a `session/resume` method to the protocol has been moved to P + +## session/close RFD moves to Preview stage + +The RFD for allowing agents to close a given session has been moved to Preview stage. Please review the [RFD](/rfds/session-close) 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 e90e42c4..abb6fb8a 100644 --- a/schema/schema.unstable.json +++ b/schema/schema.unstable.json @@ -1247,7 +1247,7 @@ "$ref": "#/$defs/CloseSessionRequest" } ], - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCloses an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `session.close` capability.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCloses an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `sessionCapabilities.close` capability.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", "title": "CloseSessionRequest" }, { @@ -1484,7 +1484,7 @@ "x-side": "agent" }, "CloseSessionRequest": { - "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 closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `session.close` 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 closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `sessionCapabilities.close` capability.", "properties": { "_meta": { "additionalProperties": true, diff --git a/src/agent.rs b/src/agent.rs index 5d064bfc..0dbfb838 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -1608,7 +1608,7 @@ impl ResumeSessionResponse { /// (treat it as if `session/cancel` was called) and then free up any resources /// associated with the session. /// -/// Only available if the Agent supports the `session.close` capability. +/// Only available if the Agent supports the `sessionCapabilities.close` capability. #[cfg(feature = "unstable_session_close")] #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] #[schemars(extend("x-side" = "agent", "x-method" = SESSION_CLOSE_METHOD_NAME))] @@ -4714,7 +4714,7 @@ pub enum ClientRequest { /// /// Closes an active session and frees up any resources associated with it. /// - /// This method is only available if the agent advertises the `session.close` capability. + /// This method is only available if the agent advertises the `sessionCapabilities.close` capability. /// /// The agent must cancel any ongoing work (as if `session/cancel` was called) /// and then free up any resources associated with the session.