Skip to content

Commit 4c333a5

Browse files
ahmedhesham6benbrandt
ahmedhesham6
and
benbrandt
authored
RFD: session/list API for session discovery and management (#211)
* RFD: session/list API for session discovery and management Proposes a new session/list endpoint to enable: - Discovery of existing sessions - Session history browsing - Multi-session management - Better UX for resuming conversations The endpoint supports: - Filtering by creation date, access date, and working directory - Pagination with limit/offset - Sorting by various criteria - Optional capability for agents with session persistence Includes detailed JSON-RPC request/response examples and addresses common questions about alternatives, interaction with session/load, and pagination strategies. * docs(rfd): use _meta for session info metadata Replace metadata with _meta in docs/rfds/sessions-list-api.mdx Update JSON response example and response field list Keep prose references to “metadata” unchanged * docs(rfd): refactor session/list API design Major changes to sessions-list-api.mdx: - Switch from offset-based to cursor-based pagination using continuation tokens - Rename `lastAccessedAt` to `updatedAt` for consistency across the API - Remove `preview` field from SessionInfo (out of scope for this RFD) - Remove session orphaning from problem statement - Replace `sortBy`/`sortOrder` parameters with `search` parameter - Remove `total` count from response (incompatible with cursor pagination) - Update all request/response examples to reflect new pagination model - Clarify response includes `hasMore` and `nextContinuationToken` instead of `total` * Add usernamess and format the document --------- Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
1 parent 0629798 commit 4c333a5

File tree

2 files changed

+348
-1
lines changed

2 files changed

+348
-1
lines changed

‎docs/docs.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@
8888
"tab": "RFDs",
8989
"pages": [
9090
"rfds/about",
91-
{ "group": "Draft", "pages": [] },
91+
{ "group": "Draft", "pages": ["rfds/sessions-list-api"] },
9292
{ "group": "Preview", "pages": [] },
9393
{ "group": "Accepted", "pages": ["rfds/introduce-rfd-process"] },
9494
{ "group": "Completed", "pages": [] }

‎docs/rfds/sessions-list-api.mdx‎

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
---
2+
title: "Session List API"
3+
---
4+
5+
Author(s): [@ahmedhesham6](https://github.com/ahmedhesham6)
6+
Champion: [@benbrandt](https://github.com/benbrandt)
7+
8+
## Elevator pitch
9+
10+
Add a `session/list` endpoint to the ACP protocol that allows clients to query and enumerate existing sessions from an agent, enabling session management features like session history, session switching, and session cleanup.
11+
12+
## Status quo
13+
14+
Currently, the ACP protocol provides session management through `session/new` and `session/load` endpoints. However, there is no way for clients to:
15+
16+
1. **Discover existing sessions** - Clients cannot query what sessions exist on an agent
17+
2. **Display session history** - Users cannot see a list of their past conversations
18+
3. **Manage multiple sessions** - Switching between sessions requires clients to track session IDs themselves
19+
4. **Clean up old sessions** - No way to discover stale or abandoned sessions for cleanup
20+
21+
This creates several problems:
22+
23+
- **Poor user experience** - Users cannot browse their conversation history or resume previous sessions easily
24+
- **Client-side complexity** - Each client must implement its own session tracking and persistence
25+
- **Inconsistent behavior** - Different clients handle session management differently, leading to fragmented experiences
26+
27+
The current workaround is for clients to maintain their own session registry, but this:
28+
29+
- Requires persistent storage on the client side
30+
- Can get out of sync if sessions are created/destroyed outside the client
31+
- Doesn't work across different client instances or devices
32+
- Cannot leverage agent-side session metadata or state
33+
34+
## What we propose to do about it
35+
36+
Add a new `session/list` JSON-RPC method to the protocol that returns metadata about sessions known to the agent. This endpoint would:
37+
38+
1. **Return a list of sessions** with essential metadata:
39+
- `sessionId` - Unique identifier
40+
- `createdAt` - Timestamp when session was created
41+
- `updatedAt` - Timestamp of last update to the session
42+
- `cwd` - Working directory for the session
43+
- `title` - Optional human-readable title (could be auto-generated from first prompt)
44+
- `_meta` - Optional agent-specific metadata
45+
46+
2. **Support filtering and pagination**:
47+
- Filter by creation date, last accessed date, or working directory
48+
- Limit the number of results returned
49+
- Search by title or agent-provided metadata
50+
51+
3. **Be an optional capability**:
52+
- Agents advertise `listSessions: true` in initialization if they support this feature
53+
- Clients check for this capability before attempting to call `session/list`
54+
- Agents without persistent session storage don't need to implement this
55+
56+
### JSON-RPC Request
57+
58+
The client calls `session/list` with optional filtering and pagination parameters:
59+
60+
```json
61+
{
62+
"jsonrpc": "2.0",
63+
"id": 2,
64+
"method": "session/list",
65+
"params": {
66+
"cwd": "/home/user/project",
67+
"createdAfter": "2025-10-20T00:00:00Z",
68+
"limit": 20,
69+
"continuationToken": "offset:20",
70+
"search": "auth"
71+
}
72+
}
73+
```
74+
75+
#### Request Parameters
76+
77+
All parameters are optional:
78+
79+
- `cwd` (string) - Filter sessions by working directory
80+
- `createdAfter` (string) - ISO 8601 timestamp, only return sessions created after this time
81+
- `createdBefore` (string) - ISO 8601 timestamp, only return sessions created before this time
82+
- `updatedAfter` (string) - ISO 8601 timestamp, only return sessions updated after this time
83+
- `limit` (number) - Maximum number of results to return (default: 50, max: 1000)
84+
- `continuationToken` (string) - Opaque/stringified token from a previous response for cursor-based pagination
85+
- `search` (string) - Free-text search across titles or agent metadata
86+
87+
#### Minimal Request Example
88+
89+
A request with no filters returns all sessions with default sorting:
90+
91+
```json
92+
{
93+
"jsonrpc": "2.0",
94+
"id": 2,
95+
"method": "session/list",
96+
"params": {}
97+
}
98+
```
99+
100+
### JSON-RPC Response
101+
102+
The agent responds with a list of sessions and cursor pagination metadata:
103+
104+
```json
105+
{
106+
"jsonrpc": "2.0",
107+
"id": 2,
108+
"result": {
109+
"sessions": [
110+
{
111+
"sessionId": "sess_abc123def456",
112+
"createdAt": "2025-10-29T10:30:00Z",
113+
"updatedAt": "2025-10-29T14:22:15Z",
114+
"cwd": "/home/user/project",
115+
"title": "Implement session list API",
116+
"_meta": {
117+
"messageCount": 12,
118+
"hasErrors": false
119+
}
120+
},
121+
{
122+
"sessionId": "sess_xyz789ghi012",
123+
"createdAt": "2025-10-28T09:15:00Z",
124+
"updatedAt": "2025-10-28T16:45:30Z",
125+
"cwd": "/home/user/another-project",
126+
"title": "Debug authentication flow"
127+
},
128+
{
129+
"sessionId": "sess_uvw345rst678",
130+
"createdAt": "2025-10-27T14:00:00Z",
131+
"updatedAt": "2025-10-27T15:30:00Z",
132+
"cwd": "/home/user/project"
133+
}
134+
],
135+
"hasMore": true,
136+
"nextContinuationToken": "offset:40"
137+
}
138+
}
139+
```
140+
141+
#### Response Fields
142+
143+
**Response object:**
144+
145+
- `sessions` (array) - Array of session information objects
146+
- `hasMore` (boolean) - Whether more results are available after this page
147+
- `nextContinuationToken` (string, optional) - Pass this token in the next request's `continuationToken` to fetch the next page
148+
149+
**SessionInfo object:**
150+
151+
- `sessionId` (string, required) - Unique identifier for the session
152+
- `createdAt` (string, required) - ISO 8601 timestamp when session was created
153+
- `updatedAt` (string, required) - ISO 8601 timestamp of last activity
154+
- `cwd` (string, required) - Working directory for the session
155+
- `title` (string, optional) - Human-readable title (may be auto-generated from first prompt)
156+
- `_meta` (object, optional) - Agent-specific metadata (e.g., message count, error status, tags)
157+
158+
#### Empty Result Example
159+
160+
When no sessions match the criteria:
161+
162+
```json
163+
{
164+
"jsonrpc": "2.0",
165+
"id": 2,
166+
"result": {
167+
"sessions": [],
168+
"hasMore": false
169+
}
170+
}
171+
```
172+
173+
## Shiny future
174+
175+
Once this feature exists:
176+
177+
1. **Clients can build session browsers** - Users can view a list of all their conversations, sorted by recency or relevance
178+
2. **Session switching becomes seamless** - Users can easily switch between ongoing conversations
179+
3. **Better resource management** - Clients can identify and clean up old or inactive sessions
180+
4. **Cross-device continuity** - Users could potentially access their sessions from different devices (if agent supports it)
181+
5. **Improved UX patterns**:
182+
- "Recent conversations" sidebar
183+
- Search through past sessions
184+
- Archive/delete old sessions
185+
- Resume interrupted work easily
186+
187+
Agents that implement this feature gain:
188+
189+
- Better visibility into active sessions
190+
- Opportunity to implement session lifecycle policies
191+
- Foundation for future features like session sharing or collaboration
192+
193+
## Implementation details and plan
194+
195+
### Phase 1: Core Protocol Changes
196+
197+
1. **Update schema.json** to add:
198+
- `session/list` method definition
199+
- `ListSessionsRequest` and `ListSessionsResponse` types
200+
- `SessionInfo` type
201+
- `listSessions` capability flag
202+
203+
2. **Update protocol documentation** in `/docs/protocol/session-setup.mdx`:
204+
- Document the new endpoint
205+
- Explain when to use it vs. maintaining client-side session tracking
206+
- Provide examples of common use cases
207+
208+
### Phase 2: Reference Implementation
209+
210+
3. **Implement in Rust SDK** (`rust/agent.rs` and `rust/client.rs`):
211+
- Add `list_sessions` method to agent trait
212+
- Provide default implementation (empty list) for agents without persistence
213+
- Add client method to call `session/list`
214+
215+
4. **Add to TypeScript SDKs** (if applicable):
216+
- Update TypeScript types
217+
- Add client methods
218+
219+
### Phase 3: Example Implementation
220+
221+
5. **Create example agent** that demonstrates:
222+
- In-memory session registry
223+
- Automatic title generation from first prompt
224+
- Session lifecycle management (cleanup after N days)
225+
- Pagination and filtering
226+
227+
### Compatibility Considerations
228+
229+
- **Backward compatible**: Existing agents continue working without implementing this
230+
- **Capability-based**: Clients check for `listSessions` capability before using
231+
- **No breaking changes**: No modifications to existing endpoints
232+
233+
### Security Considerations
234+
235+
- **Session isolation**: Agents must ensure sessions are only listed for the authenticated client
236+
- **Resource limits**: Agents should enforce reasonable limits on pagination to prevent abuse
237+
238+
## Frequently asked questions
239+
240+
### What alternative approaches did you consider, and why did you settle on this one?
241+
242+
Several alternatives were considered:
243+
244+
1. **Client-side session tracking only** - This is the current approach, but it has limitations:
245+
- Doesn't work across devices
246+
- Can get out of sync
247+
- Adds complexity to every client implementation
248+
249+
2. **Session events/notifications** - Push notifications when sessions are created/destroyed:
250+
- More complex to implement
251+
- Requires long-lived connections
252+
- Still requires client-side state management
253+
- Better suited as a future enhancement, not a replacement
254+
255+
3. **File-based session manifest** - Agent writes session list to a file that clients read:
256+
- Couples agent and client file system access
257+
- Doesn't work for remote agents
258+
- No standard format
259+
260+
The proposed RPC approach is:
261+
262+
- **Consistent with existing protocol design** - Uses same RPC patterns as other endpoints
263+
- **Flexible** - Supports filtering, pagination, and agent-specific metadata
264+
- **Optional** - Agents can opt-in based on their architecture
265+
- **Simple** - Single request/response pattern, easy to implement and use
266+
267+
### Why not make this mandatory for all agents?
268+
269+
Many agents may not have persistent storage or multi-session capabilities. Making this optional:
270+
271+
- Allows simple, stateless agents to remain compliant
272+
- Reduces implementation burden
273+
- Lets agents evolve session management over time
274+
275+
### How does this interact with `session/load`?
276+
277+
`session/load` remains the mechanism to actually restore a session. `session/list` is for discovery only:
278+
279+
1. Client calls `session/list` to get available sessions
280+
2. User selects a session
281+
3. Client calls `session/load` with the chosen `sessionId`
282+
283+
Agents may support `session/list` without supporting `session/load` (e.g., for read-only session browsing).
284+
285+
### Should we include session content in the list response?
286+
287+
No, for several reasons:
288+
289+
- **Performance** - Full conversation history could be large
290+
- **Privacy** - Listing sessions might be less sensitive than exposing full content
291+
- **Separation of concerns** - Use `session/load` to get full session content
292+
293+
### What about session deletion?
294+
295+
Session deletion is intentionally left out of this RFD to keep scope focused. A future `session/delete` endpoint could be proposed separately. For now, agents can implement their own lifecycle policies.
296+
297+
### How should pagination work for large session lists?
298+
299+
We use cursor-based pagination with an opaque continuation token:
300+
301+
- Request includes `limit` and optional `continuationToken`
302+
- Response includes `hasMore` and `nextContinuationToken` when more data is available
303+
- Clients should not assume anything about the token's contents; treat it as opaque
304+
- The token MUST be a string; never send a raw JSON object as the token
305+
306+
Good request example:
307+
308+
```json
309+
{
310+
"jsonrpc": "2.0",
311+
"id": 2,
312+
"method": "session/list",
313+
"params": {
314+
"cwd": "/home/user/project",
315+
"createdAfter": "2025-10-20T00:00:00Z",
316+
"limit": 20,
317+
"continuationToken": "offset:0",
318+
"search": "auth"
319+
}
320+
}
321+
```
322+
323+
Corresponding response example:
324+
325+
```json
326+
{
327+
"jsonrpc": "2.0",
328+
"id": 2,
329+
"result": {
330+
"sessions": [
331+
/* ... */
332+
],
333+
"hasMore": true,
334+
"nextContinuationToken": "offset:20"
335+
}
336+
}
337+
```
338+
339+
## Revision history
340+
341+
- **2025-10-29**: Initial draft proposal
342+
- **2025-10-30**: Update to use `_meta` field for agent-specific metadata
343+
- **2025-10-30**: Switch from offset-based to cursor-based pagination using continuation tokens
344+
- **2025-10-30**: Rename `lastAccessedAt` to `updatedAt` for consistency
345+
- **2025-10-30**: Remove `preview` field from SessionInfo (out of scope)
346+
- **2025-10-30**: Remove session orphaning from problem statement
347+
- **2025-10-30**: Replace `sortBy`/`sortOrder` with `search` parameter; remove `total` count from response

0 commit comments

Comments
 (0)