Skip to content

The agent that grows with you

fix(gateway): fill the context breakdown without a live agent

unsupportedpastelsc9b067feb7ed
diff --git a/agent/context_breakdown.py b/agent/context_breakdown.py
index 6d9fedec6c5..a720ff321f1 100644
--- a/agent/context_breakdown.py
+++ b/agent/context_breakdown.py
@@ -140,9 +140,40 @@ def context_usage_fields(compressor: Any) -> dict[str, Any]:
"context_source": source, "context_estimated": source != "provider_usage"}
+def _categories(system_prompt: str, skills: str, tools: Sequence[dict], messages: list[dict],
+ rules: str = "", memory: str = "") -> dict[str, Any]:
+ """The category list in display order and its estimated total."""
+ from agent.model_metadata import estimate_messages_tokens_rough
+ builtin_tools, mcp_tools, subagent_tools = _split_tools(tools)
+ tokens_by_id = {
+ "system_prompt": _chars_to_tokens(system_prompt),
+ "tool_definitions": _json_tokens(builtin_tools),
+ "rules": _chars_to_tokens(rules),
+ "skills": _chars_to_tokens(skills),
+ "mcp": _json_tokens(mcp_tools),
+ "subagent_definitions": _json_tokens(subagent_tools),
+ "memory": _chars_to_tokens(memory),
+ "conversation": estimate_messages_tokens_rough(messages),
+ }
+ return {
+ "categories": [
+ {"color": color, "id": category_id, "label": _category_label(category_id), "tokens": tokens_by_id[category_id]}
+ for category_id, (color, _glyph_) in _CATEGORIES.items()
+ if tokens_by_id[category_id] > 0 or category_id in _ALWAYS_REPORTED
+ ],
+ "estimated_total": sum(tokens_by_id.values()),
+ }
+
+
+def stored_context_breakdown(system_prompt: str, tools: Sequence[dict], messages: list[dict]) -> dict[str, Any]:
+ """Categories and estimated total from a frozen system prompt and tool schemas, without an agent. Only an
+ agent re-renders the prompt's tiers apart, so ``rules`` and ``memory`` count inside ``system_prompt``."""
+ skills_index = _skills_block(system_prompt)
+ return _categories(_strip_blocks(system_prompt, skills_index), skills_index, tools, messages)
+
+
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
from agent.usage_anchor import anchored_context_tokens
from agent.system_prompt import build_system_prompt_parts
@@ -154,18 +185,9 @@ def compute_session_context_breakdown(agent: Any, messages: Optional[list[dict]]
system_prompt_text = _join(
_strip_blocks(stable, skills_index), _strip_blocks(parts.get("volatile", "") or "", memory_block, user_block)
)
- builtin_tools, mcp_tools, subagent_tools = _split_tools(list(getattr(agent, "tools", None) or []))
- tokens_by_id = {
- "system_prompt": _chars_to_tokens(system_prompt_text),
- "tool_definitions": _json_tokens(builtin_tools),
- "rules": _chars_to_tokens(parts.get("context", "") or ""),
- "skills": _chars_to_tokens(skills_index),
- "mcp": _json_tokens(mcp_tools),
- "subagent_definitions": _json_tokens(subagent_tools),
- "memory": _chars_to_tokens(_join(memory_block, user_block)),
- "conversation": estimate_messages_tokens_rough(messages),
- }
- estimated_total = sum(tokens_by_id.values())
+ breakdown = _categories(system_prompt_text, skills_index, list(getattr(agent, "tools", None) or []), messages,
+ rules=parts.get("context", "") or "", memory=_join(memory_block, user_block))
+ estimated_total = breakdown["estimated_total"]
comp = getattr(agent, "context_compressor", None)
context_max = int(getattr(comp, "context_length", 0) or 0) if comp else 0
@@ -194,17 +216,12 @@ def compute_session_context_breakdown(agent: Any, messages: Optional[list[dict]]
context_used = min(context_used, context_max)
return {
- "categories": [
- {"color": color, "id": category_id, "label": _category_label(category_id), "tokens": tokens_by_id[category_id]}
- for category_id, (color, _glyph_) in _CATEGORIES.items()
- if tokens_by_id[category_id] > 0 or category_id in _ALWAYS_REPORTED
- ],
+ **breakdown,
"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 "",
}
diff --git a/gateway/session_tui_reads.py b/gateway/session_tui_reads.py
index 262328cf5d0..fc16f1ee14b 100644
--- a/gateway/session_tui_reads.py
+++ b/gateway/session_tui_reads.py
@@ -11,6 +11,7 @@ from __future__ import annotations
import asyncio
import contextlib
+import json
from collections import Counter
from pathlib import Path
@@ -36,6 +37,12 @@ def _stored_id(authority, ref) -> str:
return ref.session_id
+def _context_id(authority, ref) -> str:
+ """The compression tip the session's model context lives in; the runtime id may still name a parent."""
+ stored = _stored_id(authority, ref)
+ return authority.db.get_compression_tip(stored) or stored
+
+
def _status(authority, ref, live, policy, agent, arg) -> str:
"""``tui_gateway/methods_session.py`` ``session.status`` on main, for the owner's session."""
from hermes_cli.status_report import build_status_fields, status_lines
@@ -66,7 +73,7 @@ def _status(authority, ref, live, policy, agent, arg) -> str:
def _context(authority, ref, live, policy, agent, arg) -> str:
"""Main's ``_format_live_context_output``: counts by role, model/provider, then the category
table off the live agent (``render_context_breakdown_lines(grid=False)``), else the stored usage."""
- stored = _stored_id(authority, ref)
+ stored = _context_id(authority, ref)
rows = []
with contextlib.suppress(Exception):
rows = authority.db.get_messages_as_conversation(stored, include_ancestors=True, include_row_ids=True)
@@ -77,8 +84,7 @@ def _context(authority, ref, live, policy, agent, arg) -> str:
with contextlib.suppress(Exception):
from agent.context_breakdown import (
compute_context_details, compute_session_context_breakdown, render_context_breakdown_lines)
- conversation = authority.db.get_messages_as_conversation(stored, include_ancestors=True)
- payload = compute_session_context_breakdown(agent, conversation)
+ payload = compute_session_context_breakdown(agent, authority.db.get_resume_conversations(stored)[0])
details = None
if arg.strip().lower() in {'all', 'full', 'details'}:
with contextlib.suppress(Exception):
@@ -119,9 +125,10 @@ async def run_tui_read(authority, ref, live, policy, render, arg) -> dict:
async def context_breakdown(connection, ref, params) -> dict:
"""``session.context_breakdown`` on the owner: the category estimate (``compute_session_context_
- breakdown``) and context-file manifest of this session's resident agent over its stored
- transcript, built in the session's workspace. Before the agent exists: empty categories plus the
- session's stored usage (the contract's pre-build shape)."""
+ breakdown``) and context-file manifest of this session's resident agent over its compression tip's
+ model history, built in the session's workspace. With no resident agent (not run since the gateway
+ started, or reaped): the same categories from what the session froze (``_stored_breakdown``) beside
+ its stored usage."""
from gateway.session_busy_controls import authorize
from hermes_state_runtime import RuntimeStoreError
if set(params) - {'session_id', 'profile'} or not isinstance(ref.session_id, str) or not ref.session_id:
@@ -132,39 +139,53 @@ async def context_breakdown(connection, ref, params) -> dict:
if live is None:
raise RuntimeStoreError('not_found')
agent = authority.agent(ref)
+ usage = None
if agent is None:
from gateway.session_usage import stats
usage = await stats(connection, ref, {'session_id': ref.session_id})
usage = usage.get('usage') if isinstance(usage.get('usage'), dict) else usage
- return {'categories': [], 'context_max': int(usage.get('context_max') or 0),
- 'context_percent': int(usage.get('context_percent') or 0),
- 'context_used': int(usage.get('context_used') or 0), 'estimated_total': 0,
- 'context_estimated': bool(usage.get('context_estimated', False)),
- 'context_source': str(usage.get('context_source') or 'provider_usage'),
- 'model': str(usage.get('model') or '')}
from gateway.session_authorities import owner_scope
from gateway.session_commands import _session_workspace
- stored = _stored_id(authority, ref)
def build():
from agent.context_breakdown import compute_session_context_breakdown
from agent.context_file_sources import context_file_sources_for_agent
with owner_scope(authority), _session_workspace(authority.runner, live.source):
+ tip = _context_id(authority, ref)
# A revision probe is two indexed reads; the rebuild walks the whole transcript and the
# system prompt. Reuse the payload while neither the transcript nor the agent moved.
- key = (id(agent), _agent_context_marks(agent),
- authority.db.conversation_revision(stored, include_ancestors=True))
+ key = (id(agent), _agent_context_marks(agent), authority.db.conversation_revision(tip))
cached = live.context_breakdown
if cached is not None and cached[0] == key:
return dict(cached[1])
- conversation = authority.db.get_messages_as_conversation(stored, include_ancestors=True)
- payload = compute_session_context_breakdown(agent, conversation)
- payload['context_files'] = context_file_sources_for_agent(agent)
+ # The display history keeps superseded compression segments; only the model projection
+ # (the tip's active rows, no session_meta) is the working context.
+ conversation = authority.db.get_resume_conversations(tip)[0]
+ if agent is None:
+ payload = _stored_breakdown(authority.db.get_session(tip) or {}, conversation, usage)
+ else:
+ payload = compute_session_context_breakdown(agent, conversation)
+ payload['context_files'] = context_file_sources_for_agent(agent)
live.context_breakdown = (key, payload)
return dict(payload)
return await asyncio.to_thread(build)
+def _stored_breakdown(row, conversation, usage) -> dict:
+ """``stored_context_breakdown`` over the session row's frozen system prompt and tools[] pin, beside its
+ stored usage. A legacy name-only pin has no schemas to measure."""
+ from agent.context_breakdown import stored_context_breakdown
+ breakdown = {'categories': [], 'estimated_total': 0}
+ # No prompt until an agent first built one: nothing to measure yet, the contract's pre-build shape.
+ if prompt := row.get('system_prompt'):
+ pin = json.loads(row.get('tool_names') or 'null')
+ breakdown = stored_context_breakdown(prompt, pin['tools'] if isinstance(pin, dict) else [], conversation)
+ return {**breakdown, 'context_max': int(usage.get('context_max') or 0),
+ 'context_percent': int(usage.get('context_percent') or 0), 'context_used': int(usage.get('context_used') or 0),
+ 'context_estimated': bool(usage.get('context_estimated', False)),
+ 'context_source': str(usage.get('context_source') or 'provider_usage'), 'model': str(usage.get('model') or '')}
+
+
def _agent_context_marks(agent) -> tuple:
"""What the breakdown reads off the agent besides the transcript: model, toolset size, window,
measured prompt tokens, compressions and the usage anchors."""
diff --git a/tests/gateway/test_tui_context_breakdown_scope.py b/tests/gateway/test_tui_context_breakdown_scope.py
new file mode 100644
index 00000000000..34301d27482
--- /dev/null
+++ b/tests/gateway/test_tui_context_breakdown_scope.py
@@ -0,0 +1,69 @@
+"""``session.context_breakdown`` (Desktop context popover) and TUI ``/context`` measure the compression
+tip's model history, and the popover's categories survive a session with no resident agent."""
+from types import SimpleNamespace
+
+import pytest
+
+from tests.gateway import test_tui_session_reads as reads
+
+owner = reads.owner
+
+
+async def test_context_breakdown_without_a_resident_agent_estimates_the_stored_freeze(owner, monkeypatch):
+ """A session not run since the gateway started (or reaped) still gets the agent path's categories,
+ from its frozen system prompt and tools[] pin, over its stored transcript."""
+ from agent import system_prompt
+ from agent.context_breakdown import compute_session_context_breakdown
+ from gateway.session_tui_reads import _stored_id
+
+ sid = (await owner.call('session.create', request_id='idle', source='tui', cwd=str(owner.workdir)))['session_id']
+ db = owner.authority.db
+ stored = _stored_id(owner.authority, SimpleNamespace(session_id=sid))
+ prompt = 'You are Hermes. ' * 50 + '\n<available_skills>\n - plan: write plans\n</available_skills>'
+ tools = [{'type': 'function', 'function': {'name': 'terminal', 'parameters': {'type': 'object'}}},
+ {'type': 'function', 'function': {'name': 'mcp_docs_search', 'description': 'search ' * 20}}]
+ db.update_system_prompt(stored, prompt)
+ db.update_session_tool_names(stored, {'version': 'v', 'tools': tools})
+ db.append_message(stored, 'user', 'hello ' * 100)
+ db.append_message(stored, 'assistant', 'hi')
+ assert owner.authority.agent(SimpleNamespace(session_id=sid)) is None
+
+ monkeypatch.setattr(system_prompt, 'build_system_prompt_parts', lambda a: {'stable': prompt})
+ expected = compute_session_context_breakdown(SimpleNamespace(tools=tools), db.get_resume_conversations(stored)[0])
+ actual = await owner.call('session.context_breakdown', session_id=sid)
+ assert actual['categories'] == expected['categories'], actual
+ assert {c['id'] for c in actual['categories']} == {'system_prompt', 'tool_definitions', 'skills', 'mcp',
+ 'conversation'}
+ assert actual['estimated_total'] == expected['estimated_total']
+
+
+async def test_context_breakdown_measures_only_the_compression_tips_model_history(owner, monkeypatch):
+ """The runtime id still names the compressed parent; neither its superseded segment nor the tip's
+ session bookkeeping is model context, in the popover or the TUI's /context table."""
+ from agent import system_prompt
+ from agent.context_breakdown import compute_session_context_breakdown, render_context_breakdown_lines
+ from gateway.session_tui_reads import _stored_id
+
+ sid = (await owner.call('session.create', request_id='lineage', source='tui', cwd=str(owner.workdir)))['session_id']
+ db = owner.authority.db
+ root = _stored_id(owner.authority, SimpleNamespace(session_id=sid))
+ for i in range(4):
+ db.append_message(root, 'user' if i % 2 == 0 else 'assistant', f'old segment {i} ' * 1000)
+ db.end_session(root, 'compression')
+ db.create_session('tip', source='tui', parent_session_id=root)
+ db.append_message('tip', 'session_meta', 'not model input ' * 1000)
+ db.append_message('tip', 'user', 'summary of prior turns')
+ db.append_message('tip', 'assistant', 'current answer')
+ agent = SimpleNamespace(model='fake-model', provider='custom', tools=[])
+ owner.authority.runner._cached_agent_for = lambda route: agent
+ monkeypatch.setattr(system_prompt, 'build_system_prompt_parts', lambda a: {'stable': 'frozen identity'})
+
+ model_history = db.get_resume_conversations('tip')[0]
+ assert [m['content'] for m in model_history] == ['summary of prior turns', 'current answer']
+ expected = compute_session_context_breakdown(agent, model_history)
+ actual = await owner.call('session.context_breakdown', session_id=sid)
+ assert actual['categories'] == expected['categories'], actual
+ assert actual['estimated_total'] == expected['estimated_total']
+ assert '\n'.join(render_context_breakdown_lines(expected, grid=False)) in await reads._exec(owner, sid, 'context')