docs(rfd): Add session usage and context status RFD #316

ahmedhesham6 · 2025-12-07T00:51:43Z

Proposes standardized tracking of token usage, cost estimation, and context window status across ACP implementations.

Token usage reported in PromptResponse (per-turn data)
Context window and cost reported in session/status (session state)

Proposes standardized tracking of token usage, cost estimation, and context window status across ACP implementations. - Token usage reported in PromptResponse (per-turn data) - Context window and cost reported in session/status (session state)

versecafe · 2025-12-08T21:22:08Z

docs/rfds/session-usage-context-status.mdx

+      "percentage": 26.5,
+      "remaining": 147000


are these two fields needed, they are fully derivable from size and used

They’re redundant mathematically, but they carry the agent’s own calculation/rounding and simplify client work

versecafe · 2025-12-08T21:22:41Z

docs/rfds/session-usage-context-status.mdx

+- `percentage` (number, required) - Percentage used (0-100)
+- `remaining` (number, required) - Tokens remaining


ditto on the derived fields from size and used are these fields needed

versecafe · 2025-12-08T21:23:41Z

docs/rfds/session-usage-context-status.mdx

+
+### Design Principles
+
+1. **Separation of concerns** - Token usage is per-turn data, context window and cost are session state


how will this work with subagent "tools" that aren't performing full turns but are actively updating token usage frequently

benbrandt · 2025-12-11T13:36:43Z

@josevalim @SteffenDE I'd love to get your input on this one since you were looking into this a bit

SteffenDE · 2025-12-11T14:50:39Z

We like the idea and we definitely want to have a way to do this in ACP! For us, the most important part is the current usage (in percent). Including a usage in prompt responses feels like a no-brainer, but since an ACP prompt often consists of multiple agent turns, wrappers like Claude-Code-ACP would need to accumulate the different tokens from the turns. I think that's alright though. As mentioned in #316 (comment), one needs to be careful about usage data from subagents, as those should not be included, or optionally provided separately.

The PR proposes a new session/status method. I'm not sure if agents like Claude Code have proper APIs to query the current status at any time, so a different idea would be to only send the current usage information (current tokens, max tokens, percent) as part of session/update notifications only. An agent that supports getting the current usage without a prompt may then immediately send the update when creating a new chat, resuming a chat, forking a chat, etc., similar to how the available command updates are sent. An agent that only provides usage when actively prompting could only start sending the updates after sending a new prompt. That might mean that when resuming a chat, the client UI cannot immediately show the usage, but it allows more flexibility for agents.

ahmedhesham6 · 2025-12-11T16:22:04Z

@SteffenDE Thanks a lot for the detailed explanation and context 🙏
Just to confirm I understood you correctly — is this roughly what you’re suggesting for the session/update approach?

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123",
    "update": {
      "sessionUpdate": "context",
      "used": 53000,
      "size": 200000,
      "percentage": 26.5
    }
  }
}

If this matches what you had in mind, I can adjust the RFD in that direction.

SteffenDE · 2025-12-11T16:44:30Z

@ahmedhesham6 yes! I'd wait before changing things though, since I'm not a maintainer here and basically just stating my opinion :D

ahmedhesham6 · 2025-12-11T17:08:50Z

What do you think @benbrandt?

benbrandt · 2025-12-12T13:43:58Z

Yeah I think something simple to start would be great. As @SteffenDE mentioned, support for this will likely vary wildly (and we've also seen mixed support of even these basic metrics within the same agent lol)

I think we should let this be driven by the agent, as they will likely get the information from the provider and may forward it, but might not hold on to it. Requiring them to have the data at all points might be too much... So I'd opt for a simple way to report the basic information we feel we need, and go from there

…cations Refines the tracking of context window and cost information by transitioning from `session/status` requests to `session/update` notifications. This change allows agents to proactively push updates, enhancing flexibility and real-time data availability for clients. The `cost` field is now optional, and the `remaining` field has been removed, as clients can compute it from `size` and `used`. Updated documentation to reflect these changes and provide clearer usage patterns.

benbrandt · 2025-12-15T12:19:01Z

docs/rfds/session-usage-context-status.mdx

+- `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
+- `reasoning_tokens` (number, optional) - Total reasoning tokens (for o1/o3 models)


since in ACP we usually refer to this as thought I wonder if we could align that?

benbrandt · 2025-12-15T12:19:51Z

docs/rfds/session-usage-context-status.mdx

+
+- `used` (number, required) - Tokens currently in context
+- `size` (number, required) - Total context window size in tokens
+- `percentage` (number, required) - Percentage used (0-100)


Do we send this just to save a calculation on the client? since we allow them to calculate remaining, maybe we let them do this too?

benbrandt · 2025-12-15T12:21:50Z

docs/rfds/session-usage-context-status.mdx

+
+#### Cost Fields (optional)
+
+- `cost` (object, optional) - Cumulative session cost


naming nitpick: it seems weird that this is part of a "context" update.
I wonder if all of this is just usage from a conceptual point of view?
And roughly the same data can be sent at the end of the turn, with mid-turn updates? So kind of merge these?

It seems you want to distinguish between turn usage vs total usage. Which makes sense, but I wonder if we can distinguish then between turn vs session usage?

benbrandt · 2025-12-15T12:25:04Z

docs/rfds/session-usage-context-status.mdx

+- Agent knows exact context window size (varies by model)
+- Agent knows how it counts tokens (different tokenizers)
+- Agent knows about special tokens, system messages, etc.
+- Client can still recalculate if needed (all raw data provided)


I dont' really understand these arguments... Unless percentage will somehow be different than used / total (which would be weird) I feel the agent gets all of this by controlling the token counts already

ahmedhesham6 requested a review from a team as a code owner December 7, 2025 00:51

versecafe reviewed Dec 8, 2025

View reviewed changes

benbrandt reviewed Dec 15, 2025

View reviewed changes

		- `percentage` (number, required) - Percentage used (0-100)
		- `remaining` (number, required) - Tokens remaining


		### Design Principles

		1. Separation of concerns - Token usage is per-turn data, context window and cost are session state


		#### Cost Fields (optional)

		- `cost` (object, optional) - Cumulative session cost

docs(rfd): Add session usage and context status RFD #316

Are you sure you want to change the base?

docs(rfd): Add session usage and context status RFD #316

Conversation

ahmedhesham6 commented Dec 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benbrandt commented Dec 11, 2025

Uh oh!

SteffenDE commented Dec 11, 2025

Uh oh!

ahmedhesham6 commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SteffenDE commented Dec 11, 2025

Uh oh!

ahmedhesham6 commented Dec 11, 2025

Uh oh!

benbrandt commented Dec 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ahmedhesham6 commented Dec 11, 2025 •

edited

Loading