Skip to content

Commit 15806a2

Browse files
benbrandtbenbrandt
authored
feat: Stabilize Session Config Options (#64)
updates the schema to 0.10.8 Also adds unstable support for session usage
1 parent 51bb194 commit 15806a2

File tree

6 files changed

+378
-225
lines changed

6 files changed

+378
-225
lines changed

‎schema/schema.json‎

Lines changed: 139 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -718,7 +718,7 @@
718718
"$ref": "#/$defs/SetSessionConfigOptionRequest"
719719
}
720720
],
721-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSets the current value for a session configuration option.",
721+
"description": "Sets the current value for a session configuration option.",
722722
"title": "SetSessionConfigOptionRequest"
723723
},
724724
{
@@ -867,7 +867,7 @@
867867
"x-docs-ignore": true
868868
},
869869
"ConfigOptionUpdate": {
870-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSession configuration options have been updated.",
870+
"description": "Session configuration options have been updated.",
871871
"properties": {
872872
"_meta": {
873873
"additionalProperties": true,
@@ -1013,6 +1013,22 @@
10131013
"required": ["content"],
10141014
"type": "object"
10151015
},
1016+
"Cost": {
1017+
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCost information for a session.",
1018+
"properties": {
1019+
"amount": {
1020+
"description": "Total cumulative cost for session.",
1021+
"format": "double",
1022+
"type": "number"
1023+
},
1024+
"currency": {
1025+
"description": "ISO 4217 currency code (e.g., \"USD\", \"EUR\").",
1026+
"type": "string"
1027+
}
1028+
},
1029+
"required": ["amount", "currency"],
1030+
"type": "object"
1031+
},
10161032
"CreateTerminalRequest": {
10171033
"description": "Request to create a new terminal and execute a command.",
10181034
"properties": {
@@ -1352,7 +1368,7 @@
13521368
"type": ["object", "null"]
13531369
},
13541370
"configOptions": {
1355-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial session configuration options if supported by the Agent.",
1371+
"description": "Initial session configuration options if supported by the Agent.",
13561372
"items": {
13571373
"$ref": "#/$defs/SessionConfigOption"
13581374
},
@@ -1706,7 +1722,7 @@
17061722
"type": ["object", "null"]
17071723
},
17081724
"configOptions": {
1709-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial session configuration options if supported by the Agent.",
1725+
"description": "Initial session configuration options if supported by the Agent.",
17101726
"items": {
17111727
"$ref": "#/$defs/SessionConfigOption"
17121728
},
@@ -1960,7 +1976,7 @@
19601976
"type": ["object", "null"]
19611977
},
19621978
"configOptions": {
1963-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial session configuration options if supported by the Agent.",
1979+
"description": "Initial session configuration options if supported by the Agent.",
19641980
"items": {
19651981
"$ref": "#/$defs/SessionConfigOption"
19661982
},
@@ -2224,6 +2240,17 @@
22242240
}
22252241
],
22262242
"description": "Indicates why the agent stopped processing the turn."
2243+
},
2244+
"usage": {
2245+
"anyOf": [
2246+
{
2247+
"$ref": "#/$defs/Usage"
2248+
},
2249+
{
2250+
"type": "null"
2251+
}
2252+
],
2253+
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage for this turn (optional)."
22272254
}
22282255
},
22292256
"required": ["stopReason"],
@@ -2527,7 +2554,7 @@
25272554
"type": ["object", "null"]
25282555
},
25292556
"configOptions": {
2530-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial session configuration options if supported by the Agent.",
2557+
"description": "Initial session configuration options if supported by the Agent.",
25312558
"items": {
25322559
"$ref": "#/$defs/SessionConfigOption"
25332560
},
@@ -2630,15 +2657,15 @@
26302657
"type": "object"
26312658
},
26322659
"SessionConfigGroupId": {
2633-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a session configuration option value group.",
2660+
"description": "Unique identifier for a session configuration option value group.",
26342661
"type": "string"
26352662
},
26362663
"SessionConfigId": {
2637-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a session configuration option.",
2664+
"description": "Unique identifier for a session configuration option.",
26382665
"type": "string"
26392666
},
26402667
"SessionConfigOption": {
2641-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session configuration option selector and its current state.",
2668+
"description": "A session configuration option selector and its current state.",
26422669
"discriminator": {
26432670
"propertyName": "type"
26442671
},
@@ -2720,10 +2747,10 @@
27202747
"type": "string"
27212748
}
27222749
],
2723-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSemantic category for a session configuration option.\n\nThis is intended to help Clients distinguish broadly common selectors (e.g. model selector vs\nsession mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,\nplacement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown\ncategories gracefully.\n\nCategory names beginning with `_` are free for custom use, like other ACP extension methods.\nCategory names that do not begin with `_` are reserved for the ACP spec."
2750+
"description": "Semantic category for a session configuration option.\n\nThis is intended to help Clients distinguish broadly common selectors (e.g. model selector vs\nsession mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,\nplacement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown\ncategories gracefully.\n\nCategory names beginning with `_` are free for custom use, like other ACP extension methods.\nCategory names that do not begin with `_` are reserved for the ACP spec."
27242751
},
27252752
"SessionConfigSelect": {
2726-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA single-value selector (dropdown) session configuration option payload.",
2753+
"description": "A single-value selector (dropdown) session configuration option payload.",
27272754
"properties": {
27282755
"currentValue": {
27292756
"allOf": [
@@ -2746,7 +2773,7 @@
27462773
"type": "object"
27472774
},
27482775
"SessionConfigSelectGroup": {
2749-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA group of possible values for a session configuration option.",
2776+
"description": "A group of possible values for a session configuration option.",
27502777
"properties": {
27512778
"_meta": {
27522779
"additionalProperties": true,
@@ -2777,7 +2804,7 @@
27772804
"type": "object"
27782805
},
27792806
"SessionConfigSelectOption": {
2780-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA possible value for a session configuration option.",
2807+
"description": "A possible value for a session configuration option.",
27812808
"properties": {
27822809
"_meta": {
27832810
"additionalProperties": true,
@@ -2823,10 +2850,10 @@
28232850
"type": "array"
28242851
}
28252852
],
2826-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nPossible values for a session configuration option."
2853+
"description": "Possible values for a session configuration option."
28272854
},
28282855
"SessionConfigValueId": {
2829-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a session configuration option value.",
2856+
"description": "Unique identifier for a session configuration option value.",
28302857
"type": "string"
28312858
},
28322859
"SessionForkCapabilities": {
@@ -3166,7 +3193,7 @@
31663193
"$ref": "#/$defs/ConfigOptionUpdate"
31673194
}
31683195
],
3169-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSession configuration options have been updated.",
3196+
"description": "Session configuration options have been updated.",
31703197
"properties": {
31713198
"sessionUpdate": {
31723199
"const": "config_option_update",
@@ -3191,11 +3218,27 @@
31913218
},
31923219
"required": ["sessionUpdate"],
31933220
"type": "object"
3221+
},
3222+
{
3223+
"allOf": [
3224+
{
3225+
"$ref": "#/$defs/UsageUpdate"
3226+
}
3227+
],
3228+
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for the session.",
3229+
"properties": {
3230+
"sessionUpdate": {
3231+
"const": "usage_update",
3232+
"type": "string"
3233+
}
3234+
},
3235+
"required": ["sessionUpdate"],
3236+
"type": "object"
31943237
}
31953238
]
31963239
},
31973240
"SetSessionConfigOptionRequest": {
3198-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for setting a session configuration option.",
3241+
"description": "Request parameters for setting a session configuration option.",
31993242
"properties": {
32003243
"_meta": {
32013244
"additionalProperties": true,
@@ -3233,7 +3276,7 @@
32333276
"x-side": "agent"
32343277
},
32353278
"SetSessionConfigOptionResponse": {
3236-
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `session/set_config_option` method.",
3279+
"description": "Response to `session/set_config_option` method.",
32373280
"properties": {
32383281
"_meta": {
32393282
"additionalProperties": true,
@@ -3813,6 +3856,84 @@
38133856
"required": ["hint"],
38143857
"type": "object"
38153858
},
3859+
"Usage": {
3860+
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage information for a prompt turn.",
3861+
"properties": {
3862+
"cachedReadTokens": {
3863+
"description": "Total cache read tokens.",
3864+
"format": "uint64",
3865+
"minimum": 0,
3866+
"type": ["integer", "null"]
3867+
},
3868+
"cachedWriteTokens": {
3869+
"description": "Total cache write tokens.",
3870+
"format": "uint64",
3871+
"minimum": 0,
3872+
"type": ["integer", "null"]
3873+
},
3874+
"inputTokens": {
3875+
"description": "Total input tokens across all turns.",
3876+
"format": "uint64",
3877+
"minimum": 0,
3878+
"type": "integer"
3879+
},
3880+
"outputTokens": {
3881+
"description": "Total output tokens across all turns.",
3882+
"format": "uint64",
3883+
"minimum": 0,
3884+
"type": "integer"
3885+
},
3886+
"thoughtTokens": {
3887+
"description": "Total thought/reasoning tokens",
3888+
"format": "uint64",
3889+
"minimum": 0,
3890+
"type": ["integer", "null"]
3891+
},
3892+
"totalTokens": {
3893+
"description": "Sum of all token types across session.",
3894+
"format": "uint64",
3895+
"minimum": 0,
3896+
"type": "integer"
3897+
}
3898+
},
3899+
"required": ["totalTokens", "inputTokens", "outputTokens"],
3900+
"type": "object"
3901+
},
3902+
"UsageUpdate": {
3903+
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for a session.",
3904+
"properties": {
3905+
"_meta": {
3906+
"additionalProperties": true,
3907+
"description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
3908+
"type": ["object", "null"]
3909+
},
3910+
"cost": {
3911+
"anyOf": [
3912+
{
3913+
"$ref": "#/$defs/Cost"
3914+
},
3915+
{
3916+
"type": "null"
3917+
}
3918+
],
3919+
"description": "Cumulative session cost (optional)."
3920+
},
3921+
"size": {
3922+
"description": "Total context window size in tokens.",
3923+
"format": "uint64",
3924+
"minimum": 0,
3925+
"type": "integer"
3926+
},
3927+
"used": {
3928+
"description": "Tokens currently in context.",
3929+
"format": "uint64",
3930+
"minimum": 0,
3931+
"type": "integer"
3932+
}
3933+
},
3934+
"required": ["used", "size"],
3935+
"type": "object"
3936+
},
38163937
"WaitForTerminalExitRequest": {
38173938
"description": "Request to wait for a terminal command to exit.",
38183939
"properties": {

‎scripts/generate.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import * as fs from "fs/promises";
55
import { dirname } from "path";
66
import * as prettier from "prettier";
77

8-
const CURRENT_SCHEMA_RELEASE = "v0.10.7";
8+
const CURRENT_SCHEMA_RELEASE = "v0.10.8";
99

1010
await main();
1111

‎src/acp.ts‎

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -112,12 +112,12 @@ export class AgentSideConnection {
112112
return result ?? {};
113113
}
114114
case schema.AGENT_METHODS.session_set_config_option: {
115-
if (!agent.unstable_setSessionConfigOption) {
115+
if (!agent.setSessionConfigOption) {
116116
throw RequestError.methodNotFound(method);
117117
}
118118
const validatedParams =
119119
validate.zSetSessionConfigOptionRequest.parse(params);
120-
return agent.unstable_setSessionConfigOption(validatedParams);
120+
return agent.setSessionConfigOption(validatedParams);
121121
}
122122
default:
123123
if (agent.extMethod) {
@@ -727,18 +727,12 @@ export class ClientSideConnection implements Agent {
727727
}
728728

729729
/**
730-
* **UNSTABLE**
731-
*
732-
* This capability is not part of the spec yet, and may be removed or changed at any point.
733-
*
734730
* Set a configuration option for a given session.
735731
*
736732
* The response contains the full set of configuration options and their current values,
737733
* as changing one option may affect the available values or state of other options.
738-
*
739-
* @experimental
740734
*/
741-
async unstable_setSessionConfigOption(
735+
async setSessionConfigOption(
742736
params: schema.SetSessionConfigOptionRequest,
743737
): Promise<schema.SetSessionConfigOptionResponse> {
744738
return await this.#connection.sendRequest(
@@ -1552,18 +1546,12 @@ export interface Agent {
15521546
params: schema.SetSessionModelRequest,
15531547
): Promise<schema.SetSessionModelResponse | void>;
15541548
/**
1555-
* **UNSTABLE**
1556-
*
1557-
* This capability is not part of the spec yet, and may be removed or changed at any point.
1558-
*
15591549
* Set a configuration option for a given session.
15601550
*
15611551
* The response contains the full set of configuration options and their current values,
15621552
* as changing one option may affect the available values or state of other options.
1563-
*
1564-
* @experimental
15651553
*/
1566-
unstable_setSessionConfigOption?(
1554+
setSessionConfigOption?(
15671555
params: schema.SetSessionConfigOptionRequest,
15681556
): Promise<schema.SetSessionConfigOptionResponse>;
15691557
/**

‎src/schema/index.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ export type {
2424
Content,
2525
ContentBlock,
2626
ContentChunk,
27+
Cost,
2728
CreateTerminalRequest,
2829
CreateTerminalResponse,
2930
CurrentModeUpdate,
@@ -126,6 +127,8 @@ export type {
126127
ToolCallUpdate,
127128
ToolKind,
128129
UnstructuredCommandInput,
130+
Usage,
131+
UsageUpdate,
129132
WaitForTerminalExitRequest,
130133
WaitForTerminalExitResponse,
131134
WriteTextFileRequest,

0 commit comments

Comments
 (0)