Skip to content

feat(unstable): add session cursors and cursorId on session/fork - #2843

Merged
benbrandt merged 1 commit into
mainfrom
session-cursors-schema
Nov 17, 2026
Merged

benbrandt merged 1 commit into
mainfrom
session-cursors-schema

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Implements steps 1 and 2 of the Session Cursors RFD (#2114) and the fork RFD's "Forking at a cursor" section. Everything is behind the new unstable_session_cursors feature, which is part of unstable.

Schema

  • cursor_update session update in v1 and v2. It is an upsert keyed by cursorId. capabilities is a nullable patch object, the same shape as tool call capabilities. anchor is required on the first update for a cursor.
  • CursorAnchor is a union tagged by type: user_message, agent_message, agent_thought, session_message, tool_call, and compaction. Each carries the entity's ID and a position of before or after. Unknown types and positions are preserved, so a Client can tell that it cannot place the cursor and does not guess.
  • cursorId on session/fork and a fork cursor capability, behind unstable_session_fork and unstable_session_cursors together.
  • session.cursors Client capability in v1. V2 needs no capability, because Clients ignore session updates they don't know.

In v1, the session_message anchor is also behind unstable_subagents, like session messages themselves.

Parsing

  • capabilities and _meta parse leniently. A malformed capability reads as not advertised.
  • anchor and the fork cursorId are strict. A malformed anchor fails the update, and a malformed cursorId fails the request with -32602. It never falls back to forking the whole session.
  • A malformed value for a known anchor type never falls through to the Other variant. cursor_update is in the v2 list of known discriminators for the same reason.

Docs

  • Draft v1 and v2 protocol pages describe the update, anchors, how a Client places a cursor, how to pass one to a method, forking at a cursor, replay, and lifetime. The v1 page also covers the Client capability and the cases where a live prompt has no user message to anchor to.
  • The RFD updates page gets the "moves to Draft" entry that docs(rfd): add session cursors RFD #2114 missed.
  • Both RFDs note what landed in their revision histories.

Notes for review

  • Each anchor variant accepts _meta, which the RFD did not spell out. It follows the other nested union payloads, and the RFD's revision history now says so.
  • The anchor payloads are named CursorMessageAnchor, CursorToolCallAnchor, and CursorCompactionAnchor. The four message anchor types share one struct.

Testing

npm run generate leaves no diff. The clippy passes, cargo test --all-features, the per-feature schema and generator test runs, the docs.rs build, Prettier, and the spellcheck all pass locally.

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.
@benbrandt
benbrandt requested a review from a team as a code owner November 17, 2026 11:14
@benbrandt
benbrandt enabled auto-merge (squash) November 17, 2026 11:16
@benbrandt
benbrandt merged commit 417a9f5 into main Nov 17, 2026
13 checks passed
@benbrandt
benbrandt deleted the session-cursors-schema branch November 17, 2026 11:19
@acp-release-bot acp-release-bot Bot mentioned this pull request Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant