Skip to content

Commit 3cc4e29

Browse files
benbrandtbenbrandt
authored
feat(schema): Stabilize session usage updates (#1371)
1 parent 701f217 commit 3cc4e29

18 files changed

Lines changed: 453 additions & 92 deletions

‎Cargo.toml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ unstable = [
2828
"unstable_nes",
2929
"unstable_plan_operations",
3030
"unstable_session_fork",
31-
"unstable_session_usage",
3231
"unstable_end_turn_token_usage",
3332
"unstable_message_id",
3433
"unstable_boolean_config",
@@ -46,7 +45,6 @@ unstable_mcp_over_acp = []
4645
unstable_nes = []
4746
unstable_plan_operations = []
4847
unstable_session_fork = []
49-
unstable_session_usage = []
5048
unstable_end_turn_token_usage = []
5149
unstable_message_id = []
5250
unstable_boolean_config = []

‎docs/docs.json‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -209,18 +209,15 @@
209209
},
210210
{
211211
"group": "Preview",
212-
"pages": [
213-
"rfds/rust-sdk-v1",
214-
"rfds/session-usage",
215-
"rfds/message-id"
216-
]
212+
"pages": ["rfds/rust-sdk-v1", "rfds/message-id"]
217213
},
218214
{
219215
"group": "Completed",
220216
"pages": [
221217
"rfds/introduce-rfd-process",
222218
"rfds/session-config-options",
223219
"rfds/session-list",
220+
"rfds/session-usage",
224221
"rfds/session-delete",
225222
"rfds/session-info-update",
226223
"rfds/meta-propagation",

‎docs/protocol/v1/draft/prompt-turn.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,31 @@ If the model requested tool calls, these are also reported immediately:
185185
}
186186
```
187187

188+
#### Session Usage Updates
189+
190+
The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`:
191+
192+
```json
193+
{
194+
"jsonrpc": "2.0",
195+
"method": "session/update",
196+
"params": {
197+
"sessionId": "sess_abc123def456",
198+
"update": {
199+
"sessionUpdate": "usage_update",
200+
"used": 53000,
201+
"size": 200000,
202+
"cost": {
203+
"amount": 0.045,
204+
"currency": "USD"
205+
}
206+
}
207+
}
208+
}
209+
```
210+
211+
`used` and `size` are required and non-null token counts for the current session context. `cost` is optional and, if present, `amount` and `currency` are required. `currency` is an ISO 4217 currency code like `"USD"`.
212+
188213
### 4. Check for Completion
189214

190215
If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`:

‎docs/protocol/v1/draft/schema.mdx‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3514,10 +3514,6 @@ A change in `messageId` indicates a new message has started.
35143514

35153515
## <span class="font-mono">Cost</span>
35163516

3517-
**UNSTABLE**
3518-
3519-
This capability is not part of the spec yet, and may be removed or changed at any point.
3520-
35213517
Cost information for a session.
35223518

35233519
**Type:** Object
@@ -7502,10 +7498,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d
75027498
</ResponseField>
75037499

75047500
<ResponseField name="usage_update" type="object">
7505-
**UNSTABLE**
7506-
7507-
This capability is not part of the spec yet, and may be removed or changed at any point.
7508-
75097501
Context window and cost update for the session.
75107502

75117503
<Expandable title="Properties">
@@ -8193,10 +8185,6 @@ Token usage information for a prompt turn.
81938185

81948186
## <span class="font-mono">UsageUpdate</span>
81958187

8196-
**UNSTABLE**
8197-
8198-
This capability is not part of the spec yet, and may be removed or changed at any point.
8199-
82008188
Context window and cost update for a session.
82018189

82028190
**Type:** Object

‎docs/protocol/v1/prompt-turn.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,31 @@ If the model requested tool calls, these are also reported immediately:
182182
}
183183
```
184184

185+
#### Session Usage Updates
186+
187+
The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`:
188+
189+
```json
190+
{
191+
"jsonrpc": "2.0",
192+
"method": "session/update",
193+
"params": {
194+
"sessionId": "sess_abc123def456",
195+
"update": {
196+
"sessionUpdate": "usage_update",
197+
"used": 53000,
198+
"size": 200000,
199+
"cost": {
200+
"amount": 0.045,
201+
"currency": "USD"
202+
}
203+
}
204+
}
205+
}
206+
```
207+
208+
`used` and `size` are required and non-null token counts for the current session context. `cost` is optional and, if present, `amount` and `currency` are required. `currency` is an ISO 4217 currency code like `"USD"`.
209+
185210
### 4. Check for Completion
186211

187212
If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`:

‎docs/protocol/v1/schema.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1908,6 +1908,21 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
19081908
A single item of content
19091909
</ResponseField>
19101910

1911+
## <span class="font-mono">Cost</span>
1912+
1913+
Cost information for a session.
1914+
1915+
**Type:** Object
1916+
1917+
**Properties:**
1918+
1919+
<ResponseField name="amount" type={"number"} required>
1920+
Total cumulative cost for session.
1921+
</ResponseField>
1922+
<ResponseField name="currency" type={"string"} required>
1923+
ISO 4217 currency code (e.g., "USD", "EUR").
1924+
</ResponseField>
1925+
19111926
## <span class="font-mono">CurrentModeUpdate</span>
19121927

19131928
The current mode of the session has changed
@@ -3589,6 +3604,41 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
35893604
</Expandable>
35903605
</ResponseField>
35913606

3607+
<ResponseField name="usage_update" type="object">
3608+
Context window and cost update for the session.
3609+
3610+
<Expandable title="Properties">
3611+
3612+
<ResponseField name="_meta" type={"object | null"} >
3613+
The _meta property is reserved by ACP to allow clients and agents to attach additional
3614+
metadata to their interactions. Implementations MUST NOT make assumptions about values at
3615+
these keys.
3616+
3617+
See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3618+
3619+
</ResponseField>
3620+
<ResponseField name="cost" type={<><span><a href="#cost">Cost</a></span><span> | null</span></>} >
3621+
Cumulative session cost (optional).
3622+
</ResponseField>
3623+
<ResponseField name="sessionUpdate" type={"string"} required>
3624+
The discriminator value. Must be `"usage_update"`.
3625+
</ResponseField>
3626+
<ResponseField name="size" type={"uint64"} required>
3627+
Total context window size in tokens.
3628+
3629+
- Minimum: `0`
3630+
3631+
</ResponseField>
3632+
<ResponseField name="used" type={"uint64"} required>
3633+
Tokens currently in context.
3634+
3635+
- Minimum: `0`
3636+
3637+
</ResponseField>
3638+
3639+
</Expandable>
3640+
</ResponseField>
3641+
35923642
## <span class="font-mono">StopReason</span>
35933643

35943644
Reasons why an agent stops processing a prompt turn.
@@ -4036,3 +4086,35 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
40364086
<ResponseField name="hint" type={"string"} required>
40374087
A hint to display when the input hasn't been provided yet
40384088
</ResponseField>
4089+
4090+
## <span class="font-mono">UsageUpdate</span>
4091+
4092+
Context window and cost update for a session.
4093+
4094+
**Type:** Object
4095+
4096+
**Properties:**
4097+
4098+
<ResponseField name="_meta" type={"object | null"} >
4099+
The _meta property is reserved by ACP to allow clients and agents to attach additional
4100+
metadata to their interactions. Implementations MUST NOT make assumptions about values at
4101+
these keys.
4102+
4103+
See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4104+
4105+
</ResponseField>
4106+
<ResponseField name="cost" type={<><span><a href="#cost">Cost</a></span><span> | null</span></>} >
4107+
Cumulative session cost (optional).
4108+
</ResponseField>
4109+
<ResponseField name="size" type={"uint64"} required>
4110+
Total context window size in tokens.
4111+
4112+
- Minimum: `0`
4113+
4114+
</ResponseField>
4115+
<ResponseField name="used" type={"uint64"} required>
4116+
Tokens currently in context.
4117+
4118+
- Minimum: `0`
4119+
4120+
</ResponseField>

‎docs/protocol/v2/draft/prompt-turn.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,31 @@ If the model requested tool calls, these are also reported immediately:
189189
}
190190
```
191191

192+
#### Session Usage Updates
193+
194+
The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`:
195+
196+
```json
197+
{
198+
"jsonrpc": "2.0",
199+
"method": "session/update",
200+
"params": {
201+
"sessionId": "sess_abc123def456",
202+
"update": {
203+
"sessionUpdate": "usage_update",
204+
"used": 53000,
205+
"size": 200000,
206+
"cost": {
207+
"amount": 0.045,
208+
"currency": "USD"
209+
}
210+
}
211+
}
212+
}
213+
```
214+
215+
`used` and `size` are required and non-null token counts for the current session context. `cost` is optional and, if present, `amount` and `currency` are required. `currency` is an ISO 4217 currency code like `"USD"`.
216+
192217
### 4. Check for Completion
193218

194219
If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`:

‎docs/protocol/v2/draft/schema.mdx‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3065,10 +3065,6 @@ A change in `messageId` indicates a new message has started.
30653065

30663066
## <span class="font-mono">Cost</span>
30673067

3068-
**UNSTABLE**
3069-
3070-
This capability is not part of the spec yet, and may be removed or changed at any point.
3071-
30723068
Cost information for a session.
30733069

30743070
**Type:** Object
@@ -7088,10 +7084,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
70887084
</ResponseField>
70897085

70907086
<ResponseField name="usage_update" type="object">
7091-
**UNSTABLE**
7092-
7093-
This capability is not part of the spec yet, and may be removed or changed at any point.
7094-
70957087
Context window and cost update for the session.
70967088

70977089
<Expandable title="Properties">
@@ -7812,10 +7804,6 @@ Token usage information for a prompt turn.
78127804

78137805
## <span class="font-mono">UsageUpdate</span>
78147806

7815-
**UNSTABLE**
7816-
7817-
This capability is not part of the spec yet, and may be removed or changed at any point.
7818-
78197807
Context window and cost update for a session.
78207808

78217809
**Type:** Object

‎docs/protocol/v2/prompt-turn.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,31 @@ If the model requested tool calls, these are also reported immediately:
186186
}
187187
```
188188

189+
#### Session Usage Updates
190+
191+
The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`:
192+
193+
```json
194+
{
195+
"jsonrpc": "2.0",
196+
"method": "session/update",
197+
"params": {
198+
"sessionId": "sess_abc123def456",
199+
"update": {
200+
"sessionUpdate": "usage_update",
201+
"used": 53000,
202+
"size": 200000,
203+
"cost": {
204+
"amount": 0.045,
205+
"currency": "USD"
206+
}
207+
}
208+
}
209+
}
210+
```
211+
212+
`used` and `size` are required and non-null token counts for the current session context. `cost` is optional and, if present, `amount` and `currency` are required. `currency` is an ISO 4217 currency code like `"USD"`.
213+
189214
### 4. Check for Completion
190215

191216
If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`:

0 commit comments

Comments
 (0)