Skip to content

The agent that grows with you

fix(gateway): match the embedded ticker's usage view on session.usage; deprecate the flat counters

unsupportedpastelsf09ade93407b
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/usage.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/usage.test.tsx
index 96a0dfbabd2..339d708c3a3 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/usage.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/usage.test.tsx
@@ -3,11 +3,70 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { ClientSessionState } from '@/app/types'
import { createClientSessionState } from '@/lib/chat-runtime'
+import { cacheHitLabel, contextBarLabel, tokensPerSecondLabel, usageContextLabel } from '@/lib/statusbar'
import { $currentUsage } from '@/store/session'
import { type MessageStreamHarness, renderMessageStream } from './test-harness'
const SID = 'session-1'
+
+// What gateway/session_usage.py::publish_usage sends a local viewer: the embedded ticker's nested
+// `usage` view plus the deprecated top-level counters (#140194).
+const GATEWAY_FRAME = {
+ active_subagents: 0,
+ api_calls: 3,
+ avg_latency_s: 3.0,
+ cache_read_tokens: 36_000,
+ cache_write_tokens: 800,
+ completion_tokens: 380,
+ compression_count: 0,
+ config_context_length: 200_000,
+ context_length: 200_000,
+ context_source: 'provider_usage',
+ context_tokens: 42_000,
+ fallback_model: null,
+ input_tokens: 1_200,
+ last_prompt_tokens: 42_000,
+ last_turn_tokens: 0,
+ model: 'claude-opus-5-5',
+ output_tokens: 380,
+ prompt_tokens: 42_000,
+ provider: 'anthropic',
+ rate_limit: null,
+ reasoning_tokens: 0,
+ tokens_per_s: 63.33,
+ total_tokens: 42_380,
+ usage: {
+ active_subagents: 0,
+ avg_latency_s: 3.0,
+ avg_tps: 63.3,
+ cache_hit_pct: 86,
+ calls: 3,
+ completion: 380,
+ compressions: 0,
+ context_estimated: false,
+ context_max: 200_000,
+ context_percent: 21,
+ context_source: 'provider_usage',
+ context_used: 42_000,
+ input: 1_200,
+ model: 'claude-opus-5-5',
+ output: 380,
+ prompt: 42_000,
+ reasoning: 0,
+ total: 42_380
+ }
+}
+
+const METERS = ['[██░░░░░░░░] 21%', '42k/200k', '86%', '63 t/s']
+
+const meters = (usage: Parameters<typeof contextBarLabel>[0]) => [
+ contextBarLabel(usage),
+ usageContextLabel(usage),
+ cacheHitLabel(usage),
+ tokensPerSecondLabel(usage)
+]
+
// $currentUsage mirrors the primary session; ClientSessionState.usage drives
// the same status bar when a secondary tile is focused.
const BASELINE = { calls: 2, compressions: 1, input: 500, output: 40, total: 540 }
@@ -84,6 +143,24 @@ describe('useMessageStream status-bar usage scoping', () => {
expect(sessionStates.get(SID)?.usage).toEqual($currentUsage.get())
})
+ it('paints the status-bar meters from the gateway frame', () => {
+ $currentUsage.set({ calls: 0, input: 0, output: 0, total: 0 })
+ mountStream()
+
+ act(() => stream.handleEvent({ payload: GATEWAY_FRAME, session_id: SID, type: 'session.usage' }))
+
+ expect(meters($currentUsage.get())).toEqual(METERS)
+
+ // A bundle older than usageFromTick merged only `payload.usage`; the nested view alone fills the
+ // same meters, and the deprecated counters alone still map to them too.
+ const { usage: nested, ...counters } = GATEWAY_FRAME
+
+ expect(meters(nested)).toEqual(METERS)
+ $currentUsage.set({ calls: 0, input: 0, output: 0, total: 0 })
+ act(() => stream.handleEvent({ payload: counters, session_id: SID, type: 'session.usage' }))
+ expect(meters($currentUsage.get())).toEqual(METERS)
+ })
+
it('maps latency and active subagents from a canonical tick the same way Ink does', () => {
mountStream()
diff --git a/apps/shared/src/gateway-contract.generated.ts b/apps/shared/src/gateway-contract.generated.ts
index 6f1889a8b01..4dac1767312 100644
--- a/apps/shared/src/gateway-contract.generated.ts
+++ b/apps/shared/src/gateway-contract.generated.ts
@@ -5606,7 +5606,7 @@ export interface StatusUpdatePayload {
kind: string
text: string
}
-/** ``server._start_usage_ticker`` (``usage``), or a canonical local viewer's session-cumulative counters (``gateway/session_usage.py::usage_stats``, the ``session.stats`` dict) at the top level: published after every API call and at turn end, what main's classic CLI read off its agent. */
+/** ``usage``: the status-bar view (``server._get_usage``), sent by the embedded backend's ticker (``server._start_usage_ticker``) and by a canonical local viewer's gateway after every API call and at turn end (``gateway/session_usage.py::usage_frame``). Read this. Deprecated: the top-level session-cumulative counters (``usage_stats``, the ``session.stats`` dict) that the gateway frame also carries. They are kept for existing readers; new readers use ``usage``, or ``session.stats`` for the raw counters. The embedded ticker never sends them. */
export interface SessionUsagePayload {
usage?: Usage | null
input_tokens?: number | null
diff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.json
index e5a81d10b6d..a9489bc19e3 100644
--- a/apps/shared/src/gateway-contract.openrpc.json
+++ b/apps/shared/src/gateway-contract.openrpc.json
@@ -38249,7 +38249,7 @@
},
"SessionUsagePayload": {
"additionalProperties": false,
- "description": "``server._start_usage_ticker`` (``usage``), or a canonical local viewer's session-cumulative\ncounters (``gateway/session_usage.py::usage_stats``, the ``session.stats`` dict) at the top level:\npublished after every API call and at turn end, what main's classic CLI read off its agent.",
+ "description": "``usage``: the status-bar view (``server._get_usage``), sent by the embedded backend's ticker\n(``server._start_usage_ticker``) and by a canonical local viewer's gateway after every API call\nand at turn end (``gateway/session_usage.py::usage_frame``). Read this.\n\nDeprecated: the top-level session-cumulative counters (``usage_stats``, the ``session.stats``\ndict) that the gateway frame also carries. They are kept for existing readers; new readers use\n``usage``, or ``session.stats`` for the raw counters. The embedded ticker never sends them.",
"properties": {
"usage": {
"anyOf": [
diff --git a/gateway/session_usage.py b/gateway/session_usage.py
index 6b02ffacaea..af59fb5fe9f 100644
--- a/gateway/session_usage.py
+++ b/gateway/session_usage.py
@@ -124,7 +124,7 @@ def tui_usage(stats: dict) -> dict:
usage.update(context_used=used, context_max=maximum,
context_percent=max(0, min(100, round(used / maximum * 100))),
context_source=source, context_estimated=source != "provider_usage")
- if stats.get("context_length") is not None:
+ if stats.get("context_source") is not None: # a compressor, sized or not (``_get_usage``'s ``if comp``)
usage["compressions"] = stats.get("compression_count") or 0
prompt_total, cache_read = stats.get("prompt_tokens") or 0, stats.get("cache_read_tokens") or 0
if prompt_total > 0 and cache_read > 0:
@@ -147,6 +147,13 @@ def usage_frame(stats: dict) -> dict:
``payload.usage``, so its context / cache-hit / tokens-per-second meters render their empty
placeholder for as long as the frame carries the counters alone. Publishing both serves either
viewer from one frame, and leaves the counters untouched for every existing consumer.
+
+ ``usage`` is the embedded ticker's ``server._get_usage`` view (same keys, same rules, same
+ omissions; ``avg_latency_s`` / ``avg_tps`` are rounded from the counters' two decimals), so a
+ Desktop bundle that reads only ``payload.usage`` fills its meters here too. The
+ top-level counters on this event are deprecated: new viewers read ``usage`` (or call
+ ``session.stats`` for the counters). They stay for ``hermes_cli.gateway_agent``, the Ink TUI and
+ Desktop's ``usageFromTick`` until those read ``usage``.
"""
return {"usage": tui_usage(stats), **stats}
diff --git a/tests/gateway/test_local_viewer_usage.py b/tests/gateway/test_local_viewer_usage.py
index 8dca3e3458d..44cd5bfba79 100644
--- a/tests/gateway/test_local_viewer_usage.py
+++ b/tests/gateway/test_local_viewer_usage.py
@@ -150,6 +150,31 @@ def test_usage_frame_carries_the_tui_view_the_desktop_status_bar_reads():
assert usage['avg_tps'] == 10.0 and usage['cache_hit_pct'] == 9 and usage['compressions'] == 1
+def _parity_agents():
+ yield pytest.param(_agent(), id='steady')
+ # A compressor that does not know its window yet: the ticker still reports its compactions.
+ unsized = _agent()
+ unsized.context_compressor.context_length = 0
+ yield pytest.param(unsized, id='unsized-compressor')
+ # Nothing measured yet: no context, cache, latency or throughput figures, never zeros.
+ yield pytest.param(SimpleNamespace(model='fake-model', session_api_calls=0, context_compressor=None,
+ get_rate_limit_state=lambda: None), id='fresh')
+
+
[email protected]('agent', list(_parity_agents()))
+def test_published_usage_view_matches_the_embedded_ticker(agent):
+ """An older Desktop bundle reads only ``payload.usage`` off ``session.usage``, as the embedded
+ backend's ticker sends it (``{'usage': server._get_usage(agent)}``). The gateway frame's nested
+ view is that same object, computed from the same agent."""
+ from gateway.session_usage import publish_usage
+ from tui_gateway.server import _get_usage
+ published = []
+ publish_usage(_turn(Platform.LOCAL, published, agent), agent)
+ kind, frame = published[-1]
+ assert kind == 'session.usage'
+ assert frame['usage'] == _get_usage(agent)
+
+
def test_turn_end_publishes_the_agents_banner_info():
"""Main re-emitted ``session.info`` at every turn end; the first turn's carries the built agent's
``system_prompt`` (the banner's ``▸ System Prompt — N chars`` row, FINDINGS row 2) and tools."""
diff --git a/tui_gateway/contracts/events.py b/tui_gateway/contracts/events.py
index 55383ceb140..b44328f5f04 100644
--- a/tui_gateway/contracts/events.py
+++ b/tui_gateway/contracts/events.py
@@ -272,9 +272,13 @@ event("status.update", StatusUpdatePayload, doc="Transient status line (kind: st
class SessionUsagePayload(Payload):
- """``server._start_usage_ticker`` (``usage``), or a canonical local viewer's session-cumulative
- counters (``gateway/session_usage.py::usage_stats``, the ``session.stats`` dict) at the top level:
- published after every API call and at turn end, what main's classic CLI read off its agent."""
+ """``usage``: the status-bar view (``server._get_usage``), sent by the embedded backend's ticker
+ (``server._start_usage_ticker``) and by a canonical local viewer's gateway after every API call
+ and at turn end (``gateway/session_usage.py::usage_frame``). Read this.
+
+ Deprecated: the top-level session-cumulative counters (``usage_stats``, the ``session.stats``
+ dict) that the gateway frame also carries. They are kept for existing readers; new readers use
+ ``usage``, or ``session.stats`` for the raw counters. The embedded ticker never sends them."""
usage: Usage | None = None
input_tokens: int | None = None