From 639c00b6fd2fe95cd3abf33759c759ec5dde9327 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Tue, 17 Nov 2026 12:10:02 +0100 Subject: [PATCH] feat(unstable): add session cursors and cursorId on session/fork Implement steps 1 and 2 of the Session Cursors RFD behind the new `unstable_session_cursors` feature, and the fork RFD's "Forking at a cursor" section. - Add `SessionUpdate::CursorUpdate` in v1 and v2, with `CursorUpdate`, `CursorId`, `CursorCapabilities`, `CursorAnchor`, and `CursorAnchorPosition`. The update is an upsert keyed by `cursorId`. `capabilities` is a nullable patch, like tool call capabilities. - Anchors cover user messages, agent messages, agent thoughts, session messages, tool calls, and compactions. Unknown anchor types and positions are preserved, so a Client can tell that it cannot place the cursor. - Parse `capabilities` and `_meta` leniently. A malformed anchor fails the update, and a malformed known anchor type never falls through to the `Other` fallback. - Add the `session.cursors` Client capability in v1. V2 needs no capability. - Add an optional `cursorId` to `session/fork` and a `fork` cursor capability, behind `unstable_session_fork` and `unstable_session_cursors`. A malformed `cursorId` fails with `-32602` and is not treated as omitted. - List `cursor_update` as a known v2 discriminator so a malformed update never falls through to the `Other` fallback. - Document cursors, anchors, placement, replay, and forking at a cursor in the draft v1 and v2 protocol pages. - Add the RFD's Draft entry to the RFD updates page and note the landed steps in both RFDs' revision histories. --- agent-client-protocol-schema/Cargo.toml | 2 + agent-client-protocol-schema/src/v1/agent.rs | 81 ++ agent-client-protocol-schema/src/v1/client.rs | 863 +++++++++++++++++- agent-client-protocol-schema/src/v2/agent.rs | 80 ++ agent-client-protocol-schema/src/v2/client.rs | 781 ++++++++++++++++ .../tests/experimental_compatibility.rs | 17 + docs/protocol/v1/draft/initialization.mdx | 17 + docs/protocol/v1/draft/overview.mdx | 1 + docs/protocol/v1/draft/prompt-turn.mdx | 135 +++ docs/protocol/v1/draft/schema.mdx | 500 ++++++++++ docs/protocol/v1/draft/session-setup.mdx | 7 + docs/protocol/v2/draft/extensibility.mdx | 21 +- docs/protocol/v2/draft/overview.mdx | 6 +- docs/protocol/v2/draft/prompt-lifecycle.mdx | 124 +++ docs/protocol/v2/draft/schema.mdx | 492 ++++++++++ docs/protocol/v2/draft/session-setup.mdx | 7 + docs/rfds/session-cursors.mdx | 3 +- docs/rfds/session-fork.mdx | 1 + docs/rfds/updates.mdx | 7 + schema-generator/src/main.rs | 90 ++ schema/v1/schema.unstable.json | 412 +++++++++ schema/v2/schema.unstable.json | 406 ++++++++ 22 files changed, 4038 insertions(+), 15 deletions(-) diff --git a/agent-client-protocol-schema/Cargo.toml b/agent-client-protocol-schema/Cargo.toml index bc7af1da7..2a1dbc66d 100644 --- a/agent-client-protocol-schema/Cargo.toml +++ b/agent-client-protocol-schema/Cargo.toml @@ -35,6 +35,7 @@ unstable = [ "unstable_prompt_suggestions", "unstable_proxy_chains", "unstable_session_archive", + "unstable_session_cursors", "unstable_session_fork", "unstable_session_status", "unstable_session_options", @@ -55,6 +56,7 @@ unstable_plan_operations = [] unstable_prompt_suggestions = [] unstable_proxy_chains = [] unstable_session_archive = [] +unstable_session_cursors = [] unstable_session_fork = [] unstable_session_status = [] unstable_session_options = [] diff --git a/agent-client-protocol-schema/src/v1/agent.rs b/agent-client-protocol-schema/src/v1/agent.rs index e7abf8b3d..73ce291a7 100644 --- a/agent-client-protocol-schema/src/v1/agent.rs +++ b/agent-client-protocol-schema/src/v1/agent.rs @@ -13,6 +13,12 @@ use serde_with::{DefaultOnError, DefaultOnNull, VecSkipError, serde_as, skip_ser use crate::{IntoOption, ProtocolVersion}; +#[cfg(all( + feature = "unstable_session_fork", + feature = "unstable_session_cursors" +))] +use super::CursorId; + use super::{ ClientCapabilities, ContentBlock, ExtNotification, ExtRequest, ExtResponse, Meta, SessionId, }; @@ -1689,6 +1695,21 @@ impl LoadSessionResponse { pub struct ForkSessionRequest { /// The ID of the session to fork. pub session_id: SessionId, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// The session cursor to fork at. The new session's history is the source + /// session's history before the cursor. + /// + /// Optional. Omitted and `null` are equivalent and fork the whole session. + /// Clients MUST only send the ID of a cursor that the Agent announced on the + /// source session and that currently advertises `capabilities.fork`. The Agent + /// rejects any other ID with `-32602`. It does not fall back to forking the + /// whole session. + #[cfg(feature = "unstable_session_cursors")] + #[serde(default)] + pub cursor_id: Option, /// The working directory for this session. Must be an absolute path. pub cwd: PathBuf, /// Additional workspace roots to activate for this session. Each path must be absolute. @@ -1756,6 +1777,8 @@ impl ForkSessionRequest { pub fn new(session_id: impl Into, cwd: impl Into) -> Self { Self { session_id: session_id.into(), + #[cfg(feature = "unstable_session_cursors")] + cursor_id: None, cwd: cwd.into(), additional_directories: vec![], mcp_servers: vec![], @@ -1766,6 +1789,21 @@ impl ForkSessionRequest { } } + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// The session cursor to fork at. Omitting it forks the whole session. + /// + /// Clients MUST only send the ID of a cursor that the Agent announced on the + /// source session and that currently advertises `capabilities.fork`. + #[cfg(feature = "unstable_session_cursors")] + #[must_use] + pub fn cursor_id(mut self, cursor_id: impl IntoOption) -> Self { + self.cursor_id = cursor_id.into_option(); + self + } + /// Additional workspace roots to activate for this session. Each path must be absolute. #[must_use] pub fn additional_directories(mut self, additional_directories: Vec) -> Self { @@ -9158,4 +9196,47 @@ mod test_serialization { json!({"state": "unauthenticated"}) ); } + + #[cfg(all( + feature = "unstable_session_fork", + feature = "unstable_session_cursors" + ))] + #[test] + fn fork_session_request_cursor_id_is_optional_and_strict() { + let request = ForkSessionRequest::new("sess_abc123", "/home/user/project") + .cursor_id(CursorId::new("cur_1")); + let wire = json!({ + "sessionId": "sess_abc123", + "cursorId": "cur_1", + "cwd": "/home/user/project" + }); + assert_eq!(serde_json::to_value(&request).unwrap(), wire); + assert_eq!( + serde_json::from_value::(wire).unwrap(), + request + ); + + // Omitted and `null` both fork the whole session. + for wire in [ + json!({ "sessionId": "sess_abc123", "cwd": "/home/user/project" }), + json!({ "sessionId": "sess_abc123", "cwd": "/home/user/project", "cursorId": null }), + ] { + assert_eq!( + serde_json::from_value::(wire) + .unwrap() + .cursor_id, + None + ); + } + + // A malformed cursor ID fails the request. It never forks the whole session. + assert!( + serde_json::from_value::(json!({ + "sessionId": "sess_abc123", + "cwd": "/home/user/project", + "cursorId": 7 + })) + .is_err() + ); + } } diff --git a/agent-client-protocol-schema/src/v1/client.rs b/agent-client-protocol-schema/src/v1/client.rs index 2b475aad5..19b3381b6 100644 --- a/agent-client-protocol-schema/src/v1/client.rs +++ b/agent-client-protocol-schema/src/v1/client.rs @@ -6,17 +6,22 @@ use std::{path::PathBuf, sync::Arc}; use derive_more::{Display, From}; -#[cfg(all(feature = "schemars", feature = "unstable_subagents"))] +#[cfg(all( + feature = "schemars", + any(feature = "unstable_subagents", feature = "unstable_session_cursors") +))] use schemars::Schema; use serde::{Deserialize, Serialize}; use serde_with::{DefaultOnError, DefaultOnNull, VecSkipError, serde_as, skip_serializing_none}; -#[cfg(feature = "unstable_subagents")] +#[cfg(any(feature = "unstable_subagents", feature = "unstable_session_cursors"))] use std::collections::BTreeMap; #[cfg(feature = "unstable_auth_status")] use super::AuthStatusUpdateNotification; #[cfg(feature = "unstable_subagents")] use super::Error; +#[cfg(feature = "unstable_session_cursors")] +use super::ToolCallId; #[cfg(all( feature = "unstable_subagents", feature = "unstable_end_turn_token_usage" @@ -171,6 +176,16 @@ pub enum SessionUpdate { /// /// This capability is not part of the spec yet, and may be removed or changed at any point. /// + /// A session cursor has been announced or its capabilities have changed. + /// + /// Agents MUST only send this update when the Client advertised + /// the `session.cursors` Client capability. + #[cfg(feature = "unstable_session_cursors")] + CursorUpdate(CursorUpdate), + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// /// Announces a child session created and owned by this session, or updates /// that ownership association's metadata. #[cfg(feature = "unstable_subagents")] @@ -939,6 +954,563 @@ impl CompactionSummaryChunk { } } +// Session cursors + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Unique identifier for a session cursor within a session. +/// +/// The Agent generates it, and it is never reused for another position in the +/// session. Clients MUST NOT parse, change, or construct it. +/// +/// See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). +#[cfg(feature = "unstable_session_cursors")] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)] +#[serde(transparent)] +#[from(forward)] +#[non_exhaustive] +pub struct CursorId(pub Arc); + +#[cfg(feature = "unstable_session_cursors")] +impl CursorId { + /// Wraps a protocol string as a typed [`CursorId`]. + #[must_use] + pub fn new(id: impl Into) -> Self { + id.into() + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// A session cursor upsert. A cursor names one position in the session's timeline. +/// +/// The first update for a `cursorId` MUST include `anchor`. The anchor is fixed +/// after that, and later updates change only `capabilities`. +/// +/// Agents MUST only send this update when the Client advertised +/// the `session.cursors` Client capability. +/// +/// `capabilities` and `_meta` have patch semantics: omission leaves the stored +/// value unchanged, `null` clears it, and a concrete value replaces it. +/// +/// See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorUpdate { + /// The Agent-owned ID of this cursor, unique within the session. + pub cursor_id: CursorId, + /// The methods that currently accept this cursor. + /// + /// Omission leaves the capabilities unchanged, `null` clears them, and an object replaces + /// the whole previous value. A new cursor starts with none. + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")] + pub capabilities: MaybeUndefined, + /// Where the cursor is, relative to an entity the Client holds. + /// + /// Required on the first update for a cursor. The Agent MUST NOT change it afterwards. + /// A later update can omit it or repeat the same anchor. Omitted and `null` are + /// equivalent and leave the stored anchor unchanged. + #[serde(default)] + pub anchor: Option, + /// Extensible metadata patch for this cursor. + #[serde_as(deserialize_as = "DefaultOnError>")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde( + rename = "_meta", + default, + skip_serializing_if = "MaybeUndefined::is_undefined" + )] + pub meta: MaybeUndefined, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorUpdate { + /// Builds a cursor update with the anchor and patch fields omitted. + #[must_use] + pub fn new(cursor_id: impl Into) -> Self { + Self { + cursor_id: cursor_id.into(), + capabilities: MaybeUndefined::Undefined, + anchor: None, + meta: MaybeUndefined::Undefined, + } + } + + /// Replaces, clears, or leaves unchanged the methods that accept this cursor. + #[must_use] + pub fn capabilities( + mut self, + capabilities: impl IntoMaybeUndefined, + ) -> Self { + self.capabilities = capabilities.into_maybe_undefined(); + self + } + + /// Sets the anchor. The first update for a cursor MUST carry one. + #[must_use] + pub fn anchor(mut self, anchor: impl IntoOption) -> Self { + self.anchor = anchor.into_option(); + self + } + + /// Sets, clears, or omits the metadata patch. + #[must_use] + pub fn meta(mut self, meta: impl IntoMaybeUndefined) -> Self { + self.meta = meta.into_maybe_undefined(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// The methods that currently accept a session cursor. +/// +/// A malformed value falls back to no capabilities, so the Client never passes a +/// cursor to a method the Agent did not advertise. +/// +/// See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorCapabilities { + /// Permits the Client to fork the session at this cursor with `session/fork`. + /// + /// Omitted and `null` are equivalent and mean unsupported. An object (including `{}`) + /// means supported. + #[cfg(feature = "unstable_session_fork")] + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + pub fork: Option, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorCapabilities { + /// Builds an empty capability set. No method accepts the cursor. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Permits or stops permitting `session/fork` at this cursor. + #[cfg(feature = "unstable_session_fork")] + #[must_use] + pub fn fork(mut self, fork: impl IntoOption) -> Self { + self.fork = fork.into_option(); + self + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Capability to fork the session at a cursor with `session/fork`. +/// +/// Supplying `{}` advertises support. An omitted or `null` `fork` does not. +#[cfg(all( + feature = "unstable_session_cursors", + feature = "unstable_session_fork" +))] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[non_exhaustive] +pub struct CursorForkCapabilities { + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(all( + feature = "unstable_session_cursors", + feature = "unstable_session_fork" +))] +impl CursorForkCapabilities { + /// Builds an empty capability object advertising fork support. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Where a session cursor is, relative to an entity the Client holds. +/// +/// The anchor names the entity by its type and ID, and `position` says on which +/// side of that entity the cursor is. A known `type` with a malformed payload is +/// an error. It does not fall back to the unknown-type variant. +/// +/// See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). +#[cfg(feature = "unstable_session_cursors")] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(tag = "type", rename_all = "snake_case")] +#[non_exhaustive] +pub enum CursorAnchor { + /// The cursor is next to a user message. + UserMessage(CursorMessageAnchor), + /// The cursor is next to an agent message. + AgentMessage(CursorMessageAnchor), + /// The cursor is next to an agent thought. + AgentThought(CursorMessageAnchor), + /// The cursor is next to a session-directed message. + #[cfg(feature = "unstable_subagents")] + SessionMessage(CursorMessageAnchor), + /// The cursor is next to a tool call. + ToolCall(CursorToolCallAnchor), + /// The cursor is next to a compaction. + Compaction(CursorCompactionAnchor), + /// Custom or future anchor type. + /// + /// Values beginning with `_` are reserved for implementation-specific + /// extensions. Unknown values that do not begin with `_` are reserved for + /// future ACP variants. + /// + /// A Client that does not recognize the type cannot place the cursor and + /// MUST NOT guess a place for it. + #[serde(untagged)] + Other(OtherCursorAnchor), +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// On which side of the anchored entity a session cursor is. +#[cfg(feature = "unstable_session_cursors")] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "snake_case")] +#[non_exhaustive] +pub enum CursorAnchorPosition { + /// The cursor is immediately before the entity. The history before the + /// cursor does not include the entity. + Before, + /// The cursor is immediately after the entity. The history before the + /// cursor includes the entity and nothing that follows it in the timeline. + After, + /// Custom or future position. + /// + /// Values beginning with `_` are reserved for implementation-specific + /// extensions. Other unknown values are reserved for future ACP positions. + /// A Client that does not recognize the value cannot place the cursor. + #[serde(untagged)] + Other(String), +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// A session cursor anchor to a message. The anchor's `type` names the kind of message. +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorMessageAnchor { + /// The ID of the anchored message. + pub message_id: MessageId, + /// On which side of the message the cursor is. + pub position: CursorAnchorPosition, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorMessageAnchor { + /// Builds an anchor to a message without metadata. + #[must_use] + pub fn new(message_id: impl Into, position: CursorAnchorPosition) -> Self { + Self { + message_id: message_id.into(), + position, + meta: None, + } + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// A session cursor anchor to a tool call. +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorToolCallAnchor { + /// The ID of the anchored tool call. + pub tool_call_id: ToolCallId, + /// On which side of the tool call the cursor is. + pub position: CursorAnchorPosition, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorToolCallAnchor { + /// Builds an anchor to a tool call without metadata. + #[must_use] + pub fn new(tool_call_id: impl Into, position: CursorAnchorPosition) -> Self { + Self { + tool_call_id: tool_call_id.into(), + position, + meta: None, + } + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// A session cursor anchor to a compaction. +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorCompactionAnchor { + /// The ID of the anchored compaction. + pub compaction_id: CompactionId, + /// On which side of the compaction the cursor is. + pub position: CursorAnchorPosition, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorCompactionAnchor { + /// Builds an anchor to a compaction without metadata. + #[must_use] + pub fn new(compaction_id: impl Into, position: CursorAnchorPosition) -> Self { + Self { + compaction_id: compaction_id.into(), + position, + meta: None, + } + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Custom or future session cursor anchor payload. +/// +/// This preserves the unknown `type` discriminator and the rest of the anchor +/// object for implementations that store, replay, proxy, or forward cursors. +#[cfg(feature = "unstable_session_cursors")] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, PartialEq, Eq)] +#[cfg_attr(feature = "schemars", schemars(inline))] +#[cfg_attr(feature = "schemars", schemars(transform = other_cursor_anchor_schema))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct OtherCursorAnchor { + /// Custom or future anchor type. + /// + /// Values beginning with `_` are reserved for implementation-specific + /// extensions. Unknown values that do not begin with `_` are reserved for + /// future ACP variants. + #[serde(rename = "type")] + pub type_: String, + /// The remaining fields of the unknown anchor payload, preserved verbatim, + /// including `_meta`. + #[serde(flatten)] + pub fields: BTreeMap, +} + +#[cfg(feature = "unstable_session_cursors")] +impl OtherCursorAnchor { + /// Builds [`OtherCursorAnchor`] from an unknown discriminator and preserves the remaining extension fields. + #[must_use] + pub fn new(type_: impl Into, mut fields: BTreeMap) -> Self { + fields.remove("type"); + Self { + type_: type_.into(), + fields, + } + } +} + +#[cfg(feature = "unstable_session_cursors")] +impl<'de> Deserialize<'de> for OtherCursorAnchor { + fn deserialize(deserializer: D) -> Result + where + D: serde::Deserializer<'de>, + { + let mut fields = BTreeMap::::deserialize(deserializer)?; + let type_ = fields + .remove("type") + .ok_or_else(|| serde::de::Error::missing_field("type"))?; + let serde_json::Value::String(type_) = type_ else { + return Err(serde::de::Error::custom("`type` must be a string")); + }; + + if KNOWN_CURSOR_ANCHOR_TYPES.contains(&type_.as_str()) { + return Err(serde::de::Error::custom(format!( + "known cursor anchor `{type_}` did not match its schema" + ))); + } + + Ok(Self { type_, fields }) + } +} + +#[cfg(feature = "unstable_session_cursors")] +const KNOWN_CURSOR_ANCHOR_TYPES: &[&str] = &[ + "user_message", + "agent_message", + "agent_thought", + #[cfg(feature = "unstable_subagents")] + "session_message", + "tool_call", + "compaction", +]; + +#[cfg(all(feature = "unstable_session_cursors", feature = "schemars"))] +fn other_cursor_anchor_schema(schema: &mut Schema) { + let known = KNOWN_CURSOR_ANCHOR_TYPES + .iter() + .map(|type_| { + serde_json::json!({ + "properties": { "type": { "const": type_, "type": "string" } }, + "required": ["type"], + "type": "object" + }) + }) + .collect::>(); + schema.insert("not".into(), serde_json::json!({ "anyOf": known })); +} + /// **UNSTABLE** /// /// This capability is not part of the spec yet, and may be removed or changed at any point. @@ -3739,6 +4311,19 @@ pub struct ClientSessionCapabilities { #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub prompt_suggestions: Option, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Support for `cursor_update` session updates. + /// + /// Optional. Omitted or `null` both mean the client does not advertise support. + /// Supplying `{}` means the client handles `cursor_update`. + #[cfg(feature = "unstable_session_cursors")] + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + pub cursors: Option, /// The _meta property is reserved by ACP to allow clients and agents to attach additional /// metadata to their interactions. Implementations MUST NOT make assumptions about values at /// these keys. @@ -3800,6 +4385,18 @@ impl ClientSessionCapabilities { self } + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Advertises support for `cursor_update` session updates. + #[cfg(feature = "unstable_session_cursors")] + #[must_use] + pub fn cursors(mut self, cursors: impl IntoOption) -> Self { + self.cursors = cursors.into_option(); + self + } + /// The _meta property is reserved by ACP to allow clients and agents to attach additional /// metadata to their interactions. Implementations MUST NOT make assumptions about values at /// these keys. @@ -3842,6 +4439,29 @@ impl NoticeCapabilities { } } +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Client support for `cursor_update` session updates. +/// +/// See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). +#[cfg(feature = "unstable_session_cursors")] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct SessionCursorsCapabilities {} + +#[cfg(feature = "unstable_session_cursors")] +impl SessionCursorsCapabilities { + /// Advertises support for `cursor_update` session updates. + #[must_use] + pub fn new() -> Self { + Self {} + } +} + /// **UNSTABLE** /// /// This capability is not part of the spec yet, and may be removed or changed at any point. @@ -6291,4 +6911,243 @@ mod tests { ); } } + + #[cfg(feature = "unstable_session_cursors")] + #[test] + fn cursor_updates_round_trip_and_patch_capabilities() { + use serde_json::json; + + let update = SessionUpdate::CursorUpdate( + CursorUpdate::new("cur_1") + .capabilities(CursorCapabilities::new()) + .anchor(CursorAnchor::UserMessage(CursorMessageAnchor::new( + "msg_user_2", + CursorAnchorPosition::Before, + ))), + ); + let wire = json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1", + "capabilities": {}, + "anchor": { "type": "user_message", "messageId": "msg_user_2", "position": "before" } + }); + assert_eq!(serde_json::to_value(&update).unwrap(), wire); + assert_eq!( + serde_json::from_value::(wire).unwrap(), + update + ); + + // A later update can carry the ID alone. Nothing is changed. + let SessionUpdate::CursorUpdate(omitted) = serde_json::from_value(json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1" + })) + .unwrap() else { + panic!("expected cursor update"); + }; + assert!(omitted.capabilities.is_undefined()); + assert_eq!(omitted.anchor, None); + assert!(omitted.meta.is_undefined()); + assert_eq!( + serde_json::to_value(SessionUpdate::CursorUpdate(CursorUpdate::new("cur_1"))).unwrap(), + json!({ "sessionUpdate": "cursor_update", "cursorId": "cur_1" }) + ); + + // `null` clears the capabilities. A `null` anchor is the same as an omitted one. + let SessionUpdate::CursorUpdate(cleared) = serde_json::from_value(json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1", + "capabilities": null, + "anchor": null + })) + .unwrap() else { + panic!("expected cursor update"); + }; + assert!(cleared.capabilities.is_null()); + assert_eq!(cleared.anchor, None); + assert_eq!( + serde_json::to_value(SessionUpdate::CursorUpdate( + CursorUpdate::new("cur_1").capabilities(None) + )) + .unwrap(), + json!({ "sessionUpdate": "cursor_update", "cursorId": "cur_1", "capabilities": null }) + ); + } + + #[cfg(feature = "unstable_session_cursors")] + #[test] + fn cursor_anchors_cover_each_entity_type_and_preserve_unknown_ones() { + use serde_json::json; + + for (anchor, wire) in [ + ( + CursorAnchor::AgentMessage(CursorMessageAnchor::new( + "msg_agent_1", + CursorAnchorPosition::After, + )), + json!({ "type": "agent_message", "messageId": "msg_agent_1", "position": "after" }), + ), + ( + CursorAnchor::AgentThought(CursorMessageAnchor::new( + "msg_agent_1", + CursorAnchorPosition::After, + )), + json!({ "type": "agent_thought", "messageId": "msg_agent_1", "position": "after" }), + ), + #[cfg(feature = "unstable_subagents")] + ( + CursorAnchor::SessionMessage(CursorMessageAnchor::new( + "msg_session_1", + CursorAnchorPosition::Before, + )), + json!({ "type": "session_message", "messageId": "msg_session_1", "position": "before" }), + ), + ( + CursorAnchor::ToolCall(CursorToolCallAnchor::new( + "call_1", + CursorAnchorPosition::After, + )), + json!({ "type": "tool_call", "toolCallId": "call_1", "position": "after" }), + ), + ( + CursorAnchor::Compaction(CursorCompactionAnchor::new( + "cmp_1", + CursorAnchorPosition::Before, + )), + json!({ "type": "compaction", "compactionId": "cmp_1", "position": "before" }), + ), + ] { + assert_eq!(serde_json::to_value(&anchor).unwrap(), wire); + assert_eq!( + serde_json::from_value::(wire).unwrap(), + anchor + ); + } + + // An unknown anchor type keeps its payload. + let wire = json!({ "type": "_acme_marker", "markerId": "mk_1", "position": "after" }); + let other = serde_json::from_value::(wire.clone()).unwrap(); + assert!(matches!(other, CursorAnchor::Other(_))); + assert_eq!(serde_json::to_value(&other).unwrap(), wire); + + // An unknown position keeps its value. + let wire = + json!({ "type": "user_message", "messageId": "msg_user_2", "position": "inside" }); + let future = serde_json::from_value::(wire.clone()).unwrap(); + assert_eq!( + future, + CursorAnchor::UserMessage(CursorMessageAnchor::new( + "msg_user_2", + CursorAnchorPosition::Other("inside".into()), + )) + ); + assert_eq!(serde_json::to_value(&future).unwrap(), wire); + } + + #[cfg(feature = "unstable_session_cursors")] + #[test] + fn malformed_cursor_anchor_fails_the_update() { + use serde_json::json; + + // A wrong anchor would place the cursor somewhere else, so it is never defaulted. + for anchor in [ + json!({ "type": "user_message", "position": "before" }), + json!({ "type": "tool_call", "toolCallId": 7, "position": "after" }), + json!({ "type": "compaction", "compactionId": "cmp_1" }), + json!({ "messageId": "msg_user_2", "position": "before" }), + json!("before"), + ] { + assert!( + serde_json::from_value::(json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1", + "anchor": anchor + })) + .is_err(), + "{anchor}" + ); + } + assert!( + serde_json::from_value::(json!({ "sessionUpdate": "cursor_update" })) + .is_err() + ); + } + + #[cfg(feature = "unstable_session_cursors")] + #[test] + fn malformed_cursor_capabilities_are_not_advertised() { + use serde_json::json; + + // Malformed capabilities are treated as omitted. The update still parses. + let SessionUpdate::CursorUpdate(update) = serde_json::from_value(json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1", + "capabilities": "fork" + })) + .unwrap() else { + panic!("expected cursor update"); + }; + assert!(update.capabilities.is_undefined()); + + // Capabilities this implementation does not know are ignored. + assert_eq!( + serde_json::from_value::(json!({ "futureMethod": {} })).unwrap(), + CursorCapabilities::new() + ); + + #[cfg(feature = "unstable_session_fork")] + { + assert_eq!( + serde_json::to_value(CursorCapabilities::new().fork(CursorForkCapabilities::new())) + .unwrap(), + json!({ "fork": {} }) + ); + assert_eq!( + serde_json::from_value::(json!({ "fork": {} })) + .unwrap() + .fork, + Some(CursorForkCapabilities::new()) + ); + for fork in [json!(null), json!(true), json!("yes")] { + assert_eq!( + serde_json::from_value::(json!({ "fork": fork })) + .unwrap() + .fork, + None + ); + } + } + } + + #[cfg(feature = "unstable_session_cursors")] + #[test] + fn client_session_cursors_capability_is_optional_and_lenient() { + use serde_json::json; + + assert_eq!( + serde_json::to_value( + ClientSessionCapabilities::new().cursors(SessionCursorsCapabilities::new()) + ) + .unwrap(), + json!({ "cursors": {} }) + ); + assert_eq!( + serde_json::from_value::(json!({ "cursors": {} })) + .unwrap() + .cursors, + Some(SessionCursorsCapabilities::new()) + ); + for wire in [ + json!({}), + json!({ "cursors": null }), + json!({ "cursors": "yes" }), + ] { + assert_eq!( + serde_json::from_value::(wire) + .unwrap() + .cursors, + None + ); + } + } } diff --git a/agent-client-protocol-schema/src/v2/agent.rs b/agent-client-protocol-schema/src/v2/agent.rs index 94532874e..bebc29b80 100644 --- a/agent-client-protocol-schema/src/v2/agent.rs +++ b/agent-client-protocol-schema/src/v2/agent.rs @@ -20,6 +20,11 @@ use super::{ }; use crate::{IntoOption, ProtocolVersion}; +#[cfg(all( + feature = "unstable_session_fork", + feature = "unstable_session_cursors" +))] +use super::CursorId; #[cfg(feature = "unstable_session_status")] use super::StateUpdate; @@ -1528,6 +1533,21 @@ impl NewSessionResponse { pub struct ForkSessionRequest { /// The ID of the session to fork. pub session_id: SessionId, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// The session cursor to fork at. The new session's history is the source + /// session's history before the cursor. + /// + /// Optional. Omitted and `null` are equivalent and fork the whole session. + /// Clients MUST only send the ID of a cursor that the Agent announced on the + /// source session and that currently advertises `capabilities.fork`. The Agent + /// rejects any other ID with `-32602`. It does not fall back to forking the + /// whole session. + #[cfg(feature = "unstable_session_cursors")] + #[serde(default)] + pub cursor_id: Option, /// The working directory for this session. Must be an absolute path. pub cwd: AbsolutePath, /// Additional workspace roots to activate for this session. Each path must be absolute. @@ -1595,6 +1615,8 @@ impl ForkSessionRequest { pub fn new(session_id: impl Into, cwd: impl Into) -> Self { Self { session_id: session_id.into(), + #[cfg(feature = "unstable_session_cursors")] + cursor_id: None, cwd: cwd.into(), additional_directories: vec![], mcp_servers: vec![], @@ -1605,6 +1627,21 @@ impl ForkSessionRequest { } } + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// The session cursor to fork at. Omitting it forks the whole session. + /// + /// Clients MUST only send the ID of a cursor that the Agent announced on the + /// source session and that currently advertises `capabilities.fork`. + #[cfg(feature = "unstable_session_cursors")] + #[must_use] + pub fn cursor_id(mut self, cursor_id: impl IntoOption) -> Self { + self.cursor_id = cursor_id.into_option(); + self + } + /// Additional workspace roots to activate for this session. Each path must be absolute. #[must_use] pub fn additional_directories(mut self, additional_directories: I) -> Self @@ -10698,4 +10735,47 @@ mod test_serialization { json!({"state": "unauthenticated"}) ); } + + #[cfg(all( + feature = "unstable_session_fork", + feature = "unstable_session_cursors" + ))] + #[test] + fn fork_session_request_cursor_id_is_optional_and_strict() { + let request = ForkSessionRequest::new("sess_abc123", "/home/user/project") + .cursor_id(CursorId::new("cur_1")); + let wire = json!({ + "sessionId": "sess_abc123", + "cursorId": "cur_1", + "cwd": "/home/user/project" + }); + assert_eq!(serde_json::to_value(&request).unwrap(), wire); + assert_eq!( + serde_json::from_value::(wire).unwrap(), + request + ); + + // Omitted and `null` both fork the whole session. + for wire in [ + json!({ "sessionId": "sess_abc123", "cwd": "/home/user/project" }), + json!({ "sessionId": "sess_abc123", "cwd": "/home/user/project", "cursorId": null }), + ] { + assert_eq!( + serde_json::from_value::(wire) + .unwrap() + .cursor_id, + None + ); + } + + // A malformed cursor ID fails the request. It never forks the whole session. + assert!( + serde_json::from_value::(json!({ + "sessionId": "sess_abc123", + "cwd": "/home/user/project", + "cursorId": 7 + })) + .is_err() + ); + } } diff --git a/agent-client-protocol-schema/src/v2/client.rs b/agent-client-protocol-schema/src/v2/client.rs index 0bbf26774..f2ae88bef 100644 --- a/agent-client-protocol-schema/src/v2/client.rs +++ b/agent-client-protocol-schema/src/v2/client.rs @@ -171,6 +171,16 @@ pub enum SessionUpdate { /// the `session.promptSuggestions` Client capability. #[cfg(feature = "unstable_prompt_suggestions")] PromptSuggestionsUpdate(PromptSuggestionsUpdate), + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// A session cursor has been announced or its capabilities have changed. + /// + /// No Client capability is required. Clients that do not understand + /// cursors may ignore this update. + #[cfg(feature = "unstable_session_cursors")] + CursorUpdate(CursorUpdate), /// Announces a child session created and owned by this session, or updates /// that ownership association's metadata. SubagentUpdate(SubagentUpdate), @@ -894,6 +904,564 @@ impl CompactionSummaryChunk { } } +// Session cursors + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Unique identifier for a session cursor within a session. +/// +/// The Agent generates it, and it is never reused for another position in the +/// session. Clients MUST NOT parse, change, or construct it. +/// +/// See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). +#[cfg(feature = "unstable_session_cursors")] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)] +#[serde(transparent)] +#[from(forward)] +#[non_exhaustive] +pub struct CursorId(pub Arc); + +#[cfg(feature = "unstable_session_cursors")] +impl CursorId { + /// Wraps a protocol string as a typed [`CursorId`]. + #[must_use] + pub fn new(id: impl Into) -> Self { + id.into() + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// A session cursor upsert. A cursor names one position in the session's timeline. +/// +/// The first update for a `cursorId` MUST include `anchor`. The anchor is fixed +/// after that, and later updates change only `capabilities`. +/// +/// `capabilities` and `_meta` have patch semantics: omission leaves the stored +/// value unchanged, `null` clears it, and an object replaces `capabilities` as a +/// whole. A concrete `_meta` object patches the stored metadata by top-level key +/// instead of replacing it. +/// +/// See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorUpdate { + /// The Agent-owned ID of this cursor, unique within the session. + pub cursor_id: CursorId, + /// The methods that currently accept this cursor. + /// + /// Omission leaves the capabilities unchanged, `null` clears them, and an object replaces + /// the whole previous value. A new cursor starts with none. + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")] + pub capabilities: MaybeUndefined, + /// Where the cursor is, relative to an entity the Client holds. + /// + /// Required on the first update for a cursor. The Agent MUST NOT change it afterwards. + /// A later update can omit it or repeat the same anchor. Omitted and `null` are + /// equivalent and leave the stored anchor unchanged. + #[serde(default)] + pub anchor: Option, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` + /// clears it. An object patches the stored metadata by top-level key: keys it omits are + /// unchanged, a key set to `null` is removed, and any other value replaces that key's + /// stored value without merging nested objects. Beyond this patch rule, implementations + /// MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) + #[serde_as(deserialize_as = "DefaultOnError>")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde( + rename = "_meta", + default, + skip_serializing_if = "MaybeUndefined::is_undefined" + )] + pub meta: MaybeUndefined, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorUpdate { + /// Builds a cursor update with the anchor and patch fields omitted. + #[must_use] + pub fn new(cursor_id: impl Into) -> Self { + Self { + cursor_id: cursor_id.into(), + capabilities: MaybeUndefined::Undefined, + anchor: None, + meta: MaybeUndefined::Undefined, + } + } + + /// Replaces, clears, or leaves unchanged the methods that accept this cursor. + #[must_use] + pub fn capabilities( + mut self, + capabilities: impl IntoMaybeUndefined, + ) -> Self { + self.capabilities = capabilities.into_maybe_undefined(); + self + } + + /// Sets the anchor. The first update for a cursor MUST carry one. + #[must_use] + pub fn anchor(mut self, anchor: impl IntoOption) -> Self { + self.anchor = anchor.into_option(); + self + } + + /// Patches, clears, or leaves unchanged cursor metadata. + /// + /// A concrete object patches stored metadata by top-level key. See + /// [`apply_meta_update`](super::apply_meta_update). + #[must_use] + pub fn meta(mut self, meta: impl IntoMaybeUndefined) -> Self { + self.meta = meta.into_maybe_undefined(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// The methods that currently accept a session cursor. +/// +/// A malformed value falls back to no capabilities, so the Client never passes a +/// cursor to a method the Agent did not advertise. +/// +/// See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorCapabilities { + /// Permits the Client to fork the session at this cursor with `session/fork`. + /// + /// Omitted and `null` are equivalent and mean unsupported. An object (including `{}`) + /// means supported. + #[cfg(feature = "unstable_session_fork")] + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + pub fork: Option, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorCapabilities { + /// Builds an empty capability set. No method accepts the cursor. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Permits or stops permitting `session/fork` at this cursor. + #[cfg(feature = "unstable_session_fork")] + #[must_use] + pub fn fork(mut self, fork: impl IntoOption) -> Self { + self.fork = fork.into_option(); + self + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Capability to fork the session at a cursor with `session/fork`. +/// +/// Supplying `{}` advertises support. An omitted or `null` `fork` does not. +#[cfg(all( + feature = "unstable_session_cursors", + feature = "unstable_session_fork" +))] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[non_exhaustive] +pub struct CursorForkCapabilities { + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(all( + feature = "unstable_session_cursors", + feature = "unstable_session_fork" +))] +impl CursorForkCapabilities { + /// Builds an empty capability object advertising fork support. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Where a session cursor is, relative to an entity the Client holds. +/// +/// The anchor names the entity by its type and ID, and `position` says on which +/// side of that entity the cursor is. A known `type` with a malformed payload is +/// an error. It does not fall back to the unknown-type variant. +/// +/// See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). +#[cfg(feature = "unstable_session_cursors")] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(tag = "type", rename_all = "snake_case")] +#[non_exhaustive] +pub enum CursorAnchor { + /// The cursor is next to a user message. + UserMessage(CursorMessageAnchor), + /// The cursor is next to an agent message. + AgentMessage(CursorMessageAnchor), + /// The cursor is next to an agent thought. + AgentThought(CursorMessageAnchor), + /// The cursor is next to a session-directed message. + SessionMessage(CursorMessageAnchor), + /// The cursor is next to a tool call. + ToolCall(CursorToolCallAnchor), + /// The cursor is next to a compaction. + Compaction(CursorCompactionAnchor), + /// Custom or future anchor type. + /// + /// Values beginning with `_` are reserved for implementation-specific + /// extensions. Unknown values that do not begin with `_` are reserved for + /// future ACP variants. + /// + /// A Client that does not recognize the type cannot place the cursor and + /// MUST NOT guess a place for it. + #[serde(untagged)] + Other(OtherCursorAnchor), +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// On which side of the anchored entity a session cursor is. +#[cfg(feature = "unstable_session_cursors")] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "snake_case")] +#[non_exhaustive] +pub enum CursorAnchorPosition { + /// The cursor is immediately before the entity. The history before the + /// cursor does not include the entity. + Before, + /// The cursor is immediately after the entity. The history before the + /// cursor includes the entity and nothing that follows it in the timeline. + After, + /// Custom or future position. + /// + /// Values beginning with `_` are reserved for implementation-specific + /// extensions. Other unknown values are reserved for future ACP positions. + /// A Client that does not recognize the value cannot place the cursor. + #[serde(untagged)] + Other(String), +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// A session cursor anchor to a message. The anchor's `type` names the kind of message. +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorMessageAnchor { + /// The ID of the anchored message. + pub message_id: MessageId, + /// On which side of the message the cursor is. + pub position: CursorAnchorPosition, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorMessageAnchor { + /// Builds an anchor to a message without metadata. + #[must_use] + pub fn new(message_id: impl Into, position: CursorAnchorPosition) -> Self { + Self { + message_id: message_id.into(), + position, + meta: None, + } + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// A session cursor anchor to a tool call. +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorToolCallAnchor { + /// The ID of the anchored tool call. + pub tool_call_id: ToolCallId, + /// On which side of the tool call the cursor is. + pub position: CursorAnchorPosition, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorToolCallAnchor { + /// Builds an anchor to a tool call without metadata. + #[must_use] + pub fn new(tool_call_id: impl Into, position: CursorAnchorPosition) -> Self { + Self { + tool_call_id: tool_call_id.into(), + position, + meta: None, + } + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// A session cursor anchor to a compaction. +#[cfg(feature = "unstable_session_cursors")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CursorCompactionAnchor { + /// The ID of the anchored compaction. + pub compaction_id: CompactionId, + /// On which side of the compaction the cursor is. + pub position: CursorAnchorPosition, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_cursors")] +impl CursorCompactionAnchor { + /// Builds an anchor to a compaction without metadata. + #[must_use] + pub fn new(compaction_id: impl Into, position: CursorAnchorPosition) -> Self { + Self { + compaction_id: compaction_id.into(), + position, + meta: None, + } + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Custom or future session cursor anchor payload. +/// +/// This preserves the unknown `type` discriminator and the rest of the anchor +/// object for implementations that store, replay, proxy, or forward cursors. +#[cfg(feature = "unstable_session_cursors")] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, PartialEq, Eq)] +#[cfg_attr(feature = "schemars", schemars(inline))] +#[cfg_attr(feature = "schemars", schemars(transform = other_cursor_anchor_schema))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct OtherCursorAnchor { + /// Custom or future anchor type. + /// + /// Values beginning with `_` are reserved for implementation-specific + /// extensions. Unknown values that do not begin with `_` are reserved for + /// future ACP variants. + #[serde(rename = "type")] + pub type_: String, + /// The remaining fields of the unknown anchor payload, preserved verbatim, + /// including `_meta`. + #[serde(flatten)] + pub fields: BTreeMap, +} + +#[cfg(feature = "unstable_session_cursors")] +impl OtherCursorAnchor { + /// Builds [`OtherCursorAnchor`] from an unknown discriminator and preserves the remaining extension fields. + #[must_use] + pub fn new(type_: impl Into, mut fields: BTreeMap) -> Self { + fields.remove("type"); + Self { + type_: type_.into(), + fields, + } + } +} + +#[cfg(feature = "unstable_session_cursors")] +impl<'de> Deserialize<'de> for OtherCursorAnchor { + fn deserialize(deserializer: D) -> Result + where + D: serde::Deserializer<'de>, + { + let mut fields = BTreeMap::::deserialize(deserializer)?; + let type_ = fields + .remove("type") + .ok_or_else(|| serde::de::Error::missing_field("type"))?; + let serde_json::Value::String(type_) = type_ else { + return Err(serde::de::Error::custom("`type` must be a string")); + }; + + if KNOWN_CURSOR_ANCHOR_TYPES.contains(&type_.as_str()) { + return Err(serde::de::Error::custom(format!( + "known cursor anchor `{type_}` did not match its schema" + ))); + } + + Ok(Self { type_, fields }) + } +} + +#[cfg(feature = "unstable_session_cursors")] +const KNOWN_CURSOR_ANCHOR_TYPES: &[&str] = &[ + "user_message", + "agent_message", + "agent_thought", + "session_message", + "tool_call", + "compaction", +]; + +#[cfg(all(feature = "unstable_session_cursors", feature = "schemars"))] +fn other_cursor_anchor_schema(schema: &mut Schema) { + super::schema_util::reject_known_string_discriminators( + schema, + "type", + KNOWN_CURSOR_ANCHOR_TYPES, + ); +} + /// Marks the end of the history replay requested by `session/resume`. /// /// The Agent sends this once on a session for each `session/resume` request @@ -1303,6 +1871,10 @@ fn is_known_session_update(session_update: &str) -> bool { if session_update == "prompt_suggestions_update" { return true; } + #[cfg(feature = "unstable_session_cursors")] + if session_update == "cursor_update" { + return true; + } if matches!( session_update, "subagent_update" | "session_message" | "session_message_chunk" @@ -1360,6 +1932,8 @@ fn other_session_update_schema(schema: &mut Schema) { "replay_complete", #[cfg(feature = "unstable_prompt_suggestions")] "prompt_suggestions_update", + #[cfg(feature = "unstable_session_cursors")] + "cursor_update", "subagent_update", "session_message", "session_message_chunk", @@ -7541,4 +8115,211 @@ mod tests { .is_err() ); } + + #[cfg(feature = "unstable_session_cursors")] + #[test] + fn cursor_updates_round_trip_and_patch_capabilities() { + use serde_json::json; + + let update = SessionUpdate::CursorUpdate( + CursorUpdate::new("cur_1") + .capabilities(CursorCapabilities::new()) + .anchor(CursorAnchor::UserMessage(CursorMessageAnchor::new( + "msg_user_2", + CursorAnchorPosition::Before, + ))), + ); + let wire = json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1", + "capabilities": {}, + "anchor": { "type": "user_message", "messageId": "msg_user_2", "position": "before" } + }); + assert_eq!(serde_json::to_value(&update).unwrap(), wire); + assert_eq!( + serde_json::from_value::(wire).unwrap(), + update + ); + + // A later update can carry the ID alone. Nothing is changed. + let SessionUpdate::CursorUpdate(omitted) = serde_json::from_value(json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1" + })) + .unwrap() else { + panic!("expected cursor update"); + }; + assert!(omitted.capabilities.is_undefined()); + assert_eq!(omitted.anchor, None); + assert!(omitted.meta.is_undefined()); + assert_eq!( + serde_json::to_value(SessionUpdate::CursorUpdate(CursorUpdate::new("cur_1"))).unwrap(), + json!({ "sessionUpdate": "cursor_update", "cursorId": "cur_1" }) + ); + + // `null` clears the capabilities. A `null` anchor is the same as an omitted one. + let SessionUpdate::CursorUpdate(cleared) = serde_json::from_value(json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1", + "capabilities": null, + "anchor": null + })) + .unwrap() else { + panic!("expected cursor update"); + }; + assert!(cleared.capabilities.is_null()); + assert_eq!(cleared.anchor, None); + assert_eq!( + serde_json::to_value(SessionUpdate::CursorUpdate( + CursorUpdate::new("cur_1").capabilities(None) + )) + .unwrap(), + json!({ "sessionUpdate": "cursor_update", "cursorId": "cur_1", "capabilities": null }) + ); + } + + #[cfg(feature = "unstable_session_cursors")] + #[test] + fn cursor_anchors_cover_each_entity_type_and_preserve_unknown_ones() { + use serde_json::json; + + for (anchor, wire) in [ + ( + CursorAnchor::AgentMessage(CursorMessageAnchor::new( + "msg_agent_1", + CursorAnchorPosition::After, + )), + json!({ "type": "agent_message", "messageId": "msg_agent_1", "position": "after" }), + ), + ( + CursorAnchor::AgentThought(CursorMessageAnchor::new( + "msg_agent_1", + CursorAnchorPosition::After, + )), + json!({ "type": "agent_thought", "messageId": "msg_agent_1", "position": "after" }), + ), + ( + CursorAnchor::SessionMessage(CursorMessageAnchor::new( + "msg_session_1", + CursorAnchorPosition::Before, + )), + json!({ "type": "session_message", "messageId": "msg_session_1", "position": "before" }), + ), + ( + CursorAnchor::ToolCall(CursorToolCallAnchor::new( + "call_1", + CursorAnchorPosition::After, + )), + json!({ "type": "tool_call", "toolCallId": "call_1", "position": "after" }), + ), + ( + CursorAnchor::Compaction(CursorCompactionAnchor::new( + "cmp_1", + CursorAnchorPosition::Before, + )), + json!({ "type": "compaction", "compactionId": "cmp_1", "position": "before" }), + ), + ] { + assert_eq!(serde_json::to_value(&anchor).unwrap(), wire); + assert_eq!( + serde_json::from_value::(wire).unwrap(), + anchor + ); + } + + // An unknown anchor type keeps its payload. + let wire = json!({ "type": "_acme_marker", "markerId": "mk_1", "position": "after" }); + let other = serde_json::from_value::(wire.clone()).unwrap(); + assert!(matches!(other, CursorAnchor::Other(_))); + assert_eq!(serde_json::to_value(&other).unwrap(), wire); + + // An unknown position keeps its value. + let wire = + json!({ "type": "user_message", "messageId": "msg_user_2", "position": "inside" }); + let future = serde_json::from_value::(wire.clone()).unwrap(); + assert_eq!( + future, + CursorAnchor::UserMessage(CursorMessageAnchor::new( + "msg_user_2", + CursorAnchorPosition::Other("inside".into()), + )) + ); + assert_eq!(serde_json::to_value(&future).unwrap(), wire); + } + + #[cfg(feature = "unstable_session_cursors")] + #[test] + fn malformed_cursor_anchor_fails_the_update() { + use serde_json::json; + + // A wrong anchor would place the cursor somewhere else, so it is never defaulted. + for anchor in [ + json!({ "type": "user_message", "position": "before" }), + json!({ "type": "tool_call", "toolCallId": 7, "position": "after" }), + json!({ "type": "compaction", "compactionId": "cmp_1" }), + json!({ "messageId": "msg_user_2", "position": "before" }), + json!("before"), + ] { + assert!( + serde_json::from_value::(json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1", + "anchor": anchor + })) + .is_err(), + "{anchor}" + ); + } + // A malformed known update does not fall back to the unknown-update variant. + assert!( + serde_json::from_value::(json!({ "sessionUpdate": "cursor_update" })) + .is_err() + ); + } + + #[cfg(feature = "unstable_session_cursors")] + #[test] + fn malformed_cursor_capabilities_are_not_advertised() { + use serde_json::json; + + // Malformed capabilities are treated as omitted. The update still parses. + let SessionUpdate::CursorUpdate(update) = serde_json::from_value(json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1", + "capabilities": "fork" + })) + .unwrap() else { + panic!("expected cursor update"); + }; + assert!(update.capabilities.is_undefined()); + + // Capabilities this implementation does not know are ignored. + assert_eq!( + serde_json::from_value::(json!({ "futureMethod": {} })).unwrap(), + CursorCapabilities::new() + ); + + #[cfg(feature = "unstable_session_fork")] + { + assert_eq!( + serde_json::to_value(CursorCapabilities::new().fork(CursorForkCapabilities::new())) + .unwrap(), + json!({ "fork": {} }) + ); + assert_eq!( + serde_json::from_value::(json!({ "fork": {} })) + .unwrap() + .fork, + Some(CursorForkCapabilities::new()) + ); + for fork in [json!(null), json!(true), json!("yes")] { + assert_eq!( + serde_json::from_value::(json!({ "fork": fork })) + .unwrap() + .fork, + None + ); + } + } + } } diff --git a/agent-client-protocol-schema/tests/experimental_compatibility.rs b/agent-client-protocol-schema/tests/experimental_compatibility.rs index 598d0355e..2e635aaac 100644 --- a/agent-client-protocol-schema/tests/experimental_compatibility.rs +++ b/agent-client-protocol-schema/tests/experimental_compatibility.rs @@ -126,6 +126,22 @@ fn experimental_skill_references_roundtrip_with_or_without_local_support() { assert_eq!(serde_json::to_value(update).unwrap(), wire); } +#[test] +fn experimental_cursor_updates_roundtrip_with_or_without_local_support() { + let wire = json!({ + "sessionUpdate": "cursor_update", + "cursorId": "cur_1", + "capabilities": {}, + "anchor": {"type": "user_message", "messageId": "msg_user_2", "position": "before"} + }); + let update = decode_update(&wire); + #[cfg(feature = "unstable_session_cursors")] + assert!(matches!(update, SessionUpdate::CursorUpdate(_))); + #[cfg(not(feature = "unstable_session_cursors"))] + assert!(matches!(update, SessionUpdate::Other(_))); + assert_eq!(serde_json::to_value(update).unwrap(), wire); +} + #[test] fn unknown_standard_and_custom_updates_preserve_their_payloads() { for tag in ["future_display_update", "_acme_display_update"] { @@ -210,6 +226,7 @@ fn session_update_fallback_schema_excludes_only_locally_recognized_variants() { "prompt_suggestions_update", cfg!(feature = "unstable_prompt_suggestions"), ), + ("cursor_update", cfg!(feature = "unstable_session_cursors")), ] { assert_eq!( excluded diff --git a/docs/protocol/v1/draft/initialization.mdx b/docs/protocol/v1/draft/initialization.mdx index 3c418b5fa..f480e309c 100644 --- a/docs/protocol/v1/draft/initialization.mdx +++ b/docs/protocol/v1/draft/initialization.mdx @@ -286,6 +286,23 @@ The Client opts in to other content types with the following fields. They have t Learn more about Prompt Suggestions +#### Session cursors (unstable) + + + The Client handles `cursor_update` session updates. This field is optional and + nullable. Omitting `session` or `cursors`, or setting either to `null`, means + unsupported. Supplying `{}` means supported. Agents must not send + `cursor_update` without this capability. + + + + Learn more about Session Cursors + + ### Agent capabilities The Agent **SHOULD** specify whether it supports the following capabilities: diff --git a/docs/protocol/v1/draft/overview.mdx b/docs/protocol/v1/draft/overview.mdx index efdd13220..141da6031 100644 --- a/docs/protocol/v1/draft/overview.mdx +++ b/docs/protocol/v1/draft/overview.mdx @@ -223,6 +223,7 @@ Clients provide the interface between users and agents. They are typically code - [User-facing notices](/protocol/v1/draft/prompt-turn#session-notices) - [Context compactions](/protocol/v1/draft/prompt-turn#session-compaction) - [Prompt suggestions](/protocol/v1/draft/prompt-turn#prompt-suggestions-unstable) (unstable) +- [Session cursors](/protocol/v1/draft/prompt-turn#session-cursors-unstable) (unstable) diff --git a/docs/protocol/v1/draft/prompt-turn.mdx b/docs/protocol/v1/draft/prompt-turn.mdx index b7ba39d6c..aed2682bf 100644 --- a/docs/protocol/v1/draft/prompt-turn.mdx +++ b/docs/protocol/v1/draft/prompt-turn.mdx @@ -33,6 +33,7 @@ Agents send `session/update` notifications to report streamed content, tool acti | `compaction_update` | Creates or updates a [context compaction](#session-compaction). Requires the Client's `session.compaction` capability. | | `compaction_summary_chunk` | Appends content to a [compaction's retained summary](#session-compaction). Requires the Client's `session.compaction` capability. | | `prompt_suggestions_update` | **Draft only.** Replaces the session's current list of [prompt suggestions](#prompt-suggestions-unstable). Requires the Client's `session.promptSuggestions` capability. | +| `cursor_update` | **Draft only.** Announces a [session cursor](#session-cursors-unstable) or changes the methods that accept it. Requires the Client's `session.cursors` capability. | This is the complete set of variants defined in the current draft [`SessionUpdate` schema](/protocol/v1/draft/schema#sessionupdate), which describes each payload in detail. Draft-only variants are unstable and may change or be removed. The walkthrough below illustrates common uses of these updates. @@ -573,6 +574,140 @@ history. Collapsing it is a local presentation choice. It also does not replace [`usage_update`](#session-usage-updates), which reports current context-window usage and cost rather than a compaction boundary. +#### Session cursors (unstable) + +A session cursor names one position in the session's timeline where the Client can +run a method, such as forking the session there. The Agent announces a cursor only +for a position where at least one method works. A Client can't act at a position +that has no cursor. + +The Agent **MUST NOT** send `cursor_update` unless the Client advertised support by +supplying `clientCapabilities.session.cursors: {}` in its `initialize` request. +Omitting `session` or `cursors`, or setting either field to `null`, means the +Client does not support these updates. This requirement applies to both live +updates and `session/load` replay. There is no Agent capability. An Agent that +supports cursors announces them. + +The Agent announces a cursor with a `cursor_update`: + +```json +{ + "jsonrpc": "2.0", + "method": "session/update", + "params": { + "sessionId": "sess_abc123def456", + "update": { + "sessionUpdate": "cursor_update", + "cursorId": "cur_9f2c41", + "capabilities": { + "fork": {} + }, + "anchor": { + "type": "user_message", + "messageId": "msg_user_2", + "position": "before" + } + } + } +} +``` + +`cursor_update` is an upsert keyed by `cursorId`: + +- `cursorId` is required and non-null. It is an opaque, Agent-owned string, unique within the session and never reused for another position. Clients **MUST NOT** parse, change, or construct it. +- `capabilities` is an optional, nullable patch that says which methods currently accept the cursor. Omitted leaves the stored value unchanged, `null` clears it, and an object replaces the whole previous value. A new cursor starts with none. +- `anchor` places the cursor. The first update for a `cursorId` **MUST** include it, and the Agent **MUST NOT** change it afterwards. A later update can omit it or repeat the same anchor. Omitted and `null` are equivalent and leave the stored anchor unchanged. +- `_meta` is an optional, nullable patch. Omitted leaves the stored value unchanged, `null` clears it, and an object replaces it. + +A cursor never moves. To offer a different position, the Agent announces a new +cursor. Later updates change only `capabilities`, for example to add a method that +became possible at the position or to remove one that no longer is. + +Each capability in `capabilities` is an optional, nullable object. Omitted or `null` +means unsupported, and `{}` advertises support. `capabilities: null` and +`capabilities: {}` both mean that no method accepts the cursor. Clients ignore +capabilities they don't recognize. A malformed `capabilities` value is treated as +omitted. + +| Capability | Meaning | +| ---------- | ---------------------------------------------------- | +| `fork` | `session/fork` accepts the cursor in its `cursorId`. | + +`anchor` names an entity the Client holds by its `type` and ID: + +| `type` | ID field | Entity | +| ----------------- | -------------- | ----------------------------------------------------------------- | +| `user_message` | `messageId` | A user message | +| `agent_message` | `messageId` | An agent message | +| `agent_thought` | `messageId` | An agent thought | +| `session_message` | `messageId` | A [session-directed message](#session-directed-messages-unstable) | +| `tool_call` | `toolCallId` | A tool call | +| `compaction` | `compactionId` | A compaction | + +The anchor's `position` field says on which side of the entity the cursor is: + +- `before`: the cursor is immediately before the entity. The history before the cursor does not include the entity. +- `after`: the cursor is immediately after the entity. The history before the cursor includes the entity and nothing that follows it in the timeline. + +The entity **MUST** belong to the same session, and the Agent **MUST** report it on +that session before it sends a `cursor_update` anchored to it. A malformed anchor +makes the whole update invalid. Unknown `type` and `position` values are preserved, so a later version or an extension can add more. + +v1 message IDs are optional, but an anchor to a message needs one. An Agent that +announces cursors **MUST** send a `messageId` on every message it anchors to. + +v1 does not require the Agent to report the user's prompt as a session update, and +the `session/prompt` response carries no `messageId`. The Client then holds no user +message for that prompt, and the Agent can't anchor `before` it. The Agent anchors +the same position `after` the last message, tool call, or compaction before the +prompt. The first prompt of a session has nothing before it, so that position has +no cursor. After `session/load`, replayed user messages that carry a `messageId` +can be anchored `before` or `after`. + +A Client can't place a cursor in three cases: + +- It holds no anchor for the cursor, for example because it missed the first update. +- It does not hold the anchored entity, for example because it resumed without a replay. +- It doesn't recognize the anchor's `type` or `position`. + +The Client **MUST NOT** guess a place for such a cursor. A +[replay](/protocol/v1/draft/session-setup#loading-sessions) delivers each entity before the cursors anchored to it. + +A method that accepts a cursor takes its `cursorId`: + +- Clients **MUST** only pass a cursor that the Agent announced on that session and that currently advertises the capability for the method. +- Clients **MUST** pass the `cursorId`. They **MUST NOT** pass the anchor's entity ID in its place. +- The Agent **MUST** reject the request with `-32602` (Invalid params) when it did not issue the `cursorId` for that session, when it no longer accepts the cursor, or when the cursor does not support that method. It **MUST NOT** act at a different position, and it **MUST NOT** handle the request as if the `cursorId` had been omitted. + +`session/fork` is the first method that accepts a cursor. With a `cursorId`, the new +session's history is the source session's history before the cursor: + +```json +{ + "jsonrpc": "2.0", + "id": 7, + "method": "session/fork", + "params": { + "sessionId": "sess_abc123def456", + "cursorId": "cur_9f2c41", + "cwd": "/home/user/project" + } +} +``` + +`cursorId` is optional. Omitted and `null` are equivalent and fork the whole +session. The source session does not change, and its cursors stay valid. The new +session does not inherit them. The Client learns the new session's cursors from +`cursor_update` notifications on the new session. + +A cursor belongs to its session, not to a connection or a Client. It stays valid +until the Agent invalidates it. The end of a connection, `session/close`, `session/load`, and `session/resume` do not +invalidate a cursor. Agents **SHOULD** accept a cursor for as long as they retain +the history at its position, and Clients **MAY** store cursors with their copy of +the session. The Agent can stop accepting a cursor at any time. It **SHOULD** then +send a `cursor_update` that clears the cursor's `capabilities`, if the session is +active on a connection. + #### Session usage updates The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`: diff --git a/docs/protocol/v1/draft/schema.mdx b/docs/protocol/v1/draft/schema.mdx index a887ccb7b..a0bd401b3 100644 --- a/docs/protocol/v1/draft/schema.mdx +++ b/docs/protocol/v1/draft/schema.mdx @@ -775,6 +775,21 @@ has. The Agent SHOULD NOT send `config_option_update` notifications for these en and SHOULD NOT send other `session/update` notifications caused by applying them before it responds. + +CursorId | null} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +The session cursor to fork at. The new session's history is the source +session's history before the cursor. + +Optional. Omitted and `null` are equivalent and fork the whole session. +Clients MUST only send the ID of a cursor that the Agent announced on the +source session and that currently advertises `capabilities.fork`. The Agent +rejects any other ID with `-32602`. It does not fall back to forking the +whole session. + The working directory for this session. Must be an absolute path. @@ -3700,6 +3715,17 @@ means unsupported. `\{\}` advertises the complete compaction contract. Omitted or `null` both mean the client does not advertise support for any config option extensions. + +SessionCursorsCapabilities | null} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Support for `cursor_update` session updates. + +Optional. Omitted or `null` both mean the client does not advertise support. +Supplying `\{\}` means the client handles `cursor_update`. + NoticeCapabilities | null} > Support for live user-facing `notice` session updates. @@ -4138,6 +4164,428 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d The ID of the current mode +## CursorAnchor + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Where a session cursor is, relative to an entity the Client holds. + +The anchor names the entity by its type and ID, and `position` says on which +side of that entity the cursor is. A known `type` with a malformed payload is +an error. It does not fall back to the unknown-type variant. + +See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). + +**Type:** Union + + +The cursor is next to a user message. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + + The discriminator value. Must be `"user_message"`. + + + + + + +The cursor is next to an agent message. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + + The discriminator value. Must be `"agent_message"`. + + + + + + +The cursor is next to an agent thought. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + + The discriminator value. Must be `"agent_thought"`. + + + + + + +The cursor is next to a session-directed message. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + + The discriminator value. Must be `"session_message"`. + + + + + + +The cursor is next to a tool call. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +CursorAnchorPosition} required> + On which side of the tool call the cursor is. + +ToolCallId} required> + The ID of the anchored tool call. + + + The discriminator value. Must be `"tool_call"`. + + + + + + +The cursor is next to a compaction. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +CompactionId} required> + The ID of the anchored compaction. + +CursorAnchorPosition} required> + On which side of the compaction the cursor is. + + + The discriminator value. Must be `"compaction"`. + + + + + + +Custom or future anchor type. + +Values beginning with `_` are reserved for implementation-specific +extensions. Unknown values that do not begin with `_` are reserved for +future ACP variants. + +A Client that does not recognize the type cannot place the cursor and +MUST NOT guess a place for it. + + + + + Custom or future anchor type. + +Values beginning with `_` are reserved for implementation-specific +extensions. Unknown values that do not begin with `_` are reserved for +future ACP variants. + + + + + + +## CursorAnchorPosition + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +On which side of the anchored entity a session cursor is. + +**Type:** Union + + + The cursor is immediately before the entity. The history before the cursor + does not include the entity. + + + + The cursor is immediately after the entity. The history before the cursor + includes the entity and nothing that follows it in the timeline. + + + +Custom or future position. + +Values beginning with `_` are reserved for implementation-specific +extensions. Other unknown values are reserved for future ACP positions. +A Client that does not recognize the value cannot place the cursor. + + + +## CursorCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +The methods that currently accept a session cursor. + +A malformed value falls back to no capabilities, so the Client never passes a +cursor to a method the Agent did not advertise. + +See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +CursorForkCapabilities | null} > + Permits the Client to fork the session at this cursor with `session/fork`. + +Omitted and `null` are equivalent and mean unsupported. An object (including `\{\}`) +means supported. + + + +## CursorCompactionAnchor + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor anchor to a compaction. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +CompactionId} required> + The ID of the anchored compaction. + +CursorAnchorPosition} required> + On which side of the compaction the cursor is. + + +## CursorForkCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Capability to fork the session at a cursor with `session/fork`. + +Supplying `\{\}` advertises support. An omitted or `null` `fork` does not. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + + +## CursorId + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Unique identifier for a session cursor within a session. + +The Agent generates it, and it is never reused for another position in the +session. Clients MUST NOT parse, change, or construct it. + +See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). + +**Type:** `string` + +## CursorMessageAnchor + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor anchor to a message. The anchor's `type` names the kind of message. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + +## CursorToolCallAnchor + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor anchor to a tool call. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + + +CursorAnchorPosition} required> + On which side of the tool call the cursor is. + +ToolCallId} required> + The ID of the anchored tool call. + + +## CursorUpdate + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor upsert. A cursor names one position in the session's timeline. + +The first update for a `cursorId` MUST include `anchor`. The anchor is fixed +after that, and later updates change only `capabilities`. + +Agents MUST only send this update when the Client advertised +the `session.cursors` Client capability. + +`capabilities` and `_meta` have patch semantics: omission leaves the stored +value unchanged, `null` clears it, and a concrete value replaces it. + +See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). + +**Type:** Object + +**Properties:** + + + Extensible metadata patch for this cursor. + +CursorAnchor | null} > + Where the cursor is, relative to an entity the Client holds. + +Required on the first update for a cursor. The Agent MUST NOT change it afterwards. +A later update can omit it or repeat the same anchor. Omitted and `null` are +equivalent and leave the stored anchor unchanged. + + +CursorCapabilities | null} > + The methods that currently accept this cursor. + +Omission leaves the capabilities unchanged, `null` clears them, and an object replaces +the whole previous value. A new cursor starts with none. + + +CursorId} required> + The Agent-owned ID of this cursor, unique within the session. + + ## Diff A diff representing file modifications. @@ -7515,6 +7963,18 @@ Unique identifier for a session configuration option value. **Type:** `string` +## SessionCursorsCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Client support for `cursor_update` session updates. + +See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). + +**Type:** `object` + ## SessionDeleteCapabilities Capabilities for the `session/delete` method. @@ -8600,6 +9060,46 @@ the rest. + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor has been announced or its capabilities have changed. + +Agents MUST only send this update when the Client advertised +the `session.cursors` Client capability. + + + + + Extensible metadata patch for this cursor. + +CursorAnchor | null} > + Where the cursor is, relative to an entity the Client holds. + +Required on the first update for a cursor. The Agent MUST NOT change it afterwards. +A later update can omit it or repeat the same anchor. Omitted and `null` are +equivalent and leave the stored anchor unchanged. + + +CursorCapabilities | null} > + The methods that currently accept this cursor. + +Omission leaves the capabilities unchanged, `null` clears them, and an object replaces +the whole previous value. A new cursor starts with none. + + +CursorId} required> + The Agent-owned ID of this cursor, unique within the session. + + + The discriminator value. Must be `"cursor_update"`. + + + + + **UNSTABLE** diff --git a/docs/protocol/v1/draft/session-setup.mdx b/docs/protocol/v1/draft/session-setup.mdx index 68144b3e3..305ae068f 100644 --- a/docs/protocol/v1/draft/session-setup.mdx +++ b/docs/protocol/v1/draft/session-setup.mdx @@ -149,6 +149,13 @@ capability. [Prompt suggestions](/protocol/v1/draft/prompt-turn#prompt-suggestions-unstable) are not conversation history and **SHOULD NOT** be replayed. A loaded session starts with an empty list of suggestions. After loading finishes, the Agent may send a new `prompt_suggestions_update`, subject to the Client's `session.promptSuggestions` capability. +Unstable [session cursors](/protocol/v1/draft/prompt-turn#session-cursors-unstable) are part of the replayed history, subject to the Client's `session.cursors` capability: + +- The Agent **SHOULD** send a `cursor_update` for each cursor in the loaded history that it still accepts. A replayed update carries the cursor's `capabilities` and `anchor`, like a first update, and follows the replayed entity it is anchored to. +- Agents **SHOULD** use the same `cursorId` for the same position in every load. +- A load rebuilds the session's cursors. The Client **SHOULD** discard the cursors it held for the session and build them again from the replayed `cursor_update` notifications. +- Message IDs need not stay the same across a load, so the Client does not match a replayed anchor to an entity it held before. + For example, a user message from the conversation history: ```json diff --git a/docs/protocol/v2/draft/extensibility.mdx b/docs/protocol/v2/draft/extensibility.mdx index 19c4846df..a9ead31e9 100644 --- a/docs/protocol/v2/draft/extensibility.mdx +++ b/docs/protocol/v2/draft/extensibility.mdx @@ -28,16 +28,17 @@ Each feature defines its negotiation requirements, whether stable or experimenta For example: -| Feature | Negotiation and receiver behavior | -| --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Session deletion](/protocol/v2/draft/session-delete) | The Agent advertises `session.delete`. Clients must not call `session/delete` without it. | -| [Elicitation](/protocol/v2/draft/elicitation#checking-support) | The Client advertises each supported mode under `elicitation`. Agents must not request other modes. | -| [Provider configuration](/protocol/v2/draft/initialization#agent-capabilities) (experimental) | The Agent advertises `capabilities.providers`. Clients must not call provider configuration methods without it. | -| [Notices](/protocol/v2/draft/prompt-lifecycle#session-notices) and [compaction](/protocol/v2/draft/prompt-lifecycle#session-compaction) | No Client capability is required in v2. Clients without feature-specific handling may preserve, ignore, or generically display the updates. | -| [Markdown plans](/protocol/v2/draft/agent-plan#unstable-plan-operations) (experimental) | No Client capability is required in v2. Clients without this plan representation use the unknown plan-content fallback. Sending one does not establish that it will be rendered. | -| [End-turn token usage](/protocol/v2/draft/prompt-lifecycle#end-turn-token-usage-unstable) (experimental) | Optional `usage` on an idle `state_update`, not on the prompt response. No capability is required. Clients may ignore it. | -| [Prompt suggestions](/protocol/v2/draft/prompt-lifecycle#prompt-suggestions-unstable) (experimental) | The Client advertises `session.promptSuggestions`. Agents must not send `prompt_suggestions_update` without it. | -| [Skills](/protocol/v2/draft/slash-commands#skills-unstable) (experimental) | The Client advertises `session.commands.skill`. Agents must not send `skill` command entries without it. The Agent advertises `session.prompt.skill`. Clients must not send `skill` content blocks that it does not allow. | +| Feature | Negotiation and receiver behavior | +| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [Session deletion](/protocol/v2/draft/session-delete) | The Agent advertises `session.delete`. Clients must not call `session/delete` without it. | +| [Elicitation](/protocol/v2/draft/elicitation#checking-support) | The Client advertises each supported mode under `elicitation`. Agents must not request other modes. | +| [Provider configuration](/protocol/v2/draft/initialization#agent-capabilities) (experimental) | The Agent advertises `capabilities.providers`. Clients must not call provider configuration methods without it. | +| [Notices](/protocol/v2/draft/prompt-lifecycle#session-notices) and [compaction](/protocol/v2/draft/prompt-lifecycle#session-compaction) | No Client capability is required in v2. Clients without feature-specific handling may preserve, ignore, or generically display the updates. | +| [Markdown plans](/protocol/v2/draft/agent-plan#unstable-plan-operations) (experimental) | No Client capability is required in v2. Clients without this plan representation use the unknown plan-content fallback. Sending one does not establish that it will be rendered. | +| [End-turn token usage](/protocol/v2/draft/prompt-lifecycle#end-turn-token-usage-unstable) (experimental) | Optional `usage` on an idle `state_update`, not on the prompt response. No capability is required. Clients may ignore it. | +| [Prompt suggestions](/protocol/v2/draft/prompt-lifecycle#prompt-suggestions-unstable) (experimental) | The Client advertises `session.promptSuggestions`. Agents must not send `prompt_suggestions_update` without it. | +| [Skills](/protocol/v2/draft/slash-commands#skills-unstable) (experimental) | The Client advertises `session.commands.skill`. Agents must not send `skill` command entries without it. The Agent advertises `session.prompt.skill`. Clients must not send `skill` content blocks that it does not allow. | +| [Session cursors](/protocol/v2/draft/prompt-lifecycle#session-cursors-unstable) (experimental) | No Client or Agent capability is required in v2. An Agent that supports cursors sends `cursor_update`. Clients without cursor handling may preserve or ignore it. A method that accepts a `cursorId` still needs its own capability, such as `session.fork`. | These rules are specific to v2. Features with capability gates in v1 retain those gates on v1 connections. diff --git a/docs/protocol/v2/draft/overview.mdx b/docs/protocol/v2/draft/overview.mdx index 6d888776d..2dcc56568 100644 --- a/docs/protocol/v2/draft/overview.mdx +++ b/docs/protocol/v2/draft/overview.mdx @@ -206,8 +206,10 @@ Clients provide the interface between users and agents. They are typically code option updates](/protocol/v2/draft/session-config-options#from-the-agent), [context compactions](/protocol/v2/draft/prompt-lifecycle#session-compaction), [user-facing notices](/protocol/v2/draft/prompt-lifecycle#session-notices), - and unstable [prompt - suggestions](/protocol/v2/draft/prompt-lifecycle#prompt-suggestions-unstable). + unstable [prompt + suggestions](/protocol/v2/draft/prompt-lifecycle#prompt-suggestions-unstable), + and unstable [session + cursors](/protocol/v2/draft/prompt-lifecycle#session-cursors-unstable). ## Request cancellation diff --git a/docs/protocol/v2/draft/prompt-lifecycle.mdx b/docs/protocol/v2/draft/prompt-lifecycle.mdx index c99718dff..eee281608 100644 --- a/docs/protocol/v2/draft/prompt-lifecycle.mdx +++ b/docs/protocol/v2/draft/prompt-lifecycle.mdx @@ -40,6 +40,7 @@ Agents send `session/update` notifications to report streamed content, tool acti | `compaction_summary_chunk` | Appends content to a [compaction's retained summary](#session-compaction). | | `replay_complete` | Marks the [end of a history replay](/protocol/v2/draft/session-setup#replay-complete) requested by `session/resume`. | | `prompt_suggestions_update` | **Draft only.** Replaces the session's current list of [prompt suggestions](#prompt-suggestions-unstable). Requires the Client's `session.promptSuggestions` capability. | +| `cursor_update` | **Draft only.** Announces a [session cursor](#session-cursors-unstable) or changes the methods that accept it. | This is the complete set of standard variants defined in the current draft [`SessionUpdate` schema](/protocol/v2/draft/schema#sessionupdate), which describes each payload in detail. Draft-only variants are unstable and may change or be removed. The walkthrough below illustrates common uses of these updates. @@ -70,6 +71,8 @@ The Agent **MUST NOT** reuse an ID for a different entity of the same type withi An update or chunk for an ID the Client hasn't seen creates the entity with its defaults and then applies, so a chunk can arrive before any full update. Clients **MUST NOT** drop it. An entity's first update or chunk fixes its timeline position in receive order: it follows previously received timeline content and precedes content first received later. Later updates and chunks patch the entity in place without moving it, including after the session reports `idle`. Updates for different entities may interleave, and a new ID does not end any other entity. Clients that show an entity outside the timeline, such as a plan panel, may ignore its position. +Unstable [session cursors](#session-cursors-unstable) are also created and updated by ID, with `cursorId`. They are not timeline entities. A cursor's place comes from its anchor, not from receive order. + ### Session-directed messages The Agent may report outgoing and incoming messages between sessions, @@ -830,6 +833,127 @@ history. Collapsing it is a local presentation choice. It also does not replace [`usage_update`](#session-usage-updates), which reports current context-window usage and cost rather than a compaction boundary. +#### Session cursors (unstable) + +A session cursor names one position in the session's timeline where the Client can +run a method, such as forking the session there. The Agent announces a cursor only +for a position where at least one method works. A Client can't act at a position +that has no cursor. + +No Client capability is required in v2. Clients without cursor-specific +handling may preserve or ignore these updates under the +[v2 negotiation rules](/protocol/v2/draft/extensibility#experimental-features-and-negotiation). +There is no Agent capability either. An Agent that supports cursors announces them. + +The Agent announces a cursor with a `cursor_update`: + +```json +{ + "jsonrpc": "2.0", + "method": "session/update", + "params": { + "sessionId": "sess_abc123def456", + "update": { + "sessionUpdate": "cursor_update", + "cursorId": "cur_9f2c41", + "capabilities": { + "fork": {} + }, + "anchor": { + "type": "user_message", + "messageId": "msg_user_2", + "position": "before" + } + } + } +} +``` + +`cursor_update` is an upsert keyed by `cursorId`: + +- `cursorId` is required and non-null. It is an opaque, Agent-owned string, unique within the session and never reused for another position. Clients **MUST NOT** parse, change, or construct it. +- `capabilities` is an optional, nullable patch that says which methods currently accept the cursor. Omitted leaves the stored value unchanged, `null` clears it, and an object replaces the whole previous value. A new cursor starts with none. +- `anchor` places the cursor. The first update for a `cursorId` **MUST** include it, and the Agent **MUST NOT** change it afterwards. A later update can omit it or repeat the same anchor. Omitted and `null` are equivalent and leave the stored anchor unchanged. +- `_meta` follows the [metadata patch](/protocol/v2/draft/extensibility#metadata-patches) rules. + +A cursor never moves. To offer a different position, the Agent announces a new +cursor. Later updates change only `capabilities`, for example to add a method that +became possible at the position or to remove one that no longer is. + +Each capability in `capabilities` is an optional, nullable object. Omitted or `null` +means unsupported, and `{}` advertises support. `capabilities: null` and +`capabilities: {}` both mean that no method accepts the cursor. Clients ignore +capabilities they don't recognize. A malformed `capabilities` value is treated as +omitted. + +| Capability | Meaning | +| ---------- | ---------------------------------------------------- | +| `fork` | `session/fork` accepts the cursor in its `cursorId`. | + +`anchor` names an entity the Client holds by its `type` and ID: + +| `type` | ID field | Entity | +| ----------------- | -------------- | -------------------------------------------------------- | +| `user_message` | `messageId` | A user message | +| `agent_message` | `messageId` | An agent message | +| `agent_thought` | `messageId` | An agent thought | +| `session_message` | `messageId` | A [session-directed message](#session-directed-messages) | +| `tool_call` | `toolCallId` | A tool call | +| `compaction` | `compactionId` | A compaction | + +The anchor's `position` field says on which side of the entity the cursor is: + +- `before`: the cursor is immediately before the entity. The history before the cursor does not include the entity. +- `after`: the cursor is immediately after the entity. The history before the cursor includes the entity and nothing that follows it in the timeline. + +The entity **MUST** belong to the same session, and the Agent **MUST** report it on +that session before it sends a `cursor_update` anchored to it. A malformed anchor +makes the whole update invalid. `type` and `position` accept [custom and future values](/protocol/v2/draft/extensibility#enum-and-tagged-union-variants). + +A Client can't place a cursor in three cases: + +- It holds no anchor for the cursor, for example because it missed the first update. +- It does not hold the anchored entity, for example because it resumed without a replay. +- It doesn't recognize the anchor's `type` or `position`. + +The Client **MUST NOT** guess a place for such a cursor. A +[replay](/protocol/v2/draft/session-setup#replay-contents) delivers each entity before the cursors anchored to it. + +A method that accepts a cursor takes its `cursorId`: + +- Clients **MUST** only pass a cursor that the Agent announced on that session and that currently advertises the capability for the method. +- Clients **MUST** pass the `cursorId`. They **MUST NOT** pass the anchor's entity ID in its place. +- The Agent **MUST** reject the request with `-32602` (Invalid params) when it did not issue the `cursorId` for that session, when it no longer accepts the cursor, or when the cursor does not support that method. It **MUST NOT** act at a different position, and it **MUST NOT** handle the request as if the `cursorId` had been omitted. + +`session/fork` is the first method that accepts a cursor. With a `cursorId`, the new +session's history is the source session's history before the cursor: + +```json +{ + "jsonrpc": "2.0", + "id": 7, + "method": "session/fork", + "params": { + "sessionId": "sess_abc123def456", + "cursorId": "cur_9f2c41", + "cwd": "/home/user/project" + } +} +``` + +`cursorId` is optional. Omitted and `null` are equivalent and fork the whole +session. The source session does not change, and its cursors stay valid. The new +session does not inherit them. The Client learns the new session's cursors from +`cursor_update` notifications on the new session. + +A cursor belongs to its session, not to a connection or a Client. It stays valid +until the Agent invalidates it. The end of a connection, `session/close`, and `session/resume` do not +invalidate a cursor. Agents **SHOULD** accept a cursor for as long as they retain +the history at its position, and Clients **MAY** store cursors with their copy of +the session. The Agent can stop accepting a cursor at any time. It **SHOULD** then +send a `cursor_update` that clears the cursor's `capabilities`, if the session is +active on a connection. + #### Session usage updates The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`: diff --git a/docs/protocol/v2/draft/schema.mdx b/docs/protocol/v2/draft/schema.mdx index 3fc3b4b34..73927eafa 100644 --- a/docs/protocol/v2/draft/schema.mdx +++ b/docs/protocol/v2/draft/schema.mdx @@ -822,6 +822,21 @@ has. The Agent SHOULD NOT send `config_option_update` notifications for these en and SHOULD NOT send other `session/update` notifications caused by applying them before it responds. + +CursorId | null} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +The session cursor to fork at. The new session's history is the source +session's history before the cursor. + +Optional. Omitted and `null` are equivalent and fork the whole session. +Clients MUST only send the ID of a cursor that the Agent announced on the +source session and that currently advertises `capabilities.fork`. The Agent +rejects any other ID with `-32602`. It does not fall back to forking the +whole session. + AbsolutePath} required> The working directory for this session. Must be an absolute path. @@ -4470,6 +4485,435 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d unit such as "credits". +## CursorAnchor + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Where a session cursor is, relative to an entity the Client holds. + +The anchor names the entity by its type and ID, and `position` says on which +side of that entity the cursor is. A known `type` with a malformed payload is +an error. It does not fall back to the unknown-type variant. + +See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). + +**Type:** Union + + +The cursor is next to a user message. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + + The discriminator value. Must be `"user_message"`. + + + + + + +The cursor is next to an agent message. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + + The discriminator value. Must be `"agent_message"`. + + + + + + +The cursor is next to an agent thought. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + + The discriminator value. Must be `"agent_thought"`. + + + + + + +The cursor is next to a session-directed message. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + + The discriminator value. Must be `"session_message"`. + + + + + + +The cursor is next to a tool call. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +CursorAnchorPosition} required> + On which side of the tool call the cursor is. + +ToolCallId} required> + The ID of the anchored tool call. + + + The discriminator value. Must be `"tool_call"`. + + + + + + +The cursor is next to a compaction. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +CompactionId} required> + The ID of the anchored compaction. + +CursorAnchorPosition} required> + On which side of the compaction the cursor is. + + + The discriminator value. Must be `"compaction"`. + + + + + + +Custom or future anchor type. + +Values beginning with `_` are reserved for implementation-specific +extensions. Unknown values that do not begin with `_` are reserved for +future ACP variants. + +A Client that does not recognize the type cannot place the cursor and +MUST NOT guess a place for it. + + + + + Custom or future anchor type. + +Values beginning with `_` are reserved for implementation-specific +extensions. Unknown values that do not begin with `_` are reserved for +future ACP variants. + + + + + + +## CursorAnchorPosition + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +On which side of the anchored entity a session cursor is. + +**Type:** Union + + + The cursor is immediately before the entity. The history before the cursor + does not include the entity. + + + + The cursor is immediately after the entity. The history before the cursor + includes the entity and nothing that follows it in the timeline. + + + +Custom or future position. + +Values beginning with `_` are reserved for implementation-specific +extensions. Other unknown values are reserved for future ACP positions. +A Client that does not recognize the value cannot place the cursor. + + + +## CursorCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +The methods that currently accept a session cursor. + +A malformed value falls back to no capabilities, so the Client never passes a +cursor to a method the Agent did not advertise. + +See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +CursorForkCapabilities | null} > + Permits the Client to fork the session at this cursor with `session/fork`. + +Omitted and `null` are equivalent and mean unsupported. An object (including `\{\}`) +means supported. + + + +## CursorCompactionAnchor + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor anchor to a compaction. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +CompactionId} required> + The ID of the anchored compaction. + +CursorAnchorPosition} required> + On which side of the compaction the cursor is. + + +## CursorForkCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Capability to fork the session at a cursor with `session/fork`. + +Supplying `\{\}` advertises support. An omitted or `null` `fork` does not. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + + +## CursorId + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Unique identifier for a session cursor within a session. + +The Agent generates it, and it is never reused for another position in the +session. Clients MUST NOT parse, change, or construct it. + +See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). + +**Type:** `string` + +## CursorMessageAnchor + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor anchor to a message. The anchor's `type` names the kind of message. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +MessageId} required> + The ID of the anchored message. + +CursorAnchorPosition} required> + On which side of the message the cursor is. + + +## CursorToolCallAnchor + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor anchor to a tool call. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +CursorAnchorPosition} required> + On which side of the tool call the cursor is. + +ToolCallId} required> + The ID of the anchored tool call. + + +## CursorUpdate + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor upsert. A cursor names one position in the session's timeline. + +The first update for a `cursorId` MUST include `anchor`. The anchor is fixed +after that, and later updates change only `capabilities`. + +`capabilities` and `_meta` have patch semantics: omission leaves the stored +value unchanged, `null` clears it, and an object replaces `capabilities` as a +whole. A concrete `_meta` object patches the stored metadata by top-level key +instead of replacing it. + +See the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors). + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` +clears it. An object patches the stored metadata by top-level key: keys it omits are +unchanged, a key set to `null` is removed, and any other value replaces that key's +stored value without merging nested objects. Beyond this patch rule, implementations +MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/draft/extensibility#metadata-patches) + + +CursorAnchor | null} > + Where the cursor is, relative to an entity the Client holds. + +Required on the first update for a cursor. The Agent MUST NOT change it afterwards. +A later update can omit it or repeat the same anchor. Omitted and `null` are +equivalent and leave the stored anchor unchanged. + + +CursorCapabilities | null} > + The methods that currently accept this cursor. + +Omission leaves the capabilities unchanged, `null` clears them, and an object replaces +the whole previous value. A new cursor starts with none. + + +CursorId} required> + The Agent-owned ID of this cursor, unique within the session. + + ## Diff File changes produced by a tool call. @@ -10244,6 +10688,54 @@ the rest. + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A session cursor has been announced or its capabilities have changed. + +No Client capability is required. Clients that do not understand +cursors may ignore this update. + + + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` +clears it. An object patches the stored metadata by top-level key: keys it omits are +unchanged, a key set to `null` is removed, and any other value replaces that key's +stored value without merging nested objects. Beyond this patch rule, implementations +MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/draft/extensibility#metadata-patches) + + +CursorAnchor | null} > + Where the cursor is, relative to an entity the Client holds. + +Required on the first update for a cursor. The Agent MUST NOT change it afterwards. +A later update can omit it or repeat the same anchor. Omitted and `null` are +equivalent and leave the stored anchor unchanged. + + +CursorCapabilities | null} > + The methods that currently accept this cursor. + +Omission leaves the capabilities unchanged, `null` clears them, and an object replaces +the whole previous value. A new cursor starts with none. + + +CursorId} required> + The Agent-owned ID of this cursor, unique within the session. + + + The discriminator value. Must be `"cursor_update"`. + + + + + Announces a child session created and owned by this session, or updates that ownership association's metadata. diff --git a/docs/protocol/v2/draft/session-setup.mdx b/docs/protocol/v2/draft/session-setup.mdx index 0562e94c4..83e885c00 100644 --- a/docs/protocol/v2/draft/session-setup.mdx +++ b/docs/protocol/v2/draft/session-setup.mdx @@ -320,6 +320,13 @@ mention. 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. +Replay also reports unstable [session cursors](/protocol/v2/draft/prompt-lifecycle#session-cursors-unstable): + +- When an Agent replays history, it **SHOULD** send a `cursor_update` for each cursor in that history that it still accepts. A replayed update carries the cursor's `capabilities` and `anchor`, like a first update, and follows the replayed entity it is anchored to. +- Agents **SHOULD** use the same `cursorId` for the same position in every replay. +- A full replay rebuilds the session's cursors, like its other entities. The Client **SHOULD** discard the cursors it held for the session and build them again from the replayed `cursor_update` notifications. A replayed cursor can carry a different anchor than it had before, for example when a `messageId` changed across the replay. +- A resume without replay announces no cursors for earlier history. The cursors the Client already holds stay usable. + When all requested replay entries have been reported to the Client, the Agent **MUST** send [`replay_complete`](#replay-complete), synchronize current state as described below, then respond to the original `session/resume` request. diff --git a/docs/rfds/session-cursors.mdx b/docs/rfds/session-cursors.mdx index 0b8f915e0..18885e82a 100644 --- a/docs/rfds/session-cursors.mdx +++ b/docs/rfds/session-cursors.mdx @@ -285,7 +285,7 @@ Not determined: whether Claude Code accepts a fork that ends on a tool use witho - `CursorCapabilities` with `_meta`, mirroring `ToolCallCapabilities`. It starts with no capabilities, and each RFD that adopts cursors adds its own. A malformed value falls back to unsupported, so the Client never passes a cursor to a method the Agent did not advertise. - `CursorAnchor`, a union tagged by `type` with the message, tool call, and compaction variants and a fallback that preserves unknown types. A known `type` with a malformed payload still fails. In v1, the `session_message` variant is behind `unstable_subagents`. - `ClientSessionCapabilities.cursors` in v1. -2. **Docs.** Describe cursors in the draft prompt lifecycle and session setup pages for both versions: the `cursor_update` update, the rules for passing a `cursorId`, and cursors in replay contents. Add `cursor_update` to the session update tables and cursors to the v2 entity ID table. +2. **Docs.** Describe cursors in the draft prompt lifecycle and session setup pages for both versions: the `cursor_update` update, the rules for passing a `cursorId`, and cursors in replay contents. Add `cursor_update` to the session update tables. Next to the v2 entity ID table, say that a cursor is updated by ID but takes its place from its anchor, not from receive order. 3. **SDKs.** Expose the types. A Client SDK can track the cursors of a session and drop them on a full replay. 4. **Validation.** Implement cursors together with the first method that adopts them, in at least one Agent adapter and one Client before Preview. Cover a cursor announced after its entity, a cursor announced again in replay, a cursor whose capabilities were cleared, a `cursorId` passed to a method the cursor does not advertise, and a `cursorId` from another session. In v1, also cover a cursor for a live prompt that is anchored `after` the preceding entity, and the same position after a `session/load`. 5. **Stabilization.** Decide on the v1 part separately from the v2 part, after that validation. @@ -360,6 +360,7 @@ A fork-specific `forkPoint` update was considered in [PR #629](https://github.co ## Revision history +- 2026-11-16: Steps 1 and 2 of the plan landed. The v1 and v2 schemas have `cursor_update`, `CursorId`, `CursorCapabilities`, `CursorAnchor`, and the v1 `session.cursors` Client capability, behind `unstable_session_cursors`. Each anchor variant also accepts `_meta`. The draft protocol pages describe cursors under [v1 Prompt Turn](/protocol/v1/draft/prompt-turn#session-cursors-unstable) and [v2 Prompt Lifecycle](/protocol/v2/draft/prompt-lifecycle#session-cursors-unstable). - 2026-11-16: Left the use of cursors for partial replay as an open question. Defined when a Client can't place a cursor. - 2026-11-14: Cursors are now identified by `cursorId` and announced with `cursor_update`, an upsert that carries per-cursor `capabilities` in place of `validFor`. Replaced `beforeMessageId` and `afterMessageId` with a typed `anchor` that also covers tool calls and compactions. Every cursor has an anchor, so a v1 Agent that announces cursors also sends message IDs. Defined lifetime, invalidation, replay, the `-32602` rule, the v1 Client capability, and the differences in v1. Added an adapter validation for claude-agent-acp and codex-acp. Moved the method changes out of this RFD. Each method's RFD adopts cursors, starting with session fork. - 2026-09-07: Initial draft diff --git a/docs/rfds/session-fork.mdx b/docs/rfds/session-fork.mdx index 410db9050..1ebf4889b 100644 --- a/docs/rfds/session-fork.mdx +++ b/docs/rfds/session-fork.mdx @@ -167,3 +167,4 @@ None. This proposal is inspired by the abilities exposed in Claude Agent SDK. It - 2025-12-10: Adjust fork options to align with `session/load`. - 2026-10-12: Clarify that a forked session is active once the agent responds, so the client does not need to resume it before prompting. - 2026-11-14: Added forking at a [session cursor](./session-cursors.mdx), with an optional `cursorId` on `session/fork` and a `fork` cursor capability. +- 2026-11-16: `cursorId` on `session/fork` and the `fork` cursor capability are in the v1 and v2 schemas, behind `unstable_session_fork` and `unstable_session_cursors`. diff --git a/docs/rfds/updates.mdx b/docs/rfds/updates.mdx index 852159ed3..65783bd7d 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 Cursors RFD moves to Draft stage + +The RFD for session cursors has moved to Draft. A cursor names a position in a session where a Client can run a method, such as forking the session there. Agents announce cursors with a `cursor_update` session update that says which methods accept each one. Please review the [RFD](/rfds/session-cursors) and provide feedback. + + + ## Agent Skills RFD moves to Draft stage diff --git a/schema-generator/src/main.rs b/schema-generator/src/main.rs index 6dc5600df..4a8c7933f 100644 --- a/schema-generator/src/main.rs +++ b/schema-generator/src/main.rs @@ -732,6 +732,96 @@ mod schema_annotation_tests { } } + #[cfg(feature = "unstable")] + #[test] + fn generated_unstable_cursor_update_is_lenient_for_capabilities_and_strict_for_the_anchor() { + let schema = root_schema_value(); + + let update = def_schema(&schema, "CursorUpdate"); + assert_eq!(update["required"], serde_json::json!(["cursorId"])); + assert!(update["description"].as_str().unwrap().contains("UNSTABLE")); + + // A malformed capability is dropped, so the Client never passes a cursor + // to a method the Agent did not advertise. + let capabilities = property_schema(&schema, "CursorUpdate", "capabilities"); + assert!(schema_contains_ref( + capabilities, + "#/$defs/CursorCapabilities" + )); + assert_bool_extension(capabilities, DEFAULT_ON_ERROR_EXTENSION); + assert_bool_extension( + property_schema(&schema, "CursorCapabilities", "fork"), + DEFAULT_ON_ERROR_EXTENSION, + ); + + // A malformed anchor fails the update. A default would place the cursor + // somewhere else. + let anchor = property_schema(&schema, "CursorUpdate", "anchor"); + assert!(schema_contains_ref(anchor, "#/$defs/CursorAnchor")); + assert_no_extension(anchor, DEFAULT_ON_ERROR_EXTENSION); + + // A malformed cursor ID fails `session/fork`. It never forks the whole session. + let cursor_id = property_schema(&schema, "ForkSessionRequest", "cursorId"); + assert!(schema_contains_ref(cursor_id, "#/$defs/CursorId")); + assert_no_extension(cursor_id, DEFAULT_ON_ERROR_EXTENSION); + assert!( + !def_schema(&schema, "ForkSessionRequest")["required"] + .as_array() + .unwrap() + .contains(&Value::from("cursorId")) + ); + + let updates = def_schema(&schema, "SessionUpdate"); + let variants = updates + .get("oneOf") + .or_else(|| updates.get("anyOf")) + .and_then(Value::as_array) + .unwrap(); + let variant = variants + .iter() + .find(|variant| { + variant.pointer("/properties/sessionUpdate/const") + == Some(&Value::from("cursor_update")) + }) + .expect("missing cursor_update variant"); + assert!(schema_contains_ref(variant, "#/$defs/CursorUpdate")); + assert!( + variant["description"] + .as_str() + .unwrap() + .contains("UNSTABLE") + ); + + // Only v1 needs a Client capability. The v2 union is open. + #[cfg(not(feature = "unstable_protocol_v2"))] + { + let capability = property_schema(&schema, "ClientSessionCapabilities", "cursors"); + assert!(schema_contains_ref( + capability, + "#/$defs/SessionCursorsCapabilities" + )); + assert_bool_extension(capability, DEFAULT_ON_ERROR_EXTENSION); + } + + #[cfg(feature = "unstable_protocol_v2")] + { + let fallback = variants + .iter() + .find(|variant| variant["title"] == "other") + .unwrap(); + assert!( + fallback["not"]["anyOf"] + .as_array() + .unwrap() + .iter() + .any(|variant| { + variant.pointer("/properties/sessionUpdate/const") + == Some(&Value::from("cursor_update")) + }) + ); + } + } + #[cfg(not(feature = "unstable_protocol_v2"))] #[test] fn generated_v1_compaction_capability_is_optional_nullable_and_stable() { diff --git a/schema/v1/schema.unstable.json b/schema/v1/schema.unstable.json index 93a0618ef..67b8fbead 100644 --- a/schema/v1/schema.unstable.json +++ b/schema/v1/schema.unstable.json @@ -4903,6 +4903,22 @@ } ] }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor has been announced or its capabilities have changed.\n\nAgents MUST only send this update when the Client advertised\nthe `session.cursors` Client capability.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "cursor_update" + } + }, + "required": ["sessionUpdate"], + "allOf": [ + { + "$ref": "#/$defs/CursorUpdate" + } + ] + }, { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAnnounces a child session created and owned by this session, or updates\nthat ownership association's metadata.", "type": "object", @@ -5722,6 +5738,375 @@ }, "required": ["suggestions"] }, + "CursorId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a session cursor within a session.\n\nThe Agent generates it, and it is never reused for another position in the\nsession. Clients MUST NOT parse, change, or construct it.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "type": "string" + }, + "CursorCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe methods that currently accept a session cursor.\n\nA malformed value falls back to no capabilities, so the Client never passes a\ncursor to a method the Agent did not advertise.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "type": "object", + "properties": { + "fork": { + "description": "Permits the Client to fork the session at this cursor with `session/fork`.\n\nOmitted and `null` are equivalent and mean unsupported. An object (including `{}`)\nmeans supported.", + "anyOf": [ + { + "$ref": "#/$defs/CursorForkCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "CursorForkCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability to fork the session at a cursor with `session/fork`.\n\nSupplying `{}` advertises support. An omitted or `null` `fork` does not.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "CursorAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhere a session cursor is, relative to an entity the Client holds.\n\nThe anchor names the entity by its type and ID, and `position` says on which\nside of that entity the cursor is. A known `type` with a malformed payload is\nan error. It does not fall back to the unknown-type variant.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "anyOf": [ + { + "description": "The cursor is next to a user message.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "user_message" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to an agent message.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_message" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to an agent thought.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_thought" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to a session-directed message.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "session_message" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to a tool call.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "tool_call" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorToolCallAnchor" + } + ] + }, + { + "description": "The cursor is next to a compaction.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "compaction" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorCompactionAnchor" + } + ] + }, + { + "title": "other", + "description": "Custom or future anchor type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nA Client that does not recognize the type cannot place the cursor and\nMUST NOT guess a place for it.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future anchor type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": ["type"], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "user_message" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_message" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_thought" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "session_message" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "tool_call" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "compaction" + } + }, + "required": ["type"] + } + ] + }, + "additionalProperties": true + } + ] + }, + "CursorAnchorPosition": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nOn which side of the anchored entity a session cursor is.", + "anyOf": [ + { + "description": "The cursor is immediately before the entity. The history before the\ncursor does not include the entity.", + "type": "string", + "const": "before" + }, + { + "description": "The cursor is immediately after the entity. The history before the\ncursor includes the entity and nothing that follows it in the timeline.", + "type": "string", + "const": "after" + }, + { + "title": "other", + "description": "Custom or future position.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP positions.\nA Client that does not recognize the value cannot place the cursor.", + "type": "string" + } + ] + }, + "CursorMessageAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor anchor to a message. The anchor's `type` names the kind of message.", + "type": "object", + "properties": { + "messageId": { + "description": "The ID of the anchored message.", + "allOf": [ + { + "$ref": "#/$defs/MessageId" + } + ] + }, + "position": { + "description": "On which side of the message the cursor is.", + "allOf": [ + { + "$ref": "#/$defs/CursorAnchorPosition" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["messageId", "position"] + }, + "CursorToolCallAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor anchor to a tool call.", + "type": "object", + "properties": { + "toolCallId": { + "description": "The ID of the anchored tool call.", + "allOf": [ + { + "$ref": "#/$defs/ToolCallId" + } + ] + }, + "position": { + "description": "On which side of the tool call the cursor is.", + "allOf": [ + { + "$ref": "#/$defs/CursorAnchorPosition" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["toolCallId", "position"] + }, + "CursorCompactionAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor anchor to a compaction.", + "type": "object", + "properties": { + "compactionId": { + "description": "The ID of the anchored compaction.", + "allOf": [ + { + "$ref": "#/$defs/CompactionId" + } + ] + }, + "position": { + "description": "On which side of the compaction the cursor is.", + "allOf": [ + { + "$ref": "#/$defs/CursorAnchorPosition" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["compactionId", "position"] + }, + "CursorUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor upsert. A cursor names one position in the session's timeline.\n\nThe first update for a `cursorId` MUST include `anchor`. The anchor is fixed\nafter that, and later updates change only `capabilities`.\n\nAgents MUST only send this update when the Client advertised\nthe `session.cursors` Client capability.\n\n`capabilities` and `_meta` have patch semantics: omission leaves the stored\nvalue unchanged, `null` clears it, and a concrete value replaces it.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "type": "object", + "properties": { + "cursorId": { + "description": "The Agent-owned ID of this cursor, unique within the session.", + "allOf": [ + { + "$ref": "#/$defs/CursorId" + } + ] + }, + "capabilities": { + "description": "The methods that currently accept this cursor.\n\nOmission leaves the capabilities unchanged, `null` clears them, and an object replaces\nthe whole previous value. A new cursor starts with none.", + "anyOf": [ + { + "$ref": "#/$defs/CursorCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "anchor": { + "description": "Where the cursor is, relative to an entity the Client holds.\n\nRequired on the first update for a cursor. The Agent MUST NOT change it afterwards.\nA later update can omit it or repeat the same anchor. Omitted and `null` are\nequivalent and leave the stored anchor unchanged.", + "anyOf": [ + { + "$ref": "#/$defs/CursorAnchor" + }, + { + "type": "null" + } + ] + }, + "_meta": { + "description": "Extensible metadata patch for this cursor.", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["cursorId"] + }, "SubagentSessionCapabilities": { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient-initiated session mutations permitted for a specific subagent session.\n\nA mutation requires an explicit per-child capability. Support for the method\non ordinary sessions does not grant support on a child.", "type": "object", @@ -6819,6 +7204,18 @@ ], "x-deserialize-default-on-error": true }, + "cursors": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSupport for `cursor_update` session updates.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client handles `cursor_update`.", + "anyOf": [ + { + "$ref": "#/$defs/SessionCursorsCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", "type": ["object", "null"], @@ -6955,6 +7352,10 @@ } } }, + "SessionCursorsCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient support for `cursor_update` session updates.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "type": "object" + }, "SubagentCapabilities": { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability marker for exposing reusable child sessions as restricted ACP sessions.\n\nSupplying `{}` advertises support for child association and state updates,\nsession-directed messages, and restricted-session semantics. The client\nmust advertise this capability before the agent sends subagent updates or\nsession-directed messages.", "type": "object", @@ -7701,6 +8102,17 @@ } ] }, + "cursorId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe session cursor to fork at. The new session's history is the source\nsession's history before the cursor.\n\nOptional. Omitted and `null` are equivalent and fork the whole session.\nClients MUST only send the ID of a cursor that the Agent announced on the\nsource session and that currently advertises `capabilities.fork`. The Agent\nrejects any other ID with `-32602`. It does not fall back to forking the\nwhole session.", + "anyOf": [ + { + "$ref": "#/$defs/CursorId" + }, + { + "type": "null" + } + ] + }, "cwd": { "description": "The working directory for this session. Must be an absolute path.", "type": "string" diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json index 607fdf8e0..856e5df12 100644 --- a/schema/v2/schema.unstable.json +++ b/schema/v2/schema.unstable.json @@ -6398,6 +6398,22 @@ } ] }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor has been announced or its capabilities have changed.\n\nNo Client capability is required. Clients that do not understand\ncursors may ignore this update.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "cursor_update" + } + }, + "required": ["sessionUpdate"], + "allOf": [ + { + "$ref": "#/$defs/CursorUpdate" + } + ] + }, { "description": "Announces a child session created and owned by this session, or updates\nthat ownership association's metadata.", "type": "object", @@ -6679,6 +6695,16 @@ }, "required": ["sessionUpdate"] }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "cursor_update" + } + }, + "required": ["sessionUpdate"] + }, { "type": "object", "properties": { @@ -7701,6 +7727,375 @@ }, "required": ["suggestions"] }, + "CursorId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a session cursor within a session.\n\nThe Agent generates it, and it is never reused for another position in the\nsession. Clients MUST NOT parse, change, or construct it.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "type": "string" + }, + "CursorCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe methods that currently accept a session cursor.\n\nA malformed value falls back to no capabilities, so the Client never passes a\ncursor to a method the Agent did not advertise.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "type": "object", + "properties": { + "fork": { + "description": "Permits the Client to fork the session at this cursor with `session/fork`.\n\nOmitted and `null` are equivalent and mean unsupported. An object (including `{}`)\nmeans supported.", + "anyOf": [ + { + "$ref": "#/$defs/CursorForkCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "CursorForkCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability to fork the session at a cursor with `session/fork`.\n\nSupplying `{}` advertises support. An omitted or `null` `fork` does not.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "CursorAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhere a session cursor is, relative to an entity the Client holds.\n\nThe anchor names the entity by its type and ID, and `position` says on which\nside of that entity the cursor is. A known `type` with a malformed payload is\nan error. It does not fall back to the unknown-type variant.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "anyOf": [ + { + "description": "The cursor is next to a user message.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "user_message" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to an agent message.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_message" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to an agent thought.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_thought" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to a session-directed message.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "session_message" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to a tool call.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "tool_call" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorToolCallAnchor" + } + ] + }, + { + "description": "The cursor is next to a compaction.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "compaction" + } + }, + "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/CursorCompactionAnchor" + } + ] + }, + { + "title": "other", + "description": "Custom or future anchor type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nA Client that does not recognize the type cannot place the cursor and\nMUST NOT guess a place for it.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future anchor type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": ["type"], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "user_message" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_message" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_thought" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "session_message" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "tool_call" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "compaction" + } + }, + "required": ["type"] + } + ] + }, + "additionalProperties": true + } + ] + }, + "CursorAnchorPosition": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nOn which side of the anchored entity a session cursor is.", + "anyOf": [ + { + "description": "The cursor is immediately before the entity. The history before the\ncursor does not include the entity.", + "type": "string", + "const": "before" + }, + { + "description": "The cursor is immediately after the entity. The history before the\ncursor includes the entity and nothing that follows it in the timeline.", + "type": "string", + "const": "after" + }, + { + "title": "other", + "description": "Custom or future position.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP positions.\nA Client that does not recognize the value cannot place the cursor.", + "type": "string" + } + ] + }, + "CursorMessageAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor anchor to a message. The anchor's `type` names the kind of message.", + "type": "object", + "properties": { + "messageId": { + "description": "The ID of the anchored message.", + "allOf": [ + { + "$ref": "#/$defs/MessageId" + } + ] + }, + "position": { + "description": "On which side of the message the cursor is.", + "allOf": [ + { + "$ref": "#/$defs/CursorAnchorPosition" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["messageId", "position"] + }, + "CursorToolCallAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor anchor to a tool call.", + "type": "object", + "properties": { + "toolCallId": { + "description": "The ID of the anchored tool call.", + "allOf": [ + { + "$ref": "#/$defs/ToolCallId" + } + ] + }, + "position": { + "description": "On which side of the tool call the cursor is.", + "allOf": [ + { + "$ref": "#/$defs/CursorAnchorPosition" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["toolCallId", "position"] + }, + "CursorCompactionAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor anchor to a compaction.", + "type": "object", + "properties": { + "compactionId": { + "description": "The ID of the anchored compaction.", + "allOf": [ + { + "$ref": "#/$defs/CompactionId" + } + ] + }, + "position": { + "description": "On which side of the compaction the cursor is.", + "allOf": [ + { + "$ref": "#/$defs/CursorAnchorPosition" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["compactionId", "position"] + }, + "CursorUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor upsert. A cursor names one position in the session's timeline.\n\nThe first update for a `cursorId` MUST include `anchor`. The anchor is fixed\nafter that, and later updates change only `capabilities`.\n\n`capabilities` and `_meta` have patch semantics: omission leaves the stored\nvalue unchanged, `null` clears it, and an object replaces `capabilities` as a\nwhole. A concrete `_meta` object patches the stored metadata by top-level key\ninstead of replacing it.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "type": "object", + "properties": { + "cursorId": { + "description": "The Agent-owned ID of this cursor, unique within the session.", + "allOf": [ + { + "$ref": "#/$defs/CursorId" + } + ] + }, + "capabilities": { + "description": "The methods that currently accept this cursor.\n\nOmission leaves the capabilities unchanged, `null` clears them, and an object replaces\nthe whole previous value. A new cursor starts with none.", + "anyOf": [ + { + "$ref": "#/$defs/CursorCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "anchor": { + "description": "Where the cursor is, relative to an entity the Client holds.\n\nRequired on the first update for a cursor. The Agent MUST NOT change it afterwards.\nA later update can omit it or repeat the same anchor. Omitted and `null` are\nequivalent and leave the stored anchor unchanged.", + "anyOf": [ + { + "$ref": "#/$defs/CursorAnchor" + }, + { + "type": "null" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted leaves the stored metadata unchanged. `null`\nclears it. An object patches the stored metadata by top-level key: keys it omits are\nunchanged, a key set to `null` is removed, and any other value replaces that key's\nstored value without merging nested objects. Beyond this patch rule, implementations\nMUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/draft/extensibility#metadata-patches)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["cursorId"] + }, "SubagentSessionCapabilities": { "description": "Client-initiated session mutations permitted for a specific subagent session.\n\nA mutation requires an explicit per-child capability. Support for the method\non ordinary sessions does not grant support on a child.", "type": "object", @@ -9214,6 +9609,17 @@ } ] }, + "cursorId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe session cursor to fork at. The new session's history is the source\nsession's history before the cursor.\n\nOptional. Omitted and `null` are equivalent and fork the whole session.\nClients MUST only send the ID of a cursor that the Agent announced on the\nsource session and that currently advertises `capabilities.fork`. The Agent\nrejects any other ID with `-32602`. It does not fall back to forking the\nwhole session.", + "anyOf": [ + { + "$ref": "#/$defs/CursorId" + }, + { + "type": "null" + } + ] + }, "cwd": { "description": "The working directory for this session. Must be an absolute path.", "allOf": [