feat(unstable): Add unstable support for session usage

Cargo.toml

@@ -22,6 +22,7 @@ unstable = [
     "unstable_session_list",
     "unstable_session_model",
     "unstable_session_resume",
+    "unstable_session_usage",
 ]
 unstable_cancel_request = []
 unstable_session_config_options = []
@@ -30,6 +31,7 @@ unstable_session_info_update = []
 unstable_session_list = []
 unstable_session_model = []
 unstable_session_resume = []
+unstable_session_usage = []
 
 [[bin]]
 name = "generate"

docs/protocol/draft/schema.mdx

@@ -612,6 +612,14 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 <ResponseField name="stopReason" type={<a href="#stopreason">StopReason</a>} required>
   Indicates why the agent stopped processing the turn.
 </ResponseField>
+<ResponseField name="usage" type={<><span><a href="#usage">Usage</a></span><span> | null</span></>} >
+  **UNSTABLE**
+
+This capability is not part of the spec yet, and may be removed or changed at any point.
+
+Token usage for this turn (optional).
+
+</ResponseField>
 
 <a id="session-resume"></a>
 ### <span class="font-mono">session/resume</span>
@@ -1955,6 +1963,25 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
   A single item of content
 </ResponseField>
 
+## <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
+
+**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
@@ -3687,6 +3714,44 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 </Expandable>
 </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">
+
+<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/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>
+</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.
@@ -4131,3 +4196,88 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 <ResponseField name="hint" type={"string"} required>
   A hint to display when the input hasn't been provided yet
 </ResponseField>
+
+## <span class="font-mono">Usage</span>
+
+**UNSTABLE**
+
+This capability is not part of the spec yet, and may be removed or changed at any point.
+
+Token usage information for a prompt turn.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="cachedReadTokens" type={"integer | null"} >
+  Total cache read tokens.
+
+    - Minimum: `0`
+
+</ResponseField>
+<ResponseField name="cachedWriteTokens" type={"integer | null"} >
+  Total cache write tokens.
+
+    - Minimum: `0`
+
+</ResponseField>
+<ResponseField name="inputTokens" type={"uint64"} required>
+  Total input tokens across all turns.
+
+    - Minimum: `0`
+
+</ResponseField>
+<ResponseField name="outputTokens" type={"uint64"} required>
+  Total output tokens across all turns.
+
+    - Minimum: `0`
+
+</ResponseField>
+<ResponseField name="thoughtTokens" type={"integer | null"} >
+  Total thought/reasoning tokens
+
+    - Minimum: `0`
+
+</ResponseField>
+<ResponseField name="totalTokens" type={"uint64"} required>
+  Sum of all token types across session.
+
+    - Minimum: `0`
+
+</ResponseField>
+
+## <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
+
+**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/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>

docs/rfds/session-usage.mdx

@@ -92,7 +92,7 @@ Add a `usage` field to `PromptResponse` for token consumption tracking:
 - `total_tokens` (number, required) - Sum of all token types across session
 - `input_tokens` (number, required) - Total input tokens across all turns
 - `output_tokens` (number, required) - Total output tokens across all turns
-- `thought_tokens` (number, optional) - Total thought/reasoning tokens (for o1/o3 models)
+- `thought_tokens` (number, optional) - Total thought/reasoning tokens
 - `cached_read_tokens` (number, optional) - Total cache read tokens
 - `cached_write_tokens` (number, optional) - Total cache write tokens
 

schema/schema.unstable.json

@@ -1013,6 +1013,22 @@
       "required": ["content"],
       "type": "object"
     },
+    "Cost": {
+      "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.",
+      "properties": {
+        "amount": {
+          "description": "Total cumulative cost for session.",
+          "format": "double",
+          "type": "number"
+        },
+        "currency": {
+          "description": "ISO 4217 currency code (e.g., \"USD\", \"EUR\").",
+          "type": "string"
+        }
+      },
+      "required": ["amount", "currency"],
+      "type": "object"
+    },
     "CreateTerminalRequest": {
       "description": "Request to create a new terminal and execute a command.",
       "properties": {
@@ -2224,6 +2240,17 @@
             }
           ],
           "description": "Indicates why the agent stopped processing the turn."
+        },
+        "usage": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Usage"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "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)."
         }
       },
       "required": ["stopReason"],
@@ -3191,6 +3218,22 @@
           },
           "required": ["sessionUpdate"],
           "type": "object"
+        },
+        {
+          "allOf": [
+            {
+              "$ref": "#/$defs/UsageUpdate"
+            }
+          ],
+          "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.",
+          "properties": {
+            "sessionUpdate": {
+              "const": "usage_update",
+              "type": "string"
+            }
+          },
+          "required": ["sessionUpdate"],
+          "type": "object"
         }
       ]
     },
@@ -3813,6 +3856,84 @@
       "required": ["hint"],
       "type": "object"
     },
+    "Usage": {
+      "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.",
+      "properties": {
+        "cachedReadTokens": {
+          "description": "Total cache read tokens.",
+          "format": "uint64",
+          "minimum": 0,
+          "type": ["integer", "null"]
+        },
+        "cachedWriteTokens": {
+          "description": "Total cache write tokens.",
+          "format": "uint64",
+          "minimum": 0,
+          "type": ["integer", "null"]
+        },
+        "inputTokens": {
+          "description": "Total input tokens across all turns.",
+          "format": "uint64",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "outputTokens": {
+          "description": "Total output tokens across all turns.",
+          "format": "uint64",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "thoughtTokens": {
+          "description": "Total thought/reasoning tokens",
+          "format": "uint64",
+          "minimum": 0,
+          "type": ["integer", "null"]
+        },
+        "totalTokens": {
+          "description": "Sum of all token types across session.",
+          "format": "uint64",
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": ["totalTokens", "inputTokens", "outputTokens"],
+      "type": "object"
+    },
+    "UsageUpdate": {
+      "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.",
+      "properties": {
+        "_meta": {
+          "additionalProperties": true,
+          "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)",
+          "type": ["object", "null"]
+        },
+        "cost": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Cost"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Cumulative session cost (optional)."
+        },
+        "size": {
+          "description": "Total context window size in tokens.",
+          "format": "uint64",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "used": {
+          "description": "Tokens currently in context.",
+          "format": "uint64",
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": ["used", "size"],
+      "type": "object"
+    },
     "WaitForTerminalExitRequest": {
       "description": "Request to wait for a terminal command to exit.",
       "properties": {