Skip to content

Commit 2f40371

Browse files
benbrandtbenbrandt
authored
RFD Draft: Session Config Options (#210)
* RFD Draft: Session Config Options Proposing the ability to add Agent provided configuration options to a session. This makes the current pattern used by session modes more flexible, rather than adding additional hard-coded selectors to the protocol. * Clarify return types * add one more question * Address PR feedback * Remove extra word
1 parent ecea849 commit 2f40371

File tree

4 files changed

+250
-1
lines changed

4 files changed

+250
-1
lines changed

‎docs/docs.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,10 @@
8888
"tab": "RFDs",
8989
"pages": [
9090
"rfds/about",
91-
{ "group": "Draft", "pages": ["rfds/session-list"] },
91+
{
92+
"group": "Draft",
93+
"pages": ["rfds/session-list", "rfds/session-config-options"]
94+
},
9295
{ "group": "Preview", "pages": [] },
9396
{ "group": "Accepted", "pages": ["rfds/introduce-rfd-process"] },
9497
{ "group": "Completed", "pages": [] }

‎docs/rfds/TEMPLATE.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ Instructions:
1414

1515
-->
1616

17+
Author(s): [githubhandle](url)
18+
1719
## Elevator pitch
1820

1921
> What are you proposing to change?

‎docs/rfds/introduce-rfd-process.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
title: "Introduce RFD Process"
33
---
44

5+
Author(s): [@benbrandt](https://github.com/benbrandt)
6+
57
## Elevator pitch
68

79
> What are you proposing to change? Bullet points welcome.

‎docs/rfds/session-config-options.mdx‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
title: "Session Config Options"
3+
---
4+
5+
Author(s): [@benbrandt](https://github.com/benbrandt)
6+
7+
## Elevator pitch
8+
9+
> What are you proposing to change?
10+
11+
Allow Agents to provide an arbitrary list of configuration selectors for a given session. Rather than only supporting modes or models, we can allow each Agent to more flexibly specify which configurations to allow the Client to offer the user.
12+
13+
## Status quo
14+
15+
> How do things work today and what problems does this cause? Why would we change things?
16+
17+
Currently, we allow Agents to [specify a list of modes](https://agentclientprotocol.com/protocol/session-modes) they can run in. The state of the currently selected item is allowed to be modified by both the [Client](https://agentclientprotocol.com/protocol/session-modes#from-the-client) and the [Agent](https://agentclientprotocol.com/protocol/session-modes#from-the-agent).
18+
19+
The obvious next selector was a [model selector](https://github.com/agentclientprotocol/agent-client-protocol/pull/182). However, when implementing this, it became clear that even for our current agents, it is not just as simple as "which model do you want?", but also which variant of a given model in terms of thinking parameters that might be better to express as yet another selector.
20+
21+
Adding more hard-coded selector options would potentially lead the protocol to need to support many optional ones, or implementors would need to try to find the best existing selector to hack an option into if there wasn't an obvious fit. And if, a few months from now, no agents support something like a mode or reasoning selector, the protocol is left with leftover methods no one really uses, cluttering the interface.
22+
23+
Since this space is moving fast, we ideally would find a more flexible option with enough constraints to allow Clients and Agents to both reason about the options provided.
24+
25+
## What we propose to do about it
26+
27+
> What are you proposing to improve the situation?
28+
29+
Instead, we can allow Agents to provide configuration options in the `session/new` response that not only provide a list of options, but also a `key` of some kind that is a unique identifier for that selector.
30+
31+
When the Client receives or sends an update to this selector, it would require both the selector key and the key for the new value.
32+
33+
To start, we could continue offering single-value selectors (dropdowns), but allow for the Agent to decide what those are for.
34+
35+
## Shiny future
36+
37+
> How will things will play out once this feature exists?
38+
39+
The Agent provides a list of available configuration options. The Agent cannot rely on the Client to set or even display these options, as it may not support it. So an Agent MUST always have a default configuration value for every option it provides, and MUST be able to run a turn without these configuration options being set.
40+
41+
The Client can render the options provided, send updated values to the Agent, and also display any changes the Agent made during the course of it's execution (for example, if it changes modes or models because of fallbacks or a change in strategy, so that the user can always see the current state).
42+
43+
Since we are moving to a world in which there are multiple configuration options, some of which may depend on each other, the Agent MUST provide the complete set of configuration options and their current values whenever a change is made. We would tradeoff some extra data being sent to the Client in order to help minimize the amount of state required to be managed by the Client. The Client would submit a new value, and receive back the full state of all configuration options that it can then replace it's current state with and render. So if changing a model means there are no thinking options, or a new option becomes available, or another value needs to change because the values of an option are different, the Agent will reflect this in its response by providing the entire new state (or an error if it is somehow an invalid selection).
44+
45+
## Implementation details and plan
46+
47+
> Tell me more about your implementation. What is your detailed implementation plan?
48+
49+
To start, we can implement this based on the [Session Modes](https://agentclientprotocol.com/protocol/session-modes) api.
50+
51+
Something like an `InitializeResponse` that looks like:
52+
53+
```json
54+
{
55+
"jsonrpc": "2.0",
56+
"id": 1,
57+
"result": {
58+
"sessionId": "sess_abc123def456",
59+
"configOptions": [
60+
{
61+
"id": "mode", // this is the unique `key` for communication about which option is being used
62+
"name": "Session Mode", // Human-readable label for the option
63+
"description": "Optional description for the Client to display to the user."
64+
"type": "select",
65+
"currentValue": "ask",
66+
"options": [
67+
{
68+
"value": "ask",
69+
"name": "Ask",
70+
"description": "Request permission before making any changes"
71+
},
72+
{
73+
"value": "code",
74+
"name": "Code",
75+
"description": "Write and modify code with full tool access"
76+
}
77+
]
78+
},
79+
{
80+
"id": "models",
81+
"name": "Model",
82+
"type": "select",
83+
"currentValue": "ask",
84+
"options": [
85+
{
86+
"value": "model-1",
87+
"name": "Model 1",
88+
"description": "The fastest model"
89+
},
90+
{
91+
"value": "model-2",
92+
"name": "Model 2",
93+
"description": "The most powerful model"
94+
}
95+
]
96+
}
97+
]
98+
}
99+
}
100+
```
101+
102+
When we introduce this, we could also allow for grouped options, in case there are logical sub-headers and groupings for the options in an individual selector.
103+
104+
```json
105+
{
106+
"id": "models",
107+
"name": "Model",
108+
"currentValue": "ask",
109+
"type": "select",
110+
"options": [
111+
{
112+
"group": "Provider A",
113+
"options": [
114+
{
115+
"value": "model-1",
116+
"name": "Model 1",
117+
"description": "The fastest model"
118+
}
119+
]
120+
},
121+
{
122+
"group": "Provider B",
123+
"options": [
124+
{
125+
"value": "model-2",
126+
"name": "Model 2",
127+
"description": "The most powerful model"
128+
}
129+
]
130+
}
131+
]
132+
}
133+
```
134+
135+
We use a list of objects for all of these, to ensure consistent ordering of both the config options and the possible values across languages that may or may not preserve ordering.
136+
137+
For grouping options, it needs to be explored whether or not grouped and ungrouped options can be interspersed, or if we need to restrict to one mode or the other (likely the latter).
138+
139+
For updating the value from the client and agent, it would follow the same pattern as [session modes](https://agentclientprotocol.com/protocol/session-modes#from-the-client) but have an additional key.
140+
141+
```json
142+
{
143+
"jsonrpc": "2.0",
144+
"id": 2,
145+
"method": "session/set_config_option",
146+
"params": {
147+
"sessionId": "sess_abc123def456",
148+
"configId": "mode",
149+
"value": "code"
150+
}
151+
}
152+
```
153+
154+
And the response to this request would return the full list of config options with current values.
155+
156+
```json
157+
{
158+
"jsonrpc": "2.0",
159+
"id": 2,
160+
"result": {
161+
"configOptions": [
162+
{
163+
"id": "mode",
164+
"name": "Session Mode",
165+
"type": "select",
166+
"currentValue": "ask",
167+
"options": [..]
168+
},
169+
{
170+
"id": "models",
171+
"name": "Model",
172+
"type": "select",
173+
"currentValue": "ask",
174+
"options": [..]
175+
}
176+
]
177+
}
178+
}
179+
```
180+
181+
The notification would return the full list of config options with current values as well.
182+
183+
```json
184+
{
185+
"jsonrpc": "2.0",
186+
"method": "session/update",
187+
"params": {
188+
"sessionId": "sess_abc123def456",
189+
"update": {
190+
"sessionUpdate": "config_option_update",
191+
"configOptions": [
192+
{
193+
"id": "mode",
194+
"name": "Session Mode",
195+
"type": "select",
196+
"currentValue": "ask",
197+
"options": [..]
198+
},
199+
{
200+
"id": "models",
201+
"name": "Model",
202+
"type": "select",
203+
"currentValue": "ask",
204+
"options": [..]
205+
}
206+
]
207+
}
208+
}
209+
}
210+
```
211+
212+
We would also likely move session modes to be `@deprecated` in favor of this approach. Until it is removed, we may want Agents to support both fields, and then the Client, if it uses the new config options, should only use the config options supplied and not the `modes` field to avoid duplication.
213+
214+
The config options would also take a `type` field to specify different forms of input for the Client to display. If a client receives an option it doesn't recognize, it should ignore it. Since the Agent is required to have a default value, it can gracefully degrade and ignore the option and the Agent should handle it regardless. The Client should also treat the list of options as prioritized by the Agent. So, if for some reason the Agent provides more options than the Client can reasonably display, the Client should show as many as possible, starting at the beginning of the list.
215+
216+
We will start with just supporting `select` for now, and expand to other types as needed.
217+
218+
## Frequently asked questions
219+
220+
> What questions have arisen over the course of authoring this document or during subsequent discussions?
221+
222+
### What alternative approaches did you consider, and why did you settle on this one?
223+
224+
As noted, the Zed team already looked into and implemented experimental support for a model selector.
225+
226+
However, this has already diverged from how the Codex CLI is modeling their model selector as of last week, so it seems reasonable to, as per a core design principle of the protocol, only limit the Agent implementations where necessary for the Client to render a faithful UX. Maximizing flexibility for the Agent as they iterate on the best way to model new paradigms seems key here, and it is unclear whether the Client benefits from knowing which type of selector this is.
227+
228+
We originally discussed internally having a design closer to this proposal, however walked it back thinking it would be helpful for the Client to know what was being selected. However, as we've now dealt with multiple Agent implementations, it is unclear if this has actually helped the Client, and allowing for more flexibility seems desirable.
229+
230+
### What about connection-level configuration options?
231+
232+
This RFD is only concerned with session-level configuration, for which it seems reasonable to require that the Agent can select a default value at all times and not require input from the client before continuing.
233+
234+
There seems to be another type of configuration option that is needed when first setting up an Agent (i.e. provider options, plugins, etc.) that are more persistent and may be required by an Agent prior to being able to create a session. These would need to be tackled somewhere closer to the initialization phase, or elsewhere and are out of scope for this RFD.
235+
236+
### What about multi-value selectors? or checkboxes? Or _insert favorite input option here_?
237+
238+
This is a question we should discuss of how much complexity we want to introduce for the first version, and how we want to express this to via Client capabilities to allow for more option types in the future.
239+
240+
## Revision history
241+
242+
- 2025-10-29: Initial draft

0 commit comments

Comments
 (0)