From 747431fbe4c5d82fde1eb4de440749a5cc23f8e1 Mon Sep 17 00:00:00 2001 From: "mark.tkachenko" Date: Mon, 14 Sep 2026 16:17:28 +0200 Subject: [PATCH 1/5] Sessions archive rfd --- docs/rfds/session-archive.mdx | 194 ++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 docs/rfds/session-archive.mdx diff --git a/docs/rfds/session-archive.mdx b/docs/rfds/session-archive.mdx new file mode 100644 index 000000000..6d762fc7d --- /dev/null +++ b/docs/rfds/session-archive.mdx @@ -0,0 +1,194 @@ +--- +title: "Session Archive and Unarchive" +--- + +Authors: Mark Tkachenko, Evgeniy Stepanov + +## Elevator pitch + +> What are you proposing to change? + +Standardize reversible session archiving: Clients can hide conversations from default history, discover archived sessions, and restore them with the same ID and saved history. + +## Status quo + +> How do things work today and what problems does this cause? Why would we change things? + +[`session/delete`](/protocol/v1/session-delete) removes sessions from history but permits permanent deletion. [`session/close`](/protocol/v1/session-setup#closing-active-sessions) releases execution resources. Neither guarantees reversible hiding, and [`session/list`](/protocol/v1/session-list) cannot explicitly request archived sessions. + +## What we propose to do about it + +> What are you proposing to improve the situation? + +### Methods + +`session/archive` hides a session from default history: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "session/archive", + "params": { "sessionId": "sess_abc123" } +} +``` + +`session/unarchive` restores it: + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "session/unarchive", + "params": { "sessionId": "sess_abc123" } +} +``` + +Both return an empty result with the matching request ID: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +`sessionId` is required and non-null. Both methods support the usual optional `_meta` field in requests and responses. + +### Capabilities + +Agents advertise the methods independently: + +- **v1:** `agentCapabilities.sessionCapabilities.archive` and `.unarchive`. +- **v2 draft:** `capabilities.session.archive` and `.unarchive`. + +`{}` enables the corresponding method; omission or `null` means unsupported. Clients **MUST** check support before calling it. + +Advertising either capability **MUST** also enable archived listing and state reporting. In v1, this requires `sessionCapabilities.list: {}`; v2 already requires listing for Agents supporting sessions. + +Example v1 initialization response: + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "result": { + "protocolVersion": 1, + "agentCapabilities": { + "sessionCapabilities": { + "list": {}, + "archive": {}, + "unarchive": {} + } + } + } +} +``` + +### Listing and state + +Extend `session/list` with an optional `archived` parameter to include archived sessions: + +| Value | Sessions returned | +| --------------------------- | ------------------------ | +| Omitted, `null`, or `false` | Unarchived only. | +| `true` | Unarchived and archived. | + +Clients **MUST NOT** send this parameter without either archive capability. It combines with `cwd` and applies before pagination. Clients keep the same `cwd` and `archived` values when following `nextCursor`; changing either starts a new pagination sequence. + +Include archived sessions alongside unarchived sessions: + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "session/list", + "params": { + "cwd": "/home/user/project", + "archived": true + } +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "sessions": [ + { + "sessionId": "sess_abc123", + "cwd": "/home/user/project", + "title": "Implement session archive support", + "archived": true + }, + { + "sessionId": "sess_def456", + "cwd": "/home/user/project", + "title": "Update session documentation", + "archived": false + } + ] + } +} +``` + +Add an optional, non-null boolean `archived` to: + +- **`SessionInfo`:** required in list results when either archive capability is advertised. Otherwise, omission conveys no archive-state guarantee. +- **`SessionInfoUpdate`:** omission leaves state unchanged. Agents **SHOULD** report changes through existing `session_info_update` notifications to connected session observers. Listing remains the source of truth after reconnecting; no global subscription is introduced. + +```json +{ + "jsonrpc": "2.0", + "method": "session/update", + "params": { + "sessionId": "sess_abc123", + "update": { + "sessionUpdate": "session_info_update", + "archived": true + } + } +} +``` + +### Guarantees + +- **Preservation:** Both operations preserve the ID and saved conversation. Archive state persists with session history across connections and restarts; ordinary retention policies still apply. +- **Independent execution:** Neither operation loads, resumes, closes, or cancels a session. Agents **MAY** reject archiving an active session without changing archive state if stopping it would be necessary. Clients can explicitly close it first. +- **Explicit restoration:** Closing, loading, or resuming does not change archive state. Agents may require unarchiving before loading or resuming. +- **Idempotency:** Repeating the desired state succeeds for retained, non-deleted sessions. Unknown, deleted, or expired sessions return `Resource not found` (`-32002`). Neither method requires activation on the current connection. +- **Consistency:** Success commits the change; subsequent list requests reflect it unless another operation intervenes. Concurrent mutations are serialized per session. +- **Deletion:** Deleted sessions remain excluded regardless of the `archived` parameter. Unarchive does not undo deletion; Clients must not substitute deletion for archiving. +- **Activity:** Archiving and unarchiving alone **SHOULD NOT** change `updatedAt`. + +## Shiny future + +> How will things will play out once this feature exists? + +A user archives a conversation in one Client, finds it in another Client's archived history, and restores it for continued work. + +## Implementation details and plan + +> Tell me more about your implementation. What is your detailed implementation plan? + +Add the methods, capabilities, filter, and state fields behind `unstable_session_archive`; regenerate v1/v2 schemas and update conversions, SDKs, and docs. Validate restoration, retries, persistence, pagination, active sessions, and deletion compatibility with Agent and Client implementations before preview. + +## Frequently asked questions + +> What questions have arisen over the course of authoring this document or during subsequent discussions? + +## Why separate methods? + +They match the requested actions and allow independent capabilities. A boolean setter is possible, but a general metadata-editing API exceeds this request. Extending deletion cannot guarantee recovery when Agents may permanently remove data. + +## What needs discussion? + +- **Active sessions:** Keep execution separate as proposed, or make archiving also close the session? +- **Discovery:** Should including archived sessions have its own capability for Agents that support neither mutation? +- **Migration:** Some adapters implement deletion through native archiving. They need a distinction to keep deleted sessions out of archived results; how should historical records without that distinction be handled? + +## Revision history + +- 2026-09-14: Initial proposal. From 0c1cf58149c97fe338994cc9215c962d49fc2fae Mon Sep 17 00:00:00 2001 From: "mark.tkachenko" Date: Mon, 14 Sep 2026 17:06:42 +0200 Subject: [PATCH 2/5] delete capability added, archive capabilities merged, meta added --- docs/rfds/session-archive.mdx | 48 ++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/docs/rfds/session-archive.mdx b/docs/rfds/session-archive.mdx index 6d762fc7d..d60507e29 100644 --- a/docs/rfds/session-archive.mdx +++ b/docs/rfds/session-archive.mdx @@ -29,7 +29,10 @@ Standardize reversible session archiving: Clients can hide conversations from de "jsonrpc": "2.0", "id": 1, "method": "session/archive", - "params": { "sessionId": "sess_abc123" } + "params": { + "sessionId": "sess_abc123", + "_meta": {} + } } ``` @@ -40,34 +43,45 @@ Standardize reversible session archiving: Clients can hide conversations from de "jsonrpc": "2.0", "id": 2, "method": "session/unarchive", - "params": { "sessionId": "sess_abc123" } + "params": { + "sessionId": "sess_abc123", + "_meta": {} + } } ``` -Both return an empty result with the matching request ID: +Both return a result object with optional `_meta` and the matching request ID: ```json { "jsonrpc": "2.0", "id": 1, - "result": {} + "result": { "_meta": {} } } ``` -`sessionId` is required and non-null. Both methods support the usual optional `_meta` field in requests and responses. +The new models are: + +| Models | Fields | +| ---------------------------------------------------- | ------------------------------------------------------------ | +| `ArchiveSessionRequest`, `UnarchiveSessionRequest` | Required, non-null `sessionId: SessionId`; optional `_meta`. | +| `ArchiveSessionResponse`, `UnarchiveSessionResponse` | Optional `_meta`. | +| `SessionArchiveCapabilities` | Optional `_meta`. | + +In each model, `_meta` is an object with arbitrary values. Omission and `null` are equivalent. An empty result `{}` remains valid when no metadata is supplied. ### Capabilities -Agents advertise the methods independently: +Agents advertise one shared `archive` capability: -- **v1:** `agentCapabilities.sessionCapabilities.archive` and `.unarchive`. -- **v2 draft:** `capabilities.session.archive` and `.unarchive`. +- **v1:** `agentCapabilities.sessionCapabilities.archive`. +- **v2 draft:** `capabilities.session.archive`. -`{}` enables the corresponding method; omission or `null` means unsupported. Clients **MUST** check support before calling it. +`{}` means the Agent **MUST** support both methods, archived listing, and state reporting; omission or `null` means unsupported. Clients **MUST** check support before using either method or the list parameter. -Advertising either capability **MUST** also enable archived listing and state reporting. In v1, this requires `sessionCapabilities.list: {}`; v2 already requires listing for Agents supporting sessions. +In v1, this also requires `sessionCapabilities.list: {}`; v2 already requires listing for Agents supporting sessions. -Example v1 initialization response: +Example v1 initialization response, also advertising the existing `delete` capability for `session/delete`: ```json { @@ -78,8 +92,8 @@ Example v1 initialization response: "agentCapabilities": { "sessionCapabilities": { "list": {}, - "archive": {}, - "unarchive": {} + "delete": {}, + "archive": { "_meta": {} } } } } @@ -95,7 +109,7 @@ Extend `session/list` with an optional `archived` parameter to include archived | Omitted, `null`, or `false` | Unarchived only. | | `true` | Unarchived and archived. | -Clients **MUST NOT** send this parameter without either archive capability. It combines with `cwd` and applies before pagination. Clients keep the same `cwd` and `archived` values when following `nextCursor`; changing either starts a new pagination sequence. +The parameter combines with `cwd` and applies before pagination. Clients keep the same `cwd` and `archived` values when following `nextCursor`; changing either starts a new pagination sequence. Include archived sessions alongside unarchived sessions: @@ -136,7 +150,7 @@ Include archived sessions alongside unarchived sessions: Add an optional, non-null boolean `archived` to: -- **`SessionInfo`:** required in list results when either archive capability is advertised. Otherwise, omission conveys no archive-state guarantee. +- **`SessionInfo`:** required in list results when the `archive` capability is advertised. Otherwise, omission conveys no archive-state guarantee. - **`SessionInfoUpdate`:** omission leaves state unchanged. Agents **SHOULD** report changes through existing `session_info_update` notifications to connected session observers. Listing remains the source of truth after reconnecting; no global subscription is introduced. ```json @@ -173,7 +187,7 @@ A user archives a conversation in one Client, finds it in another Client's archi > Tell me more about your implementation. What is your detailed implementation plan? -Add the methods, capabilities, filter, and state fields behind `unstable_session_archive`; regenerate v1/v2 schemas and update conversions, SDKs, and docs. Validate restoration, retries, persistence, pagination, active sessions, and deletion compatibility with Agent and Client implementations before preview. +Add the methods, shared capability, filter, and state fields behind `unstable_session_archive`; regenerate v1/v2 schemas and update conversions, SDKs, and docs. Validate restoration, retries, persistence, pagination, active sessions, and deletion compatibility with Agent and Client implementations before preview. ## Frequently asked questions @@ -181,7 +195,7 @@ Add the methods, capabilities, filter, and state fields behind `unstable_session ## Why separate methods? -They match the requested actions and allow independent capabilities. A boolean setter is possible, but a general metadata-editing API exceeds this request. Extending deletion cannot guarantee recovery when Agents may permanently remove data. +They express opposite state transitions under one shared capability. A boolean setter is possible, but a general metadata-editing API exceeds this request. Extending deletion cannot guarantee recovery when Agents may permanently remove data. ## What needs discussion? From f47f6dad7460c3d6b06e455e322a0e6e359a0eac Mon Sep 17 00:00:00 2001 From: "mark.tkachenko" Date: Tue, 15 Sep 2026 13:36:51 +0200 Subject: [PATCH 3/5] Update session-archive.mdx --- docs/rfds/session-archive.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rfds/session-archive.mdx b/docs/rfds/session-archive.mdx index d60507e29..fd9abfa4a 100644 --- a/docs/rfds/session-archive.mdx +++ b/docs/rfds/session-archive.mdx @@ -8,7 +8,7 @@ Authors: Mark Tkachenko, Evgeniy Stepanov > What are you proposing to change? -Standardize reversible session archiving: Clients can hide conversations from default history, discover archived sessions, and restore them with the same ID and saved history. +Standardize reversible session archiving in both ACP v1 and v2: Clients can hide conversations from default history, discover archived sessions, and restore them with the same ID and saved history. ## Status quo @@ -187,7 +187,7 @@ A user archives a conversation in one Client, finds it in another Client's archi > Tell me more about your implementation. What is your detailed implementation plan? -Add the methods, shared capability, filter, and state fields behind `unstable_session_archive`; regenerate v1/v2 schemas and update conversions, SDKs, and docs. Validate restoration, retries, persistence, pagination, active sessions, and deletion compatibility with Agent and Client implementations before preview. +The implementation **MUST** cover both ACP v1 and v2: `session/archive`, `session/unarchive`, all new models with `_meta`, the shared `archive` capability, the `session/list` parameter, and archive-state reporting. Implement these behind `unstable_session_archive`, regenerate both versions' schemas, and update conversions, SDKs, and docs. Validate restoration, retries, persistence, pagination, active sessions, and deletion compatibility in both protocol versions before preview. ## Frequently asked questions From 42c20db03deca1af4b2b7f22e34a483737d3bda4 Mon Sep 17 00:00:00 2001 From: "mark.tkachenko" Date: Wed, 16 Sep 2026 13:49:13 +0200 Subject: [PATCH 4/5] delete meta added --- docs/rfds/session-archive.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rfds/session-archive.mdx b/docs/rfds/session-archive.mdx index fd9abfa4a..dd0c2cf5a 100644 --- a/docs/rfds/session-archive.mdx +++ b/docs/rfds/session-archive.mdx @@ -81,7 +81,7 @@ Agents advertise one shared `archive` capability: In v1, this also requires `sessionCapabilities.list: {}`; v2 already requires listing for Agents supporting sessions. -Example v1 initialization response, also advertising the existing `delete` capability for `session/delete`: +Both `archive` and the existing `delete` capability support optional `_meta` in v1 and v2. Example v1 initialization response: ```json { @@ -92,7 +92,7 @@ Example v1 initialization response, also advertising the existing `delete` capab "agentCapabilities": { "sessionCapabilities": { "list": {}, - "delete": {}, + "delete": { "_meta": {} }, "archive": { "_meta": {} } } } From 9b43476e3e40de41f3eac3c719292c3f0969a267 Mon Sep 17 00:00:00 2001 From: "mark.tkachenko" Date: Wed, 16 Sep 2026 14:07:44 +0200 Subject: [PATCH 5/5] removed explicit meta where not applicable --- docs/rfds/session-archive.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/rfds/session-archive.mdx b/docs/rfds/session-archive.mdx index dd0c2cf5a..20048b485 100644 --- a/docs/rfds/session-archive.mdx +++ b/docs/rfds/session-archive.mdx @@ -31,7 +31,6 @@ Standardize reversible session archiving in both ACP v1 and v2: Clients can hide "method": "session/archive", "params": { "sessionId": "sess_abc123", - "_meta": {} } } ``` @@ -45,7 +44,6 @@ Standardize reversible session archiving in both ACP v1 and v2: Clients can hide "method": "session/unarchive", "params": { "sessionId": "sess_abc123", - "_meta": {} } } ``` @@ -92,8 +90,8 @@ Both `archive` and the existing `delete` capability support optional `_meta` in "agentCapabilities": { "sessionCapabilities": { "list": {}, - "delete": { "_meta": {} }, - "archive": { "_meta": {} } + "delete": {}, + "archive": {} } } }