Skip to content

Commit 415d821

Browse files
ignatovbenbrandt
ignatov
and
benbrandt
authored
docs(rfd): Draft: Session info update notification (#288)
* Add RFD for session info update notification - Adds session_info_update variant to SessionUpdate - Enables real-time session metadata updates (title, _meta) - Follows existing notification pattern (available_commands_update, current_mode_update) - All fields optional for partial updates - Must stay aligned with SessionInfo structure * add to website --------- Co-authored-by: Sergey Ignatov <[email protected]> Co-authored-by: Ben Brandt <[email protected]>
1 parent 13d18e0 commit 415d821

File tree

3 files changed

+380
-1
lines changed

3 files changed

+380
-1
lines changed

‎docs/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,8 @@
9797
"rfds/session-fork",
9898
"rfds/request-cancellation",
9999
"rfds/session-resume",
100-
"rfds/meta-propagation"
100+
"rfds/meta-propagation",
101+
"rfds/session-info-update"
101102
]
102103
},
103104
{ "group": "Preview", "pages": [] },

‎docs/rfds/session-info-update.mdx‎

Lines changed: 371 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,371 @@
1+
---
2+
title: "Session Info Update"
3+
---
4+
5+
- Author(s): [@ignatov](https://github.com/ignatov)
6+
7+
## Elevator pitch
8+
9+
Add a `session_info_update` variant to the existing `SessionUpdate` notification type that allows agents to update session metadata (particularly title/name), enabling dynamic session identification in client UIs without requiring a new endpoint.
10+
11+
## Status quo
12+
13+
Currently, the ACP protocol provides session management through `session/new`, `session/load`, and `session/list` (unstable). The `session/list` endpoint returns `SessionInfo` objects that include an optional `title` field for displaying session names in client UIs.
14+
15+
However, there are several problems:
16+
17+
1. **No way to communicate title updates** - The `title` field in `SessionInfo` is static in the list response. Agents cannot dynamically update it as the session evolves.
18+
19+
2. **No mechanism for real-time metadata updates** - Unlike commands (`available_commands_update`) or modes (`current_mode_update`), there's no way for agents to:
20+
- Auto-generate titles after the first meaningful exchange
21+
- Update titles as conversation context shifts
22+
- Provide custom metadata that reflects session state
23+
24+
3. **Inconsistent with protocol patterns** - Other dynamic session properties use `session/update` notifications (commands, modes, plans), but metadata has no equivalent mechanism.
25+
26+
The current workaround is for clients to:
27+
28+
- Maintain their own title mapping (doesn't persist or sync)
29+
- Only show static metadata from `session/list`
30+
- Have no way to receive agent-generated titles in real-time
31+
32+
## What we propose to do about it
33+
34+
Add a new `session_info_update` variant to the existing `SessionUpdate` discriminated union that allows agents to notify clients about metadata changes. This update would:
35+
36+
1. **Follow the existing `SessionUpdate` pattern**:
37+
- Uses the same notification mechanism as `available_commands_update`, `current_mode_update`, etc.
38+
- Sent via `session/update` method
39+
- Agent-initiated, no request/response needed
40+
41+
2. **Align with `SessionInfo` structure**:
42+
- Contains the same fields as `SessionInfo` from `session/list`
43+
- All fields are optional (partial updates)
44+
- Enables incremental metadata updates
45+
- **Important**: `SessionInfoUpdate` must stay aligned with `SessionInfo` - when new fields are added to `SessionInfo`, they should also be added to `SessionInfoUpdate` as optional fields
46+
47+
3. **Support common use cases**:
48+
- Agent auto-generates title after first prompt
49+
- Agent updates title as conversation context shifts
50+
- Agent provides custom metadata for client features (tags, status, etc.)
51+
- User explicitly requests title change (agent responds with update notification)
52+
53+
4. **Integrate seamlessly**:
54+
- No new capability required (uses existing `session/update` mechanism)
55+
- Compatible with `session/list` - metadata should persist and be reflected in list responses
56+
- Works during active sessions
57+
58+
### Notification Structure
59+
60+
The agent sends a `session/update` notification with `sessionUpdate: "session_info_update"`:
61+
62+
```json
63+
{
64+
"jsonrpc": "2.0",
65+
"method": "session/update",
66+
"params": {
67+
"sessionId": "sess_abc123def456",
68+
"update": {
69+
"sessionUpdate": "session_info_update",
70+
"title": "Implement user authentication",
71+
"_meta": {
72+
"tags": ["feature", "auth"],
73+
"priority": "high"
74+
}
75+
}
76+
}
77+
}
78+
```
79+
80+
### SessionInfoUpdate Type
81+
82+
The update type mirrors `SessionInfo` but with all fields optional:
83+
84+
```typescript
85+
{
86+
sessionUpdate: "session_info_update",
87+
title?: string | null, // Update or clear the title
88+
updatedAt?: string | null, // ISO 8601 timestamp (usually agent sets this)
89+
_meta?: object | null // Custom metadata (merged with existing)
90+
}
91+
```
92+
93+
**Note:** `sessionId` and `cwd` are NOT included since:
94+
95+
- `sessionId` is already in the notification's `params`
96+
- `cwd` is immutable and set during `session/new`
97+
98+
### Examples
99+
100+
#### Update title and working directory metadata
101+
102+
After the user sends their first meaningful prompt, the agent can generate and send a title along with metadata about the working directory:
103+
104+
```json
105+
{
106+
"jsonrpc": "2.0",
107+
"method": "session/update",
108+
"params": {
109+
"sessionId": "sess_abc123def456",
110+
"update": {
111+
"sessionUpdate": "session_info_update",
112+
"title": "Debug authentication timeout",
113+
"_meta": {
114+
"projectName": "api-server",
115+
"branch": "main"
116+
}
117+
}
118+
}
119+
}
120+
```
121+
122+
#### Update title as conversation evolves
123+
124+
As the conversation shifts focus:
125+
126+
```json
127+
{
128+
"jsonrpc": "2.0",
129+
"method": "session/update",
130+
"params": {
131+
"sessionId": "sess_abc123def456",
132+
"update": {
133+
"sessionUpdate": "session_info_update",
134+
"title": "Debug authentication timeout → Add retry logic"
135+
}
136+
}
137+
}
138+
```
139+
140+
## Shiny future
141+
142+
Once this feature exists:
143+
144+
1. **Dynamic session identification** - Agents can:
145+
- Auto-generate meaningful titles from conversation content
146+
- Update titles as conversations evolve
147+
- Provide rich metadata for better organization
148+
149+
2. **Improved client UIs** - Clients can:
150+
- Show real-time title updates in session lists
151+
- Display session status, tags, or other metadata
152+
- Update UI immediately without polling `session/list`
153+
154+
3. **Consistent protocol patterns** - Session metadata updates work like other dynamic session properties (commands, modes), creating a unified model
155+
156+
4. **Bidirectional workflows** - Combined with a potential future request method:
157+
- User renames session → client sends request → agent acknowledges with `session_info_update` notification
158+
- Agent auto-generates title → sends `session_info_update` notification → client displays it
159+
160+
5. **Enhanced use cases**:
161+
- Session templates that auto-set titles and tags
162+
- Progress indicators via `_meta`
163+
- Integration with external tools via metadata
164+
- Rich session browsing and filtering
165+
166+
## Implementation details and plan
167+
168+
### Phase 1: Schema Changes
169+
170+
1. **Update `schema.unstable.json`**:
171+
- Add `SessionInfoUpdate` type definition
172+
- Add new variant to `SessionUpdate` oneOf array
173+
- Align fields with `SessionInfo` but make all optional
174+
175+
```json
176+
{
177+
"SessionInfoUpdate": {
178+
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUpdate to session metadata. All fields are optional to support partial updates.",
179+
"properties": {
180+
"_meta": {
181+
"description": "Extension point for implementations"
182+
},
183+
"title": {
184+
"description": "Human-readable title for the session",
185+
"type": ["string", "null"]
186+
},
187+
"updatedAt": {
188+
"description": "ISO 8601 timestamp of last activity",
189+
"type": ["string", "null"]
190+
}
191+
},
192+
"type": "object"
193+
}
194+
}
195+
```
196+
197+
Add to `SessionUpdate` oneOf:
198+
199+
```json
200+
{
201+
"allOf": [
202+
{
203+
"$ref": "#/$defs/SessionInfoUpdate"
204+
}
205+
],
206+
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUpdate to session metadata",
207+
"properties": {
208+
"sessionUpdate": {
209+
"const": "session_info_update",
210+
"type": "string"
211+
}
212+
},
213+
"required": ["sessionUpdate"],
214+
"type": "object"
215+
}
216+
```
217+
218+
### Phase 2: Protocol Documentation
219+
220+
2. **Create documentation** in `/docs/protocol/session-metadata.mdx`:
221+
- Explain the notification mechanism
222+
- Provide examples of common patterns
223+
- Document merge semantics for `_meta`
224+
- Clarify relationship with `session/list`
225+
226+
3. **Update existing docs**:
227+
- Reference in `/docs/protocol/session-setup.mdx`
228+
- Add to `/docs/protocol/prompt-turn.mdx` session update section
229+
230+
### Phase 3: SDK Implementation
231+
232+
4. **Implement in Rust SDK**:
233+
- Add `SessionInfoUpdate` struct
234+
- Add variant to `SessionUpdate` enum
235+
- Update notification handling in agent and client traits
236+
- Add helper methods for common patterns
237+
238+
5. **Implement in TypeScript SDK** (if applicable):
239+
- Add TypeScript types
240+
- Update notification handlers
241+
- Add helper methods
242+
243+
### Phase 4: Example Implementation
244+
245+
6. **Update example agents**:
246+
- Demonstrate auto-generating title from first prompt
247+
- Show updating metadata during session
248+
- Example of using `_meta` for custom fields
249+
250+
### Compatibility Considerations
251+
252+
- **Fully backward compatible**: This adds a new notification variant to an existing mechanism
253+
- **No breaking changes**: Existing agents and clients continue working
254+
- **Graceful degradation**: Clients that don't handle this notification simply ignore it
255+
- **No new capability needed**: Uses existing `session/update` infrastructure
256+
257+
### Design Decisions
258+
259+
**Why notification instead of request/response?**
260+
261+
- Consistent with existing `SessionUpdate` patterns (`available_commands_update`, `current_mode_update`)
262+
- Agents initiate updates based on conversation state
263+
- Simpler than bidirectional request/response
264+
- Enables real-time updates without polling
265+
266+
**Why make all fields optional?**
267+
268+
- Allows partial updates (only update what changed)
269+
- More efficient - don't resend unchanged data
270+
- Flexible for different use cases
271+
- Mirrors partial update patterns in other protocols
272+
273+
**Why not include `sessionId` and `cwd` in the update?**
274+
275+
- `sessionId` is already in the notification params
276+
- `cwd` is immutable (set in `session/new`, never changes)
277+
- Keeps update focused on mutable metadata
278+
279+
**How do `_meta` updates work?**
280+
281+
- **Merge semantics**: New `_meta` fields are merged with existing ones
282+
- To clear a specific field: `"_meta": { "fieldName": null }`
283+
- To clear all custom metadata: `"_meta": null`
284+
285+
### Security Considerations
286+
287+
- **No additional security concerns**: Uses existing session authentication
288+
- **Input validation**:
289+
- Agents should validate title length (recommend 500 chars max)
290+
- Sanitize metadata to prevent injection
291+
- Validate `_meta` structure based on agent requirements
292+
- **Resource limits**: Agents should limit update frequency and metadata size
293+
294+
## Frequently asked questions
295+
296+
### Why not create a new endpoint like `session/update-metadata`?
297+
298+
The notification pattern is more appropriate because:
299+
300+
1. **Consistency**: Other dynamic session properties (commands, modes) use notifications
301+
2. **Agent-initiated**: Agents typically generate titles from conversation context
302+
3. **Real-time**: No request/response overhead, updates flow naturally
303+
4. **Simpler**: Reuses existing `session/update` infrastructure
304+
305+
### How does this work with `session/list`?
306+
307+
The updated metadata should persist and be reflected in subsequent `session/list` calls. The notification provides real-time updates to connected clients, while `session/list` provides the current state for discovery.
308+
309+
### Can clients trigger title updates?
310+
311+
This RFD covers agent-initiated updates. Client-initiated updates could work by:
312+
313+
1. Client sends a prompt asking to rename session
314+
2. Agent updates its internal state
315+
3. Agent sends `session_info_update` notification
316+
4. Client receives and displays the update
317+
318+
A future RFD could add explicit request/response for this if needed.
319+
320+
### What if multiple updates are sent in quick succession?
321+
322+
Clients should apply updates incrementally in order. Each notification represents a delta, not a full replacement (except for fields explicitly set to `null`).
323+
324+
### Should `updatedAt` be automatically set by the agent?
325+
326+
Yes, typically the agent should update this timestamp when any session activity occurs, not just when metadata changes. However, including it in `session_info_update` allows agents to explicitly control it if needed.
327+
328+
### Do agents need a new capability for this?
329+
330+
No. All agents that support `session/update` notifications can send this variant. Clients that don't recognize it will ignore it (standard JSON-RPC behavior).
331+
332+
### How does this interact with `session/fork`?
333+
334+
When forking, the parent session's metadata could be copied (implementation choice). The forked session would have its own `sessionId` and could receive separate `session_info_update` notifications.
335+
336+
### What happens if title is too long?
337+
338+
This is an implementation choice. Agents MAY:
339+
340+
- Truncate long titles
341+
- Reject updates (though this is a notification, so no error response)
342+
- Set a reasonable limit (e.g., 500 characters)
343+
344+
Clients SHOULD handle long titles gracefully (truncate in UI, show tooltip, etc.).
345+
346+
### Can `_meta` have nested objects?
347+
348+
Yes, `_meta` is an arbitrary object. Agents define its structure. The merge semantics apply recursively - nested objects are merged, not replaced entirely.
349+
350+
### What alternative approaches did you consider, and why did you settle on this one?
351+
352+
Several alternatives were considered:
353+
354+
1. **Add a new request/response endpoint (`session/update-metadata`)** - This would be inconsistent with how other dynamic session properties (commands, modes) are handled. The notification pattern is more appropriate for agent-initiated updates.
355+
356+
2. **Add title parameter to `session/new`** - Only allows setting title at creation time, doesn't support dynamic updates as the conversation evolves.
357+
358+
3. **Client-side only metadata tracking** - Doesn't work across devices, can get out of sync, and duplicates storage. This is the current workaround and has significant limitations.
359+
360+
4. **Generic `session/update` request for all properties** - Could conflict with immutable properties (sessionId, cwd) and has unclear semantics about what can be updated.
361+
362+
The proposed notification-based approach:
363+
364+
- **Consistent** with existing protocol patterns
365+
- **Flexible** for both agent-initiated and user-initiated updates
366+
- **Simple** to implement and understand
367+
- **Extensible** via `_meta` field
368+
369+
## Revision history
370+
371+
- **2025-11-28**: Initial draft proposal

‎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="December 3, 2025" tags={["RFD"]}>
8+
## session_info_update notification RFD moves to Draft stage
9+
10+
The RFD for adding a new `session_info_update` variant on the `session/update` notification in the protocol has been moved to Draft stage. Please review the [RFD](./rfds/session-info-update) for more information on the current proposal and provide feedback as work on the implementation begins.
11+
12+
</Update>
13+
714
<Update label="December 3, 2025" tags={["RFD"]}>
815
## _meta Propagation RFD moves to Draft stage
916

0 commit comments

Comments
 (0)