Skip to content

Commit 701f217

Browse files
benbrandtbenbrandt
authored
feat(schema): Stabilize session/delete (#1370)
1 parent cb6e027 commit 701f217

28 files changed

Lines changed: 464 additions & 154 deletions

‎Cargo.toml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,6 @@ unstable = [
2727
"unstable_mcp_over_acp",
2828
"unstable_nes",
2929
"unstable_plan_operations",
30-
"unstable_session_delete",
3130
"unstable_session_fork",
3231
"unstable_session_usage",
3332
"unstable_end_turn_token_usage",
@@ -46,7 +45,6 @@ unstable_llm_providers = []
4645
unstable_mcp_over_acp = []
4746
unstable_nes = []
4847
unstable_plan_operations = []
49-
unstable_session_delete = []
5048
unstable_session_fork = []
5149
unstable_session_usage = []
5250
unstable_end_turn_token_usage = []

‎docs/docs.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@
7272
"protocol/v1/authentication",
7373
"protocol/v1/session-setup",
7474
"protocol/v1/session-list",
75+
"protocol/v1/session-delete",
7576
"protocol/v1/prompt-turn",
7677
"protocol/v1/content",
7778
"protocol/v1/tool-calls",
@@ -121,6 +122,7 @@
121122
"protocol/v2/authentication",
122123
"protocol/v2/session-setup",
123124
"protocol/v2/session-list",
125+
"protocol/v2/session-delete",
124126
"protocol/v2/prompt-turn",
125127
"protocol/v2/content",
126128
"protocol/v2/tool-calls",
@@ -209,7 +211,6 @@
209211
"group": "Preview",
210212
"pages": [
211213
"rfds/rust-sdk-v1",
212-
"rfds/session-delete",
213214
"rfds/session-usage",
214215
"rfds/message-id"
215216
]
@@ -220,6 +221,7 @@
220221
"rfds/introduce-rfd-process",
221222
"rfds/session-config-options",
222223
"rfds/session-list",
224+
"rfds/session-delete",
223225
"rfds/session-info-update",
224226
"rfds/meta-propagation",
225227
"rfds/acp-agent-registry",

‎docs/protocol/v1/draft/initialization.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,12 @@ As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `ses
208208

209209
Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities.
210210

211+
<ResponseField name="delete" type="SessionDeleteCapabilities Object">
212+
The [`session/delete`](/protocol/v1/draft/session-delete) method is available.
213+
Omitted or `null` means the Agent does not advertise support. Supplying `{}`
214+
means the Agent supports deleting sessions from `session/list`.
215+
</ResponseField>
216+
211217
<ResponseField
212218
name="additionalDirectories"
213219
type="SessionAdditionalDirectoriesCapabilities Object"

‎docs/protocol/v1/draft/schema.mdx‎

Lines changed: 1 addition & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -973,20 +973,12 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d
973973
<a id="session-delete"></a>
974974
### <span class="font-mono">session/delete</span>
975975

976-
**UNSTABLE**
977-
978-
This capability is not part of the spec yet, and may be removed or changed at any point.
979-
980976
Deletes an existing session from `session/list`.
981977

982978
This method is only available if the agent advertises the `sessionCapabilities.delete` capability.
983979

984980
#### <span class="font-mono">DeleteSessionRequest</span>
985981

986-
**UNSTABLE**
987-
988-
This capability is not part of the spec yet, and may be removed or changed at any point.
989-
990982
Request parameters for deleting an existing session from `session/list`.
991983

992984
Only available if the Agent supports the `sessionCapabilities.delete` capability.
@@ -1009,10 +1001,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d
10091001

10101002
#### <span class="font-mono">DeleteSessionResponse</span>
10111003

1012-
**UNSTABLE**
1013-
1014-
This capability is not part of the spec yet, and may be removed or changed at any point.
1015-
10161004
Response from deleting a session.
10171005

10181006
**Type:** Object
@@ -6655,11 +6643,7 @@ additional-root list associated with a listed session.
66556643
Whether the agent supports `session/close`.
66566644
</ResponseField>
66576645
<ResponseField name="delete" type={<><span><a href="#sessiondeletecapabilities">SessionDeleteCapabilities</a></span><span> | null</span></>} >
6658-
**UNSTABLE**
6659-
6660-
This capability is not part of the spec yet, and may be removed or changed at any point.
6661-
6662-
Whether the agent supports `session/delete`.
6646+
Whether the agent supports `session/delete`.
66636647

66646648
Optional. Omitted or `null` both mean the agent does not advertise support.
66656649
Supplying `\{\}` means the agent supports deleting sessions from `session/list`.
@@ -6930,10 +6914,6 @@ Unique identifier for a session configuration option value.
69306914

69316915
## <span class="font-mono">SessionDeleteCapabilities</span>
69326916

6933-
**UNSTABLE**
6934-
6935-
This capability is not part of the spec yet, and may be removed or changed at any point.
6936-
69376917
Capabilities for the `session/delete` method.
69386918

69396919
Supplying `\{\}` means the agent supports deleting sessions from `session/list`.

‎docs/protocol/v1/draft/session-delete.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ sequenceDiagram
3232

3333
## Checking Support
3434

35-
Before attempting to delete a session, Clients **MUST** verify that the Agent supports this capability by checking the unstable `sessionCapabilities.delete` field in the `initialize` response:
35+
Before attempting to delete a session, Clients **MUST** verify that the Agent supports this capability by checking the `sessionCapabilities.delete` field in the `initialize` response:
3636

3737
```json highlight={7-9}
3838
{

‎docs/protocol/v1/draft/session-list.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,8 @@ include `additionalDirectories` in returned `SessionInfo` objects to report
5858
additional workspace roots for listed sessions.
5959

6060
<Note>
61-
If the Agent advertises the unstable `sessionCapabilities.delete` capability,
62-
Clients can remove sessions from future `session/list` results with
61+
If the Agent advertises the `sessionCapabilities.delete` capability, Clients
62+
can remove sessions from future `session/list` results with
6363
[`session/delete`](/protocol/v1/draft/session-delete).
6464
</Note>
6565

‎docs/protocol/v1/initialization.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,12 @@ As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `ses
207207

208208
Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities.
209209

210+
<ResponseField name="delete" type="SessionDeleteCapabilities Object">
211+
The [`session/delete`](/protocol/v1/session-delete) method is available.
212+
Omitted or `null` means the Agent does not advertise support. Supplying `{}`
213+
means the Agent supports deleting sessions from `session/list`.
214+
</ResponseField>
215+
210216
<ResponseField
211217
name="additionalDirectories"
212218
type="SessionAdditionalDirectoriesCapabilities Object"

‎docs/protocol/v1/schema.mdx‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,52 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
297297

298298
</ResponseField>
299299

300+
<a id="session-delete"></a>
301+
### <span class="font-mono">session/delete</span>
302+
303+
Deletes an existing session from `session/list`.
304+
305+
This method is only available if the agent advertises the `sessionCapabilities.delete` capability.
306+
307+
#### <span class="font-mono">DeleteSessionRequest</span>
308+
309+
Request parameters for deleting an existing session from `session/list`.
310+
311+
Only available if the Agent supports the `sessionCapabilities.delete` capability.
312+
313+
**Type:** Object
314+
315+
**Properties:**
316+
317+
<ResponseField name="_meta" type={"object | null"} >
318+
The _meta property is reserved by ACP to allow clients and agents to attach additional
319+
metadata to their interactions. Implementations MUST NOT make assumptions about values at
320+
these keys.
321+
322+
See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
323+
324+
</ResponseField>
325+
<ResponseField name="sessionId" type={<a href="#sessionid">SessionId</a>} required>
326+
The ID of the session to delete.
327+
</ResponseField>
328+
329+
#### <span class="font-mono">DeleteSessionResponse</span>
330+
331+
Response from deleting a session.
332+
333+
**Type:** Object
334+
335+
**Properties:**
336+
337+
<ResponseField name="_meta" type={"object | null"} >
338+
The _meta property is reserved by ACP to allow clients and agents to attach additional
339+
metadata to their interactions. Implementations MUST NOT make assumptions about values at
340+
these keys.
341+
342+
See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
343+
344+
</ResponseField>
345+
300346
<a id="session-list"></a>
301347
### <span class="font-mono">session/list</span>
302348

@@ -2865,6 +2911,13 @@ additional-root list associated with a listed session.
28652911
</ResponseField>
28662912
<ResponseField name="close" type={<><span><a href="#sessionclosecapabilities">SessionCloseCapabilities</a></span><span> | null</span></>} >
28672913
Whether the agent supports `session/close`.
2914+
</ResponseField>
2915+
<ResponseField name="delete" type={<><span><a href="#sessiondeletecapabilities">SessionDeleteCapabilities</a></span><span> | null</span></>} >
2916+
Whether the agent supports `session/delete`.
2917+
2918+
Optional. Omitted or `null` both mean the agent does not advertise support.
2919+
Supplying `\{\}` means the agent supports deleting sessions from `session/list`.
2920+
28682921
</ResponseField>
28692922
<ResponseField name="list" type={<><span><a href="#sessionlistcapabilities">SessionListCapabilities</a></span><span> | null</span></>} >
28702923
Whether the agent supports `session/list`.
@@ -3057,6 +3110,25 @@ Unique identifier for a session configuration option value.
30573110

30583111
**Type:** `string`
30593112

3113+
## <span class="font-mono">SessionDeleteCapabilities</span>
3114+
3115+
Capabilities for the `session/delete` method.
3116+
3117+
Supplying `\{\}` means the agent supports deleting sessions from `session/list`.
3118+
3119+
**Type:** Object
3120+
3121+
**Properties:**
3122+
3123+
<ResponseField name="_meta" type={"object | null"} >
3124+
The _meta property is reserved by ACP to allow clients and agents to attach additional
3125+
metadata to their interactions. Implementations MUST NOT make assumptions about values at
3126+
these keys.
3127+
3128+
See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3129+
3130+
</ResponseField>
3131+
30603132
## <span class="font-mono">SessionId</span>
30613133

30623134
A unique identifier for a conversation session between a client and agent.

‎docs/protocol/v1/session-delete.mdx‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
title: "Session Delete"
3+
description: "Removing sessions from session history"
4+
---
5+
6+
The `session/delete` method allows Clients to remove sessions from an Agent's `session/list` results. This gives users a standard way to manage session history across ACP Clients and Agents.
7+
8+
Before deleting sessions, Clients **MUST** first complete the [initialization](/protocol/v1/initialization) phase and verify the Agent supports this capability.
9+
10+
<br />
11+
12+
```mermaid
13+
sequenceDiagram
14+
participant Client
15+
participant Agent
16+
17+
Note over Agent,Client: Initialized
18+
19+
Client->>Agent: session/list
20+
Agent-->>Client: session/list response (sessions)
21+
22+
alt User deletes a session
23+
Client->>Agent: session/delete (sessionId)
24+
Agent-->>Client: session/delete response
25+
end
26+
27+
Client->>Agent: session/list
28+
Agent-->>Client: session/list response (without deleted session)
29+
```
30+
31+
<br />
32+
33+
## Checking Support
34+
35+
Before attempting to delete a session, Clients **MUST** verify that the Agent supports this capability by checking the `sessionCapabilities.delete` field in the `initialize` response:
36+
37+
```json highlight={7-9}
38+
{
39+
"jsonrpc": "2.0",
40+
"id": 0,
41+
"result": {
42+
"protocolVersion": 1,
43+
"agentCapabilities": {
44+
"sessionCapabilities": {
45+
"delete": {}
46+
}
47+
}
48+
}
49+
}
50+
```
51+
52+
If `sessionCapabilities.delete` is omitted or `null`, the Agent does not support deleting sessions and Clients **MUST NOT** attempt to call `session/delete`. Supplying `{}` means the Agent supports the method.
53+
54+
## Deleting a Session
55+
56+
Clients delete a session by calling `session/delete` with the session ID to remove from session history:
57+
58+
```json
59+
{
60+
"jsonrpc": "2.0",
61+
"id": 3,
62+
"method": "session/delete",
63+
"params": {
64+
"sessionId": "sess_abc123def456"
65+
}
66+
}
67+
```
68+
69+
<ParamField path="sessionId" type="SessionId" required>
70+
Unique identifier for the session to delete.
71+
</ParamField>
72+
73+
On success, the Agent returns an empty result:
74+
75+
```json
76+
{
77+
"jsonrpc": "2.0",
78+
"id": 3,
79+
"result": {}
80+
}
81+
```
82+
83+
## Semantics
84+
85+
- Deleted sessions no longer appear in future `session/list` results.
86+
- Deleting an already-deleted session, or a session that never existed, **SHOULD** succeed silently.
87+
- Agents may implement soft delete or hard delete. ACP only specifies the user-facing session-list behavior.
88+
- Behavior for `session/load` on a deleted session is implementation-defined.
89+
- Behavior for deleting an active session is implementation-defined.

‎docs/protocol/v1/session-list.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,12 @@ Agents that also advertise `sessionCapabilities.additionalDirectories` may
5757
include `additionalDirectories` in returned `SessionInfo` objects to report
5858
additional workspace roots for listed sessions.
5959

60+
<Note>
61+
If the Agent advertises the `sessionCapabilities.delete` capability, Clients
62+
can remove sessions from future `session/list` results with
63+
[`session/delete`](/protocol/v1/session-delete).
64+
</Note>
65+
6066
## Listing Sessions
6167

6268
Clients discover existing sessions by calling the `session/list` method with optional filtering and pagination parameters:

0 commit comments

Comments
 (0)