turn_summary.py 8.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209
  1. """Per-turn accounting for the interactive CLI (display-only, pure).
  2. :class:`TurnSummaryCollector` rides the ``tool_progress_callback`` feed (``tool.completed``
  3. events carry the tool name and raw result) and tallies what a turn did — no agent-loop state
  4. is threaded through. :func:`format_turn_summary` renders a tally plus wall-clock duration
  5. into one dim line: ``⋯ 12.4s · edited 2 files +18 -3 · read 4 files · ran 3 commands``.
  6. :func:`format_token_flow` is the spinner-side cumulative token readout (``↓ 1.2k tok``).
  7. """
  8. from __future__ import annotations
  9. import json
  10. from dataclasses import dataclass, field
  11. from typing import Any
  12. __all__ = [
  13. "TurnSummaryCollector",
  14. "TurnTally",
  15. "format_elapsed",
  16. "format_token_flow",
  17. "format_turn_summary",
  18. ]
  19. SUMMARY_PREFIX = "⋯" # terminal chrome, deliberately not an emoji
  20. # A tool-less turn faster than this is a plain chat reply: formatter returns "".
  21. _MIN_TOOLLESS_SECONDS = 2.0
  22. # Max "verb + count" segments before collapsing the rest into "+N more".
  23. _MAX_SEGMENTS = 4
  24. # Tool name -> (verb, singular noun, plural noun), past tense. Unlisted tools (plugin/MCP)
  25. # fall into a generic "called N tools" bucket.
  26. _VERB_GROUPS: dict[str, tuple[str, str, str]] = {
  27. "write_file": ("edited", "file", "files"),
  28. "patch": ("edited", "file", "files"),
  29. "read_file": ("read", "file", "files"),
  30. "web_extract": ("read", "page", "pages"),
  31. "terminal": ("ran", "command", "commands"),
  32. "execute_code": ("ran", "script", "scripts"),
  33. "search_files": ("searched", "path", "paths"),
  34. "web_search": ("searched the web", "time", "times"),
  35. "session_search": ("searched sessions", "time", "times"),
  36. "browser_navigate": ("browsed", "page", "pages"),
  37. "skill_view": ("read", "skill", "skills"),
  38. "skill_manage": ("updated", "skill", "skills"),
  39. "skills_list": ("listed skills", "time", "times"),
  40. "todo_list": ("updated", "task list", "task lists"),
  41. "delegate_task": ("delegated", "task", "tasks"),
  42. "memory": ("updated", "memory", "memories"),
  43. }
  44. _EDIT_VERB = "edited" # verb group that carries file-edit line deltas (+X -Y) when known
  45. # Render order: edits first, then reads, then commands; others in first-seen order.
  46. _VERB_PRIORITY: tuple[str, ...] = ("edited", "read", "ran")
  47. # Tools whose results may report a unified diff we can count lines from.
  48. _DIFF_RESULT_TOOLS = frozenset({"patch"})
  49. @dataclass
  50. class TurnTally:
  51. """What a single turn did, as observed from the tool-progress feed."""
  52. # verb -> {noun_plural: count}; insertion order gives stable rendering.
  53. verbs: dict[str, dict[str, int]] = field(default_factory=dict)
  54. other_tools: int = 0
  55. lines_added: int = 0
  56. lines_removed: int = 0
  57. # True once an edit tool reported a countable diff ("+0 -0" vs "unknown").
  58. has_line_deltas: bool = False
  59. @property
  60. def total_tools(self) -> int:
  61. return sum(sum(nouns.values()) for nouns in self.verbs.values()) + self.other_tools
  62. def _extract_line_deltas(tool_name: str, result: Any) -> tuple[int, int] | None:
  63. """(added, removed) from a tool result that already reports a diff, else None.
  64. Never shells out to git or re-reads files; ``+++``/``---`` headers excluded."""
  65. if tool_name not in _DIFF_RESULT_TOOLS:
  66. return None
  67. payload: Any = result
  68. if isinstance(payload, str):
  69. text = payload.strip()
  70. if not text.startswith("{"):
  71. return None
  72. try:
  73. # strict=False tolerates raw control chars inside an embedded diff.
  74. payload = json.loads(text, strict=False)
  75. except Exception:
  76. return None
  77. if not isinstance(payload, dict):
  78. return None
  79. diff = payload.get("diff")
  80. if not isinstance(diff, str) or not diff.strip():
  81. return None
  82. body = [ln for ln in diff.splitlines() if not ln.startswith(("+++", "---"))]
  83. added = sum(ln.startswith("+") for ln in body)
  84. removed = sum(ln.startswith("-") for ln in body)
  85. # A diff with no +/- content lines tells us nothing: unknown, not "+0 -0".
  86. if added == 0 and removed == 0:
  87. return None
  88. return added, removed
  89. class TurnSummaryCollector:
  90. """Accumulate per-turn tool tallies from the CLI's ``_on_tool_progress`` feed."""
  91. def __init__(self) -> None:
  92. self._tally = TurnTally()
  93. def begin(self) -> None:
  94. """Start a fresh turn (drops any prior tally)."""
  95. self._tally = TurnTally()
  96. def record_tool(self, tool_name: str | None, *, result: Any = None, is_error: bool = False) -> None:
  97. """Record one completed tool call. Failed calls are skipped: "edited 2 files"
  98. when one write was denied is exactly the over-claim to avoid."""
  99. # Internal/pseudo tools (``_thinking``) are not user-visible work.
  100. if not tool_name or is_error or tool_name.startswith("_"):
  101. return
  102. group = _VERB_GROUPS.get(tool_name)
  103. if group is None:
  104. self._tally.other_tools += 1
  105. return
  106. verb, _singular, plural = group
  107. nouns = self._tally.verbs.setdefault(verb, {})
  108. nouns[plural] = nouns.get(plural, 0) + 1
  109. if verb == _EDIT_VERB:
  110. deltas = _extract_line_deltas(tool_name, result)
  111. if deltas is not None:
  112. added, removed = deltas
  113. self._tally.lines_added += added
  114. self._tally.lines_removed += removed
  115. self._tally.has_line_deltas = True
  116. @property
  117. def tally(self) -> TurnTally:
  118. return self._tally
  119. def render(self, elapsed_seconds: float) -> str:
  120. return format_turn_summary(elapsed_seconds, self._tally)
  121. def format_elapsed(seconds: float) -> str:
  122. """``12.4s`` / ``2m05s``."""
  123. seconds = max(seconds, 0.0)
  124. if seconds < 60:
  125. return f"{seconds:.1f}s"
  126. minutes, rest = divmod(round(seconds), 60)
  127. return f"{minutes}m{rest:02d}s"
  128. def _pluralize(count: int, plural_noun: str) -> str:
  129. """``"1 file"`` / ``"3 files"`` from a plural noun form."""
  130. if count != 1:
  131. return f"{count} {plural_noun}"
  132. for suffix, singular_tail in (("ies", "y"), ("ses", "s"), ("s", "")):
  133. if plural_noun.endswith(suffix):
  134. return f"1 {plural_noun[:-len(suffix)]}{singular_tail}"
  135. return f"1 {plural_noun}"
  136. def format_turn_summary(elapsed_seconds: float, tally: TurnTally | None, *, max_segments: int = _MAX_SEGMENTS) -> str:
  137. """Render the per-turn accounting line, or ``""`` when there's nothing to say.
  138. Pure; gating (``display.turn_summary``, quiet mode, CLI-only) is the caller's job."""
  139. if tally is None:
  140. tally = TurnTally()
  141. ordered = [v for v in _VERB_PRIORITY if v in tally.verbs] + [v for v in tally.verbs if v not in _VERB_PRIORITY]
  142. segments: list[str] = []
  143. for verb in ordered:
  144. parts = [_pluralize(count, plural) for plural, count in tally.verbs[verb].items() if count]
  145. if not parts:
  146. continue
  147. segment = f"{verb} {', '.join(parts)}"
  148. if verb == _EDIT_VERB and tally.has_line_deltas:
  149. segment += f" +{tally.lines_added} -{tally.lines_removed}"
  150. segments.append(segment)
  151. if tally.other_tools:
  152. segments.append(f"called {_pluralize(tally.other_tools, 'tools')}")
  153. if not segments and tally.total_tools == 0 and elapsed_seconds < _MIN_TOOLLESS_SECONDS:
  154. return ""
  155. if max_segments > 0 and len(segments) > max_segments:
  156. hidden = len(segments) - max_segments
  157. segments = segments[:max_segments] + [f"+{hidden} more"]
  158. return f"{SUMMARY_PREFIX} " + " · ".join([format_elapsed(elapsed_seconds)] + segments)
  159. def format_token_flow(output_tokens: Any, *, arrow: str = "↓") -> str:
  160. """Cumulative turn tokens for the live spinner (``↓ 1.2k tok``); ``""`` for a
  161. non-positive count so nothing misleading shows before the first response."""
  162. try:
  163. count = int(output_tokens)
  164. except (TypeError, ValueError):
  165. return ""
  166. if count <= 0:
  167. return ""
  168. if count < 1000:
  169. return f"{arrow} {count} tok"
  170. if count < 1_000_000:
  171. return f"{arrow} {count / 1000:.1f}k tok"
  172. return f"{arrow} {count / 1_000_000:.1f}M tok"