-
Notifications
You must be signed in to change notification settings - Fork 125
docs(rfd): Session Config Options to Preview stage #378
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
benbrandt
wants to merge
1
commit into
main
Choose a base branch
from
session-config-docs
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+283
−2
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,281 @@ | ||
| --- | ||
| title: "Session Config Options" | ||
| description: "Flexible configuration selectors for agent sessions" | ||
| --- | ||
|
|
||
| Agents can provide an arbitrary list of configuration options for a session, allowing Clients to offer users customizable selectors for things like models, modes, reasoning levels, and more. | ||
|
|
||
| <Info> | ||
| Session Config Options are the preferred way to expose session-level | ||
| configuration. If an Agent provides `configOptions`, Clients **SHOULD** use | ||
| them instead of the deprecated [`modes`](../session-modes) field. | ||
| </Info> | ||
|
|
||
| ## Initial State | ||
|
|
||
| During [Session Setup](../session-setup) the Agent **MAY** return a list of configuration options and their current values: | ||
|
|
||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "id": 1, | ||
| "result": { | ||
| "sessionId": "sess_abc123def456", | ||
| "configOptions": [ | ||
| { | ||
| "id": "mode", | ||
| "name": "Session Mode", | ||
| "description": "Controls how the agent requests permission", | ||
| "category": "mode", | ||
| "type": "select", | ||
| "currentValue": "ask", | ||
| "options": [ | ||
| { | ||
| "value": "ask", | ||
| "name": "Ask", | ||
| "description": "Request permission before making any changes" | ||
| }, | ||
| { | ||
| "value": "code", | ||
| "name": "Code", | ||
| "description": "Write and modify code with full tool access" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "id": "model", | ||
| "name": "Model", | ||
| "category": "model", | ||
| "type": "select", | ||
| "currentValue": "model-1", | ||
| "options": [ | ||
| { | ||
| "value": "model-1", | ||
| "name": "Model 1", | ||
| "description": "The fastest model" | ||
| }, | ||
| { | ||
| "value": "model-2", | ||
| "name": "Model 2", | ||
| "description": "The most powerful model" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| <ResponseField name="configOptions" type="ConfigOption[]"> | ||
| The list of configuration options available for this session. The order of | ||
| this array represents the Agent's preferred priority. Clients **SHOULD** | ||
| respect this ordering when displaying options. | ||
| </ResponseField> | ||
|
|
||
| ### ConfigOption | ||
|
|
||
| <ResponseField name="id" type="string" required> | ||
| Unique identifier for this configuration option. Used when setting values. | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="name" type="string" required> | ||
| Human-readable label for the option | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="description" type="string"> | ||
| Optional description providing more details about what this option controls | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="category" type="ConfigOptionCategory"> | ||
| Optional [semantic category](#option-categories) to help Clients provide | ||
| consistent UX | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="type" type="ConfigOptionType" required> | ||
| The type of input control. Currently only `select` is supported. | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="currentValue" type="string" required> | ||
| The currently selected value for this option | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="options" type="ConfigOptionValue[]" required> | ||
| The available values for this option | ||
| </ResponseField> | ||
|
|
||
| ### ConfigOptionValue | ||
|
|
||
| <ResponseField name="value" type="string" required> | ||
| The value identifier used when setting this option | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="name" type="string" required> | ||
| Human-readable name to display | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="description" type="string"> | ||
| Optional description of what this value does | ||
| </ResponseField> | ||
|
|
||
| ## Option Categories | ||
|
|
||
| Each config option **MAY** include a `category` field. Categories are semantic metadata intended to help Clients provide consistent UX, such as attaching keyboard shortcuts, choosing icons, or deciding placement. | ||
|
|
||
| <Warning> | ||
| Categories are for UX purposes only and **MUST NOT** be required for | ||
| correctness. Clients **MUST** handle missing or unknown categories gracefully | ||
| by treating them as `other`. | ||
| </Warning> | ||
|
|
||
| | Category | Description | | ||
| | --------------- | ------------------------------------------- | | ||
| | `mode` | Session mode selector | | ||
| | `model` | Model selector | | ||
| | `thought_level` | Thought/reasoning level selector | | ||
| | `other` | Unknown or uncategorized selector (default) | | ||
|
|
||
| When multiple options share the same category, Clients **SHOULD** use the array ordering to resolve ties, preferring earlier options in the list for prominent placement or keyboard shortcuts. | ||
|
|
||
| ## Option Ordering | ||
|
|
||
| The order of the `configOptions` array is significant. Agents **SHOULD** place higher-priority options first in the list. | ||
|
|
||
| Clients **SHOULD**: | ||
|
|
||
| - Display options in the order provided by the Agent | ||
| - Use ordering to resolve ties when multiple options share the same category | ||
| - If displaying a limited number of options, prefer those at the beginning of the list | ||
|
|
||
| ## Default Values and Graceful Degradation | ||
|
|
||
| Agents **MUST** always provide a default value for every configuration option. This ensures the Agent can operate correctly even if: | ||
|
|
||
| - The Client doesn't support configuration options | ||
| - The Client chooses not to display certain options | ||
| - The Client receives an option type it doesn't recognize | ||
|
|
||
| If a Client receives an option with an unrecognized `type`, it **SHOULD** ignore that option. The Agent will continue using its default value. | ||
|
|
||
| ## Setting a Config Option | ||
|
|
||
| The current value of a config option can be changed at any point during a session, whether the Agent is idle or generating a response. | ||
|
|
||
| ### From the Client | ||
|
|
||
| Clients can change a config option value by calling the `session/set_config_option` method: | ||
|
|
||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "id": 2, | ||
| "method": "session/set_config_option", | ||
| "params": { | ||
| "sessionId": "sess_abc123def456", | ||
| "configId": "mode", | ||
| "value": "code" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| <ParamField path="sessionId" type="SessionId" required> | ||
| The ID of the session | ||
| </ParamField> | ||
|
|
||
| <ParamField path="configId" type="string" required> | ||
| The `id` of the configuration option to change | ||
| </ParamField> | ||
|
|
||
| <ParamField path="value" type="string" required> | ||
| The new value to set. Must be one of the values listed in the option's | ||
| `options` array. | ||
| </ParamField> | ||
|
|
||
| The Agent **MUST** respond with the complete list of all configuration options and their current values: | ||
|
|
||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "id": 2, | ||
| "result": { | ||
| "configOptions": [ | ||
| { | ||
| "id": "mode", | ||
| "name": "Session Mode", | ||
| "type": "select", | ||
| "currentValue": "code", | ||
| "options": [...] | ||
| }, | ||
| { | ||
| "id": "model", | ||
| "name": "Model", | ||
| "type": "select", | ||
| "currentValue": "model-1", | ||
| "options": [...] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| <Note> | ||
| The response always contains the **complete** configuration state. This allows | ||
| Agents to reflect dependent changes. For example, if changing the model | ||
| affects available reasoning options, or if an option's available values change | ||
| based on another selection. | ||
| </Note> | ||
|
|
||
| ### From the Agent | ||
|
|
||
| The Agent can also change configuration options and notify the Client by sending a `config_options_update` session notification: | ||
|
|
||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "method": "session/update", | ||
| "params": { | ||
| "sessionId": "sess_abc123def456", | ||
| "update": { | ||
| "sessionUpdate": "config_options_update", | ||
| "configOptions": [ | ||
| { | ||
| "id": "mode", | ||
| "name": "Session Mode", | ||
| "type": "select", | ||
| "currentValue": "code", | ||
| "options": [...] | ||
| }, | ||
| { | ||
| "id": "model", | ||
| "name": "Model", | ||
| "type": "select", | ||
| "currentValue": "model-2", | ||
| "options": [...] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| This notification also contains the complete configuration state. Common reasons an Agent might update configuration options include: | ||
|
|
||
| - Switching modes after completing a planning phase | ||
| - Falling back to a different model due to rate limits or errors | ||
| - Adjusting available options based on context discovered during execution | ||
|
|
||
| ## Relationship to Session Modes | ||
|
|
||
| Session Config Options supersede the older [Session Modes](../session-modes) API. However, during the transition period, Agents that provide mode-like configuration **SHOULD** send both: | ||
|
|
||
| - `configOptions` with a `category: "mode"` option for Clients that support config options | ||
| - `modes` for Clients that only support the older API | ||
|
|
||
| If an Agent provides both `configOptions` and `modes` in the session response: | ||
|
|
||
| - Clients that support config options **SHOULD** use `configOptions` exclusively and ignore `modes` | ||
| - Clients that don't support config options **SHOULD** fall back to `modes` | ||
| - Agents **SHOULD** keep both in sync to ensure consistent behavior regardless of which field the Client uses | ||
|
|
||
| <Card icon="toggle-on" horizontal href="../session-modes"> | ||
| Learn about the deprecated Session Modes API | ||
| </Card> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Q: Can clients add other categories? Should we require that if clients opt for a "custom" category, it begins with
_for extensibility purposes?Q: Can there be multiple categories? (presumably not)
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point. I do think this other could just be a string, with maybe some convention around _ or something