The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.tsxindex 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.tsindex 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: stringtext: 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 | nullinput_tokens?: number | nulldiff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.jsonindex 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.pyindex 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 0prompt_total, cache_read = stats.get("prompt_tokens") or 0, stats.get("cache_read_tokens") or 0if 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 emptyplaceholder for as long as the frame carries the counters alone. Publishing both serves eitherviewer 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.pyindex 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.pyindex 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: stclass 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 = Noneinput_tokens: int | None = None