context_breakdown.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364
  1. """Live session context-window breakdown for UI surfaces.
  2. Estimates system prompt tiers, tool schemas, and conversation history for the
  3. category breakdown. Overall occupancy retains its provider-usage or estimate
  4. provenance; category estimates are not exact tokenizer counts or gate authority.
  5. """
  6. from __future__ import annotations
  7. import json
  8. import re
  9. from typing import Any, Dict, List, Optional, Sequence, Tuple
  10. from agent.i18n import t
  11. _SKILLS_BLOCK_RE = re.compile(r"<available_skills>.*?</available_skills>", re.DOTALL)
  12. _SUBAGENT_TOOL_NAMES = frozenset({"delegate_task"})
  13. # A category at zero tokens is dropped from the payload, which reads as "not
  14. # configured" - true for MCP, memory and skills, and false for the
  15. # conversation. Every session has one, so hiding the row at zero makes an empty
  16. # transcript indistinguishable from a breakdown that never measured it (#87903).
  17. #
  18. # The membership rule, stated so a later addition argues from the same
  19. # principle rather than from "this one felt important": a category belongs
  20. # here when zero is a MEASUREMENT of something every session has, not the
  21. # ABSENCE of something optional. "conversation" qualifies because a session
  22. # cannot not have a transcript, so zero means "nothing said yet" and is worth
  23. # showing. "mcp", "memory", "skills" and "subagent_definitions" do not: zero
  24. # there means the user configured none, which is what dropping the row already
  25. # communicates, and a permanent 0-token row would be noise on most hosts.
  26. # "system_prompt" and "tool_definitions" are always present too but are never
  27. # zero in practice, so adding them would buy nothing.
  28. _ALWAYS_REPORTED = frozenset({"conversation"})
  29. # id -> (dashboard color, /context glyph); declaration order is display order. The label is
  30. # ``gateway.context.category.<id>`` resolved when the payload is built (never at import).
  31. _CATEGORIES = {
  32. "system_prompt": ("var(--context-usage-system)", "■"),
  33. "tool_definitions": ("var(--context-usage-tools)", "▣"),
  34. "rules": ("var(--context-usage-rules)", "▩"),
  35. "skills": ("var(--context-usage-skills)", "▤"),
  36. "mcp": ("var(--context-usage-mcp)", "▥"),
  37. "subagent_definitions": ("var(--context-usage-subagents)", "▦"),
  38. "memory": ("var(--context-usage-memory)", "▧"),
  39. "conversation": ("var(--context-usage-conversation)", "▨"),
  40. }
  41. def _category_label(category_id: str) -> str:
  42. return t(f"gateway.context.category.{category_id}")
  43. _FREE_GLYPH = "·"
  44. _CONTEXT_SOURCES = frozenset({"local_estimate", "provider_usage", "provider_usage_plus_estimate"})
  45. _GRID_COLUMNS = 20
  46. _GRID_ROWS = 5 # 100 cells → 1 cell per percent of the context window
  47. _DETAILS_TABLE_LIMIT = 15 # display cap only; the underlying data keeps everything
  48. def _chars_to_tokens(text: str) -> int:
  49. from agent.model_metadata import estimate_tokens_rough
  50. return estimate_tokens_rough(text)
  51. def _json_tokens(value: Any) -> int:
  52. return _chars_to_tokens(json.dumps(value, ensure_ascii=False)) if value else 0
  53. def _bytes_to_tokens(size: Optional[int]) -> Optional[int]:
  54. from agent.model_metadata import CHARS_PER_TOKEN
  55. return None if size is None else (int(size) + 3) // CHARS_PER_TOKEN
  56. def _skills_block(stable: str) -> str:
  57. """The live ``<available_skills>`` block inside the stable tier, or ''."""
  58. m = _SKILLS_BLOCK_RE.search(stable)
  59. return m.group(0) if m else ""
  60. def _split_tools(tools: Sequence[dict]) -> tuple[list[dict], list[dict], list[dict]]:
  61. builtin: list[dict] = []
  62. mcp: list[dict] = []
  63. subagent: list[dict] = []
  64. for tool in tools:
  65. fn = tool.get("function") if isinstance(tool, dict) else None
  66. name = str((fn if isinstance(fn, dict) else tool).get("name") or "")
  67. bucket = mcp if name.startswith("mcp_") else subagent if name in _SUBAGENT_TOOL_NAMES else builtin
  68. bucket.append(tool)
  69. return builtin, mcp, subagent
  70. def _memory_blocks(agent: Any) -> tuple[str, str]:
  71. memory_block = user_block = ""
  72. store = getattr(agent, "_memory_store", None)
  73. try:
  74. if store is not None and getattr(agent, "_memory_enabled", True):
  75. memory_block = store.format_for_system_prompt("memory") or ""
  76. if store is not None and getattr(agent, "_user_profile_enabled", True):
  77. user_block = store.format_for_system_prompt("user") or ""
  78. except Exception:
  79. pass
  80. return memory_block, user_block
  81. def _strip_blocks(text: str, *blocks: str) -> str:
  82. for block in blocks:
  83. if block:
  84. text = text.replace(block, "")
  85. return text.strip()
  86. def _join(*parts: str) -> str:
  87. return "\n\n".join(part for part in parts if part).strip()
  88. def _glyph(cat: dict[str, Any]) -> str:
  89. return _CATEGORIES.get(str(cat.get("id") or ""), (None, "▪"))[1]
  90. def context_display_source(compressor: Any) -> str:
  91. """Distinguish the built-in preflight display seed from a provider reading.
  92. Engines without the built-in real-usage ledger own their occupancy figure.
  93. A seed never updates that ledger, even if its number later matches real usage.
  94. """
  95. real = getattr(compressor, "last_real_prompt_tokens", None)
  96. shown = getattr(compressor, "last_prompt_tokens", 0) or 0
  97. return "local_estimate" if isinstance(real, (int, float)) and shown > 0 and shown != real else "provider_usage"
  98. def context_usage_fields(compressor: Any) -> dict[str, Any]:
  99. """Current occupancy only; lifetime throughput is never a context fallback."""
  100. used = max(0, getattr(compressor, "last_prompt_tokens", 0) or 0)
  101. maximum = getattr(compressor, "context_length", 0) or 0
  102. if not used or not maximum:
  103. return {}
  104. used = min(used, maximum)
  105. source = context_display_source(compressor)
  106. return {"context_used": used, "context_max": maximum,
  107. "context_percent": max(0, min(100, round(used / maximum * 100))),
  108. "context_source": source, "context_estimated": source != "provider_usage"}
  109. def _categories(system_prompt: str, skills: str, tools: Sequence[dict], messages: list[dict],
  110. rules: str = "", memory: str = "") -> dict[str, Any]:
  111. """The category list in display order and its estimated total."""
  112. from agent.model_metadata import estimate_messages_tokens_rough
  113. builtin_tools, mcp_tools, subagent_tools = _split_tools(tools)
  114. tokens_by_id = {
  115. "system_prompt": _chars_to_tokens(system_prompt),
  116. "tool_definitions": _json_tokens(builtin_tools),
  117. "rules": _chars_to_tokens(rules),
  118. "skills": _chars_to_tokens(skills),
  119. "mcp": _json_tokens(mcp_tools),
  120. "subagent_definitions": _json_tokens(subagent_tools),
  121. "memory": _chars_to_tokens(memory),
  122. "conversation": estimate_messages_tokens_rough(messages),
  123. }
  124. return {
  125. "categories": [
  126. {"color": color, "id": category_id, "label": _category_label(category_id), "tokens": tokens_by_id[category_id]}
  127. for category_id, (color, _glyph_) in _CATEGORIES.items()
  128. if tokens_by_id[category_id] > 0 or category_id in _ALWAYS_REPORTED
  129. ],
  130. "estimated_total": sum(tokens_by_id.values()),
  131. }
  132. def stored_context_breakdown(system_prompt: str, tools: Sequence[dict], messages: list[dict]) -> dict[str, Any]:
  133. """Categories and estimated total from a frozen system prompt and tool schemas, without an agent. Only an
  134. agent re-renders the prompt's tiers apart, so ``rules`` and ``memory`` count inside ``system_prompt``."""
  135. skills_index = _skills_block(system_prompt)
  136. return _categories(_strip_blocks(system_prompt, skills_index), skills_index, tools, messages)
  137. def compute_session_context_breakdown(agent: Any, messages: Optional[list[dict]] = None) -> dict[str, Any]:
  138. """Return a Cursor-style context usage breakdown for one live agent."""
  139. from agent.usage_anchor import anchored_context_tokens
  140. from agent.system_prompt import build_system_prompt_parts
  141. messages = messages or []
  142. parts = build_system_prompt_parts(agent)
  143. stable = parts.get("stable", "") or ""
  144. skills_index = _skills_block(stable)
  145. memory_block, user_block = _memory_blocks(agent)
  146. system_prompt_text = _join(
  147. _strip_blocks(stable, skills_index), _strip_blocks(parts.get("volatile", "") or "", memory_block, user_block)
  148. )
  149. breakdown = _categories(system_prompt_text, skills_index, list(getattr(agent, "tools", None) or []), messages,
  150. rules=parts.get("context", "") or "", memory=_join(memory_block, user_block))
  151. estimated_total = breakdown["estimated_total"]
  152. comp = getattr(agent, "context_compressor", None)
  153. context_max = int(getattr(comp, "context_length", 0) or 0) if comp else 0
  154. # Usage-anchored figure (provider-exact tokens of a response + delta of what was
  155. # appended since) beats last_prompt_tokens (lags) and the heuristic. Prefer the
  156. # turn-base anchor: on reasoning models later same-turn responses inflate
  157. # prompt_tokens with replayed thinking that evaporates at the turn boundary, so
  158. # anchoring on the LAST response makes the meter sawtooth. Fall back to the
  159. # last-response anchor, then measured, then estimated.
  160. anchor = getattr(agent, "_turn_base_usage_anchor", None)
  161. context_used = anchored_context_tokens(messages, anchor, charge_stale_thinking=False)
  162. if context_used is None:
  163. anchor = getattr(agent, "_usage_anchor", None)
  164. context_used = anchored_context_tokens(messages, anchor)
  165. if context_used is None:
  166. measured_used = int(getattr(comp, "last_prompt_tokens", 0) or 0) if comp else 0
  167. context_used = measured_used if measured_used > 0 else estimated_total
  168. source = context_display_source(comp) if measured_used > 0 else "local_estimate"
  169. else:
  170. delta = messages[int(anchor["base_count"]):]
  171. if delta and delta[0].get("role") == "assistant":
  172. delta = delta[1:]
  173. source = "provider_usage_plus_estimate" if delta else "provider_usage"
  174. # A single prompt can never exceed the model window; any excess is estimate drift.
  175. if context_max:
  176. context_used = min(context_used, context_max)
  177. return {
  178. **breakdown,
  179. "context_max": context_max,
  180. "context_percent": max(0, min(100, round(context_used / context_max * 100))) if context_max else 0,
  181. "context_used": context_used,
  182. "context_source": source,
  183. "context_estimated": source != "provider_usage",
  184. "model": getattr(agent, "model", "") or "",
  185. }
  186. def compute_context_details(agent: Any) -> dict[str, Any]:
  187. """Expanded per-skill / per-toolset cost listing for ``/context all``.
  188. Reuses the ``hermes prompt-size`` attribution (index-line bytes from the
  189. live skills block; schema bytes via the registry's tool→toolset map).
  190. """
  191. from hermes_cli.prompt_size import _compute_skills_breakdown, _compute_toolsets_breakdown
  192. from agent.system_prompt import build_system_prompt_parts
  193. skills_block = _skills_block(build_system_prompt_parts(agent).get("stable", "") or "")
  194. tools = list(getattr(agent, "tools", None) or [])
  195. return {
  196. "skills": [
  197. {
  198. "name": entry.get("name", ""),
  199. "index_tokens": _bytes_to_tokens(entry.get("index_line_bytes")) or 0,
  200. "skill_md_tokens": _bytes_to_tokens(entry.get("skill_md_bytes")),
  201. }
  202. for entry in (_compute_skills_breakdown(skills_block) if skills_block else [])
  203. ],
  204. "toolsets": [
  205. {
  206. "toolset": group.get("toolset", ""),
  207. "tool_count": int(group.get("tool_count", 0) or 0),
  208. "schema_tokens": _bytes_to_tokens(group.get("json_bytes")) or 0,
  209. }
  210. for group in (_compute_toolsets_breakdown(tools) if tools else [])
  211. ],
  212. }
  213. # ── /context rendering (CLI + gateway) ──────────────────────────────────────
  214. # Pure text renderers over the payload above. The gateway skips the glyph grid
  215. # (monospace is not guaranteed on messaging platforms).
  216. def render_context_grid(payload: dict[str, Any]) -> list[str]:
  217. """Glyph grid: 100 cells, one per percent of the context window; categories
  218. fill in declaration order, the remainder is free space."""
  219. context_max = int(payload.get("context_max") or 0)
  220. total_cells = _GRID_COLUMNS * _GRID_ROWS
  221. cells: list[str] = []
  222. if context_max > 0:
  223. for cat in payload.get("categories") or []:
  224. tokens = int(cat.get("tokens") or 0)
  225. # never render a nonzero category as invisible
  226. n = round(tokens / context_max * total_cells) or (1 if tokens > 0 else 0)
  227. cells.extend([_glyph(cat)] * n)
  228. cells = cells[:total_cells]
  229. cells.extend([_FREE_GLYPH] * (total_cells - len(cells)))
  230. return [" ".join(cells[row * _GRID_COLUMNS:(row + 1) * _GRID_COLUMNS]) for row in range(_GRID_ROWS)]
  231. def render_context_category_lines(payload: dict[str, Any]) -> list[str]:
  232. """Render the 'Estimated usage by category' table as plain-text lines."""
  233. categories = payload.get("categories") or []
  234. context_max = int(payload.get("context_max") or 0)
  235. estimated_total = int(payload.get("estimated_total") or 0)
  236. denom = context_max or estimated_total
  237. lines = [t("gateway.context.category_header")]
  238. if not categories:
  239. return [*lines, t("gateway.context.no_data_yet")]
  240. free_label = t("gateway.context.free_space")
  241. width = max(len(free_label), *(len(str(cat.get("label") or "")) for cat in categories))
  242. for cat in categories:
  243. tokens, label = int(cat.get("tokens") or 0), str(cat.get("label") or cat.get("id") or "")
  244. lines.append(t("gateway.context.category_row", glyph=_glyph(cat), label=f"{label:<{width}}",
  245. tokens=f"{tokens:>9,}", pct=f"{tokens / denom * 100 if denom else 0.0:>5.1f}"))
  246. if context_max > 0:
  247. free = max(0, context_max - estimated_total)
  248. lines.append(t("gateway.context.category_row", glyph=_FREE_GLYPH, label=f"{free_label:<{width}}",
  249. tokens=f"{free:>9,}", pct=f"{free / context_max * 100:>5.1f}"))
  250. return lines
  251. def _toolset_row(group: dict[str, Any]) -> str:
  252. return t("gateway.context.toolset_row", toolset=f"{group['toolset']:<24}", count=f"{group['tool_count']:>3}",
  253. tokens=f"{group['schema_tokens']:>8,}")
  254. def _skill_row(entry: dict[str, Any]) -> str:
  255. name = str(entry.get("name") or "")
  256. if len(name) > 28:
  257. name = name[:27] + "…"
  258. md = entry.get("skill_md_tokens")
  259. md_str = f"~{md:>8,}" if md is not None else f"{t('gateway.context.not_available'):>8}"
  260. return t("gateway.context.skill_row", name=f"{name:<28}", index_tokens=f"{entry['index_tokens']:>6,}", md_tokens=md_str)
  261. def _table(lines: list[str], title: str, rows: list[dict[str, Any]], fmt) -> None:
  262. """Append a titled, display-capped table (blank-separated from a preceding one)."""
  263. if not rows:
  264. return
  265. if lines:
  266. lines.append("")
  267. lines.append(title)
  268. lines.extend(fmt(row) for row in rows[:_DETAILS_TABLE_LIMIT])
  269. if len(rows) > _DETAILS_TABLE_LIMIT:
  270. lines.append(t("gateway.context.and_more", count=len(rows) - _DETAILS_TABLE_LIMIT))
  271. def render_context_details_lines(details: dict[str, Any]) -> list[str]:
  272. """Render the expanded ``/context all`` per-skill / per-toolset tables."""
  273. lines: list[str] = []
  274. _table(lines, t("gateway.context.toolsets_title"), details.get("toolsets") or [], _toolset_row)
  275. _table(lines, t("gateway.context.skills_title"), details.get("skills") or [], _skill_row)
  276. return lines
  277. def render_context_breakdown_lines(
  278. payload: dict[str, Any],
  279. *,
  280. details: Optional[dict[str, Any]] = None,
  281. grid: bool = True,
  282. ) -> list[str]:
  283. """Full /context view. ``grid`` prepends the glyph grid (CLI; the gateway
  284. keeps its own gauge); ``details`` appends the expanded listings."""
  285. lines: list[str] = [*render_context_grid(payload), ""] if grid else []
  286. lines.extend(render_context_category_lines(payload))
  287. context_max = int(payload.get("context_max") or 0)
  288. if context_max > 0:
  289. used, pct = int(payload.get("context_used") or 0), int(payload.get("context_percent") or 0)
  290. mark = "~" if payload.get("context_estimated") else ""
  291. lines.extend(["", t("gateway.context.window_line", mark=mark, used=f"{used:,}", max=f"{context_max:,}", pct=pct)])
  292. source = payload.get("context_source")
  293. if source:
  294. source_label = t(f"gateway.context.source.{source}") if source in _CONTEXT_SOURCES else source
  295. lines.append(t("gateway.context.source_line", source=source_label))
  296. if details is None:
  297. lines.extend(["", t("gateway.context.hint_all")])
  298. elif detail_lines := render_context_details_lines(details):
  299. lines.extend(["", *detail_lines])
  300. return lines