Skip to content

Commit 75169d4

Browse files
benbrandtSteffenDE
benbrandt
and
SteffenDE
authored
feat(unstable): Add unstable support for session usage (#454)
* implement session usage RFD * npm run format * revert package.lock changes * Add unstable information to doc comments --------- Co-authored-by: Steffen Deusch <steffen@deusch.me>
1 parent 3e579d3 commit 75169d4

6 files changed

Lines changed: 450 additions & 1 deletion

File tree

‎Cargo.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ unstable = [
2222
"unstable_session_list",
2323
"unstable_session_model",
2424
"unstable_session_resume",
25+
"unstable_session_usage",
2526
]
2627
unstable_cancel_request = []
2728
unstable_session_config_options = []
@@ -30,6 +31,7 @@ unstable_session_info_update = []
3031
unstable_session_list = []
3132
unstable_session_model = []
3233
unstable_session_resume = []
34+
unstable_session_usage = []
3335

3436
[[bin]]
3537
name = "generate"

‎docs/protocol/draft/schema.mdx‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -612,6 +612,14 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
612612
<ResponseField name="stopReason" type={<a href="#stopreason">StopReason</a>} required>
613613
Indicates why the agent stopped processing the turn.
614614
</ResponseField>
615+
<ResponseField name="usage" type={<><span><a href="#usage">Usage</a></span><span> | null</span></>} >
616+
**UNSTABLE**
617+
618+
This capability is not part of the spec yet, and may be removed or changed at any point.
619+
620+
Token usage for this turn (optional).
621+
622+
</ResponseField>
615623

616624
<a id="session-resume"></a>
617625
### <span class="font-mono">session/resume</span>
@@ -1955,6 +1963,25 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
19551963
A single item of content
19561964
</ResponseField>
19571965

1966+
## <span class="font-mono">Cost</span>
1967+
1968+
**UNSTABLE**
1969+
1970+
This capability is not part of the spec yet, and may be removed or changed at any point.
1971+
1972+
Cost information for a session.
1973+
1974+
**Type:** Object
1975+
1976+
**Properties:**
1977+
1978+
<ResponseField name="amount" type={"number"} required>
1979+
Total cumulative cost for session.
1980+
</ResponseField>
1981+
<ResponseField name="currency" type={"string"} required>
1982+
ISO 4217 currency code (e.g., "USD", "EUR").
1983+
</ResponseField>
1984+
19581985
## <span class="font-mono">CurrentModeUpdate</span>
19591986

19601987
The current mode of the session has changed
@@ -3687,6 +3714,44 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
36873714
</Expandable>
36883715
</ResponseField>
36893716

3717+
<ResponseField name="usage_update" type="object">
3718+
**UNSTABLE**
3719+
3720+
This capability is not part of the spec yet, and may be removed or changed at any point.
3721+
3722+
Context window and cost update for the session.
3723+
3724+
<Expandable title="Properties">
3725+
3726+
<ResponseField name="_meta" type={"object | null"} >
3727+
The _meta property is reserved by ACP to allow clients and agents to attach additional
3728+
metadata to their interactions. Implementations MUST NOT make assumptions about values at
3729+
these keys.
3730+
3731+
See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
3732+
3733+
</ResponseField>
3734+
<ResponseField name="cost" type={<><span><a href="#cost">Cost</a></span><span> | null</span></>} >
3735+
Cumulative session cost (optional).
3736+
</ResponseField>
3737+
<ResponseField name="sessionUpdate" type={"string"} required>
3738+
</ResponseField>
3739+
<ResponseField name="size" type={"uint64"} required>
3740+
Total context window size in tokens.
3741+
3742+
- Minimum: `0`
3743+
3744+
</ResponseField>
3745+
<ResponseField name="used" type={"uint64"} required>
3746+
Tokens currently in context.
3747+
3748+
- Minimum: `0`
3749+
3750+
</ResponseField>
3751+
3752+
</Expandable>
3753+
</ResponseField>
3754+
36903755
## <span class="font-mono">StopReason</span>
36913756

36923757
Reasons why an agent stops processing a prompt turn.
@@ -4131,3 +4196,88 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
41314196
<ResponseField name="hint" type={"string"} required>
41324197
A hint to display when the input hasn't been provided yet
41334198
</ResponseField>
4199+
4200+
## <span class="font-mono">Usage</span>
4201+
4202+
**UNSTABLE**
4203+
4204+
This capability is not part of the spec yet, and may be removed or changed at any point.
4205+
4206+
Token usage information for a prompt turn.
4207+
4208+
**Type:** Object
4209+
4210+
**Properties:**
4211+
4212+
<ResponseField name="cachedReadTokens" type={"integer | null"} >
4213+
Total cache read tokens.
4214+
4215+
- Minimum: `0`
4216+
4217+
</ResponseField>
4218+
<ResponseField name="cachedWriteTokens" type={"integer | null"} >
4219+
Total cache write tokens.
4220+
4221+
- Minimum: `0`
4222+
4223+
</ResponseField>
4224+
<ResponseField name="inputTokens" type={"uint64"} required>
4225+
Total input tokens across all turns.
4226+
4227+
- Minimum: `0`
4228+
4229+
</ResponseField>
4230+
<ResponseField name="outputTokens" type={"uint64"} required>
4231+
Total output tokens across all turns.
4232+
4233+
- Minimum: `0`
4234+
4235+
</ResponseField>
4236+
<ResponseField name="thoughtTokens" type={"integer | null"} >
4237+
Total thought/reasoning tokens
4238+
4239+
- Minimum: `0`
4240+
4241+
</ResponseField>
4242+
<ResponseField name="totalTokens" type={"uint64"} required>
4243+
Sum of all token types across session.
4244+
4245+
- Minimum: `0`
4246+
4247+
</ResponseField>
4248+
4249+
## <span class="font-mono">UsageUpdate</span>
4250+
4251+
**UNSTABLE**
4252+
4253+
This capability is not part of the spec yet, and may be removed or changed at any point.
4254+
4255+
Context window and cost update for a session.
4256+
4257+
**Type:** Object
4258+
4259+
**Properties:**
4260+
4261+
<ResponseField name="_meta" type={"object | null"} >
4262+
The _meta property is reserved by ACP to allow clients and agents to attach additional
4263+
metadata to their interactions. Implementations MUST NOT make assumptions about values at
4264+
these keys.
4265+
4266+
See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
4267+
4268+
</ResponseField>
4269+
<ResponseField name="cost" type={<><span><a href="#cost">Cost</a></span><span> | null</span></>} >
4270+
Cumulative session cost (optional).
4271+
</ResponseField>
4272+
<ResponseField name="size" type={"uint64"} required>
4273+
Total context window size in tokens.
4274+
4275+
- Minimum: `0`
4276+
4277+
</ResponseField>
4278+
<ResponseField name="used" type={"uint64"} required>
4279+
Tokens currently in context.
4280+
4281+
- Minimum: `0`
4282+
4283+
</ResponseField>

‎docs/rfds/session-usage.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ Add a `usage` field to `PromptResponse` for token consumption tracking:
9292
- `total_tokens` (number, required) - Sum of all token types across session
9393
- `input_tokens` (number, required) - Total input tokens across all turns
9494
- `output_tokens` (number, required) - Total output tokens across all turns
95-
- `thought_tokens` (number, optional) - Total thought/reasoning tokens (for o1/o3 models)
95+
- `thought_tokens` (number, optional) - Total thought/reasoning tokens
9696
- `cached_read_tokens` (number, optional) - Total cache read tokens
9797
- `cached_write_tokens` (number, optional) - Total cache write tokens
9898

‎schema/schema.unstable.json‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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": {
@@ -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"],
@@ -3191,6 +3218,22 @@
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
},
@@ -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": {

0 commit comments

Comments
 (0)