nullius-eval 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (291) hide show
  1. _nullius_app/.env.example +55 -0
  2. _nullius_app/app.py +96 -0
  3. _nullius_app/requirements.txt +1 -0
  4. _nullius_app/static/brand/README.md +20 -0
  5. _nullius_app/static/brand/docker.svg +1 -0
  6. _nullius_app/static/brand/favicon.svg +1 -0
  7. _nullius_app/static/brand/huggingface.svg +37 -0
  8. _nullius_app/static/brand/mark-dark.svg +1 -0
  9. _nullius_app/static/brand/marks.svg +34 -0
  10. _nullius_app/static/brand/tokens.json +51 -0
  11. _nullius_app/static/brand/typesafe.png +0 -0
  12. _nullius_app/static/brand/wordmark-dark.svg +1 -0
  13. _nullius_app/static/builder/command-builder-core.js +763 -0
  14. _nullius_app/static/builder/command-builder.css +248 -0
  15. _nullius_app/static/builder/command-builder.js +997 -0
  16. _nullius_app/static/builder/model-picker.js +113 -0
  17. _nullius_app/static/catalogue/add.js +46 -0
  18. _nullius_app/static/catalogue/agents/README.md +19 -0
  19. _nullius_app/static/catalogue/agents/goose.svg +1 -0
  20. _nullius_app/static/catalogue/agents/jiuwenswarm.svg +33 -0
  21. _nullius_app/static/catalogue/agents/marks.json +8 -0
  22. _nullius_app/static/catalogue/agents/mini-swe-agent.svg +7 -0
  23. _nullius_app/static/catalogue/agents/opencode.svg +7 -0
  24. _nullius_app/static/catalogue/catalogue.css +436 -0
  25. _nullius_app/static/catalogue/catalogue.js +87 -0
  26. _nullius_app/static/catalogue/marks.svg +29 -0
  27. _nullius_app/static/catalogue/new.js +78 -0
  28. _nullius_app/static/catalogue/versions.js +27 -0
  29. _nullius_app/static/compare/comparison.css +117 -0
  30. _nullius_app/static/controls.js +117 -0
  31. _nullius_app/static/disclosures.js +70 -0
  32. _nullius_app/static/fonts/0569c822cab6c510.ttf +0 -0
  33. _nullius_app/static/fonts/DMSans-Medium.woff2 +0 -0
  34. _nullius_app/static/fonts/DMSans-Regular.woff2 +0 -0
  35. _nullius_app/static/fonts/IBMPlexMono-Medium.woff2 +0 -0
  36. _nullius_app/static/fonts/IBMPlexMono-Regular.woff2 +0 -0
  37. _nullius_app/static/fonts/InstrumentSerif-Italic.woff2 +0 -0
  38. _nullius_app/static/fonts/InstrumentSerif-Regular.woff2 +0 -0
  39. _nullius_app/static/fonts/README.md +11 -0
  40. _nullius_app/static/fonts/c1e7453ea26a1d1e.ttf +0 -0
  41. _nullius_app/static/fonts/dmsans-OFL.txt +93 -0
  42. _nullius_app/static/fonts/ibmplexmono-OFL.txt +93 -0
  43. _nullius_app/static/fonts/instrumentserif-OFL.txt +93 -0
  44. _nullius_app/static/fonts.css +49 -0
  45. _nullius_app/static/notifications.js +49 -0
  46. _nullius_app/static/onboarding.css +78 -0
  47. _nullius_app/static/onboarding.js +158 -0
  48. _nullius_app/static/runs/board.css +358 -0
  49. _nullius_app/static/runs/board.js +127 -0
  50. _nullius_app/static/runs/launches.css +88 -0
  51. _nullius_app/static/runs/live-board.css +186 -0
  52. _nullius_app/static/runs/live-board.js +394 -0
  53. _nullius_app/static/runs/path-suggestions.js +119 -0
  54. _nullius_app/static/runs/start.css +38 -0
  55. _nullius_app/static/settings/autosave.js +162 -0
  56. _nullius_app/static/settings/custom-keys.js +100 -0
  57. _nullius_app/static/settings/data-providers.js +88 -0
  58. _nullius_app/static/settings/judges.js +61 -0
  59. _nullius_app/static/settings/modal.css +32 -0
  60. _nullius_app/static/settings/modal.js +91 -0
  61. _nullius_app/static/settings/navigation.js +55 -0
  62. _nullius_app/static/settings/prices.js +68 -0
  63. _nullius_app/static/settings/providers.js +134 -0
  64. _nullius_app/static/settings/sandbox.js +20 -0
  65. _nullius_app/static/settings/settings.css +288 -0
  66. _nullius_app/static/style.css +1752 -0
  67. _nullius_app/static/traces/conversation.css +49 -0
  68. _nullius_app/static/traces/conversation.js +215 -0
  69. _nullius_app/templates/agents/entry.html +145 -0
  70. _nullius_app/templates/agents/kits.html +55 -0
  71. _nullius_app/templates/agents/standard.html +58 -0
  72. _nullius_app/templates/base.html +479 -0
  73. _nullius_app/templates/builder/new_run.html +55 -0
  74. _nullius_app/templates/catalogue/add_dialog.html +32 -0
  75. _nullius_app/templates/catalogue/benchmark.html +270 -0
  76. _nullius_app/templates/catalogue/benchmarks.html +91 -0
  77. _nullius_app/templates/catalogue/new.html +141 -0
  78. _nullius_app/templates/catalogue/use_bundle.html +11 -0
  79. _nullius_app/templates/compare/_detail.html +37 -0
  80. _nullius_app/templates/compare/compare.html +298 -0
  81. _nullius_app/templates/compare/compare_picker.html +51 -0
  82. _nullius_app/templates/compare/compare_task.html +329 -0
  83. _nullius_app/templates/runs/_execution.html +131 -0
  84. _nullius_app/templates/runs/_runtime.html +5 -0
  85. _nullius_app/templates/runs/ascii-mark.html +485 -0
  86. _nullius_app/templates/runs/feasibility.html +127 -0
  87. _nullius_app/templates/runs/index.html +609 -0
  88. _nullius_app/templates/runs/job.html +460 -0
  89. _nullius_app/templates/runs/preparing.html +14 -0
  90. _nullius_app/templates/runs/reconcile.html +124 -0
  91. _nullius_app/templates/runs/setup.html +272 -0
  92. _nullius_app/templates/runs/start.html +51 -0
  93. _nullius_app/templates/settings/custom_keys.html +82 -0
  94. _nullius_app/templates/settings/data_providers.html +27 -0
  95. _nullius_app/templates/settings/settings.html +564 -0
  96. _nullius_app/templates/traces/_charts.html +165 -0
  97. _nullius_app/templates/traces/_conversation.html +37 -0
  98. _nullius_app/templates/traces/_judgement.html +72 -0
  99. _nullius_app/templates/traces/artifact.html +15 -0
  100. _nullius_app/templates/traces/trial.html +838 -0
  101. _nullius_app/templates/workspaces/workspaces.html +54 -0
  102. _nullius_app/web/__init__.py +1 -0
  103. _nullius_app/web/agents.py +230 -0
  104. _nullius_app/web/builder.py +406 -0
  105. _nullius_app/web/catalogue.py +370 -0
  106. _nullius_app/web/compare.py +489 -0
  107. _nullius_app/web/core.py +17 -0
  108. _nullius_app/web/execute.py +223 -0
  109. _nullius_app/web/feasibility.py +60 -0
  110. _nullius_app/web/filters.py +231 -0
  111. _nullius_app/web/judge.py +623 -0
  112. _nullius_app/web/judge_tasks.py +33 -0
  113. _nullius_app/web/onboarding.py +20 -0
  114. _nullius_app/web/reconcile.py +47 -0
  115. _nullius_app/web/runs.py +464 -0
  116. _nullius_app/web/settings.py +324 -0
  117. _nullius_app/web/shared.py +507 -0
  118. _nullius_app/web/traces.py +306 -0
  119. _nullius_app/web/workspaces.py +84 -0
  120. nullius/__init__.py +32 -0
  121. nullius/__main__.py +5 -0
  122. nullius/catalogue/__init__.py +0 -0
  123. nullius/catalogue/agents/codex/agent.json +222 -0
  124. nullius/catalogue/agents/codex/config.toml +25 -0
  125. nullius/catalogue/agents/goose/agent.json +131 -0
  126. nullius/catalogue/agents/goose/config.yaml +20 -0
  127. nullius/catalogue/agents/jiuwenswarm/agent.json +197 -0
  128. nullius/catalogue/agents/jiuwenswarm/agent.py +355 -0
  129. nullius/catalogue/agents/mini-swe-agent/agent.json +68 -0
  130. nullius/catalogue/agents/mini-swe-agent/run.py +37 -0
  131. nullius/catalogue/agents/opencode/agent.json +135 -0
  132. nullius/catalogue/agents/opencode/opencode.json +32 -0
  133. nullius/catalogue/agents/reference/agent.json +89 -0
  134. nullius/catalogue/agents/reference/agent.py +209 -0
  135. nullius/catalogue/agents/terminus-2/agent.json +64 -0
  136. nullius/catalogue/agents/terminus-2/run.py +139 -0
  137. nullius/catalogue/benchmarks/gaia/benchmark.json +72 -0
  138. nullius/catalogue/benchmarks/gaia/data-source.json +29 -0
  139. nullius/catalogue/benchmarks/gaia/driver.py +188 -0
  140. nullius/catalogue/benchmarks/gaia/env/data.Dockerfile +1 -0
  141. nullius/catalogue/benchmarks/gaia/standard.json +278 -0
  142. nullius/catalogue/benchmarks/gaia/upstream-settings.json +275 -0
  143. nullius/catalogue/benchmarks/gsm8k/benchmark.json +34 -0
  144. nullius/catalogue/benchmarks/gsm8k/driver.py +101 -0
  145. nullius/catalogue/benchmarks/gsm8k/standard.json +124 -0
  146. nullius/catalogue/benchmarks/gsm8k/upstream-settings.json +86 -0
  147. nullius/catalogue/benchmarks/humaneval/benchmark.json +36 -0
  148. nullius/catalogue/benchmarks/humaneval/driver.py +243 -0
  149. nullius/catalogue/benchmarks/humaneval/standard.json +115 -0
  150. nullius/catalogue/benchmarks/humaneval/upstream-settings.json +72 -0
  151. nullius/catalogue/benchmarks/locomo/benchmark.json +43 -0
  152. nullius/catalogue/benchmarks/locomo/driver.py +270 -0
  153. nullius/catalogue/benchmarks/locomo/standard.json +265 -0
  154. nullius/catalogue/benchmarks/locomo/upstream-settings.json +112 -0
  155. nullius/catalogue/benchmarks/longmemeval/benchmark.json +65 -0
  156. nullius/catalogue/benchmarks/longmemeval/driver.py +379 -0
  157. nullius/catalogue/benchmarks/longmemeval/standard.json +733 -0
  158. nullius/catalogue/benchmarks/longmemeval/upstream-settings.json +76 -0
  159. nullius/catalogue/benchmarks/swe-bench-verified/benchmark.json +87 -0
  160. nullius/catalogue/benchmarks/swe-bench-verified/driver.py +116 -0
  161. nullius/catalogue/benchmarks/swe-bench-verified/images.json +502 -0
  162. nullius/catalogue/benchmarks/swe-bench-verified/standard.json +108 -0
  163. nullius/catalogue/benchmarks/swe-bench-verified/upstream-settings.json +32 -0
  164. nullius/catalogue/benchmarks/tau3-bench/benchmark.json +49 -0
  165. nullius/catalogue/benchmarks/tau3-bench/driver.py +608 -0
  166. nullius/catalogue/benchmarks/tau3-bench/mcp_server.py +114 -0
  167. nullius/catalogue/benchmarks/tau3-bench/search_relay.py +19 -0
  168. nullius/catalogue/benchmarks/tau3-bench/standard.json +547 -0
  169. nullius/catalogue/benchmarks/tau3-bench/upstream-settings.json +639 -0
  170. nullius/catalogue/benchmarks/terminal-bench/benchmark.json +69 -0
  171. nullius/catalogue/benchmarks/terminal-bench/driver.py +267 -0
  172. nullius/catalogue/benchmarks/terminal-bench/standard.json +166 -0
  173. nullius/catalogue/benchmarks/terminal-bench/upstream-settings.json +36 -0
  174. nullius/catalogue/capabilities/keyword-memory/capability.json +33 -0
  175. nullius/catalogue/capabilities/keyword-memory/capability.py +55 -0
  176. nullius/catalogue/capabilities/mem0/capability.json +135 -0
  177. nullius/catalogue/capabilities/mem0/capability.py +173 -0
  178. nullius/catalogue/catalog.py +426 -0
  179. nullius/catalogue/citation.py +116 -0
  180. nullius/catalogue/harbor_entry.py +367 -0
  181. nullius/catalogue/sources.py +107 -0
  182. nullius/catalogue/storage.py +125 -0
  183. nullius/cli.py +85 -0
  184. nullius/compare/__init__.py +0 -0
  185. nullius/compare/cli.py +265 -0
  186. nullius/compare/comparison.py +184 -0
  187. nullius/execution.py +1653 -0
  188. nullius/gitrefs.py +128 -0
  189. nullius/harbor/__init__.py +0 -0
  190. nullius/harbor/feed.py +228 -0
  191. nullius/harbor/source.py +582 -0
  192. nullius/hosts.py +368 -0
  193. nullius/importers/__init__.py +140 -0
  194. nullius/importers/atif.py +387 -0
  195. nullius/importers/cli.py +135 -0
  196. nullius/importers/otel.py +274 -0
  197. nullius/judge/__init__.py +14 -0
  198. nullius/judge/batch.py +122 -0
  199. nullius/judge/client.py +433 -0
  200. nullius/judge/floors.json +86 -0
  201. nullius/judge/lanes.py +89 -0
  202. nullius/judge/questions.py +309 -0
  203. nullius/judge/reconcile.py +176 -0
  204. nullius/judge/state.py +224 -0
  205. nullius/judge/store.py +167 -0
  206. nullius/migrate.py +268 -0
  207. nullius/onboarding.py +116 -0
  208. nullius/paths.py +89 -0
  209. nullius/prerequisites.py +129 -0
  210. nullius/prices.py +283 -0
  211. nullius/progress.py +294 -0
  212. nullius/providers.py +335 -0
  213. nullius/recipes/__init__.py +0 -0
  214. nullius/recipes/launch.py +78 -0
  215. nullius/redact.py +72 -0
  216. nullius/runs/__init__.py +0 -0
  217. nullius/runs/artifacts.py +67 -0
  218. nullius/runs/classify.py +216 -0
  219. nullius/runs/cli.py +316 -0
  220. nullius/runs/feasibility.py +442 -0
  221. nullius/runs/launches.py +149 -0
  222. nullius/runs/live.py +715 -0
  223. nullius/runs/parse.py +1016 -0
  224. nullius/runs/verifier.py +241 -0
  225. nullius/sandbox.py +109 -0
  226. nullius/secrets.py +218 -0
  227. nullius/settings.py +544 -0
  228. nullius/standard/__init__.py +15 -0
  229. nullius/standard/acp.py +305 -0
  230. nullius/standard/cancellation.py +19 -0
  231. nullius/standard/cli.py +703 -0
  232. nullius/standard/conform.py +149 -0
  233. nullius/standard/container.py +1870 -0
  234. nullius/standard/definitions.py +1651 -0
  235. nullius/standard/egress.py +192 -0
  236. nullius/standard/fidelity.py +256 -0
  237. nullius/standard/forward.py +139 -0
  238. nullius/standard/hostreq.py +105 -0
  239. nullius/standard/howto.py +220 -0
  240. nullius/standard/install.py +428 -0
  241. nullius/standard/job.py +551 -0
  242. nullius/standard/jsonl.py +129 -0
  243. nullius/standard/kits/agent-conversation-v1/driver.py +27 -0
  244. nullius/standard/kits/agent-conversation-v1/standard.json +26 -0
  245. nullius/standard/kits/agent-search-v1/driver.py +171 -0
  246. nullius/standard/kits/agent-search-v1/standard.json +99 -0
  247. nullius/standard/kits/agent-task-v1/driver.py +25 -0
  248. nullius/standard/kits/agent-task-v1/standard.json +100 -0
  249. nullius/standard/kits/agent-tools-v1/driver.py +206 -0
  250. nullius/standard/kits/agent-tools-v1/mcp_kit.py +209 -0
  251. nullius/standard/kits/agent-tools-v1/standard.json +119 -0
  252. nullius/standard/kits/agent-workspace-v1/driver.py +65 -0
  253. nullius/standard/kits/agent-workspace-v1/standard.json +95 -0
  254. nullius/standard/kits/cap-memory-v1/driver.py +39 -0
  255. nullius/standard/kits/cap-memory-v1/standard.json +91 -0
  256. nullius/standard/ledger.py +326 -0
  257. nullius/standard/match.py +66 -0
  258. nullius/standard/mcp_bridge.py +62 -0
  259. nullius/standard/mcp_machine.py +193 -0
  260. nullius/standard/merge.py +239 -0
  261. nullius/standard/names.py +37 -0
  262. nullius/standard/network_requirements.py +44 -0
  263. nullius/standard/pace.py +53 -0
  264. nullius/standard/payload.py +278 -0
  265. nullius/standard/pins.py +130 -0
  266. nullius/standard/ports.py +70 -0
  267. nullius/standard/prove.py +373 -0
  268. nullius/standard/recipe.py +746 -0
  269. nullius/standard/relay.py +785 -0
  270. nullius/standard/run.py +1781 -0
  271. nullius/standard/setup_container.py +208 -0
  272. nullius/standard/shard.py +71 -0
  273. nullius/standard/web_services.py +30 -0
  274. nullius/traces/__init__.py +0 -0
  275. nullius/traces/behavior.py +131 -0
  276. nullius/traces/charts.py +898 -0
  277. nullius/traces/conversation.py +159 -0
  278. nullius/traces/otel.py +608 -0
  279. nullius/traces/trace.py +1477 -0
  280. nullius/traces/trajectory.py +586 -0
  281. nullius/workspace.py +417 -0
  282. nullius/workspace_cli.py +119 -0
  283. nullius_eval-0.1.0.dist-info/METADATA +93 -0
  284. nullius_eval-0.1.0.dist-info/RECORD +291 -0
  285. nullius_eval-0.1.0.dist-info/WHEEL +5 -0
  286. nullius_eval-0.1.0.dist-info/entry_points.txt +2 -0
  287. nullius_eval-0.1.0.dist-info/licenses/LICENSE +202 -0
  288. nullius_eval-0.1.0.dist-info/licenses/app/static/fonts/dmsans-OFL.txt +93 -0
  289. nullius_eval-0.1.0.dist-info/licenses/app/static/fonts/ibmplexmono-OFL.txt +93 -0
  290. nullius_eval-0.1.0.dist-info/licenses/app/static/fonts/instrumentserif-OFL.txt +93 -0
  291. nullius_eval-0.1.0.dist-info/top_level.txt +2 -0
@@ -0,0 +1,1477 @@
1
+ """Load an agent trace (``agent/trace.json``) into rows for a waterfall.
2
+
3
+ A sidecar to the trajectory, not a replacement: where ``trajectory.json`` carries
4
+ one timestamp per step with no duration, a trace carries measured start *and*
5
+ end per LLM call, tool call and subagent, with causal parentage. It is the first
6
+ artefact in this tree that can say where the wall clock actually went.
7
+
8
+ Two rules shape everything here.
9
+
10
+ **One global time axis.** Bars are positioned against the whole trace, never
11
+ against their parent. Log-derived children routinely start *before* their OTel
12
+ parents, because the two come from different clocks; laying out relative to the
13
+ parent would force a clamp, and the clamp would hide exactly the discrepancy the
14
+ format exists to expose. A *zoom* (``Filter.zoom``) is not a per-parent layout:
15
+ it is one explicit window — a subtree's own extent — that the reader asks for,
16
+ and everything outside it is left out of the waterfall rather than re-scaled.
17
+
18
+ **Totals are the producer's job.** ``totals`` is displayed verbatim and never
19
+ recomputed from the tree — see :class:`Totals`. A filtered view is the one case
20
+ that needs its own arithmetic, because hiding a span has to move its time
21
+ somewhere and the producer cannot be asked again; that lives in
22
+ :class:`Breakdown`, is labelled as derived wherever it is shown, and never
23
+ overwrites what the file said.
24
+
25
+ Two normalisations happen on the way in, in that order, and they are the only
26
+ two. First, a call the exporter measured is given the log spans for the reply it
27
+ produced, which the producer writes as a second copy of the same call when it has
28
+ no request id to join them on. See :func:`fold_llm_requests`; it moves rows and
29
+ no numbers. Then a span that is a *namespace* for its children rather than an
30
+ event of its own is re-kinded ``group`` and reads ``Bash [group]``: Harbor's
31
+ Claude Code instrumentation opens a ``claude_code.tool`` span carrying
32
+ ``tool_name: "Bash"`` and puts the permission wait and the actual ``Bash``
33
+ execution inside it. Counting the wrapper as work would double-count the call.
34
+ See :func:`is_group` for what qualifies and, more importantly, for the near
35
+ misses that deliberately do not.
36
+
37
+ The order is load-bearing. An ``llm_request`` holding a single ``reasoning`` or
38
+ ``output`` block of byte-identical extent is the same
39
+ duplication :func:`fold_llm_requests` resolves, and it resolves it better: the
40
+ wrapper and its one block collapse into a single span carrying both the
41
+ request's tokens and the block's text, where re-kinding leaves two rows and
42
+ charges one of them nothing. Folding first leaves ``is_group`` only the wrappers
43
+ fold could not match to a call, which is the case it is still needed for.
44
+
45
+ Everything is redacted at load, so templates hold display text only. Stdlib
46
+ only, and no Flask: ``python3 -m unittest discover -s app/tests -t app`` needs no
47
+ install at all.
48
+ """
49
+
50
+ from __future__ import annotations
51
+
52
+ import bisect
53
+ import json
54
+ import math
55
+ from dataclasses import dataclass, field
56
+
57
+ from nullius.redact import redact
58
+
59
+ NS_PER_MS = 1_000_000
60
+
61
+ # A residual under this reads as float noise from the producer's own arithmetic,
62
+ # not as real unattributed time. Rendering it produces a zero-width segment with
63
+ # a legend entry saying "0ms".
64
+ UNACCOUNTED_EPSILON_NS = NS_PER_MS
65
+
66
+ # An exporter can emit thousands of spans for a trivial task. Every row is
67
+ # rendered server-side with its own detail pane, so the page has to be bounded.
68
+ MAX_ROWS = 2000
69
+
70
+ # Nesting past this is a malformed producer, not a deep agent. JSON cannot
71
+ # express a cycle, so `load` can never hit it — but `parse` takes a dict, and
72
+ # either way a runaway tree would exhaust the stack while building the spans,
73
+ # long before any of the guards downstream got a look.
74
+ MAX_DEPTH = 64
75
+
76
+ # Legend order. Not the enum's order — this groups the model's own production
77
+ # (llm/reasoning/output) together, then work, then structure.
78
+ KIND_ORDER = (
79
+ "llm_request", "reasoning", "output", "tool", "subagent",
80
+ "session", "user_message", "compaction", "group",
81
+ )
82
+
83
+ # What a namespace span becomes. A kind of its own rather than a flag, because
84
+ # every consumer already switches on `kind` — the swatch, the legend, the chart
85
+ # split, and `_KIND_CATEGORY` below, which by omitting it charges a group no time.
86
+ GROUP_KIND = "group"
87
+
88
+ # Said in the label, because the label is the only thing most of the page shows.
89
+ # Appended rather than substituted: "Bash [group]" and "Bash" sort together and
90
+ # read as the same call seen at two levels, which is what they are.
91
+ GROUP_SUFFIX = " [group]"
92
+
93
+ # How far a namespace span's children may fall short of covering it and still
94
+ # count as accounting for all of it.
95
+ #
96
+ # They never tile it exactly. Harbor stamps the wrapper to the millisecond and
97
+ # its children to the nanosecond, so each of the two boundaries is up to 1ms out,
98
+ # and children routinely overrun the parent they sit in — the same clock
99
+ # disagreement the global axis exists to show. Allow both boundaries' rounding.
100
+ GROUP_SLACK_NS = 2 * NS_PER_MS
101
+
102
+ # Kinds that already say they bracket their children. They are exempt from the
103
+ # normalisation below, which exists to stop a span *claiming to be work* when it
104
+ # is a container — a kind that never made the claim needs no correcting, and
105
+ # `_KIND_CATEGORY` already charges these nothing.
106
+ _BRACKET_KINDS = ("session", "subagent", GROUP_KIND)
107
+
108
+ # Breakdown segments, in a fixed left-to-right order. The order carries no
109
+ # meaning — these are categories, not a timeline — but a stable one keeps the
110
+ # strip from reshuffling between trials.
111
+ _SEGMENTS = (
112
+ ("llm", "LLM", "llm_ns"),
113
+ ("tool", "Tool", "tool_ns"),
114
+ ("reasoning", "Reasoning", "reasoning_ns"),
115
+ ("idle", "Idle", "idle_ns"),
116
+ )
117
+
118
+ # The residual is a segment like any other once it reaches a strip, and both
119
+ # `segments_of` and `Breakdown.compared_to` need to name and order it.
120
+ _UNACCOUNTED = ("unaccounted", "Unaccounted")
121
+ _SEGMENT_LABELS = {key: label for key, label, _ in _SEGMENTS} | {_UNACCOUNTED[0]: _UNACCOUNTED[1]}
122
+ _SEGMENT_ORDER = [key for key, _, _ in _SEGMENTS] + [_UNACCOUNTED[0]]
123
+
124
+ # What a span's own time counts toward when a breakdown has to be recomputed for
125
+ # a filtered view. The structural kinds are absent on purpose: `session`,
126
+ # `subagent` and `group` bracket their children, so charging them would claim the
127
+ # children's work as their own, and `output` is text produced inside a call that
128
+ # is already counted as `llm`.
129
+ _KIND_CATEGORY = {"llm_request": "llm", "reasoning": "reasoning", "tool": "tool"}
130
+
131
+ # Priority for `partition`. A tool that only waits for a human beats real work,
132
+ # and both beat the LLM call they happened inside of.
133
+ _PRIORITY = ("idle", "tool", "reasoning", "llm")
134
+
135
+ # A tool whose whole job is to wait for the human. Harbor opens a span with this
136
+ # name; another producer may set an attribute instead. Either way the time
137
+ # is not the agent working, so it lands in `idle` rather than `tool`.
138
+ _BLOCKED_NAME = "claude_code.tool.blocked_on_user"
139
+ _BLOCKED_ATTR = "blocked_on_user"
140
+
141
+ # The OTel span for one API call, and the log-derived span for one *record* of
142
+ # the reply. Harbor merges the two itself when the exporter reports a request id
143
+ # (recorded in `harbor.merged_from`); when the provider returns none
144
+ # it cannot, and the same call is left drawn twice — once under the interaction,
145
+ # once under the parallel `session` subtree. `fold_llm_requests` finishes the job.
146
+ _OTEL_LLM_NAME = "claude_code.llm_request"
147
+ _LOG_LLM_NAME = "llm_request"
148
+
149
+ # What a call can be shown to have produced. A tool_use block is left untyped by
150
+ # the producer, and says nothing about what the call was for.
151
+ _BLOCK_KINDS = ("reasoning", "output")
152
+
153
+ # Provenance for a span this reader assembled, alongside the producer's own
154
+ # `harbor.merged_from`. The `app.` prefix is the whole point: it marks what was
155
+ # added here from what was measured there.
156
+ _MERGED_FROM = "app.merged_from"
157
+ _MERGED_KEYS = ("harbor.merged_from", _MERGED_FROM)
158
+
159
+ # Content fields, in reading order. `arguments` is a mapping; the rest are text.
160
+ _CONTENT_FIELDS = (
161
+ ("input", "Input"),
162
+ ("reasoning", "Reasoning"),
163
+ ("output", "Output"),
164
+ ("arguments", "Arguments"),
165
+ ("result", "Result"),
166
+ )
167
+
168
+
169
+ def segments_of(source) -> list:
170
+ """[{key, label, ns, pct}] for a stacked strip, zero-length categories dropped.
171
+
172
+ Shared by :class:`Totals` and :class:`Breakdown` so the reported strip and a
173
+ recomputed one are laid out and labelled identically — the only difference
174
+ between them should be the numbers, never the presentation.
175
+
176
+ Percentages are of the wall clock, so categories that do not close read as
177
+ short of 100% instead of being silently rescaled to fill it; ``unaccounted``
178
+ is what closes them. With no wall clock to divide by they fall back to the
179
+ segments' own sum, which is the only honest denominator left.
180
+ """
181
+ out = [
182
+ {"key": key, "label": label, "ns": int(getattr(source, attr))}
183
+ for key, label, attr in _SEGMENTS
184
+ if getattr(source, attr)
185
+ ]
186
+ if source.unaccounted_ns:
187
+ out.append({"key": _UNACCOUNTED[0], "label": _UNACCOUNTED[1], "ns": source.unaccounted_ns})
188
+ denominator = source.wall_ns or sum(seg["ns"] for seg in out)
189
+ for seg in out:
190
+ seg["pct"] = seg["ns"] / denominator * 100 if denominator else 0.0
191
+ return out
192
+
193
+
194
+ @dataclass(frozen=True)
195
+ class Extent:
196
+ """The window the axis covers, derived from the spans themselves.
197
+
198
+ Never from the host wall clock: spans are stamped inside the container and
199
+ ``totals.wall_ns`` on the host, so mixing them puts bars in the wrong place.
200
+ """
201
+
202
+ start_ns: int = 0
203
+ end_ns: int = 1
204
+ span_ns: int = 1 # floored at 1 — an all-instant trace would divide by zero
205
+
206
+
207
+ @dataclass
208
+ class Tick:
209
+ pct: float
210
+ ns: int # offset from the extent start, not an epoch value
211
+
212
+
213
+ @dataclass
214
+ class Totals:
215
+ """Run-level time, exactly as the producer reported it.
216
+
217
+ **Never recomputed from the tree.** Summing nested spans double-counts
218
+ their shared time. The producer already resolved that (it skips tools nested
219
+ inside tools, and subtracts tool time nested inside LLM spans). The only
220
+ arithmetic this class does is the residual, which is a display concern.
221
+ """
222
+
223
+ wall_ns: int | None = None
224
+ llm_ns: int | None = None
225
+ tool_ns: int | None = None
226
+ reasoning_ns: int | None = None
227
+ idle_ns: int | None = None
228
+ span_count: int | None = None
229
+ measured_span_count: int | None = None
230
+
231
+ @property
232
+ def unaccounted_ns(self) -> int:
233
+ """Wall clock the categories don't account for.
234
+
235
+ The categories are not expected to close: the session span brackets more
236
+ than its instrumented children, so a stacked bar that just leaves a gap
237
+ reads as a rendering bug. Name the gap instead. Clamped at both ends —
238
+ under an epsilon it is noise, and a negative would corrupt the geometry
239
+ silently (the same reasoning as `Trial.dur_other`).
240
+ """
241
+ if not self.wall_ns:
242
+ return 0
243
+ rest = sum(v or 0 for v in (self.llm_ns, self.tool_ns, self.reasoning_ns, self.idle_ns))
244
+ residual = self.wall_ns - rest
245
+ return int(residual) if residual >= UNACCOUNTED_EPSILON_NS else 0
246
+
247
+ @property
248
+ def segments(self) -> list:
249
+ """[{key, label, ns, pct}] for the breakdown strip."""
250
+ return segments_of(self)
251
+
252
+
253
+ @dataclass
254
+ class Breakdown:
255
+ """Category time recomputed from a set of spans — for a filtered view only.
256
+
257
+ The producer's ``totals`` stays authoritative and is never replaced by this
258
+ (see :class:`Totals`). It exists because hiding spans has to take their time
259
+ out of the picture, and the producer cannot be asked a second time.
260
+
261
+ It is deliberately *not* the same arithmetic, and it does not reproduce the
262
+ same numbers. Harbor's ``llm_ns`` is the plain sum of its LLM spans, while
263
+ this partitions the timeline so an instant covered by both a tool call and
264
+ the LLM call that asked for it is charged once, to the tool. The two are
265
+ shown as separate strips because they measure different things.
266
+
267
+ ``wall_ns`` is carried over from the source unchanged: hiding a span does not
268
+ make the run shorter, it makes more of the run unattributed. That is what
269
+ ``unaccounted_ns`` then absorbs, and it is the honest place for it to land.
270
+ """
271
+
272
+ wall_ns: int = 0
273
+ llm_ns: int = 0
274
+ tool_ns: int = 0
275
+ reasoning_ns: int = 0
276
+ idle_ns: int = 0
277
+ span_count: int = 0
278
+ measured_span_count: int = 0
279
+ tokens: dict = field(default_factory=dict)
280
+
281
+ @property
282
+ def attributed_ns(self) -> int:
283
+ """Wall clock the categories account for. Disjoint, so a plain sum."""
284
+ return self.llm_ns + self.tool_ns + self.reasoning_ns + self.idle_ns
285
+
286
+ @property
287
+ def unaccounted_ns(self) -> int:
288
+ residual = (self.wall_ns or 0) - self.attributed_ns
289
+ return int(residual) if residual >= UNACCOUNTED_EPSILON_NS else 0
290
+
291
+ @property
292
+ def segments(self) -> list:
293
+ return segments_of(self)
294
+
295
+ def compared_to(self, other: "Breakdown") -> list:
296
+ """`segments`, each carrying `delta_ns` against *other*.
297
+
298
+ The comparison a filtered view actually needs. Both sides come from this
299
+ same partition, so every delta is the filter's doing and nothing else —
300
+ whereas the difference against the producer's reported strip mixes the
301
+ filter up with two different ways of accounting for the same run, and on
302
+ a log-derived trace those disagree by minutes, not milliseconds.
303
+
304
+ A category the filter emptied keeps its entry at 0ns: dropping it would
305
+ hide the largest thing the filter did.
306
+ """
307
+ was = {seg["key"]: seg["ns"] for seg in other.segments}
308
+ out = self.segments
309
+ here = {seg["key"] for seg in out}
310
+ out.extend(
311
+ {"key": key, "label": _SEGMENT_LABELS[key], "ns": 0, "pct": 0.0}
312
+ for key in was
313
+ if key not in here
314
+ )
315
+ out.sort(key=lambda seg: _SEGMENT_ORDER.index(seg["key"]))
316
+ for seg in out:
317
+ seg["delta_ns"] = seg["ns"] - was.get(seg["key"], 0)
318
+ return out
319
+
320
+ def as_totals(self) -> dict:
321
+ """The ``totals`` block to write into a saved filtered trace."""
322
+ return {
323
+ "wall_ns": self.wall_ns,
324
+ "llm_ns": self.llm_ns,
325
+ "tool_ns": self.tool_ns,
326
+ "reasoning_ns": self.reasoning_ns,
327
+ "idle_ns": self.idle_ns,
328
+ "span_count": self.span_count,
329
+ "measured_span_count": self.measured_span_count,
330
+ "tokens": dict(self.tokens),
331
+ }
332
+
333
+
334
+ def clean(values) -> tuple:
335
+ """Deduplicated, sorted, blank-free — so one view has exactly one URL."""
336
+ return tuple(sorted({str(v) for v in values if str(v).strip()}))
337
+
338
+
339
+ def toggled(values: tuple, value: str) -> tuple:
340
+ value = str(value)
341
+ return tuple(v for v in values if v != value) if value in values else values + (value,)
342
+
343
+
344
+ @dataclass(frozen=True)
345
+ class Filter:
346
+ """What a view is leaving out: span labels, and individual spans by id.
347
+
348
+ Two axes, because they answer different questions — "never mind Bash" is a
349
+ label, "not *that* call" is one span. Both take the span's subtree with them;
350
+ see :func:`prune`.
351
+
352
+ Immutable and canonical: every mutation returns a new Filter with its values
353
+ sorted and deduplicated, so the same view always produces the same query
354
+ string, the same saved file and the same provenance block.
355
+
356
+ ``zoom`` rides along but is not a filter. It names the span whose subtree the
357
+ waterfall's axis is re-based on (``?zoom=<span id>``), and it hides nothing:
358
+ `active`, `hides` and :func:`filtered_document` are blind to it, and the
359
+ breakdown, the coverage strip and the charts stay over the whole filtered
360
+ view. It lives here because every control on the trial page links through
361
+ `query`, and a link that dropped it would silently un-zoom the reader.
362
+ """
363
+
364
+ names: tuple = ()
365
+ span_ids: tuple = ()
366
+ zoom: str = ""
367
+
368
+ @classmethod
369
+ def of(cls, names=(), span_ids=(), zoom=None) -> "Filter":
370
+ return cls(names=clean(names), span_ids=clean(span_ids), zoom=str(zoom or "").strip())
371
+
372
+ @property
373
+ def active(self) -> bool:
374
+ return bool(self.names or self.span_ids)
375
+
376
+ @property
377
+ def query(self) -> dict:
378
+ """Arguments for ``url_for``, so any filtered view is a plain link."""
379
+ out = {"hide": list(self.names), "hide_span": list(self.span_ids)}
380
+ if self.zoom:
381
+ out["zoom"] = self.zoom
382
+ return out
383
+
384
+ def hides(self, raw: dict) -> bool:
385
+ """Is this raw span filtered out?
386
+
387
+ Matched on the *displayed* label rather than the instrumentation name, so
388
+ what the chips offer, what the URL carries and what the waterfall row
389
+ shows are all one string — and, since that label is already redacted, no
390
+ raw job text ends up in a query string.
391
+ """
392
+ return (
393
+ raw_label(raw) in self.names
394
+ or str(raw.get("span_id") or "") in self.span_ids
395
+ )
396
+
397
+ def toggled_name(self, name: str) -> "Filter":
398
+ return Filter.of(toggled(self.names, name), self.span_ids, self.zoom)
399
+
400
+ def toggled_span(self, span_id: str) -> "Filter":
401
+ return Filter.of(self.names, toggled(self.span_ids, span_id), self.zoom)
402
+
403
+ def cleared(self) -> "Filter":
404
+ """Nothing hidden. The zoom is a separate view and keeps its own reset."""
405
+ return Filter(zoom=self.zoom)
406
+
407
+ def zoomed_to(self, span_id: str) -> "Filter":
408
+ return Filter.of(self.names, self.span_ids, span_id)
409
+
410
+ def unzoomed(self) -> "Filter":
411
+ return Filter.of(self.names, self.span_ids)
412
+
413
+
414
+ @dataclass
415
+ class Facet:
416
+ """One filterable label, with how many spans carry it."""
417
+
418
+ name: str
419
+ kind: str = "" # the commonest kind under this label, for the swatch
420
+ count: int = 0
421
+ hidden: bool = False
422
+
423
+
424
+ @dataclass
425
+ class Span:
426
+ span_id: str = ""
427
+ parent_span_id: str = "" # "" on roots — the key is absent, not null
428
+ name: str = "" # the instrumentation name
429
+ label: str = "" # what to display; often the tool name instead
430
+ kind: str = ""
431
+ start_ns: int = 0
432
+ end_ns: int | None = None
433
+ duration_ns: int | None = None # None means no known end — a marker, not a zero
434
+ timing_quality: str = "unknown"
435
+ source: str = ""
436
+ attributes: list = field(default_factory=list) # [(key, value_str)]
437
+ tokens: dict = field(default_factory=dict)
438
+ content: list = field(default_factory=list) # [(label, text)]
439
+ children: list = field(default_factory=list)
440
+
441
+ @property
442
+ def merged(self) -> bool:
443
+ """Assembled from more than one source (OTLP span + agent log).
444
+
445
+ Either the producer said so, or `fold_llm_requests` did it here — the
446
+ badge means the same thing to a reader, so both keys light it.
447
+ """
448
+ return any(k in _MERGED_KEYS for k, _ in self.attributes)
449
+
450
+
451
+ @dataclass
452
+ class Row:
453
+ """One rendered waterfall row: a span placed on the global axis."""
454
+
455
+ span: Span
456
+ depth: int = 0
457
+ has_children: bool = False
458
+ offset_ns: int = 0 # exact int; only the percentages become floats
459
+ left_pct: float = 0.0
460
+ width_pct: float = 0.0
461
+ is_instant: bool = False
462
+
463
+
464
+ @dataclass
465
+ class Trace:
466
+ run_id: str = ""
467
+ roots: list = field(default_factory=list)
468
+ totals: Totals = field(default_factory=Totals)
469
+ extent: Extent = field(default_factory=Extent)
470
+ axis: Extent = field(default_factory=Extent) # what the bars are placed on: `extent`, or the zoomed subtree's
471
+ rows: list = field(default_factory=list)
472
+ ticks: list = field(default_factory=list)
473
+ truncated: int = 0 # spans beyond MAX_ROWS, not rendered
474
+ shown: int = 0 # spans in the filtered view, whatever the zoom leaves in the waterfall
475
+ zoomed: "Span | None" = None # the span the waterfall is re-based on
476
+ zoom_lost: str = "" # a `zoom` that names no span in this view — shown whole, with a note
477
+ error: str = "" # set if the file could not be read
478
+ filter: Filter = field(default_factory=Filter)
479
+ facets: list = field(default_factory=list) # [Facet], from the unfiltered tree
480
+ hidden_spans: list = field(default_factory=list) # [(span_id, label)] hidden by id
481
+ hidden_count: int = 0 # spans the filter removed, subtrees included
482
+ view: Breakdown = field(default_factory=Breakdown) # totals over what is left
483
+ baseline: Breakdown = field(default_factory=Breakdown) # ... and over all of them
484
+
485
+ @property
486
+ def has_spans(self) -> bool:
487
+ return bool(self.rows)
488
+
489
+ @property
490
+ def visible(self) -> bool:
491
+ """Should the trace panel render at all.
492
+
493
+ Not just `has_spans`: a filter can legitimately hide every span, and a
494
+ panel that vanished would take its own Clear control with it.
495
+ """
496
+ return self.has_spans or self.filter.active
497
+
498
+ @property
499
+ def zero_measured(self) -> bool:
500
+ """Nothing was measured: every duration below is inferred.
501
+
502
+ The signal that instrumentation captured nothing and the producer fell
503
+ back to parsing the agent's own logs. Inferred timings are approximate
504
+ and simply wrong under parallel tool calls, so the UI has to say so.
505
+ """
506
+ return bool(self.totals.span_count) and self.totals.measured_span_count == 0
507
+
508
+ @property
509
+ def instrumented_ns(self) -> int:
510
+ """How much wall clock the spans actually cover.
511
+
512
+ Off `extent`, never `axis`: a zoom re-bases the waterfall, and the
513
+ coverage strip describes the capture, not the view.
514
+ """
515
+ return self.extent.span_ns if self.has_spans else 0
516
+
517
+ @property
518
+ def zoom_offset_ns(self) -> int:
519
+ """Where the zoomed window starts, as an offset into the capture."""
520
+ return self.axis.start_ns - self.extent.start_ns if self.zoomed else 0
521
+
522
+ @property
523
+ def coverage_pct(self) -> float:
524
+ """Share of the run the waterfall can see, 0 when unknowable.
525
+
526
+ The axis is derived from the spans, so a run where 1% was instrumented
527
+ renders bars across the full width and looks completely captured. This
528
+ is the number that says otherwise. It compares *durations* only — it
529
+ never places a container-stamped instant on the host's clock.
530
+ """
531
+ wall = self.totals.wall_ns
532
+ if not wall or not self.has_spans:
533
+ return 0.0
534
+ return min(100.0, self.instrumented_ns / wall * 100)
535
+
536
+ @property
537
+ def kinds_present(self) -> list:
538
+ seen = {r.span.kind for r in self.rows}
539
+ known = [k for k in KIND_ORDER if k in seen]
540
+ return known + sorted(seen - set(KIND_ORDER))
541
+
542
+ @property
543
+ def qualities_present(self) -> list:
544
+ seen = {r.span.timing_quality for r in self.rows}
545
+ return [q for q in ("measured", "inferred", "unknown") if q in seen]
546
+
547
+
548
+ def block_types_of(raw: dict) -> tuple:
549
+ """What kinds of block a request can be shown to have produced.
550
+
551
+ Two producers say it two ways and both are read: Harbor emits a child span
552
+ per block (`reasoning`, `output`), while another may keep the
553
+ text on the call itself. Empty when nothing says — a call whose only block
554
+ was a `tool_use` is not "an output call", it is just a call.
555
+ """
556
+ content = raw.get("content") or {}
557
+ seen = {kind for kind in _BLOCK_KINDS if content.get(kind)}
558
+ for child in raw.get("children") or []:
559
+ if isinstance(child, dict) and str(child.get("kind") or "") in _BLOCK_KINDS:
560
+ seen.add(str(child.get("kind")))
561
+ return tuple(kind for kind in _BLOCK_KINDS if kind in seen)
562
+
563
+
564
+ def label_of(name: str, attributes: dict, kind: str = "", blocks: tuple = ()) -> str:
565
+ """What to show for a span.
566
+
567
+ Merged spans overwrite `name` with the log-derived tool name ("Write");
568
+ unmerged ones keep the instrumentation name ("claude_code.tool") and put the
569
+ tool name only in an attribute. Prefer the attribute, so both render as the
570
+ tool. The raw name stays on the span for the detail pane.
571
+
572
+ An LLM call reads the same way. `claude_code.llm_request` is the exporter's
573
+ name for the same thing the agent log calls `llm_request`, so it is shown
574
+ under the log's name; and when the call produced exactly one *kind* of block
575
+ it is shown under that instead — `reasoning`, or `output`. Two kinds is not
576
+ one type, so a call that both thought and answered stays `llm_request`.
577
+
578
+ Both of those rules make a bracketing span and the call inside it share a
579
+ label, which is why `mark_groups` re-kinds the outer one before this ever
580
+ sees it: given `group`, the label says so. The suffix is added here rather
581
+ than written onto the span so that one function decides what a span is
582
+ called, and the raw name and `tool_name` reach the detail pane untouched.
583
+ """
584
+ tool = (attributes or {}).get("tool_name")
585
+ if isinstance(tool, str) and tool.strip():
586
+ label = tool.strip()
587
+ elif name in (_OTEL_LLM_NAME, _LOG_LLM_NAME):
588
+ label = blocks[0] if len(blocks) == 1 else _LOG_LLM_NAME
589
+ else:
590
+ label = name
591
+ return label + GROUP_SUFFIX if kind == GROUP_KIND else label
592
+
593
+
594
+ def _int_or_none(value) -> int | None:
595
+ return value if isinstance(value, int) and not isinstance(value, bool) else None
596
+
597
+
598
+ def _content_of(raw: dict) -> list:
599
+ out = []
600
+ for key, label in _CONTENT_FIELDS:
601
+ value = raw.get(key)
602
+ if value is None or value == "" or value == {} or value == []:
603
+ continue
604
+ if isinstance(value, (dict, list)):
605
+ value = json.dumps(value, ensure_ascii=False, indent=2)
606
+ out.append((label, redact(str(value))))
607
+ return out
608
+
609
+
610
+ def _span(raw: dict, depth: int = 0) -> Span:
611
+ # `.get(k) or {}` rather than `.get(k, {})` throughout: the producer writes
612
+ # with exclude_none, so optional fields are absent — but a null would slip
613
+ # straight past a default argument and reach the template as None.
614
+ attributes = raw.get("attributes") or {}
615
+ end_ns = _int_or_none(raw.get("end_ns"))
616
+ start_ns = _int_or_none(raw.get("start_ns")) or 0
617
+ duration_ns = _int_or_none(raw.get("duration_ns"))
618
+ if duration_ns is None and end_ns is not None:
619
+ duration_ns = end_ns - start_ns
620
+
621
+ name = redact(str(raw.get("name") or ""))
622
+ kind = str(raw.get("kind") or "")
623
+ return Span(
624
+ span_id=str(raw.get("span_id") or ""),
625
+ parent_span_id=str(raw.get("parent_span_id") or ""),
626
+ name=name,
627
+ label=redact(
628
+ label_of(str(raw.get("name") or ""), attributes, kind, block_types_of(raw))
629
+ ),
630
+ kind=kind,
631
+ start_ns=start_ns,
632
+ end_ns=end_ns,
633
+ duration_ns=duration_ns,
634
+ timing_quality=str(raw.get("timing_quality") or "unknown"),
635
+ source=str(raw.get("source") or ""),
636
+ # Keys are instrumentation enums (gen_ai.request.model), not job text, so
637
+ # they are not redacted; every value is.
638
+ attributes=sorted((str(k), redact(str(v))) for k, v in attributes.items()),
639
+ tokens={k: v for k, v in (raw.get("tokens") or {}).items() if v is not None},
640
+ content=_content_of(raw.get("content") or {}),
641
+ children=(
642
+ [_span(c, depth + 1) for c in raw.get("children") or []]
643
+ if depth < MAX_DEPTH
644
+ else []
645
+ ),
646
+ )
647
+
648
+
649
+ def all_spans(roots: list):
650
+ """Depth-first walk. Guards against a parent cycle rather than hanging."""
651
+ seen = set()
652
+
653
+ def walk(span):
654
+ if span.span_id and span.span_id in seen:
655
+ return
656
+ seen.add(span.span_id)
657
+ yield span
658
+ for child in span.children:
659
+ yield from walk(child)
660
+
661
+ for root in roots:
662
+ yield from walk(root)
663
+
664
+
665
+ def extent_of(roots: list) -> Extent:
666
+ spans = list(all_spans(roots))
667
+ if not spans:
668
+ return Extent()
669
+ start = min(s.start_ns for s in spans)
670
+ end = max((s.end_ns if s.end_ns is not None else s.start_ns) for s in spans)
671
+ # Floored at 1: a trace whose spans are all instants has end == start, and
672
+ # every percentage would come out NaN or Infinity.
673
+ return Extent(start_ns=start, end_ns=end, span_ns=max(end - start, 1))
674
+
675
+
676
+ def find_span(roots: list, span_id: str):
677
+ """The span called *span_id* in this tree, or None. Same walk as `all_spans`."""
678
+ if not span_id:
679
+ return None
680
+ return next((s for s in all_spans(roots) if s.span_id == span_id), None)
681
+
682
+
683
+ def raw_spans_of(spans: list, depth: int = 0):
684
+ """Depth-first walk of raw span dicts, straight from the document.
685
+
686
+ The filter and everything that saves a file work on raw dicts rather than on
687
+ parsed :class:`Span`s: a saved trace has to keep every field the producer
688
+ wrote — including the content this reader redacts — and a round trip through
689
+ the parser would quietly drop whatever it does not render.
690
+ """
691
+ for raw in spans:
692
+ if not isinstance(raw, dict):
693
+ continue
694
+ yield raw
695
+ if depth < MAX_DEPTH:
696
+ yield from raw_spans_of(raw.get("children") or [], depth + 1)
697
+
698
+
699
+ def raw_label(raw: dict) -> str:
700
+ """The label a raw span will be displayed under. Redacted, like the parsed one.
701
+
702
+ Reads `kind` off the span, so it agrees with :func:`_span` only once
703
+ :func:`mark_groups` has run. Everything that filters or counts by label goes
704
+ through the normalised document for that reason.
705
+ """
706
+ return redact(label_of(
707
+ str(raw.get("name") or ""), raw.get("attributes") or {},
708
+ str(raw.get("kind") or ""), block_types_of(raw),
709
+ ))
710
+
711
+
712
+ def _bare_label(raw: dict) -> str:
713
+ """A raw span's label as if it were not a group. Its identity, not its role."""
714
+ return label_of(
715
+ str(raw.get("name") or ""), raw.get("attributes") or {}, blocks=block_types_of(raw)
716
+ )
717
+
718
+
719
+ def _self_ns(raw: dict) -> int | None:
720
+ """Time inside *raw* that none of its children covers, or None if unknowable.
721
+
722
+ Overlapping children are merged and clipped to the parent first: a tool call
723
+ nested in the LLM call that asked for it would otherwise be counted twice and
724
+ make a span with real self-time look fully covered.
725
+ """
726
+ start = _int_or_none(raw.get("start_ns"))
727
+ end = _int_or_none(raw.get("end_ns"))
728
+ if start is None or end is None or end <= start:
729
+ return None
730
+ inside = []
731
+ for child in raw.get("children") or []:
732
+ if not isinstance(child, dict):
733
+ continue
734
+ low = _int_or_none(child.get("start_ns"))
735
+ high = _int_or_none(child.get("end_ns"))
736
+ if low is None or high is None:
737
+ continue
738
+ low, high = max(low, start), min(high, end)
739
+ if high > low:
740
+ inside.append((low, high))
741
+ return (end - start) - sum(high - low for low, high in merge_intervals(inside))
742
+
743
+
744
+ def _same_extent(raw: dict, child: dict) -> bool:
745
+ """Do these two spans start and end together, to within `GROUP_SLACK_NS`?
746
+
747
+ Both ends, and that is the point. Coverage alone is satisfied by a child that
748
+ overruns its parent — a background subagent hung under the launch that
749
+ returned in 47ms runs for minutes. Clipped
750
+ to the parent it covers all of it, but the launch is a real 47ms event.
751
+ """
752
+ for key in ("start_ns", "end_ns"):
753
+ mine, theirs = _int_or_none(raw.get(key)), _int_or_none(child.get(key))
754
+ if mine is None or theirs is None or abs(mine - theirs) > GROUP_SLACK_NS:
755
+ return False
756
+ return True
757
+
758
+
759
+ def is_group(raw: dict) -> bool:
760
+ """Is this span a namespace for its children rather than an event itself?
761
+
762
+ **Its children have to account for all of it**, to within `GROUP_SLACK_NS`.
763
+ A span that also spent time of its own is doing something, whatever it is
764
+ named. That is necessary but nowhere near sufficient, so one of two further
765
+ signals has to say the span adds no distinction to what it contains:
766
+
767
+ * **it shares its label with a child** — Harbor's `claude_code.tool` carries
768
+ `tool_name: "Bash"` and holds the span that actually ran Bash, so one call
769
+ would otherwise be counted twice under one name; or
770
+ * **it has a single child of the same extent** — the same bar drawn twice.
771
+ An `llm_request` may hold one `reasoning` or `output` block whose start
772
+ and end are *byte-identical* to its own,
773
+ because the producer splits a response into blocks and a one-block response
774
+ is the request again. `fold_llm_requests` runs first and collapses that
775
+ pair outright wherever it can match the request to the call it answered,
776
+ which is the better answer — one span keeping both clocks and both sets of
777
+ text. What reaches here is the remainder it could not match.
778
+
779
+ Everything else with children stays what it is, and the near misses are worth
780
+ knowing because each one looks like this from a distance. OpenCode's
781
+ `ai.streamText` also brackets the stream call it is named for, but can spend
782
+ time on its own transport; it is still a call. `claude_code.interaction`
783
+ is covered by the calls inside it, and `session`/`subagent` are exempt
784
+ outright: a kind that already announces itself as a bracket is not claiming
785
+ to be work, and `_KIND_CATEGORY` already charges it nothing. A group is
786
+ specifically a span pretending to be the event nested inside it.
787
+
788
+ A call `fold_llm_requests` gave children to is exempt for a sharper reason:
789
+ it would match, always, and the match would be this reader's own doing. The
790
+ fold moves the reply's blocks under the call and then labels the call after
791
+ what it produced, so the parent shares a label with a child by construction
792
+ and the blocks span the call because they are the reply to it. Nothing was
793
+ pretending to be anything — and the call is the one span in that subtree with
794
+ a measured clock, so re-kinding it would charge the only real measurement to
795
+ nothing and leave the inferred blocks holding the time.
796
+ """
797
+ if str(raw.get("kind") or "") in _BRACKET_KINDS:
798
+ return False
799
+ if _MERGED_FROM in (raw.get("attributes") or {}):
800
+ return False
801
+ children = [c for c in raw.get("children") or [] if isinstance(c, dict)]
802
+ if not children:
803
+ return False
804
+ self_ns = _self_ns(raw)
805
+ if self_ns is None or self_ns > GROUP_SLACK_NS:
806
+ return False
807
+ if len(children) == 1 and _same_extent(raw, children[0]):
808
+ return True
809
+ # Compared without the suffix on either side. `mark_groups` works children
810
+ # first, so an inner span may already be a group by the time the outer one is
811
+ # asked; matching on the displayed label would then miss a doubly-wrapped
812
+ # call and leave the outer one claiming to be the tool.
813
+ label = _bare_label(raw)
814
+ return any(_bare_label(c) == label for c in children)
815
+
816
+
817
+ def mark_groups(spans: list, depth: int = 0) -> list:
818
+ """*spans* with every namespace span re-kinded `group`, children first.
819
+
820
+ Runs once, before anything filters or counts, so that the label a chip
821
+ offers, the label in the query string and the label on the row are the same
822
+ string — decided per span, never per surviving child. Filtering the `Bash`
823
+ inside a group therefore leaves the group a group, still named for what it
824
+ used to contain, which is the only answer that keeps a filter from renaming
825
+ the rows it was not asked about.
826
+
827
+ Copy-on-write like :func:`prune`: a subtree with no groups in it is passed
828
+ through by reference, so the caller's document is never mutated.
829
+ """
830
+ out: list = []
831
+ changed = False
832
+ for raw in spans:
833
+ if not isinstance(raw, dict):
834
+ changed = True
835
+ continue
836
+ children = raw.get("children") or []
837
+ if children and depth < MAX_DEPTH:
838
+ marked = mark_groups(children, depth + 1)
839
+ if marked is not children:
840
+ raw, changed = dict(raw, children=marked), True
841
+ if is_group(raw):
842
+ raw, changed = dict(raw, kind=GROUP_KIND), True
843
+ out.append(raw)
844
+ return out if changed else spans
845
+
846
+
847
+ def category_of(raw: dict) -> str | None:
848
+ """Which breakdown category a span's own time belongs to, or None.
849
+
850
+ None means the span contributes no time of its own — see `_KIND_CATEGORY`.
851
+ """
852
+ kind = str(raw.get("kind") or "")
853
+ if kind == "tool" and (
854
+ str(raw.get("name") or "") == _BLOCKED_NAME
855
+ or (raw.get("attributes") or {}).get(_BLOCKED_ATTR)
856
+ ):
857
+ return "idle"
858
+ return _KIND_CATEGORY.get(kind)
859
+
860
+
861
+ def raw_extent(spans: list) -> Extent:
862
+ """The axis window, taken from the raw document.
863
+
864
+ Called with the *unfiltered* spans on purpose: hiding one must not slide the
865
+ remaining bars sideways, or a filter would look like it changed timings it
866
+ was only asked to leave out. What it removes shows up as empty axis instead.
867
+ Matches `extent_of` span for span, including its treatment of a span with no
868
+ usable start (0, like `_span`) or no end (its own start).
869
+ """
870
+ starts, ends = [], []
871
+ for raw in raw_spans_of(spans):
872
+ start = _int_or_none(raw.get("start_ns")) or 0
873
+ end = _int_or_none(raw.get("end_ns"))
874
+ starts.append(start)
875
+ ends.append(start if end is None else end)
876
+ if not starts:
877
+ return Extent()
878
+ low, high = min(starts), max(ends)
879
+ return Extent(start_ns=low, end_ns=high, span_ns=max(high - low, 1))
880
+
881
+
882
+ def inventory(spans: list, filt: "Filter | None" = None) -> list:
883
+ """Every distinct span label in the document, with how many spans carry it.
884
+
885
+ Built from the *unfiltered* tree: a hidden label still needs its chip, or
886
+ there would be no way left to bring it back.
887
+ """
888
+ filt = filt or Filter()
889
+ counts: dict = {}
890
+ kinds: dict = {}
891
+ for raw in raw_spans_of(spans):
892
+ name = raw_label(raw)
893
+ counts[name] = counts.get(name, 0) + 1
894
+ seen = kinds.setdefault(name, {})
895
+ kind = str(raw.get("kind") or "")
896
+ seen[kind] = seen.get(kind, 0) + 1
897
+ out = [
898
+ Facet(
899
+ name=name,
900
+ # One label can span kinds (a merged parent and its child both read
901
+ # "Write"); the commonest wins, since it only picks the swatch.
902
+ kind=max(kinds[name].items(), key=lambda kv: (kv[1], kv[0]))[0],
903
+ count=count,
904
+ hidden=name in filt.names,
905
+ )
906
+ for name, count in counts.items()
907
+ ]
908
+ # Commonest first, then alphabetical — a stable order, and the labels worth
909
+ # filtering are the ones there are a lot of.
910
+ out.sort(key=lambda f: (-f.count, f.name))
911
+ return out
912
+
913
+
914
+ def labels_by_id(spans: list) -> dict:
915
+ """span_id → label, over the whole unfiltered document.
916
+
917
+ So a span hidden by id can still be named in the UI that offers to unhide it.
918
+ """
919
+ return {
920
+ str(raw.get("span_id") or ""): raw_label(raw)
921
+ for raw in raw_spans_of(spans)
922
+ if raw.get("span_id")
923
+ }
924
+
925
+
926
+ def _window(raw: dict) -> tuple:
927
+ """(start, end) in ns, an unknown end read as the start — same as `_span`."""
928
+ start = _int_or_none(raw.get("start_ns")) or 0
929
+ end = _int_or_none(raw.get("end_ns"))
930
+ return start, start if end is None else end
931
+
932
+
933
+ def _tokens_key(raw: dict) -> tuple:
934
+ """A call's usage, as something comparable. Empty when none was reported."""
935
+ return tuple(
936
+ sorted(
937
+ (str(k), v)
938
+ for k, v in (raw.get("tokens") or {}).items()
939
+ if _int_or_none(v) is not None
940
+ )
941
+ )
942
+
943
+
944
+ def _request_groups(wrappers: list) -> list:
945
+ """Log request spans grouped by the reply they came from.
946
+
947
+ One API call arrives as several records — a thinking block, each tool_use,
948
+ the final text — and the producer opens a span per record. They carry one
949
+ `message.id` between them, which is exactly the grouping wanted; a producer
950
+ that omits it leaves every record its own group, which folds them one by one
951
+ and is no worse than not folding at all.
952
+ """
953
+ groups: dict = {}
954
+ order: list = []
955
+ for raw in wrappers:
956
+ key = (raw.get("attributes") or {}).get("message.id")
957
+ key = str(key) if key else "ungrouped:" + str(raw.get("span_id") or id(raw))
958
+ if key not in groups:
959
+ groups[key] = []
960
+ order.append(key)
961
+ groups[key].append(raw)
962
+ return [groups[key] for key in order]
963
+
964
+
965
+ def _match_requests(containers: list, groups: list) -> dict:
966
+ """container span_id → the log request spans belonging to it.
967
+
968
+ Harbor joins these on the request id the exporter reported. This runs where
969
+ the provider returned none, so the join is on what is left: identical usage,
970
+ and overlapping windows. Usage is a hard constraint when both sides report
971
+ it and the overlap only ranks the candidates, which is what keeps two calls
972
+ that happen to overlap from swapping their blocks.
973
+
974
+ A wrong match moves a row under the wrong call; it cannot change a number,
975
+ because folding re-parents spans and never touches a clock.
976
+ """
977
+ taken: set = set()
978
+ out: dict = {}
979
+ for container in sorted(containers, key=lambda raw: _window(raw)[0]):
980
+ c_start, c_end = _window(container)
981
+ c_tokens = _tokens_key(container)
982
+ best = None
983
+ for index, group in enumerate(groups):
984
+ if index in taken:
985
+ continue
986
+ g_start = min(_window(raw)[0] for raw in group)
987
+ g_end = max(_window(raw)[1] for raw in group)
988
+ if g_start >= c_end or c_start >= g_end:
989
+ continue
990
+ g_tokens = next((t for t in map(_tokens_key, group) if t), ())
991
+ if c_tokens and g_tokens and c_tokens != g_tokens:
992
+ continue
993
+ distance = abs(g_start - c_start)
994
+ if best is None or distance < best[0]:
995
+ best = (distance, index, group)
996
+ if best is not None:
997
+ taken.add(best[1])
998
+ out[str(container.get("span_id") or "")] = best[2]
999
+ return out
1000
+
1001
+
1002
+ def _collect_requests(
1003
+ spans: list, parent: str, containers: list, wrappers: list, depth: int = 0
1004
+ ) -> None:
1005
+ """The calls to fold into, and the log request spans still to fold.
1006
+
1007
+ A request already sitting under a call has been folded — by this function on
1008
+ an earlier read, or by Harbor itself — and must not be folded again: a saved
1009
+ view can be filtered again, which re-reads a document this has already seen,
1010
+ and a second pass would rewrite the provenance of the first.
1011
+ """
1012
+ for raw in spans:
1013
+ if not isinstance(raw, dict):
1014
+ continue
1015
+ name = str(raw.get("name") or "")
1016
+ if name == _OTEL_LLM_NAME:
1017
+ containers.append(raw)
1018
+ elif (
1019
+ name == _LOG_LLM_NAME
1020
+ and str(raw.get("source") or "") == "log"
1021
+ and parent != _OTEL_LLM_NAME
1022
+ ):
1023
+ wrappers.append(raw)
1024
+ if depth < MAX_DEPTH:
1025
+ _collect_requests(raw.get("children") or [], name, containers, wrappers, depth + 1)
1026
+
1027
+
1028
+ def _folded_child(raw: dict, parent: dict) -> dict:
1029
+ """One log request span, rewritten to sit under the call it belongs to.
1030
+
1031
+ A record that produced a single typed block *is* that block — the two share
1032
+ a window exactly — so the two spans collapse into one rather than drawing the
1033
+ same instants twice more. The block keeps its identity and content; the
1034
+ request hands over its attributes and its tokens.
1035
+
1036
+ Handing the tokens over matters more than it looks. The producer's own
1037
+ `totals.tokens` is the sum over every span it wrote, duplicated usage
1038
+ included: dropping a record's copy here would leave the recomputed breakdown
1039
+ disagreeing with the reported totals by a factor of three, and this reader
1040
+ would appear to have invented the defect.
1041
+ """
1042
+ children = [c for c in raw.get("children") or [] if isinstance(c, dict)]
1043
+ typed = [c for c in children if str(c.get("kind") or "") in _BLOCK_KINDS]
1044
+ out = dict(raw)
1045
+ if len(children) == 1 and len(typed) == 1 and _window(typed[0]) == _window(raw):
1046
+ block = typed[0]
1047
+ attributes = {**(raw.get("attributes") or {}), **(block.get("attributes") or {})}
1048
+ attributes[_MERGED_FROM] = str(raw.get("span_id") or "")
1049
+ out = dict(block, attributes=attributes)
1050
+ if raw.get("tokens") and not block.get("tokens"):
1051
+ out["tokens"] = raw["tokens"]
1052
+ out["parent_span_id"] = str(parent.get("span_id") or "")
1053
+ return out
1054
+
1055
+
1056
+ def fold_llm_requests(spans: list) -> list:
1057
+ """Each measured LLM call given the log spans for the reply it produced.
1058
+
1059
+ Without this the same call is drawn twice — as `claude_code.llm_request`
1060
+ under the interaction, and again as `llm_request` under the log's own
1061
+ `session` subtree — with the second copy carrying the reasoning and output
1062
+ text and the first carrying the only measured clock. Folding puts the blocks
1063
+ under the call, which is the shape Harbor itself writes when the exporter
1064
+ gives it a request id to join on.
1065
+
1066
+ Nothing is invented and nothing is dropped. Every span survives with its own
1067
+ start, end and tokens; a request span that collapsed into its one block is
1068
+ that block, carrying what the request knew. The rows move, the clocks do not,
1069
+ and the producer's `totals` is untouched, as ever.
1070
+
1071
+ Copy-on-write, like `prune`: a document with nothing to fold is returned by
1072
+ reference.
1073
+ """
1074
+ containers, wrappers = [], []
1075
+ _collect_requests(spans, "", containers, wrappers)
1076
+ if not containers or not wrappers:
1077
+ return spans
1078
+
1079
+ folded = _match_requests(containers, _request_groups(wrappers))
1080
+ if not folded:
1081
+ return spans
1082
+ by_id = {str(c.get("span_id") or ""): c for c in containers}
1083
+ by_container = {
1084
+ parent_id: [_folded_child(raw, by_id[parent_id]) for raw in group]
1085
+ for parent_id, group in folded.items()
1086
+ }
1087
+ moved = {id(raw) for group in folded.values() for raw in group}
1088
+ return _fold_tree(spans, by_container, moved)[0]
1089
+
1090
+
1091
+ def _fold_tree(spans: list, by_container: dict, moved: set, depth: int = 0) -> tuple:
1092
+ """(spans, changed) — the tree with the matched request spans relocated.
1093
+
1094
+ Identity, not span id, is what marks a span as moved: ids are opaque strings
1095
+ from two producers here, and a collision would otherwise delete a span rather
1096
+ than move it.
1097
+ """
1098
+ out: list = []
1099
+ changed = False
1100
+ for raw in spans:
1101
+ if not isinstance(raw, dict):
1102
+ continue
1103
+ if id(raw) in moved:
1104
+ changed = True
1105
+ continue
1106
+ children = raw.get("children") or []
1107
+ if children and depth < MAX_DEPTH:
1108
+ children, dropped = _fold_tree(children, by_container, moved, depth + 1)
1109
+ else:
1110
+ dropped = False
1111
+ blocks = by_container.get(str(raw.get("span_id") or ""))
1112
+ if blocks:
1113
+ children = sorted(children + blocks, key=lambda s: _window(s)[0])
1114
+ attributes = dict(raw.get("attributes") or {})
1115
+ attributes[_MERGED_FROM] = ", ".join(
1116
+ str((b.get("attributes") or {}).get(_MERGED_FROM) or b.get("span_id") or "")
1117
+ for b in blocks
1118
+ )
1119
+ raw = dict(raw, children=children, attributes=attributes)
1120
+ elif dropped:
1121
+ raw = dict(raw, children=children)
1122
+ changed = changed or dropped or bool(blocks)
1123
+ out.append(raw)
1124
+ return out, changed
1125
+
1126
+
1127
+ def prune(spans: list, filt: "Filter | None" = None, depth: int = 0) -> tuple:
1128
+ """(kept, removed) — hidden spans dropped, with their subtrees.
1129
+
1130
+ A hidden span takes its children with it. Keeping them would leave a tool's
1131
+ inner spans floating with no call around them, and hiding a call is a request
1132
+ to take its whole cost out of the picture — including the cost of what it did.
1133
+
1134
+ Copy-on-write: a subtree nothing was removed from is passed through by
1135
+ reference, so the caller's document is never mutated and saving a filtered
1136
+ view cannot corrupt the original.
1137
+ """
1138
+ filt = filt or Filter()
1139
+ kept: list = []
1140
+ removed = 0
1141
+ for raw in spans:
1142
+ if not isinstance(raw, dict):
1143
+ continue
1144
+ if filt.hides(raw):
1145
+ removed += 1 + sum(1 for _ in raw_spans_of(raw.get("children") or []))
1146
+ continue
1147
+ children = raw.get("children") or []
1148
+ if children and depth < MAX_DEPTH:
1149
+ children, dropped = prune(children, filt, depth + 1)
1150
+ if dropped:
1151
+ removed += dropped
1152
+ raw = dict(raw, children=children)
1153
+ kept.append(raw)
1154
+ return kept, removed
1155
+
1156
+
1157
+ def merge_intervals(intervals: list) -> list:
1158
+ """Overlapping [start, end) runs collapsed into disjoint ones."""
1159
+ out: list = []
1160
+ for start, end in sorted(intervals):
1161
+ if out and start <= out[-1][1]:
1162
+ out[-1] = (out[-1][0], max(out[-1][1], end))
1163
+ else:
1164
+ out.append((start, end))
1165
+ return out
1166
+
1167
+
1168
+ def partition(by_category: dict, priority: tuple = _PRIORITY) -> dict:
1169
+ """Split the timeline so every instant is charged to exactly one category.
1170
+
1171
+ Summing durations exceeds the wall clock as soon as spans nest or overlap,
1172
+ and both happen here: a tool call sits inside the LLM call that asked for it,
1173
+ and background subagents run alongside the main thread. Each elementary
1174
+ segment goes to the highest-priority category covering it, which keeps the
1175
+ categories disjoint by construction and the stacked strip honest.
1176
+ """
1177
+ merged = {cat: merge_intervals(by_category.get(cat) or []) for cat in priority}
1178
+ starts = {cat: [start for start, _ in ivs] for cat, ivs in merged.items()}
1179
+ edges = sorted({point for ivs in merged.values() for iv in ivs for point in iv})
1180
+ totals = {cat: 0 for cat in priority}
1181
+
1182
+ def covers(cat: str, low: int) -> bool:
1183
+ ivs = merged[cat]
1184
+ i = bisect.bisect_right(starts[cat], low) - 1
1185
+ return i >= 0 and ivs[i][1] > low
1186
+
1187
+ for low, high in zip(edges, edges[1:]):
1188
+ for cat in priority:
1189
+ if covers(cat, low):
1190
+ totals[cat] += high - low
1191
+ break
1192
+ return totals
1193
+
1194
+
1195
+ def breakdown(spans: list, wall_ns: int = 0) -> Breakdown:
1196
+ """Recompute category time, span counts and tokens over *spans*.
1197
+
1198
+ See :class:`Breakdown` for why this is not the producer's arithmetic and must
1199
+ not be presented as it. Spans with no usable end contribute no time — an
1200
+ unknown clock is not a zero one — but they are still counted and their tokens
1201
+ still add up.
1202
+ """
1203
+ by_category: dict = {}
1204
+ tokens: dict = {}
1205
+ count = 0
1206
+ measured = 0
1207
+ for raw in raw_spans_of(spans):
1208
+ count += 1
1209
+ if str(raw.get("timing_quality") or "") == "measured":
1210
+ measured += 1
1211
+ for key, value in (raw.get("tokens") or {}).items():
1212
+ if _int_or_none(value) is not None:
1213
+ tokens[key] = tokens.get(key, 0) + value
1214
+ category = category_of(raw)
1215
+ start = _int_or_none(raw.get("start_ns"))
1216
+ end = _int_or_none(raw.get("end_ns"))
1217
+ if category and start is not None and end is not None and end > start:
1218
+ by_category.setdefault(category, []).append((start, end))
1219
+ split = partition(by_category)
1220
+ return Breakdown(
1221
+ wall_ns=int(wall_ns or 0),
1222
+ llm_ns=split.get("llm", 0),
1223
+ tool_ns=split.get("tool", 0),
1224
+ reasoning_ns=split.get("reasoning", 0),
1225
+ idle_ns=split.get("idle", 0),
1226
+ span_count=count,
1227
+ measured_span_count=measured,
1228
+ tokens=tokens,
1229
+ )
1230
+
1231
+
1232
+ # Stamped into a saved view as both its producer and the hand that filtered it.
1233
+ FILTER_PRODUCER = "app/nullius/trace.py (filtered view)"
1234
+
1235
+
1236
+ def filtered_document(data: dict, filt: "Filter | None" = None) -> dict:
1237
+ """*data* with the hidden spans gone and ``totals`` recomputed over the rest.
1238
+
1239
+ What gets written to disk, and the reason :func:`prune` works on raw dicts.
1240
+ Three things are load-bearing about the result:
1241
+
1242
+ * it is still a ``harbor-trace-v1`` document, so this app can open it;
1243
+ * ``wall_ns`` is the source's, so removed time surfaces as ``unaccounted``
1244
+ rather than vanishing into a shorter run;
1245
+ * the producer's own ``totals`` survives verbatim under ``filtered``, since a
1246
+ derived number that has overwritten the measured one is unfalsifiable.
1247
+
1248
+ Filtering a view that was itself saved from a filtered view works, and the
1249
+ chain is kept under ``filtered.previous`` rather than overwritten — otherwise
1250
+ the second save would present derived totals as if they were measured.
1251
+ """
1252
+ filt = filt or Filter()
1253
+ # The same two normalisations `parse` does, in the same order, and each for
1254
+ # its own reason. Folding first because hiding a call takes its subtree with
1255
+ # it and folding is what puts the reply's blocks in that subtree, so an
1256
+ # unfolded save would drop a different set of spans than the page showed;
1257
+ # `mark_groups` because `hide` carries the displayed label, and "Bash [group]"
1258
+ # only matches a span that has been re-kinded. Both are written out with the
1259
+ # spans — the document already names this tree as its producer, and a saved
1260
+ # view that reopened as a different shape than the one saved would be worse
1261
+ # than a changed enum.
1262
+ kept, removed = prune(mark_groups(fold_llm_requests(data.get("spans") or [])), filt)
1263
+ source_totals = data.get("totals") or {}
1264
+ view = breakdown(kept, _int_or_none(source_totals.get("wall_ns")) or 0)
1265
+ out = dict(data)
1266
+ out["spans"] = kept
1267
+ out["totals"] = view.as_totals()
1268
+ # This file was written here, whatever wrote the spans — `producer` naming a
1269
+ # script that never saw these totals is exactly the kind of plausible-looking
1270
+ # provenance that makes a derived artefact unfalsifiable. The original moves
1271
+ # into the block below rather than being dropped.
1272
+ out["producer"] = FILTER_PRODUCER
1273
+ out["filtered"] = {
1274
+ "by": FILTER_PRODUCER,
1275
+ "source_producer": str(data.get("producer") or ""),
1276
+ "hide": list(filt.names),
1277
+ "hide_span": list(filt.span_ids),
1278
+ "spans_removed": removed,
1279
+ "note": (
1280
+ "totals recomputed from the spans left, by charging every instant to one "
1281
+ "category at priority idle > tool > reasoning > llm; wall_ns is the source's, "
1282
+ "so the removed time reads as unaccounted; log request spans matched to the "
1283
+ "measured call they belong to were folded under it first (app.merged_from), "
1284
+ "and spans that only bracket a same-named child are re-kinded 'group' and "
1285
+ "charged no time"
1286
+ ),
1287
+ "source_totals": source_totals,
1288
+ }
1289
+ previous = data.get("filtered")
1290
+ if isinstance(previous, dict):
1291
+ out["filtered"]["previous"] = previous
1292
+ return out
1293
+
1294
+
1295
+ def _clamp(value: float, low: float = 0.0, high: float = 100.0) -> float:
1296
+ return max(low, min(high, value))
1297
+
1298
+
1299
+ def place(span: Span, extent: Extent) -> tuple:
1300
+ """(left_pct, width_pct) on the global axis.
1301
+
1302
+ All arithmetic is Python int until this line, so the nanosecond magnitudes
1303
+ that overflow a JS double are exact here — no BigInt problem to work around.
1304
+ """
1305
+ left = _clamp((span.start_ns - extent.start_ns) / extent.span_ns * 100)
1306
+ duration = span.duration_ns or 0
1307
+ width = _clamp(duration / extent.span_ns * 100, 0.0, 100.0 - left)
1308
+ return left, width
1309
+
1310
+
1311
+ def is_instant(span: Span) -> bool:
1312
+ """No usable duration: one known instant, or an explicitly unknown clock."""
1313
+ return span.timing_quality == "unknown" or not (span.duration_ns and span.duration_ns > 0)
1314
+
1315
+
1316
+ def flatten(roots: list, collapsed=frozenset(), extent: Extent | None = None) -> tuple:
1317
+ """Depth-first rows, skipping the children of collapsed spans.
1318
+
1319
+ Returns (rows, truncated). Collapse is honoured here so it is testable, but
1320
+ the template renders every row and lets the browser hide descendants — which
1321
+ is what makes expanding a deep-linked span a no-round-trip operation.
1322
+
1323
+ *extent* is the window the rows are placed on and their offsets counted
1324
+ from. A zoomed view passes the subtree's own window here (`extent_of` over
1325
+ the one span), so every offset it shows is from the zoomed span's start —
1326
+ the same origin its axis ticks use.
1327
+ """
1328
+ if extent is None:
1329
+ extent = extent_of(roots)
1330
+
1331
+ rows: list = []
1332
+ truncated = 0
1333
+ seen: set = set()
1334
+
1335
+ def walk(span, depth):
1336
+ nonlocal truncated
1337
+ if span.span_id and span.span_id in seen:
1338
+ return
1339
+ seen.add(span.span_id)
1340
+ if len(rows) >= MAX_ROWS:
1341
+ # Count what is being dropped, so the page can say so rather than
1342
+ # silently ending mid-tree.
1343
+ truncated += 1 + sum(1 for _ in all_spans(span.children))
1344
+ return
1345
+ left, width = place(span, extent)
1346
+ rows.append(
1347
+ Row(
1348
+ span=span,
1349
+ depth=depth,
1350
+ has_children=bool(span.children),
1351
+ offset_ns=span.start_ns - extent.start_ns,
1352
+ left_pct=left,
1353
+ width_pct=width,
1354
+ is_instant=is_instant(span),
1355
+ )
1356
+ )
1357
+ if span.children and span.span_id not in collapsed:
1358
+ for child in span.children:
1359
+ walk(child, depth + 1)
1360
+
1361
+ for root in roots:
1362
+ walk(root, 0)
1363
+ return rows, truncated
1364
+
1365
+
1366
+ def ticks_for(extent: Extent, n: int = 5) -> list:
1367
+ """Axis ticks on a 1/2/5×10^k step, labelled as offsets from the start."""
1368
+ span = extent.span_ns
1369
+ if span <= 1:
1370
+ return [Tick(pct=0.0, ns=0)]
1371
+ rough = span / max(n, 1)
1372
+ magnitude = 10 ** int(math.floor(math.log10(rough)))
1373
+ step = next(
1374
+ (m * magnitude for m in (1, 2, 5, 10) if m * magnitude >= rough),
1375
+ 10 * magnitude,
1376
+ )
1377
+ ticks = []
1378
+ value = 0
1379
+ while value <= span and len(ticks) <= n * 3:
1380
+ ticks.append(Tick(pct=value / span * 100, ns=int(value)))
1381
+ value += step
1382
+ return ticks
1383
+
1384
+
1385
+ def _totals(raw: dict) -> Totals:
1386
+ if not raw:
1387
+ return Totals()
1388
+ return Totals(
1389
+ wall_ns=_int_or_none(raw.get("wall_ns")),
1390
+ llm_ns=_int_or_none(raw.get("llm_ns")),
1391
+ tool_ns=_int_or_none(raw.get("tool_ns")),
1392
+ reasoning_ns=_int_or_none(raw.get("reasoning_ns")),
1393
+ idle_ns=_int_or_none(raw.get("idle_ns")),
1394
+ span_count=_int_or_none(raw.get("span_count")),
1395
+ measured_span_count=_int_or_none(raw.get("measured_span_count")),
1396
+ )
1397
+
1398
+
1399
+ def parse(data: dict, filt: "Filter | None" = None) -> Trace:
1400
+ """Build a Trace from already-decoded JSON. Pure — what the tests drive.
1401
+
1402
+ *filt* hides spans from the view (see :class:`Filter`). Everything the filter
1403
+ controls needs the unfiltered document too, and for different reasons: the
1404
+ chips have to offer labels that are currently hidden, the axis has to stay
1405
+ where it was so the surviving bars do not move, and the producer's `totals`
1406
+ is reported whatever is on screen.
1407
+ """
1408
+ if not isinstance(data, dict):
1409
+ return Trace(error="trace.json is not an object")
1410
+
1411
+ filt = filt or Filter()
1412
+ # Normalised before anything reads it, so `raw` is the unfiltered document as
1413
+ # the page will name it — the chips, the axis, the filter and the baseline
1414
+ # breakdown all come off this list, and a span has to be folded and named the
1415
+ # same way in every one of them. Same order, and the same list, as
1416
+ # `filtered_document` writes out.
1417
+ raw = mark_groups(fold_llm_requests(data.get("spans") or []))
1418
+ kept, hidden = prune(raw, filt)
1419
+ roots = [_span(s) for s in kept]
1420
+ extent = raw_extent(raw)
1421
+ # The zoom is a second, explicit window on top of the filter — never a
1422
+ # re-scaling of the filtered view. It is looked up in the *pruned* tree, so a
1423
+ # zoom on a span the filter hides falls back to the whole trace with a note,
1424
+ # and the axis it re-bases on is the subtree's own extent (`extent_of` over
1425
+ # the one span, the same walk the global axis uses — no second layout).
1426
+ # Spans outside the subtree are left out of the rows, not squeezed in.
1427
+ axis, zoomed, zoom_lost = extent, None, ""
1428
+ if filt.zoom:
1429
+ zoomed = find_span(roots, filt.zoom)
1430
+ if zoomed is None:
1431
+ zoom_lost = filt.zoom
1432
+ else:
1433
+ axis = extent_of([zoomed])
1434
+ rows, truncated = flatten([zoomed] if zoomed else roots, extent=axis)
1435
+ totals = _totals(data.get("totals") or {})
1436
+ names = labels_by_id(raw) if filt.span_ids else {}
1437
+
1438
+ return Trace(
1439
+ # Real files emit `trial_name`; the format doc calls it `run_id`. Take
1440
+ # either, prefer what the producer actually writes.
1441
+ run_id=str(data.get("trial_name") or data.get("run_id") or ""),
1442
+ roots=roots,
1443
+ totals=totals,
1444
+ extent=extent,
1445
+ axis=axis,
1446
+ rows=rows,
1447
+ ticks=ticks_for(axis) if rows else [],
1448
+ truncated=truncated,
1449
+ shown=sum(1 for _ in all_spans(roots)),
1450
+ zoomed=zoomed,
1451
+ zoom_lost=zoom_lost,
1452
+ filter=filt,
1453
+ facets=inventory(raw, filt),
1454
+ hidden_spans=[(sid, names.get(sid, sid)) for sid in filt.span_ids],
1455
+ hidden_count=hidden,
1456
+ # The wall clock is the run's, not the view's — see `Breakdown`. With no
1457
+ # `totals` block to take it from, the instrumented window is the best
1458
+ # denominator available, and it is the one the axis already uses.
1459
+ view=breakdown(kept, totals.wall_ns or extent.span_ns),
1460
+ # The same arithmetic over the unfiltered tree, so the view can show what
1461
+ # the filter changed without the producer's own accounting in the way.
1462
+ baseline=breakdown(raw, totals.wall_ns or extent.span_ns),
1463
+ )
1464
+
1465
+
1466
+ def load(path: str, filt: "Filter | None" = None) -> Trace:
1467
+ """Read *path*, or return a Trace carrying the error.
1468
+
1469
+ A trace is an observability sidecar: a missing or broken one must never take
1470
+ the trial page down with it.
1471
+ """
1472
+ try:
1473
+ with open(path, encoding="utf-8") as fh:
1474
+ data = json.load(fh)
1475
+ except (OSError, json.JSONDecodeError) as exc:
1476
+ return Trace(error=str(exc))
1477
+ return parse(data, filt)