session_usage.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239
  1. """Session-cumulative usage for a local viewer (wave A2 / CALLMAP W3).
  2. Main's HermesCLI read its status bar (context, ``◷`` latency, ``t/s``, the spinner's ``↓ N tok``),
  3. ``/usage`` and the exit summary straight off the in-process agent's ``session_*`` counters,
  4. ``context_compressor`` and ``get_rate_limit_state()``. On the session authority the agent lives in
  5. the gateway, so the same numbers are projected here: published as ``session.usage`` after every API
  6. call and at turn end of a local-viewer turn, and returned by the ``session.stats`` verb.
  7. """
  8. from __future__ import annotations
  9. import contextlib
  10. import dataclasses
  11. import time
  12. _COUNTERS = (("input_tokens", "session_input_tokens"), ("output_tokens", "session_output_tokens"),
  13. ("cache_read_tokens", "session_cache_read_tokens"),
  14. ("cache_write_tokens", "session_cache_write_tokens"),
  15. ("prompt_tokens", "session_prompt_tokens"), ("completion_tokens", "session_completion_tokens"),
  16. ("total_tokens", "session_total_tokens"), ("reasoning_tokens", "session_reasoning_tokens"),
  17. ("api_calls", "session_api_calls"))
  18. # The output-token count at the start of the viewer's current turn (``↓ N tok`` on main's spinner).
  19. TURN_BASE_ATTR = "_viewer_turn_output_base"
  20. def _finite(value):
  21. return round(float(value), 2) if value is not None and value == value and 0 < value < 1e6 else None
  22. def _context(agent, compressor) -> dict:
  23. """Main's status-bar context figures (``_get_status_bar_snapshot``), clamped the same way."""
  24. if compressor is None:
  25. return {"last_prompt_tokens": 0, "context_tokens": 0, "context_length": None,
  26. "config_context_length": None, "context_source": None, "compression_count": 0}
  27. from agent.context_breakdown import context_display_source
  28. last = max(0, getattr(compressor, "last_prompt_tokens", 0) or 0)
  29. tokens = last
  30. with contextlib.suppress(Exception):
  31. from agent.usage_anchor import anchored_context_tokens
  32. messages = getattr(agent, "_session_messages", None)
  33. anchored = anchored_context_tokens(messages if isinstance(messages, list) else [],
  34. getattr(agent, "_turn_base_usage_anchor", None),
  35. charge_stale_thinking=False)
  36. if anchored is not None and anchored > 0:
  37. tokens = anchored
  38. length = max(0, getattr(compressor, "context_length", 0) or 0)
  39. return {"last_prompt_tokens": last, "context_tokens": min(tokens, length) if length else tokens,
  40. "context_length": length or None,
  41. "config_context_length": getattr(compressor, "_config_context_length", None),
  42. "context_source": context_display_source(compressor),
  43. "compression_count": getattr(compressor, "compression_count", 0) or 0}
  44. def _rate_limit(agent):
  45. with contextlib.suppress(Exception):
  46. state = agent.get_rate_limit_state()
  47. if state is not None and dataclasses.is_dataclass(state) and not isinstance(state, type):
  48. return dataclasses.asdict(state)
  49. return None
  50. def plan_gauge(agent) -> dict | None:
  51. """Window plans only: the allowance the status bar shows at a glance (today's, else the one that binds),
  52. from the reply headers the agent already tracks — no extra round trip, None for everyone else."""
  53. with contextlib.suppress(Exception):
  54. state = getattr(agent, "_credits_state", None)
  55. if getattr(state, "is_usage_window", False) is True: # `is True`: a Mock agent's attribute is not a plan
  56. binding = state.binding_gauge
  57. day = next((g for g in state.gauges if g.id == "day" and g.scope == "all"), None)
  58. # A full allowance is what blocks, so it wins over today's; a passed reset is no longer current.
  59. gauge = binding if binding is not None and binding.full else (day or binding)
  60. reset = getattr(gauge, "resets_at_ms", None)
  61. if gauge is not None and not (isinstance(reset, int) and 0 < reset <= int(time.time() * 1000)):
  62. return {"id": gauge.id, "label": gauge.label, "used_bp": int(gauge.used_bp),
  63. "resets_at_ms": gauge.resets_at_ms}
  64. return None
  65. def usage_stats(agent) -> dict:
  66. """The frozen ``session.usage`` / ``session.stats`` dict; zeros before the first turn built an agent."""
  67. stats: dict = {key: int(getattr(agent, attr, 0) or 0) for key, attr in _COUNTERS}
  68. stats.update(_context(agent, getattr(agent, "context_compressor", None)))
  69. avg_latency = tps = None
  70. with contextlib.suppress(Exception):
  71. latencies = list(getattr(agent, "_api_latency_history", None) or [])
  72. outputs = list(getattr(agent, "_api_output_history", None) or [])
  73. if n := min(len(latencies), len(outputs)):
  74. total = sum(latencies[-n:])
  75. avg_latency = _finite(total / n)
  76. tps = _finite(sum(outputs[-n:]) / total) if total > 0 else None
  77. active = 0
  78. with contextlib.suppress(Exception):
  79. from tools.async_delegation import active_count
  80. active = active_count()
  81. base = getattr(agent, TURN_BASE_ATTR, None)
  82. stats.update(avg_latency_s=avg_latency, tokens_per_s=tps,
  83. last_turn_tokens=max(0, stats["output_tokens"] - base) if isinstance(base, int) else 0,
  84. rate_limit=_rate_limit(agent) if agent is not None else None, active_subagents=active,
  85. model=str(getattr(agent, "model", "") or ""), provider=str(getattr(agent, "provider", "") or ""),
  86. fallback_model=(str(getattr(agent, "model", "") or "") or None)
  87. if getattr(agent, "_fallback_activated", False) is True else None)
  88. if (gauge := plan_gauge(agent)) is not None: # absent off a window plan, as on the embedded path
  89. stats["plan_gauge"] = gauge
  90. return stats
  91. def carried_compression_count(live, agent=None) -> int:
  92. """Compactions of this conversation: main's agent counted them on its compressor for the
  93. session's life. A canonical compress evicts the gateway's agent (a session boundary), so the
  94. count rides the live session and seeds the successor (``seed_compression_count``)."""
  95. own = getattr(getattr(agent, "context_compressor", None), "compression_count", 0)
  96. carried = getattr(live, "compression_count", 0)
  97. return max(carried if isinstance(carried, int) else 0, own if isinstance(own, int) else 0)
  98. def note_compression(authority, ref, live) -> None:
  99. """A committed (never an exact-retried) compress: one more compaction than the evicted agent saw."""
  100. agent = None
  101. with contextlib.suppress(AttributeError, KeyError): # a runner without an agent cache has none
  102. agent = authority.agent(ref)
  103. live.compression_count = carried_compression_count(live, agent) + 1
  104. def seed_compression_count(live, agent) -> None:
  105. compressor = getattr(agent, "context_compressor", None)
  106. if live is not None and compressor is not None:
  107. with contextlib.suppress(Exception):
  108. compressor.compression_count = carried_compression_count(live, agent)
  109. def tui_usage(stats: dict) -> dict:
  110. """``stats`` in main's TUI ``Usage`` shape (``tui_gateway/server.py::_get_usage``): the fields its
  111. status bar (context used/max/bar, ``◷`` latency, ``t/s``, ``cmp`` badge, cache hit) and ``/usage``
  112. read off ``message.complete.usage``. Absent figures are omitted, never fabricated as zeros."""
  113. usage = {"model": stats.get("model") or "", "input": stats.get("input_tokens") or stats.get("prompt_tokens") or 0,
  114. "output": stats.get("output_tokens") or stats.get("completion_tokens") or 0,
  115. "reasoning": stats.get("reasoning_tokens") or 0, "prompt": stats.get("prompt_tokens") or 0,
  116. "completion": stats.get("completion_tokens") or 0, "total": stats.get("total_tokens") or 0,
  117. "calls": stats.get("api_calls") or 0}
  118. used, maximum = stats.get("last_prompt_tokens") or 0, stats.get("context_length") or 0
  119. if used and maximum:
  120. # ``agent/context_breakdown.py::context_usage_fields``: current occupancy, clamped.
  121. used = min(used, maximum)
  122. source = stats.get("context_source") or "provider_usage"
  123. usage.update(context_used=used, context_max=maximum,
  124. context_percent=max(0, min(100, round(used / maximum * 100))),
  125. context_source=source, context_estimated=source != "provider_usage")
  126. if stats.get("context_source") is not None: # a compressor, sized or not (``_get_usage``'s ``if comp``)
  127. usage["compressions"] = stats.get("compression_count") or 0
  128. prompt_total, cache_read = stats.get("prompt_tokens") or 0, stats.get("cache_read_tokens") or 0
  129. if prompt_total > 0 and cache_read > 0:
  130. usage["cache_hit_pct"] = max(0, min(100, round(cache_read / prompt_total * 100)))
  131. for key, source_key in (("avg_latency_s", "avg_latency_s"), ("avg_tps", "tokens_per_s")):
  132. if isinstance(stats.get(source_key), (int, float)):
  133. usage[key] = round(float(stats[source_key]), 1)
  134. if isinstance(stats.get("active_subagents"), int):
  135. usage["active_subagents"] = stats["active_subagents"]
  136. if isinstance(stats.get("plan_gauge"), dict):
  137. usage["plan_gauge"] = stats["plan_gauge"]
  138. return usage
  139. def usage_frame(stats: dict) -> dict:
  140. """The ``session.usage`` event payload: BOTH views of the same counters, in one frame.
  141. ``SessionUsagePayload`` (``tui_gateway/contracts/events.py``) allows either view — the TUI
  142. ``usage`` object (``server._start_usage_ticker``) or the session-cumulative counters at the top
  143. level — and the readers on the far end want different halves. The classic CLI
  144. (``hermes_cli.gateway_connection.SessionState.apply_event``) keeps the top-level counters
  145. whenever they are present and ignores the nested view; ACP (``acp_adapter.gateway_server``)
  146. reads only the top level; a Desktop bundle older than ``usageFromTick`` reads only
  147. ``payload.usage``, so its context / cache-hit / tokens-per-second meters render their empty
  148. placeholder for as long as the frame carries the counters alone. Publishing both serves every
  149. viewer from one frame, and leaves the counters untouched for every existing consumer.
  150. ``usage`` is the standard status-bar projection of the embedded ticker's ``server._get_usage``
  151. view, with two exceptions: ``dev_credits_spent_micros`` (``HERMES_DEV_CREDITS`` only) is not
  152. carried, and ``avg_latency_s`` / ``avg_tps`` are rounded from the counters' two decimals rather
  153. than the raw values, so they can differ by 0.1 at a rounding boundary. A Desktop bundle that
  154. reads only ``payload.usage`` fills its meters here too. The
  155. top-level counters on this event are deprecated: new viewers read ``usage`` (or call
  156. ``session.stats`` for the counters). Before they can be dropped, these readers must move off
  157. them: the classic CLI's ``SessionState.apply_event`` → ``GatewayAgent.apply_session_usage``,
  158. ACP's ``_project_usage`` (``usage_update`` / ``turn_usage``), and the flat branch of
  159. ``usageFromTick`` (Desktop and Ink).
  160. """
  161. return {"usage": tui_usage(stats), **stats}
  162. def publish_usage(turn, agent, *, record: bool = False) -> None:
  163. """One ``session.usage`` frame on the viewer's stream; never breaks the turn. At turn end
  164. (``record``) the same dict rides the captured execution result, so the turn's
  165. ``message.complete`` carries main's ``usage`` (``session_settlement_recovery.completion_payload``)."""
  166. if agent is None:
  167. return
  168. with contextlib.suppress(Exception):
  169. stats = usage_stats(agent)
  170. turn._publish_execution("session.usage", usage_frame(stats))
  171. if record:
  172. from gateway.session_results import execution_result
  173. captured = execution_result.get()
  174. if captured is not None:
  175. captured["session_usage"] = stats
  176. _STORED_COUNTERS = ("input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens", "reasoning_tokens")
  177. def _stored_stats(row: dict) -> dict:
  178. """A session row's cumulative counters in ``usage_stats``' shape. The row's ``input_tokens`` excludes cache
  179. reads and writes, so the prompt total adds them back for the cache hit rate."""
  180. counts = {key: int(row.get(key) or 0) for key in _STORED_COUNTERS}
  181. return {**counts, "prompt_tokens": counts["input_tokens"] + counts["cache_read_tokens"] + counts["cache_write_tokens"],
  182. "completion_tokens": counts["output_tokens"], "total_tokens": counts["input_tokens"] + counts["output_tokens"],
  183. "api_calls": int(row.get("api_call_count") or 0), "model": row.get("model") or ""}
  184. def snapshot_usage(authority, ref, agent) -> dict | None:
  185. """The status-bar ``usage`` a resume / ``session.info`` snapshot carries, so a viewer switching to the
  186. session paints its own cache hit and ``t/s`` instead of the last-viewed session's. An agent that has
  187. called the model answers as its ``session.usage`` frames do; otherwise (no agent since a restart, or one
  188. not used yet) the stored row answers, with no ``t/s`` since latency is not stored."""
  189. if agent is not None and getattr(agent, "session_api_calls", 0):
  190. result = usage_stats(agent)
  191. result["compression_count"] = carried_compression_count(authority.sessions.get(ref.session_id), agent)
  192. return tui_usage(result)
  193. row = authority.db.get_session(ref.session_id)
  194. return tui_usage(_stored_stats(row)) if row else None
  195. async def stats(connection, ref, params):
  196. """``session.stats {session_id}``: the same dict ``session.usage`` carries."""
  197. from hermes_state_runtime import RuntimeStoreError
  198. if set(params) - {"session_id", "profile"}:
  199. raise RuntimeStoreError("invalid_params")
  200. await connection.authority.resolve(connection.actor, ref)
  201. agent = connection.authority.agent(ref)
  202. result = usage_stats(agent)
  203. result["compression_count"] = carried_compression_count(connection.authority.sessions.get(ref.session_id), agent)
  204. return result