implement session usage RFD

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,9 @@ 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></>} >
+  Token usage for this turn (optional).
+</ResponseField>
 
 <a id="session-resume"></a>
 ### <span class="font-mono">session/resume</span>
@@ -1955,6 +1958,21 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
   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
@@ -3687,6 +3705,40 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 </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/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 +4183,80 @@ 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>
+
+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 (for o1/o3 models).
+
+    - 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>
+
+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>