From 04767e7aaaa48a7306d08f2a2cc92e6647c4fb1a Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Mon, 7 Sep 2026 03:38:40 -0700
Subject: [PATCH] fix(display): distinguish estimated context from provider
usage
---
agent/context_breakdown.py | 57 ++++++--
agent/turn_finalizer.py | 7 +-
.../app/shell/context-usage-panel.test.tsx | 13 ++
.../src/app/shell/context-usage-panel.tsx | 6 +-
.../app/shell/hooks/use-statusbar-items.tsx | 2 +
apps/desktop/src/lib/statusbar.tsx | 4 +-
apps/desktop/src/types/hermes.ts | 4 +
evals/token_accounting/display_provenance.py | 131 ++++++++++++++++++
gateway/slash_commands_status.py | 28 ++--
hermes_cli/cli_info_mixin.py | 4 +-
hermes_cli/cli_status_bar_mixin.py | 12 +-
.../agent/test_context_display_provenance.py | 38 +++++
tui_gateway/methods_session.py | 4 +-
tui_gateway/methods_slash.py | 10 +-
tui_gateway/server.py | 21 +--
.../__tests__/appChromeStatusRule.test.tsx | 14 ++
ui-tui/src/app/slash/commands/session.ts | 3 +-
ui-tui/src/components/appChrome.tsx | 9 +-
ui-tui/src/gatewayTypes.ts | 2 +
ui-tui/src/types.ts | 2 +
website/docs/user-guide/cli.md | 4 +-
21 files changed, 315 insertions(+), 60 deletions(-)
create mode 100644 evals/token_accounting/display_provenance.py
create mode 100644 tests/agent/test_context_display_provenance.py
diff --git a/agent/context_breakdown.py b/agent/context_breakdown.py
index 2626bb612e..ed3999e25d 100644
--- a/agent/context_breakdown.py
+++ b/agent/context_breakdown.py
@@ -90,6 +90,29 @@ def _glyph(cat: Dict[str, Any]) -> str:
return _CATEGORIES.get(str(cat.get("id") or ""), (None, None, "▪"))[2]
+def context_display_source(compressor: Any) -> str:
+ """Distinguish the built-in preflight display seed from a provider reading.
+
+ Engines without the built-in real-usage ledger own their occupancy figure.
+ A seed never updates that ledger, even if its number later matches real usage.
+ """
+ real = getattr(compressor, "last_real_prompt_tokens", None)
+ shown = getattr(compressor, "last_prompt_tokens", 0) or 0
+ return "local_estimate" if isinstance(real, (int, float)) and shown != real else "provider_usage"
+
+
+def context_usage_fields(compressor: Any) -> Dict[str, Any]:
+ """Current occupancy only; lifetime throughput is never a context fallback."""
+ used = max(0, getattr(compressor, "last_prompt_tokens", 0) or 0)
+ maximum = getattr(compressor, "context_length", 0) or 0
+ if not used or not maximum:
+ return {}
+ source = context_display_source(compressor)
+ return {"context_used": used, "context_max": maximum,
+ "context_percent": max(0, min(100, round(used / maximum * 100))),
+ "context_source": source, "context_estimated": source != "provider_usage"}
+
+
def compute_session_context_breakdown(agent: Any, messages: Optional[List[dict]] = None) -> Dict[str, Any]:
"""Return a Cursor-style context usage breakdown for one live agent."""
from agent.model_metadata import estimate_messages_tokens_rough
@@ -125,14 +148,20 @@ def compute_session_context_breakdown(agent: Any, messages: Optional[List[dict]]
# prompt_tokens with replayed thinking that evaporates at the turn boundary, so
# anchoring on the LAST response makes the meter sawtooth. Fall back to the
# last-response anchor, then measured, then estimated.
- context_used = anchored_context_tokens(
- messages, getattr(agent, "_turn_base_usage_anchor", None), charge_stale_thinking=False
- )
+ anchor = getattr(agent, "_turn_base_usage_anchor", None)
+ context_used = anchored_context_tokens(messages, anchor, charge_stale_thinking=False)
if context_used is None:
- context_used = anchored_context_tokens(messages, getattr(agent, "_usage_anchor", None))
+ anchor = getattr(agent, "_usage_anchor", None)
+ context_used = anchored_context_tokens(messages, anchor)
if context_used is None:
measured_used = int(getattr(comp, "last_prompt_tokens", 0) or 0) if comp else 0
context_used = measured_used if measured_used > 0 else estimated_total
+ source = context_display_source(comp) if measured_used > 0 else "local_estimate"
+ else:
+ delta = messages[int(anchor["base_count"]):]
+ if delta and delta[0].get("role") == "assistant":
+ delta = delta[1:]
+ source = "provider_usage_plus_estimate" if delta else "provider_usage"
return {
"categories": [
@@ -143,6 +172,8 @@ def compute_session_context_breakdown(agent: Any, messages: Optional[List[dict]]
"context_max": context_max,
"context_percent": max(0, min(100, round(context_used / context_max * 100))) if context_max else 0,
"context_used": context_used,
+ "context_source": source,
+ "context_estimated": source != "provider_usage",
"estimated_total": estimated_total,
"model": getattr(agent, "model", "") or "",
}
@@ -214,15 +245,15 @@ def render_context_category_lines(payload: Dict[str, Any]) -> List[str]:
width = max(len("Free space"), *(len(str(cat.get("label") or "")) for cat in categories))
for cat in categories:
tokens, label = int(cat.get("tokens") or 0), str(cat.get("label") or cat.get("id") or "")
- lines.append(f"{_glyph(cat)} {label:<{width}} {tokens:>9,} tokens {tokens / denom * 100 if denom else 0.0:>5.1f}%")
+ lines.append(f"{_glyph(cat)} {label:<{width}} ~{tokens:>9,} tokens ~{tokens / denom * 100 if denom else 0.0:>5.1f}%")
if context_max > 0:
free = max(0, context_max - estimated_total)
- lines.append(f"{_FREE_GLYPH} {'Free space':<{width}} {free:>9,} tokens {free / context_max * 100:>5.1f}%")
+ lines.append(f"{_FREE_GLYPH} {'Free space':<{width}} ~{free:>9,} tokens ~{free / context_max * 100:>5.1f}%")
return lines
def _toolset_row(group: Dict[str, Any]) -> str:
- return f" {group['toolset']:<24} {group['tool_count']:>3} tools {group['schema_tokens']:>8,} tokens"
+ return f" {group['toolset']:<24} {group['tool_count']:>3} tools ~{group['schema_tokens']:>8,} tokens"
def _skill_row(entry: Dict[str, Any]) -> str:
@@ -230,8 +261,8 @@ def _skill_row(entry: Dict[str, Any]) -> str:
if len(name) > 28:
name = name[:27] + "…"
md = entry.get("skill_md_tokens")
- md_str = f"{md:>8,}" if md is not None else f"{'n/a':>8}"
- return f" {name:<28} index {entry['index_tokens']:>6,} SKILL.md {md_str} tokens"
+ md_str = f"~{md:>8,}" if md is not None else f"{'n/a':>8}"
+ return f" {name:<28} index ~{entry['index_tokens']:>6,} SKILL.md {md_str} tokens"
def _table(lines: List[str], title: str, rows: List[Dict[str, Any]], fmt) -> None:
@@ -268,7 +299,13 @@ def render_context_breakdown_lines(
context_max = int(payload.get("context_max") or 0)
if context_max > 0:
used, pct = int(payload.get("context_used") or 0), int(payload.get("context_percent") or 0)
- lines.extend(["", f"Context window: {used:,} / {context_max:,} tokens ({pct}%)"])
+ mark = "~" if payload.get("context_estimated") else ""
+ lines.extend(["", f"Context window: {mark}{used:,} / {context_max:,} tokens ({mark}{pct}%)"])
+ source = payload.get("context_source")
+ if source:
+ labels = {"local_estimate": "local estimate", "provider_usage": "provider usage",
+ "provider_usage_plus_estimate": "provider usage + estimated new messages"}
+ lines.append(f"Source: {labels.get(source, source)}; category counts are local estimates.")
if details is None:
lines.extend(["", "Use /context all for per-skill and per-toolset costs."])
diff --git a/agent/turn_finalizer.py b/agent/turn_finalizer.py
index 85074870f5..144a57fa78 100644
--- a/agent/turn_finalizer.py
+++ b/agent/turn_finalizer.py
@@ -550,7 +550,12 @@ def finalize_turn(
"provider": agent.provider,
"base_url": agent.base_url,
**{key: getattr(agent, f"session_{key}") for key in _SESSION_TOKEN_KEYS},
- "last_prompt_tokens": getattr(agent.context_compressor, "last_prompt_tokens", 0) or 0,
+ # Gateway SessionEntry persists an API reading, never the preflight display seed.
+ "last_prompt_tokens": (
+ getattr(agent.context_compressor, "last_real_prompt_tokens", agent.context_compressor.last_prompt_tokens)
+ if getattr(agent.context_compressor, "last_prompt_tokens", 0) > 0
+ else getattr(agent.context_compressor, "last_prompt_tokens", 0)
+ ) or 0,
**{key: getattr(agent, f"session_{key}") for key in _SESSION_COST_KEYS},
# Requested service tier, for billing audits (`hermes -z --usage-file`).
"service_tier": (
diff --git a/apps/desktop/src/app/shell/context-usage-panel.test.tsx b/apps/desktop/src/app/shell/context-usage-panel.test.tsx
index ec854b2167..aacf62bf26 100644
--- a/apps/desktop/src/app/shell/context-usage-panel.test.tsx
+++ b/apps/desktop/src/app/shell/context-usage-panel.test.tsx
@@ -101,6 +101,19 @@ describe('useContextBreakdown', () => {
})
describe('ContextUsagePanel', () => {
+ it('marks estimates but preserves the provider-usage header', () => {
+ for (const estimated of [true, false]) {
+ const { container, unmount } = render(
+
+ )
+ const header = container.querySelector('[data-slot="context-usage-panel"] > div')?.textContent ?? ''
+
+ expect(header.includes('~')).toBe(estimated)
+ expect(container.querySelector('li')?.textContent).toContain('~')
+ unmount()
+ }
+ })
+
it('renders the usage it is handed, so the popover matches the bar', () => {
render()
diff --git a/apps/desktop/src/app/shell/context-usage-panel.tsx b/apps/desktop/src/app/shell/context-usage-panel.tsx
index 07e08cabb5..2c3fcc0f50 100644
--- a/apps/desktop/src/app/shell/context-usage-panel.tsx
+++ b/apps/desktop/src/app/shell/context-usage-panel.tsx
@@ -40,11 +40,11 @@ export function ContextUsagePanel({ breakdown, loading, usage }: ContextUsagePan
{copy.title}
- {copy.tokenSummary(`~${compactNumber(contextUsed)}`, compactNumber(contextMax))}
+ {copy.tokenSummary(`${usage.context_estimated ? "~" : ""}${compactNumber(contextUsed)}`, compactNumber(contextMax))}
- {copy.percentFull(contextPercent)}
+ {usage.context_estimated ? '~' : ''}{copy.percentFull(contextPercent)}
@@ -57,7 +57,7 @@ export function ContextUsagePanel({ breakdown, loading, usage }: ContextUsagePan
{category.label}
- {compactNumber(category.tokens)}
+ ~{compactNumber(category.tokens)}
))}
diff --git a/apps/desktop/src/app/shell/hooks/use-statusbar-items.tsx b/apps/desktop/src/app/shell/hooks/use-statusbar-items.tsx
index f2bcf39fd2..1714e62e57 100644
--- a/apps/desktop/src/app/shell/hooks/use-statusbar-items.tsx
+++ b/apps/desktop/src/app/shell/hooks/use-statusbar-items.tsx
@@ -269,6 +269,8 @@ export function useStatusbarItems({
contextBreakdown
? {
...currentUsage,
+ context_estimated: contextBreakdown.context_estimated,
+ context_source: contextBreakdown.context_source,
context_max: contextBreakdown.context_max,
context_percent: contextBreakdown.context_percent,
context_used: contextBreakdown.context_used
diff --git a/apps/desktop/src/lib/statusbar.tsx b/apps/desktop/src/lib/statusbar.tsx
index 5b9670eef7..3bcb643bd4 100644
--- a/apps/desktop/src/lib/statusbar.tsx
+++ b/apps/desktop/src/lib/statusbar.tsx
@@ -43,7 +43,7 @@ export function contextBar(percent: number | undefined, width = 10): string {
export function usageContextLabel(usage: UsageStats): string {
if (usage.context_max) {
- return `${compactNumber(usage.context_used ?? 0)}/${compactNumber(usage.context_max)}`
+ return `${usage.context_estimated ? "~" : ""}${compactNumber(usage.context_used ?? 0)}/${compactNumber(usage.context_max)}`
}
return usage.total > 0 ? `${compactNumber(usage.total)} tok` : ''
@@ -56,7 +56,7 @@ export function contextBarLabel(usage: UsageStats): string {
const pct = Math.max(0, Math.min(100, Math.round(usage.context_percent ?? 0)))
- return `[${contextBar(usage.context_percent)}] ${pct}%`
+ return `[${contextBar(usage.context_percent)}] ${usage.context_estimated ? '~' : ''}${pct}%`
}
/** `87%` for a reported hit rate; '' when the backend omitted it (no cache
diff --git a/apps/desktop/src/types/hermes.ts b/apps/desktop/src/types/hermes.ts
index d18200d626..16203d6052 100644
--- a/apps/desktop/src/types/hermes.ts
+++ b/apps/desktop/src/types/hermes.ts
@@ -745,6 +745,8 @@ export interface UsageStats {
calls: number
context_max?: number
context_percent?: number
+ context_estimated?: boolean
+ context_source?: string
context_used?: number
cost_usd?: number
input: number
@@ -804,6 +806,8 @@ export interface ContextBreakdown {
categories: ContextUsageCategory[]
context_max: number
context_percent: number
+ context_estimated?: boolean
+ context_source?: string
context_used: number
estimated_total: number
model?: string
diff --git a/evals/token_accounting/display_provenance.py b/evals/token_accounting/display_provenance.py
new file mode 100644
index 0000000000..d32cbe3682
--- /dev/null
+++ b/evals/token_accounting/display_provenance.py
@@ -0,0 +1,131 @@
+"""Credential-free production CLI PTY / live slash display A/B.
+
+Run with the checkout's Python and --out DIRECTORY. Provider counts below are
+explicit fixture inputs, NOT measurements from a vendor. No inference is made.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import pty
+import sys
+import tempfile
+
+
+def child(out: Path) -> None:
+ from cli import HermesCLI
+ from run_agent import AIAgent
+ from agent.context_breakdown import compute_session_context_breakdown
+ from tui_gateway.server import _get_usage, _format_live_context_output
+ import threading
+ import asyncio
+ from gateway.run import GatewayRunner
+ from gateway.config import GatewayConfig
+ from gateway.session import SessionStore, SessionSource
+ from gateway.config import Platform
+ from gateway.platforms.base import MessageEvent
+
+ runner = GatewayRunner.__new__(GatewayRunner)
+ runner.config = GatewayConfig()
+ runner.session_store = SessionStore(Path(os.environ["HERMES_HOME"]) / "sessions", runner.config)
+ runner._session_db = None
+ runner.adapters = {}
+ source = SessionSource(platform=Platform.TELEGRAM, user_id="fixture", chat_id="fixture", chat_type="dm")
+ entry = runner.session_store.get_or_create_session(source)
+
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+ class ProviderFixture(BaseHTTPRequestHandler):
+ def do_POST(self):
+ request = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+ (out / "provider-request.json").write_text(json.dumps(request, indent=2))
+ response = {"id": "fixture", "object": "chat.completion", "created": 0, "model": "fixture",
+ "choices": [{"index": 0, "finish_reason": "stop", "message": {"role": "assistant", "content": "fixture answer"}}],
+ "usage": {"prompt_tokens": 1234, "completion_tokens": 20, "total_tokens": 1254}}
+ body = json.dumps(response).encode()
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def log_message(self, *args):
+ pass
+
+ server = ThreadingHTTPServer(("127.0.0.1", 0), ProviderFixture)
+ threading.Thread(target=server.serve_forever, daemon=True).start()
+ base_url = f"http://127.0.0.1:{server.server_port}/v1"
+ cli = HermesCLI(model="fixture", provider="openai-compat", api_key="fixture", base_url=base_url)
+ agent = AIAgent(model="fixture", provider="openai-compat", api_key="fixture", base_url=base_url, enabled_toolsets=[], quiet_mode=True, skip_context_files=True, skip_memory=True, save_trajectories=False)
+ agent.context_compressor._config_context_length = 100_000
+ agent.context_compressor._resolved_context_length = 100_000
+ agent._disable_streaming = True
+ cli.agent = agent
+ cli.conversation_history = [{"role": "user", "content": "fixture question"}]
+ results = {}
+ for scenario in ("local_estimate", "provider_usage", "provider_usage_plus_estimate"):
+ if scenario == "local_estimate":
+ agent.context_compressor.maybe_seed_preflight_display_tokens(1234)
+ elif scenario == "provider_usage":
+ result = agent.run_conversation("fixture question")
+ assert result["completed"] and result["last_prompt_tokens"] == 1234
+ cli.conversation_history = result["messages"]
+ else:
+ cli.conversation_history.append({"role": "user", "content": "new unpriced question"})
+ print(f"\n=== {scenario}: CLI /context ===", flush=True)
+ cli.process_command("/context")
+ usage = _get_usage(agent)
+ session = {"agent": agent, "history": cli.conversation_history, "history_lock": threading.RLock()}
+ print("=== TUI/Desktop live /context ===", flush=True)
+ print(_format_live_context_output("fixture", session, ""), flush=True)
+ runner._running_agents = {entry.session_key: agent}
+ runner.session_store.rewrite_transcript(entry.session_id, cli.conversation_history)
+ print("=== gateway /status ===", flush=True)
+ print(asyncio.run(runner._handle_status_command(MessageEvent(text="/status", source=source, message_id="fixture"))), flush=True)
+ print("=== gateway /context ===", flush=True)
+ print(asyncio.run(runner._handle_context_command(MessageEvent(text="/context", source=source, message_id="fixture"))), flush=True)
+ results[scenario] = {"breakdown": compute_session_context_breakdown(agent, cli.conversation_history), "usage": usage}
+ (out / "payloads.json").write_text(json.dumps(results, indent=2))
+ server.shutdown()
+ server.server_close()
+ print("DISPLAY_PROBE_COMPLETE", flush=True)
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--out", required=True, type=Path)
+ args = parser.parse_args()
+ out = args.out.resolve()
+ out.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(prefix="context-display-") as home:
+ pid, fd = pty.fork()
+ if pid == 0:
+ os.environ.clear()
+ os.environ.update(HOME=home, HERMES_HOME=home + "/.hermes", PATH="/usr/bin:/bin", TERM="dumb", NO_COLOR="1")
+ try:
+ child(out)
+ finally:
+ sys.stdout.flush()
+ os._exit(0)
+ chunks = []
+ while True:
+ try:
+ chunk = os.read(fd, 65536)
+ except OSError:
+ break
+ if not chunk:
+ break
+ chunks.append(chunk)
+ os.close(fd)
+ _, status = os.waitpid(pid, 0)
+ transcript = b"".join(chunks).decode(errors="replace")
+ (out / "pty.txt").write_text(transcript)
+ print(transcript)
+ if status or "DISPLAY_PROBE_COMPLETE" not in transcript:
+ raise SystemExit(1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/gateway/slash_commands_status.py b/gateway/slash_commands_status.py
index ab21e5df6f..e4f85a3995 100644
--- a/gateway/slash_commands_status.py
+++ b/gateway/slash_commands_status.py
@@ -93,7 +93,7 @@ def _status_model_route(status_agent, persisted_route: dict, session_row: dict,
_clean_str(getattr(status_agent, "provider", ""))))
ctx = getattr(status_agent, "context_compressor", None)
if ctx is not None:
- context_used = _int_value(getattr(ctx, "last_prompt_tokens", 0))
+ context_used = max(0, _int_value(getattr(ctx, "last_prompt_tokens", 0)))
context_total = _int_value(getattr(ctx, "context_length", 0))
routes.append((_clean_str(persisted_route.get("model")),
_clean_str(persisted_route.get("billing_provider"))))
@@ -189,8 +189,10 @@ def _usage_agent_stats_lines(agent) -> list[str]:
ctx = agent.context_compressor
if ctx.last_prompt_tokens > 0:
pct = _pct(ctx.last_prompt_tokens, ctx.context_length)
- lines.append(t("gateway.usage.label_context", used=_fmt(ctx.last_prompt_tokens),
- total=_fmt(ctx.context_length), pct=f"{pct:.0f}"))
+ from agent.context_breakdown import context_display_source
+ mark = "~" if context_display_source(ctx) != "provider_usage" else ""
+ lines.append(t("gateway.usage.label_context", used=mark + _fmt(ctx.last_prompt_tokens),
+ total=_fmt(ctx.context_length), pct=f"{mark}{pct:.0f}"))
if ctx.compression_count:
lines.append(t("gateway.usage.label_compressions", count=ctx.compression_count))
return lines
@@ -243,12 +245,14 @@ class GatewayStatusCommandsMixin:
lines.append(t("gateway.status.model_provider", model=model_name, provider=provider_name))
elif model_name:
lines.append(t("gateway.status.model", model=model_name))
+ from agent.context_breakdown import context_display_source
+ mark = "~" if context_display_source(getattr(status_agent, "context_compressor", None)) != "provider_usage" else ""
if context_total:
pct = min(100, round((context_used / context_total) * 100))
- lines.append(t("gateway.status.context", used=_fmt(context_used), total=_fmt(context_total),
- pct=f"{pct}"))
+ lines.append(t("gateway.status.context", used=mark + _fmt(context_used), total=_fmt(context_total),
+ pct=f"{mark}{pct}"))
elif context_used:
- lines.append(t("gateway.status.context_used", used=_fmt(context_used)))
+ lines.append(t("gateway.status.context_used", used=mark + _fmt(context_used)))
state = t("gateway.status.state_yes") if is_running else t("gateway.status.state_no")
lines += [t("gateway.status.tokens", tokens=_fmt(db_total_tokens)),
t("gateway.status.agent_running", state=state)]
@@ -311,7 +315,9 @@ class GatewayStatusCommandsMixin:
used, context_length, model_name = await self._resolve_context_figures(
agent, ctx, session_entry, source
)
- # Gauge path: real current-context figure
+ from agent.context_breakdown import context_display_source
+ mark = "~" if context_display_source(ctx) != "provider_usage" else ""
+ # Gauge path: preserve the provenance of the selected occupancy figure.
if used > 0 and context_length > 0:
pct = _pct(used, context_length)
filled = int(round(pct / 100 * 24))
@@ -319,9 +325,9 @@ class GatewayStatusCommandsMixin:
t("gateway.context.header"), "",
t("gateway.context.model", model=model_name or "?"),
t("gateway.context.window", total=_fmt(context_length)),
- t("gateway.context.in_use", used=_fmt(used), total=_fmt(context_length), pct=f"{pct:.0f}"),
+ t("gateway.context.in_use", used=mark + _fmt(used), total=_fmt(context_length), pct=f"{mark}{pct:.0f}"),
t("gateway.context.bar", bar="█" * max(0, filled) + "░" * max(0, 24 - filled)),
- t("gateway.context.headroom", headroom=_fmt(max(0, context_length - used))),
+ t("gateway.context.headroom", headroom=mark + _fmt(max(0, context_length - used))),
"",
]
# Full view — compression / throughput need the live agent.
@@ -349,7 +355,7 @@ class GatewayStatusCommandsMixin:
async def _resolve_context_figures(self, agent, ctx, session_entry, source):
"""``(used, context_length, model_name)`` for /context: used = compressor -> SessionStore;
model = agent -> SessionDB row; window = compressor -> gateway model route -> model metadata."""
- used = _n(ctx, "last_prompt_tokens") or _int_value(getattr(session_entry, "last_prompt_tokens", 0))
+ used = max(0, _n(ctx, "last_prompt_tokens")) or max(0, _int_value(getattr(session_entry, "last_prompt_tokens", 0)))
context_length = _n(ctx, "context_length")
model_name = _clean_str(getattr(agent, "model", "")) if agent is not None else ""
if not model_name and self._session_db:
@@ -495,7 +501,7 @@ class GatewayStatusCommandsMixin:
if label.endswith(f"breakdown_cat_{cat_id}"): # missing key: t() echoes it back
label = str(cat.get("label") or cat_id)
pct = round(tokens / total * 100) if total else 0
- out.append(t("gateway.usage.breakdown_line", label=label, count=_fmt(tokens), pct=pct))
+ out.append(t("gateway.usage.breakdown_line", label=label, count="~" + _fmt(tokens), pct=f"~{pct}"))
return out if len(out) > 1 else []
except Exception:
return []
diff --git a/hermes_cli/cli_info_mixin.py b/hermes_cli/cli_info_mixin.py
index 44e158f052..0d7fbbd6ca 100644
--- a/hermes_cli/cli_info_mixin.py
+++ b/hermes_cli/cli_info_mixin.py
@@ -713,7 +713,9 @@ class CLIInfoMixin:
print(f" API calls: {calls:>10,}")
print(f" Session duration: {elapsed:>10}")
print(f" {'─' * 40}")
- print(f" Current context: {last_prompt:,} / {ctx_len:,} ({pct:.0f}%)")
+ from agent.context_breakdown import context_display_source
+ mark = "~" if context_display_source(compressor) != "provider_usage" else ""
+ print(f" Current context: {mark}{last_prompt:,} / {ctx_len:,} ({mark}{pct:.0f}%)")
print(f" Messages: {len(self.conversation_history)}")
print(f" Compressions: {compressor.compression_count}")
diff --git a/hermes_cli/cli_status_bar_mixin.py b/hermes_cli/cli_status_bar_mixin.py
index 78e2914b53..1e9a7c7076 100644
--- a/hermes_cli/cli_status_bar_mixin.py
+++ b/hermes_cli/cli_status_bar_mixin.py
@@ -273,6 +273,8 @@ class CLIStatusBarMixin:
# last_prompt_tokens parks at the -1 sentinel right after a compression until the
# next real API call; clamp so the bar never renders "-1/200K".
context_tokens = max(0, getattr(compressor, "last_prompt_tokens", 0) or 0)
+ from agent.context_breakdown import context_display_source
+ snapshot["context_estimated"] = context_display_source(compressor) != "provider_usage"
# Display-only anchoring: on reasoning models a long tool loop replays the turn's
# thinking on every request, so the LAST request's prompt_tokens can exceed the
# durable transcript by hundreds of K and the bar sawtooths at the turn boundary.
@@ -288,6 +290,11 @@ class CLIStatusBarMixin:
charge_stale_thinking=False)
if _anchored is not None and _anchored > 0:
context_tokens = _anchored
+ anchor = agent._turn_base_usage_anchor
+ delta = _msgs[int(anchor["base_count"]):]
+ if delta and delta[0].get("role") == "assistant":
+ delta = delta[1:]
+ snapshot["context_estimated"] = bool(delta)
except Exception:
pass
context_length = max(0, getattr(compressor, "context_length", 0) or 0)
@@ -1003,12 +1010,13 @@ class CLIStatusBarMixin:
add("duration", _DIM, duration_label)
else:
percent = snapshot["context_percent"]
- percent_label = f"{percent}%" if percent is not None else "--"
+ mark = "~" if snapshot.get("context_estimated") else ""
+ percent_label = f"{mark}{percent}%" if percent is not None else "--"
if wide and _ok("context_detail"):
if snapshot["context_length"]:
ctx_total = _format_context_length(snapshot["context_length"])
ctx_used = format_token_count_compact(snapshot["context_tokens"])
- context_label = f"{ctx_used}/{ctx_total}"
+ context_label = f"{mark}{ctx_used}/{ctx_total}"
else:
context_label = "ctx --"
segs.append([(_DIM, context_label)])
diff --git a/tests/agent/test_context_display_provenance.py b/tests/agent/test_context_display_provenance.py
new file mode 100644
index 0000000000..3aeea146ec
--- /dev/null
+++ b/tests/agent/test_context_display_provenance.py
@@ -0,0 +1,38 @@
+"""Estimated occupancy must not masquerade as provider usage (or vice versa)."""
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from agent.context_breakdown import compute_session_context_breakdown, render_context_breakdown_lines
+from agent.context_compressor import ContextCompressor
+from agent.usage_anchor import capture_usage_anchor
+
+
+def test_context_provenance_follows_the_selected_number():
+ comp = ContextCompressor(model="fixture", config_context_length=100_000, quiet_mode=True)
+ agent = SimpleNamespace(context_compressor=comp, tools=[], model="fixture")
+ messages = [{"role": "user", "content": "fixture question"}]
+ with patch("agent.system_prompt.build_system_prompt_parts", return_value={"stable": "fixture"}):
+ for source in ("local_estimate", "provider_usage", "provider_usage_plus_estimate"):
+ if source == "provider_usage":
+ comp.update_from_response({"prompt_tokens": 1234, "completion_tokens": 20})
+ agent._usage_anchor = capture_usage_anchor(1234, 20, messages)
+ messages.append({"role": "assistant", "content": "fixture answer"})
+ elif source == "provider_usage_plus_estimate":
+ messages.append({"role": "user", "content": "a new unpriced question"})
+ data = compute_session_context_breakdown(agent, messages)
+ assert data.get("context_source") == source
+ estimated = source != "provider_usage"
+ assert data.get("context_estimated") is estimated
+ summary = next(s for s in render_context_breakdown_lines(data) if s.startswith("Context window:"))
+ assert ("Context window: ~" in summary) is estimated
+
+
+def test_preflight_seed_does_not_label_actual_usage_estimated():
+ from tui_gateway.server import _get_usage
+ comp = ContextCompressor(model="fixture", config_context_length=100_000, quiet_mode=True)
+ agent = SimpleNamespace(context_compressor=comp, model="fixture")
+ comp.maybe_seed_preflight_display_tokens(1234)
+ assert _get_usage(agent).get("context_estimated") is True
+ comp.update_from_response({"prompt_tokens": 1234, "completion_tokens": 20})
+ assert _get_usage(agent).get("context_estimated") is False
+ assert _get_usage(agent)["context_used"] == 1234
diff --git a/tui_gateway/methods_session.py b/tui_gateway/methods_session.py
index b85d53e6ba..167e573a49 100644
--- a/tui_gateway/methods_session.py
+++ b/tui_gateway/methods_session.py
@@ -1150,7 +1150,9 @@ def _(rid, params: dict, session: dict) -> dict:
"categories": [], "context_max": usage.get("context_max", 0) or 0,
"context_percent": usage.get("context_percent", 0) or 0,
"context_used": usage.get("context_used", 0) or 0,
- "estimated_total": usage.get("context_used", 0) or usage.get("total", 0) or 0,
+ "estimated_total": 0,
+ "context_estimated": usage.get("context_estimated", False),
+ "context_source": usage.get("context_source", "provider_usage"),
"model": _metadata_mirror(session).get("model", "")})
with session["history_lock"]:
history = list(session.get("history", []))
diff --git a/tui_gateway/methods_slash.py b/tui_gateway/methods_slash.py
index 5a7dc6751f..9a556fb174 100644
--- a/tui_gateway/methods_slash.py
+++ b/tui_gateway/methods_slash.py
@@ -67,7 +67,8 @@ def _format_live_usage_output(sid: str, session: dict, arg: str) -> str:
("Total tokens:", n("total")), ("API calls:", n("calls"))]
if usage.get("context_max"):
pct = int(usage.get("context_percent") or 0)
- rows.append(("Current context:", f"{n('context_used')} / {n('context_max')} ({pct}%)"))
+ mark = "~" if usage.get("context_estimated") else ""
+ rows.append(("Current context:", f"{mark}{n('context_used')} / {n('context_max')} ({mark}{pct}%)"))
rows += [("Messages:", f"{message_count:,}"), ("Compressions:", n("compressions"))]
model = usage.get("model") or _metadata_mirror(session).get("model") or getattr(agent, "model", "") or "(unknown)"
lines = ["Session Token Usage", "────────────────────────────────────────", f"Model: {model}"]
@@ -133,13 +134,14 @@ def _format_live_context_output(sid: str, session: dict, arg: str) -> str:
if model := mirror.get("model") or usage.get("model") or "":
lines.append(f"Model: {model}")
lines.append(f"Provider: {mirror.get('provider') or 'auto'}")
- context_used = int(usage.get("context_used") or usage.get("total") or 0)
+ context_used = int(usage.get("context_used") or 0)
+ mark = "~" if usage.get("context_estimated") else ""
context_max = int(usage.get("context_max") or 0)
if context_used and context_max:
lines.append(
- f"Context usage: ~{context_used:,} / {context_max:,} tokens ({(context_used / context_max) * 100:.1f}%)")
+ f"Context usage: {mark}{context_used:,} / {context_max:,} tokens ({mark}{(context_used / context_max) * 100:.1f}%)")
elif context_used:
- lines.append(f"Context usage: ~{context_used:,} tokens")
+ lines.append(f"Context usage: {mark}{context_used:,} tokens")
if usage.get("compressions"):
lines.append(f"Compressions: {int(usage.get('compressions') or 0):,}")
return "\n".join(lines)
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index 60fd932aa2..6e050072aa 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -1901,25 +1901,8 @@ def _get_usage(agent) -> dict:
}
comp = getattr(agent, "context_compressor", None)
if comp:
- # context_used is *current-window* occupancy — never usage["total"] (cumulative: an external engine
- # showed 1.9m/120k clamped to 100%). Falsy last_prompt_tokens emits NO gauge; the -1 "compression
- # just ran" sentinel clamps to 0 (matches cli.py _get_status_bar_snapshot).
- # Do NOT fall back to usage["total"] (cumulative lifetime session_total_tokens): for an external
- # context engine that doesn't report last_prompt_tokens that substitution showed lifetime totals as
- # the live context fill, yielding impossible readings such as 1.9m/120k clamped to 100% (#50421).
- # Per the issue, populate context_used/percent only from a *real* current-occupancy value and "leave
- # it unknown otherwise" — so a falsy last_prompt_tokens (0 or missing, i.e. an engine that doesn't
- # track per-window occupancy) intentionally emits no gauge rather than a fabricated 0% or the old
- # cumulative reading. The built-in compressor always reports a real last_prompt_tokens once a turn
- # runs, so it is unaffected. Clamp the -1 "compression just ran, awaiting real usage" sentinel
- # (conversation_compression.py) to 0 so the transitional turn reads as unknown (no gauge) instead of
- # leaking context_used=-1.
- last_prompt = max(0, getattr(comp, "last_prompt_tokens", 0) or 0)
- ctx_max = getattr(comp, "context_length", 0) or 0
- if ctx_max and last_prompt:
- usage.update(
- context_used=last_prompt, context_max=ctx_max,
- context_percent=max(0, min(100, round(last_prompt / ctx_max * 100))))
+ from agent.context_breakdown import context_usage_fields
+ usage.update(context_usage_fields(comp))
usage["compressions"] = getattr(comp, "compression_count", 0) or 0
# Cache-hit ratio + rolling latency/tps (CLI status-bar parity). Omitted, not fabricated, when there is no
# data (Codex reports no latency; zero cache reads shows no hit% rather than an alarming 0).
diff --git a/ui-tui/src/__tests__/appChromeStatusRule.test.tsx b/ui-tui/src/__tests__/appChromeStatusRule.test.tsx
index 24966c7995..500e5924dc 100644
--- a/ui-tui/src/__tests__/appChromeStatusRule.test.tsx
+++ b/ui-tui/src/__tests__/appChromeStatusRule.test.tsx
@@ -105,6 +105,20 @@ const baseProps = {
}
describe('StatusRule session title', () => {
+ it('marks only estimated context occupancy at every visible width', () => {
+ for (const cols of [80, 120, 200]) {
+ for (const estimated of [true, false]) {
+ const text = textContent(StatusRule({
+ ...baseProps, cols,
+ statusBarFields: new Set(['context_detail']),
+ usage: { ...baseProps.usage, context_estimated: estimated }
+ }))
+
+ expect(text.includes('~')).toBe(estimated)
+ }
+ }
+ })
+
it('pins the named session at the far-right edge instead of the cwd label', () => {
const element = StatusRule({
...baseProps,
diff --git a/ui-tui/src/app/slash/commands/session.ts b/ui-tui/src/app/slash/commands/session.ts
index c920fb5f58..ee6da350fb 100644
--- a/ui-tui/src/app/slash/commands/session.ts
+++ b/ui-tui/src/app/slash/commands/session.ts
@@ -743,7 +743,8 @@ export const sessionCommands: SlashCommand[] = [
const sections: PanelSection[] = [{ rows }]
if (r.context_max) {
- sections.push({ text: `Context: ${f(r.context_used)} / ${f(r.context_max)} (${r.context_percent}%)` })
+ const mark = r.context_estimated ? '~' : ''
+ sections.push({ text: `Context: ${mark}${f(r.context_used)} / ${f(r.context_max)} (${mark}${r.context_percent}%)` })
}
if (r.compressions) {
diff --git a/ui-tui/src/components/appChrome.tsx b/ui-tui/src/components/appChrome.tsx
index 6d12ea8b21..d49f13aa0b 100644
--- a/ui-tui/src/components/appChrome.tsx
+++ b/ui-tui/src/components/appChrome.tsx
@@ -510,6 +510,7 @@ export function StatusRule({
t
}: StatusRuleProps) {
const pct = usage.context_percent
+ const contextMark = usage.context_estimated ? '~' : ''
const barColor = ctxBarColor(pct, t)
const segs = statusBarSegments(cols)
@@ -523,8 +524,8 @@ export function StatusRule({
ok('context_detail') || ok('context_pct')
? usage.context_max
? segs.compactCtx
- ? `${fmtK(usage.context_used ?? 0)} tok`
- : `${fmtK(usage.context_used ?? 0)}/${fmtK(usage.context_max)}`
+ ? `${contextMark}${fmtK(usage.context_used ?? 0)} tok`
+ : `${contextMark}${fmtK(usage.context_used ?? 0)}/${fmtK(usage.context_max)}`
: usage.total > 0
? `${fmtK(usage.total)} tok`
: ''
@@ -603,7 +604,7 @@ export function StatusRule({
? `Δ ${(usage.dev_credits_spent_micros / 10000).toFixed(1)}¢`
: ''
- const showBar = !!bar && fits(SEP + stringWidth(`[${bar}] ${pct != null ? `${pct}%` : ''}`))
+ const showBar = !!bar && fits(SEP + stringWidth(`[${bar}] ${pct != null ? `${contextMark}${pct}%` : ''}`))
const showDuration = segs.duration && ok('duration') && !!sessionStartedAt && fits(SEP + MAX_DURATION_WIDTH)
// Idle clock — time since the last final agent response. Hidden while busy
@@ -730,7 +731,7 @@ export function StatusRule({
{showBar ? (
{' │ '}
- [{bar}] {pct != null ? `${pct}%` : ''}
+ [{bar}] {pct != null ? `${contextMark}${pct}%` : ''}
) : null}
{showDuration ? (
diff --git a/ui-tui/src/gatewayTypes.ts b/ui-tui/src/gatewayTypes.ts
index b2c2fd5955..212bfbf8f1 100644
--- a/ui-tui/src/gatewayTypes.ts
+++ b/ui-tui/src/gatewayTypes.ts
@@ -284,6 +284,8 @@ export interface SessionUsageResponse {
compressions?: number
context_max?: number
context_percent?: number
+ context_estimated?: boolean
+ context_source?: string
context_used?: number
cost_status?: 'estimated' | 'exact'
cost_usd?: number
diff --git a/ui-tui/src/types.ts b/ui-tui/src/types.ts
index 1b016da56f..7671e0f85f 100644
--- a/ui-tui/src/types.ts
+++ b/ui-tui/src/types.ts
@@ -220,6 +220,8 @@ export interface Usage {
compressions?: number
context_max?: number
context_percent?: number
+ context_estimated?: boolean
+ context_source?: string
context_used?: number
cost_status?: string
cost_usd?: number
diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md
index da7ea37bb0..cd7355a12e 100644
--- a/website/docs/user-guide/cli.md
+++ b/website/docs/user-guide/cli.md
@@ -143,7 +143,7 @@ A persistent status bar sits above the input area, updating in real time:
| Element | Description |
|---------|-------------|
| Model name | Current model (truncated if longer than 26 chars) |
-| Token count | Context tokens used / max context window |
+| Token count | Context tokens used / max context window; `~` marks an estimate |
| Context bar | Visual fill indicator with color-coded thresholds |
| Cost | Estimated session cost (or `n/a` for unknown/zero-priced models) |
| 🗜️ N | **Context compression count** — how many times the running session has been auto-compressed. Appears once the first compression fires. |
@@ -152,6 +152,8 @@ A persistent status bar sits above the input area, updating in real time:
| Session title | Once the session has a title, it appears as a gold badge pinned to the far-right edge. Long titles truncate before displacing the essential model and context fields. |
| ⚠ YOLO | **YOLO mode warning** — shown whenever `HERMES_YOLO_MODE` is on (either `hermes --yolo` at launch or `/yolo` toggled mid-session). Mirrors the banner-line warning so you can't forget you're in auto-approve mode. |
+A `~` before a context count or percentage means it includes a local estimate. This also applies to gateway `/status` and `/context`, the TUI, and the Desktop context gauge. An unchanged provider-usage reading has no `~`; a provider anchor plus unpriced new messages does. `/context` reports the selected source. Category, free-space, skill, and toolset breakdowns are always local estimates, even when the overall occupancy comes from provider usage. These display labels do not change compaction decisions or make extra provider requests.
+
The bar adapts to terminal width — full layout at ≥ 76 columns, compact at 52–75, minimal (model + duration, plus the YOLO badge when active) below 52.
**Context color coding:**