transcript-viewer 0.14.0__tar.gz → 0.15.0__tar.gz

transcript_viewer-0.14.0/README.md → transcript_viewer-0.15.0/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.5
+Name: transcript-viewer
+Version: 0.15.0
+Summary: Browse agent transcripts in a local, dependency-free web viewer.
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: atif-make>=0.8.0
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.40; extra == 'ai'
+Provides-Extra: parquet
+Requires-Dist: atif-make[parquet]>=0.8.0; extra == 'parquet'
+Description-Content-Type: text/markdown
+
 # transcript-viewer
 
 Browse agent transcripts in a local web viewer — what Claude Code, Codex and
@@ -166,17 +179,16 @@ If that directory is still there, the first run moves it to
 `~/.transcript-viewer` — index, annotations and stored keys together — and says
 so. Nothing is left behind and nothing is copied twice.
 
-A run that delegated shows what it farmed out, above its steps, as a **list**
-or a **timeline**. The list leads because the common question is what was asked
-and what came back, and the median subagent here is two steps — a bar for which
-says almost nothing. It carries the task, the kind, the steps, how long it took
-and the tools it reached for, sorted however you ask.
-
-The timeline is for when the question is *when*, and alongside what. A row is
-shared by everything that did not overlap, so a second row exists only because
-two things ran at once: thirty subagents in one session pack into eight rows,
-and a session of fifteen packs into one, which is the honest picture of a run
-that never did two things at a time. Either way a subagent is called what it was asked to
+A run that delegated shows what it farmed out, above its steps, as a
+**timeline** or a **list**. The timeline leads: a row is shared by everything
+that did not overlap, so a second row exists only because two things ran at
+once. Thirty subagents in one session pack into eight rows, and a session of
+fifteen packs into one, which is the honest picture of a run that never did two
+things at a time.
+
+The list is one chip away, and carries what a chart cannot: the task, the kind,
+the steps, how long it took and the tools it reached for, sorted however you
+ask. Whichever you pick is remembered. Either way a subagent is called what it was asked to
 do — "Review backend for bugs and DRY" rather than "general-purpose" — wherever
 that was written down, which is 50 of the 53 Claude Code subagents here; the
 kind is the fallback, and reads as a handle rather than as prose so the
@@ -186,9 +198,33 @@ in the corpus this was built against were. Two bars in the same column of the
 chart is what says it; overlap gets no colour of its own, since a second
 encoding of the same fact is noise.
 
+A subagent can delegate in turn, and in some harnesses that does not stop at two
+levels. One that did gets a row to itself, labelled, with the number it spawned
+and a control that opens them: its children appear beneath it, indented, packed
+among themselves rather than against the rest of the run. The list does the same
+with indented rows. Shut by default and remembered per subagent, so a run where
+nothing nested — which is every run in the library this was built against — is
+drawn exactly as it was before. The header says how deep the delegation went
+only when it went further than one hop.
+
+Under the chart is the shape of the delegation as numbers: every link in it
+sorted into the three kinds it can be — from the main thread, from another
+subagent, between subagents — to scale, with the counts and the ratio. A run is
+not described by its subagent count alone; five spawned by the main thread is a
+fan-out and five where two of them spawned the rest is a hierarchy, and the two
+read identically until the links are counted. Each kind is counted rather than
+assumed, so a format that starts recording one starts showing it here. Across
+the library this was built against the ratio is 100 / 0 / 0 — 52 links in 17
+transcripts, every one a call from the main thread — and 92 further subagents
+that nothing links at all, which is the fact the line exists to surface. Beside
+it: how many delegated in turn, the widest fan-out, and how many were spawned by
+nothing.
+
 Clicking a lane opens the box the transcript already has for it rather than
 showing the same thing twice, drawing the run out far enough to reach it first:
-in one real session every delegation happens after step 1,231.
+in one real session every delegation happens after step 1,231. A nested subagent
+is drawn inside its orchestrator's box, so it is the orchestrator's step that
+has to be painted and the boxes above it are unfolded on the way.
 
 A long run paints its first 250 steps at once and fills the rest in behind
 itself, so there is nothing to press and nothing to wait for. The largest run
@@ -407,29 +443,44 @@ an external file (`--split-subagents`) rather than an embedded trajectory, the
 viewer says so instead of silently showing nothing.
 
 Because branches sit anywhere in a trajectory that may run to thousands of
-steps, every session with branches gets a jump list at the top — agent type,
-task, step count — and an "only branches" filter. Steps render 250 at a time so
+steps, there is an "only branches" filter. There was also a jump list above the
+run, until the delegation box came to say everything it said and more — and to
+disagree with it, since the list counted top-level calls while the box counts
+every subagent at every depth. Steps render 250 at a time so
 a 8,000-step session stays responsive.
 
 ## Developing alongside atif-make
 
-The two packages are developed together. Installing the viewer editable makes
-its own code live:
+The two packages are developed together — a viewer feature usually needs the
+parser to record the thing first — so `atif-make` resolves from the directory
+next door rather than from the index:
 
-```sh
-uv tool install --force --editable .
+```toml
+[tool.uv.sources]
+atif-make = { path = "../atif-make", editable = true }
 ```
 
-That alone still resolves `atif-make` from git, so edits to the converter would
-not show up. To run with **both** live, add it explicitly:
+`uv run transcript-viewer` therefore runs both working copies, with no extra
+flags. uv drops that declaration when the package is built, so what is published
+still depends on the version range; a checkout without `atif-make` beside it can
+pass `--no-sources`.
+
+To make the installed command live too:
 
 ```sh
-uv run --with-editable ../atif-make transcript-viewer
+uv tool install --force --editable .
 ```
 
-Use that while changing anything in `atif-make`. Reinstall from the index
-(`uv tool install --force transcript-viewer`) when you want to test what users actually
-get.
+Reinstall from the index (`uv tool install --force transcript-viewer`) when you
+want to test what users actually get.
+
+**The page is re-read on every load; the converter is not.** `page.html` is
+stat'ed per request, so editing it shows on a refresh. Python modules are
+imported once and a converted trajectory is cached in memory for the life of the
+run, so a parser change needs the server restarted. A fix that made a session's
+delegation three levels deep looked like it had done nothing for exactly this
+reason: the page was new, the parser in memory was not, and the viewer drew what
+it was handed.
 
 ## Layout
 

transcript_viewer-0.14.0/PKG-INFO → transcript_viewer-0.15.0/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.5
-Name: transcript-viewer
-Version: 0.14.0
-Summary: Browse agent transcripts in a local, dependency-free web viewer.
-License: MIT
-Requires-Python: >=3.12
-Requires-Dist: atif-make>=0.7.1
-Provides-Extra: ai
-Requires-Dist: anthropic>=0.40; extra == 'ai'
-Provides-Extra: parquet
-Requires-Dist: atif-make[parquet]>=0.5.0; extra == 'parquet'
-Description-Content-Type: text/markdown
-
 # transcript-viewer
 
 Browse agent transcripts in a local web viewer — what Claude Code, Codex and
@@ -179,17 +166,16 @@ If that directory is still there, the first run moves it to
 `~/.transcript-viewer` — index, annotations and stored keys together — and says
 so. Nothing is left behind and nothing is copied twice.
 
-A run that delegated shows what it farmed out, above its steps, as a **list**
-or a **timeline**. The list leads because the common question is what was asked
-and what came back, and the median subagent here is two steps — a bar for which
-says almost nothing. It carries the task, the kind, the steps, how long it took
-and the tools it reached for, sorted however you ask.
-
-The timeline is for when the question is *when*, and alongside what. A row is
-shared by everything that did not overlap, so a second row exists only because
-two things ran at once: thirty subagents in one session pack into eight rows,
-and a session of fifteen packs into one, which is the honest picture of a run
-that never did two things at a time. Either way a subagent is called what it was asked to
+A run that delegated shows what it farmed out, above its steps, as a
+**timeline** or a **list**. The timeline leads: a row is shared by everything
+that did not overlap, so a second row exists only because two things ran at
+once. Thirty subagents in one session pack into eight rows, and a session of
+fifteen packs into one, which is the honest picture of a run that never did two
+things at a time.
+
+The list is one chip away, and carries what a chart cannot: the task, the kind,
+the steps, how long it took and the tools it reached for, sorted however you
+ask. Whichever you pick is remembered. Either way a subagent is called what it was asked to
 do — "Review backend for bugs and DRY" rather than "general-purpose" — wherever
 that was written down, which is 50 of the 53 Claude Code subagents here; the
 kind is the fallback, and reads as a handle rather than as prose so the
@@ -199,9 +185,33 @@ in the corpus this was built against were. Two bars in the same column of the
 chart is what says it; overlap gets no colour of its own, since a second
 encoding of the same fact is noise.
 
+A subagent can delegate in turn, and in some harnesses that does not stop at two
+levels. One that did gets a row to itself, labelled, with the number it spawned
+and a control that opens them: its children appear beneath it, indented, packed
+among themselves rather than against the rest of the run. The list does the same
+with indented rows. Shut by default and remembered per subagent, so a run where
+nothing nested — which is every run in the library this was built against — is
+drawn exactly as it was before. The header says how deep the delegation went
+only when it went further than one hop.
+
+Under the chart is the shape of the delegation as numbers: every link in it
+sorted into the three kinds it can be — from the main thread, from another
+subagent, between subagents — to scale, with the counts and the ratio. A run is
+not described by its subagent count alone; five spawned by the main thread is a
+fan-out and five where two of them spawned the rest is a hierarchy, and the two
+read identically until the links are counted. Each kind is counted rather than
+assumed, so a format that starts recording one starts showing it here. Across
+the library this was built against the ratio is 100 / 0 / 0 — 52 links in 17
+transcripts, every one a call from the main thread — and 92 further subagents
+that nothing links at all, which is the fact the line exists to surface. Beside
+it: how many delegated in turn, the widest fan-out, and how many were spawned by
+nothing.
+
 Clicking a lane opens the box the transcript already has for it rather than
 showing the same thing twice, drawing the run out far enough to reach it first:
-in one real session every delegation happens after step 1,231.
+in one real session every delegation happens after step 1,231. A nested subagent
+is drawn inside its orchestrator's box, so it is the orchestrator's step that
+has to be painted and the boxes above it are unfolded on the way.
 
 A long run paints its first 250 steps at once and fills the rest in behind
 itself, so there is nothing to press and nothing to wait for. The largest run
@@ -420,29 +430,44 @@ an external file (`--split-subagents`) rather than an embedded trajectory, the
 viewer says so instead of silently showing nothing.
 
 Because branches sit anywhere in a trajectory that may run to thousands of
-steps, every session with branches gets a jump list at the top — agent type,
-task, step count — and an "only branches" filter. Steps render 250 at a time so
+steps, there is an "only branches" filter. There was also a jump list above the
+run, until the delegation box came to say everything it said and more — and to
+disagree with it, since the list counted top-level calls while the box counts
+every subagent at every depth. Steps render 250 at a time so
 a 8,000-step session stays responsive.
 
 ## Developing alongside atif-make
 
-The two packages are developed together. Installing the viewer editable makes
-its own code live:
+The two packages are developed together — a viewer feature usually needs the
+parser to record the thing first — so `atif-make` resolves from the directory
+next door rather than from the index:
 
-```sh
-uv tool install --force --editable .
+```toml
+[tool.uv.sources]
+atif-make = { path = "../atif-make", editable = true }
 ```
 
-That alone still resolves `atif-make` from git, so edits to the converter would
-not show up. To run with **both** live, add it explicitly:
+`uv run transcript-viewer` therefore runs both working copies, with no extra
+flags. uv drops that declaration when the package is built, so what is published
+still depends on the version range; a checkout without `atif-make` beside it can
+pass `--no-sources`.
+
+To make the installed command live too:
 
 ```sh
-uv run --with-editable ../atif-make transcript-viewer
+uv tool install --force --editable .
 ```
 
-Use that while changing anything in `atif-make`. Reinstall from the index
-(`uv tool install --force transcript-viewer`) when you want to test what users actually
-get.
+Reinstall from the index (`uv tool install --force transcript-viewer`) when you
+want to test what users actually get.
+
+**The page is re-read on every load; the converter is not.** `page.html` is
+stat'ed per request, so editing it shows on a refresh. Python modules are
+imported once and a converted trajectory is cached in memory for the life of the
+run, so a parser change needs the server restarted. A fix that made a session's
+delegation three levels deep looked like it had done nothing for exactly this
+reason: the page was new, the parser in memory was not, and the viewer drew what
+it was handed.
 
 ## Layout
 

transcript_viewer-0.15.0/TODO.md

@@ -0,0 +1,40 @@
+# Deliberately not built yet
+
+Each of these was considered while building something adjacent and left out on
+purpose. The note says what is missing and what would make it worth doing, so a
+later reader can tell a decision from an oversight.
+
+## Inter-agent communication, drawn as arrows
+
+The delegation box counts the three kinds of link and shows the ratio
+(`laneShape`). What it does not do is *draw* a sideways link — a subagent
+addressing one that is not its own child would be an arrow between two bars on
+the timeline, and there is nowhere for one to go in the current layout.
+
+Worth building when a transcript has one. Across the whole library today the
+ratio reads 100 / 0 / 0 — 52 links in 17 transcripts, all of them a call from
+the main thread — so an arrow layer would have nothing to draw. The count is
+computed rather than assumed, so the day a format records a sibling message the
+number moves on its own and the arrows become the missing half.
+
+## Summarising what a subagent did
+
+The delegation box says how many steps a subagent took, how long it ran, and
+which tools it reached for. It does not say what it concluded. Doing that
+honestly means either reading the final assistant turn — which is often a wall
+of text — or generating a summary, which the AI features could do but which
+would then have to be marked as generated everywhere it appears.
+
+## Fleet scale
+
+The timeline is designed for the runs in the library: tens of subagents over
+hours. Reports of runs with **115 agents over ~1,170 minutes** are the case it
+is not designed for. Two things break first:
+
+- packed rows stop compressing, because at that many concurrent agents almost
+  everything overlaps something;
+- the 7px minimum bar width (`.bar{min-width:7px}`) stops being a floor and
+  starts being most of the chart.
+
+Both point at the same missing thing: **zoom**, and a way to collapse a group of
+lanes into one summary lane. Neither is a tweak to the current layout.

{transcript_viewer-0.14.0 → transcript_viewer-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "transcript-viewer"
-version = "0.14.0"
+version = "0.15.0"
 description = "Browse agent transcripts in a local, dependency-free web viewer."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -10,14 +10,18 @@ license = { text = "MIT" }
 # The floor is not politeness: this viewer imports atif_make.container, which
 # is how a benchmark published as one JSON array of a thousand runs becomes a
 # thousand sessions. An older atif-make fails to import at all.
-dependencies = ["atif-make>=0.7.1"]
+# 0.8.0 is where a Claude Code session that delegated more than one level deep
+# started converting to a tree. Against an older one the chart still draws, and
+# draws a flat row of subagents that nothing spawned — which reads as the
+# viewer being broken rather than the converter being old.
+dependencies = ["atif-make>=0.8.0"]
 
 [project.optional-dependencies]
 # Claude-backed explanations are opt-in, so the default install stays
 # dependency-free: pip install "transcript-viewer[ai]"
 # Datasets published as Parquet — METR's transcripts are the one so far. The
 # reader lives in atif-make, which only needs it to split a shard.
-parquet = ["atif-make[parquet]>=0.5.0"]
+parquet = ["atif-make[parquet]>=0.8.0"]
 ai = ["anthropic>=0.40"]
 
 [project.scripts]
@@ -26,6 +30,21 @@ transcript-viewer = "transcript_viewer.cli:main"
 [dependency-groups]
 dev = ["pytest>=8.0"]
 
+# Develop against the converter in the next directory, not the release.
+#
+# The two repos change together — a viewer feature usually needs the parser to
+# record the thing first — and resolving `atif-make` from PyPI meant every such
+# change looked like it had failed. A parser fix that made a session's
+# delegation three levels deep was invisible here for exactly that reason: the
+# page was local, the converter was 0.7.1, and the viewer faithfully drew what
+# the old parser handed it.
+#
+# uv drops `tool.uv.sources` when this package is built, so what is published
+# still depends on the version range above. A checkout without atif-make beside
+# it can pass `--no-sources`.
+[tool.uv.sources]
+atif-make = { path = "../atif-make", editable = true }
+
 
 [build-system]
 requires = ["hatchling"]