Skip to content

feat(schema): Stabilize session usage updates #1371

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.

Sign up for GitHub

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

Merged
benbrandt merged 1 commit into from
Jun 5, 2026
+453 −92
Merged

feat(schema): Stabilize session usage updates #1371

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@ unstable = [
"unstable_nes",
"unstable_plan_operations",
"unstable_session_fork",
"unstable_session_usage",
"unstable_end_turn_token_usage",
"unstable_message_id",
"unstable_boolean_config",
Expand All @@ -46,7 +45,6 @@ unstable_mcp_over_acp = []
unstable_nes = []
unstable_plan_operations = []
unstable_session_fork = []
unstable_session_usage = []
unstable_end_turn_token_usage = []
unstable_message_id = []
unstable_boolean_config = []
Expand Down
7 changes: 2 additions & 5 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,18 +209,15 @@
},
{
"group": "Preview",
"pages": [
"rfds/rust-sdk-v1",
"rfds/session-usage",
"rfds/message-id"
]
"pages": ["rfds/rust-sdk-v1", "rfds/message-id"]
},
{
"group": "Completed",
"pages": [
"rfds/introduce-rfd-process",
"rfds/session-config-options",
"rfds/session-list",
"rfds/session-usage",
"rfds/session-delete",
"rfds/session-info-update",
"rfds/meta-propagation",
Expand Down
25 changes: 25 additions & 0 deletions docs/protocol/v1/draft/prompt-turn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,31 @@ If the model requested tool calls, these are also reported immediately:
}
```

#### Session Usage Updates

The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`:

```json
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "usage_update",
"used": 53000,
"size": 200000,
"cost": {
"amount": 0.045,
"currency": "USD"
}
}
}
}
```

`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"`.

### 4. Check for Completion

If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`:
Expand Down
12 changes: 0 additions & 12 deletions docs/protocol/v1/draft/schema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3514,10 +3514,6 @@ A change in `messageId` indicates a new message has started.

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

**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Cost information for a session.

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

<ResponseField name="usage_update" type="object">
**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Context window and cost update for the session.

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

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

**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Context window and cost update for a session.

**Type:** Object
Expand Down
25 changes: 25 additions & 0 deletions docs/protocol/v1/prompt-turn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,31 @@ If the model requested tool calls, these are also reported immediately:
}
```

#### Session Usage Updates

The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`:

```json
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "usage_update",
"used": 53000,
"size": 200000,
"cost": {
"amount": 0.045,
"currency": "USD"
}
}
}
}
```

`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"`.

### 4. Check for Completion

If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`:
Expand Down
82 changes: 82 additions & 0 deletions docs/protocol/v1/schema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1908,6 +1908,21 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
A single item of content
</ResponseField>

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

Cost information for a session.

**Type:** Object

**Properties:**

<ResponseField name="amount" type={"number"} required>
Total cumulative cost for session.
</ResponseField>
<ResponseField name="currency" type={"string"} required>
ISO 4217 currency code (e.g., "USD", "EUR").
</ResponseField>

## <span class="font-mono">CurrentModeUpdate</span>

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

<ResponseField name="usage_update" type="object">
Context window and cost update for the session.

<Expandable title="Properties">

<ResponseField name="_meta" type={"object | null"} >
The _meta property is reserved by ACP to allow clients and agents to attach additional
metadata to their interactions. Implementations MUST NOT make assumptions about values at
these keys.

See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)

</ResponseField>
<ResponseField name="cost" type={<><span><a href="#cost">Cost</a></span><span> | null</span></>} >
Cumulative session cost (optional).
</ResponseField>
<ResponseField name="sessionUpdate" type={"string"} required>
The discriminator value. Must be `"usage_update"`.
</ResponseField>
<ResponseField name="size" type={"uint64"} required>
Total context window size in tokens.

- Minimum: `0`

</ResponseField>
<ResponseField name="used" type={"uint64"} required>
Tokens currently in context.

- Minimum: `0`

</ResponseField>

</Expandable>
</ResponseField>

## <span class="font-mono">StopReason</span>

Reasons why an agent stops processing a prompt turn.
Expand Down Expand Up @@ -4036,3 +4086,35 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
<ResponseField name="hint" type={"string"} required>
A hint to display when the input hasn't been provided yet
</ResponseField>

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

Context window and cost update for a session.

**Type:** Object

**Properties:**

<ResponseField name="_meta" type={"object | null"} >
The _meta property is reserved by ACP to allow clients and agents to attach additional
metadata to their interactions. Implementations MUST NOT make assumptions about values at
these keys.

See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)

</ResponseField>
<ResponseField name="cost" type={<><span><a href="#cost">Cost</a></span><span> | null</span></>} >
Cumulative session cost (optional).
</ResponseField>
<ResponseField name="size" type={"uint64"} required>
Total context window size in tokens.

- Minimum: `0`

</ResponseField>
<ResponseField name="used" type={"uint64"} required>
Tokens currently in context.

- Minimum: `0`

</ResponseField>
25 changes: 25 additions & 0 deletions docs/protocol/v2/draft/prompt-turn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,31 @@ If the model requested tool calls, these are also reported immediately:
}
```

#### Session Usage Updates

The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`:

```json
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "usage_update",
"used": 53000,
"size": 200000,
"cost": {
"amount": 0.045,
"currency": "USD"
}
}
}
}
```

`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"`.

### 4. Check for Completion

If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`:
Expand Down
12 changes: 0 additions & 12 deletions docs/protocol/v2/draft/schema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3065,10 +3065,6 @@ A change in `messageId` indicates a new message has started.

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

**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Cost information for a session.

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

<ResponseField name="usage_update" type="object">
**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Context window and cost update for the session.

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

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

**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Context window and cost update for a session.

**Type:** Object
Expand Down
25 changes: 25 additions & 0 deletions docs/protocol/v2/prompt-turn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,31 @@ If the model requested tool calls, these are also reported immediately:
}
```

#### Session Usage Updates

The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`:

```json
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "usage_update",
"used": 53000,
"size": 200000,
"cost": {
"amount": 0.045,
"currency": "USD"
}
}
}
}
```

`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"`.

### 4. Check for Completion

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