fix(display): distinguish estimated context from provider usage

This commit is contained in:
Teknium
2026-09-07 03:38:40 -07:00
parent 283e677ed6
commit 04767e7aaa
21 changed files with 315 additions and 60 deletions
+47 -10
View File
@@ -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."])
+6 -1
View File
@@ -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": (
@@ -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(
<ContextUsagePanel breakdown={breakdown} loading={false} usage={{ ...usage, context_estimated: estimated }} />
)
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(<ContextUsagePanel breakdown={breakdown} loading={false} usage={usage} />)
@@ -40,11 +40,11 @@ export function ContextUsagePanel({ breakdown, loading, usage }: ContextUsagePan
<p className="font-medium text-foreground">{copy.title}</p>
<span className="text-[0.6875rem] text-muted-foreground">
{copy.tokenSummary(`~${compactNumber(contextUsed)}`, compactNumber(contextMax))}
{copy.tokenSummary(`${usage.context_estimated ? "~" : ""}${compactNumber(contextUsed)}`, compactNumber(contextMax))}
</span>
</div>
<p className="text-[0.6875rem] text-foreground">{copy.percentFull(contextPercent)}</p>
<p className="text-[0.6875rem] text-foreground">{usage.context_estimated ? '~' : ''}{copy.percentFull(contextPercent)}</p>
<ContextUsageBar categories={categories} segmentTotal={segmentTotal} />
@@ -57,7 +57,7 @@ export function ContextUsagePanel({ breakdown, loading, usage }: ContextUsagePan
<span className="truncate text-muted-foreground">{category.label}</span>
</span>
<span className="shrink-0 tabular-nums text-foreground">{compactNumber(category.tokens)}</span>
<span className="shrink-0 tabular-nums text-foreground">~{compactNumber(category.tokens)}</span>
</li>
))}
</ul>
@@ -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
+2 -2
View File
@@ -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
+4
View File
@@ -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
@@ -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()
+17 -11
View File
@@ -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 []
+3 -1
View File
@@ -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}")
+10 -2
View File
@@ -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)])
@@ -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
+3 -1
View File
@@ -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", []))
+6 -4
View File
@@ -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)
+2 -19
View File
@@ -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).
@@ -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,
+2 -1
View File
@@ -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) {
+5 -4
View File
@@ -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 ? (
<Text color={t.color.muted} wrap="truncate-end">
{' │ '}
<Text color={barColor}>[{bar}]</Text> <Text color={barColor}>{pct != null ? `${pct}%` : ''}</Text>
<Text color={barColor}>[{bar}]</Text> <Text color={barColor}>{pct != null ? `${contextMark}${pct}%` : ''}</Text>
</Text>
) : null}
{showDuration ? (
+2
View File
@@ -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
+2
View File
@@ -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
+3 -1
View File
@@ -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:**