Skip to content

Commit 158f01d

Browse files
chazcbclaudebenbrandt
authored
docs(rfd): Session Delete (#395)
* Create session-delete.mdx * Update session-delete.mdx * Fix session/delete capability to be agent capability in initialize response Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Add ben as champion * add to website --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
1 parent 75169d4 commit 158f01d

3 files changed

Lines changed: 151 additions & 1 deletion

File tree

‎docs/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,8 @@
119119
"rfds/acp-agent-registry",
120120
"rfds/auth-methods",
121121
"rfds/rust-sdk-v1",
122-
"rfds/logout-method"
122+
"rfds/logout-method",
123+
"rfds/session-delete"
123124
]
124125
},
125126
{ "group": "Preview", "pages": ["rfds/session-config-options"] },

‎docs/rfds/session-delete.mdx‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: "Session Delete"
3+
---
4+
5+
Author(s): [@chazcb](https://github.com/chazcb)
6+
Champion: [@benbrandt](https://github.com/benbrandt)
7+
8+
## Elevator pitch
9+
10+
> What are you proposing to change?
11+
12+
Add a capability-gated `session/delete` method so clients can remove sessions from `session/list`. This complements `session/list` by giving users control over which sessions appear in their session history.
13+
14+
## Status quo
15+
16+
> How do things work today and what problems does this cause? Why would we change things?
17+
18+
The [`session/list` RFD](/rfds/session-list) introduced the ability for clients to enumerate sessions. However, there's no standard way to remove sessions from this list. Without `session/delete`, users have no control over their session history—old sessions accumulate, and clients must implement non-standard deletion mechanisms or rely on agent-specific cleanup policies.
19+
20+
## What we propose to do about it
21+
22+
> What are you proposing to improve the situation?
23+
24+
Add a `session/delete` JSON-RPC method that is capability-gated. Agents advertise support via `sessionCapabilities.delete` in their initialization response.
25+
26+
```json
27+
{
28+
"jsonrpc": "2.0",
29+
"id": 0,
30+
"result": {
31+
"protocolVersion": 1,
32+
"agentCapabilities": {
33+
"sessionCapabilities": {
34+
"delete": {}
35+
}
36+
}
37+
}
38+
}
39+
```
40+
41+
### Method
42+
43+
```json
44+
{
45+
"jsonrpc": "2.0",
46+
"id": 3,
47+
"method": "session/delete",
48+
"params": {
49+
"sessionId": "sess_abc123def456"
50+
}
51+
}
52+
```
53+
54+
### Request Parameters
55+
56+
| Field | Type | Required | Description |
57+
| ----------- | ----------- | -------- | --------------------- |
58+
| `sessionId` | `SessionId` | Yes | The session to delete |
59+
60+
### Response
61+
62+
On success, returns an empty result:
63+
64+
```json
65+
{
66+
"jsonrpc": "2.0",
67+
"id": 3,
68+
"result": {}
69+
}
70+
```
71+
72+
### Semantics
73+
74+
- **Capability-gated**: Agents MUST NOT accept `session/delete` calls unless they advertised `sessionCapabilities.delete` at initialization.
75+
- **Removes from list**: The primary effect is that deleted sessions no longer appear in `session/list` results.
76+
- **Implementation-defined storage behavior**: Agents may implement soft delete (mark as hidden) or hard delete (remove data). The protocol does not prescribe which.
77+
- **Implementation-defined load behavior**: Agents may choose what happens when a client calls `session/load` on a deleted session—return the session anyway, return an error, or any other behavior. The protocol does not prescribe which.
78+
- **Idempotent**: Deleting an already-deleted session (or a session that never existed) SHOULD succeed silently rather than error.
79+
80+
## Alternatives considered
81+
82+
### Automatic lifecycle policies only
83+
84+
Rely on agents to implement their own session retention policies (e.g., delete sessions older than 30 days) without exposing user control.
85+
86+
**Tradeoffs**: Users have no control over which sessions are kept. A session the user wants to keep might be deleted, or a session the user wants gone might persist.
87+
88+
### Add a `hidden` flag to sessions
89+
90+
Instead of delete, allow users to mark sessions as hidden. They'd still exist but not appear in `session/list` by default.
91+
92+
**Tradeoffs**: More complex—requires filter parameters on `session/list` to show/hide hidden sessions. For most use cases, delete is simpler and matches user expectations.
93+
94+
### Batch deletion
95+
96+
Support deleting multiple sessions in one call via a `sessionIds` array.
97+
98+
**Tradeoffs**: Could be added later as an extension. Single-session delete covers the common case and keeps the initial implementation simple.
99+
100+
## Shiny future
101+
102+
> How will things play out once this feature exists?
103+
104+
Users can manage their session history, and all ACP clients can offer this using the same protocol method rather than implementing their own mechanisms.
105+
106+
## Implementation details and plan
107+
108+
> Tell me more about your implementation. What is your detailed implementation plan?
109+
110+
1. **Schema**: Add `session/delete` method definition, `DeleteSessionRequest` and `DeleteSessionResponse` types.
111+
2. **Capabilities**: Add `sessionCapabilities.delete` capability flag.
112+
3. **Protocol**: Add `session/delete` to method tables.
113+
4. **Docs**: Update session management docs to include deletion.
114+
115+
## Frequently asked questions
116+
117+
> What questions have arisen over the course of authoring this document or during subsequent discussions?
118+
119+
### Why not prescribe soft vs hard delete?
120+
121+
Different agents have different storage architectures and compliance requirements. Some may need to retain data for auditing; others may want to free storage immediately. The protocol focuses on the user-facing behavior (removed from list) and leaves storage decisions to implementers.
122+
123+
### Why not prescribe behavior for loading deleted sessions?
124+
125+
Similar reasoning—some agents may want to allow "undelete" by loading a soft-deleted session, others may want a clean error. The protocol provides the deletion mechanism; agents decide the semantics that fit their use case.
126+
127+
### Should delete require confirmation?
128+
129+
No. Confirmation UX is a client concern. The protocol provides the delete operation; clients can add confirmation dialogs, undo functionality, or other UX patterns as they see fit.
130+
131+
### What if the session is currently active?
132+
133+
Agents may reject deletion of active sessions or handle it however they choose. This is implementation-defined. A reasonable approach is to allow deletion—the session simply won't appear in future `session/list` calls.
134+
135+
### Why is this a separate RFD from session/list?
136+
137+
The [`session/list` RFD](/rfds/session-list#what-about-session-deletion) explicitly deferred deletion to keep scope focused. Now that `session/list` is established, `session/delete` is a natural complement.
138+
139+
## Revision history
140+
141+
- **2025-02-03**: Fixed capability example to use agent capability (initialize response)
142+
- **2025-01-24**: Initial draft

‎docs/updates.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@ description: Updates and announcements about the Agent Client Protocol
44
rss: true
55
---
66

7+
<Update label="February 4, 2026" tags={["RFD"]}>
8+
## session/delete moves to Draft stage
9+
10+
The RFD for allowing clients to delete a given session has been moved to Draft stage. Please review the [RFD](./rfds/session-delete) for more information on the current proposal and provide feedback as work on the implementation begins.
11+
12+
</Update>
13+
714
<Update label="February 4, 2026" tags={["RFD"]}>
815
## Logout method moves to Draft stage
916

0 commit comments

Comments
 (0)