Skip to content

feat(unstable): add session/status method - #2735

Merged
benbrandt merged 3 commits into
mainfrom
feat/session-status
Oct 30, 2026
Merged

benbrandt merged 3 commits into
mainfrom
feat/session-status

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Adds schema support for the session-status RFD behind a new unstable_session_status feature (included in unstable), in both v1 and v2.

Shape

// session/status
SessionStatusRequest  { sessionId: SessionId, _meta? }
SessionStatusResponse { status: SessionStatus, state?: StateUpdate /* v2 only */, _meta? }
SessionStatus = "open" | "saved" | string   // unrecognized values are treated as "saved"
// unknown session → -32002 with data.sessionId
  • status: required and strict, because Clients decide whether to resume based on it. It uses the same open-enum pattern as SystemPromptMode, so custom _ values round-trip.
  • v2 state: reuses StateUpdate. A missing, null or malformed value means "not reported", never idle, as the RFD specifies.
  • Capability: sessionCapabilities.status (v1) / session.status (v2), as a SessionStatusCapabilities object.

Status values renamed from the RFD

The RFD proposed active / inactive. v2 already calls a session "active" on a connection from session/new, session/resume or session/fork until close or disconnect. A status of active that means "in memory for any connection" invites Clients to skip session/resume. open / saved follow the session lifecycle instead: session/close frees an open session, after which it reads as saved, and session/resume opens it again. The RFD is updated, with an FAQ entry and a revision history entry.

Docs

  • v2 overview: a row in the unstable features table.
  • initialization pages (v1 and v2): a status field.
  • error pages (v1 and v2): an unknown session gets -32002, and a session that exists but isn't loaded is not an error.
  • Generated: unstable JSON schemas and draft schema.mdx pages.

#2734 (session/set_title) touches the same spots in the docs and SessionCapabilities, so whichever merges second will need a small conflict resolved.

Add schema support for the session-status RFD behind the new
`unstable_session_status` feature, in both v1 and v2:

- `session/status` request with a required `sessionId`
- response with a required, open `status` (`open` or `saved`, unknown
  values treated as `saved`)
- in v2, an optional `state` foreground snapshot reusing `StateUpdate`
- `sessionCapabilities.status` (v1) / `session.status` (v2) capability
- draft overview, initialization, and error page entries

The RFD's `active` / `inactive` values are renamed to `open` / `saved`,
since v2 already uses "active" for a session attached to a connection.
@benbrandt
benbrandt requested a review from a team as a code owner October 30, 2026 18:25
@benbrandt
benbrandt enabled auto-merge (squash) October 30, 2026 18:31
# Conflicts:
#	agent-client-protocol-schema/Cargo.toml
#	agent-client-protocol-schema/src/v1/agent.rs
#	agent-client-protocol-schema/src/v2/agent.rs
#	docs/protocol/v1/draft/error.mdx
#	docs/protocol/v1/draft/initialization.mdx
#	docs/protocol/v1/draft/schema.mdx
#	docs/protocol/v2/draft/error.mdx
#	docs/protocol/v2/draft/initialization.mdx
#	docs/protocol/v2/draft/overview.mdx
#	docs/protocol/v2/draft/schema.mdx
#	schema-generator/src/main.rs
#	schema/v1/meta.unstable.json
#	schema/v1/schema.unstable.json
#	schema/v2/meta.unstable.json
#	schema/v2/schema.unstable.json
# Conflicts:
#	agent-client-protocol-schema/src/v2/agent.rs
@benbrandt
benbrandt merged commit 8eb7e74 into main Oct 30, 2026
14 checks passed
@benbrandt
benbrandt deleted the feat/session-status branch October 30, 2026 18:47
@acp-release-bot acp-release-bot Bot mentioned this pull request Oct 30, 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