Render dynamic-workflow run tree on the nested DOM (#174 PR3)

[cboos]

Final PR for #174 (dynamic-workflow support). Builds on PR1 (parse) and PR2
(Workflow tool-input rendering): splices each parsed WorkflowRun — phases →
agents → each agent's side-channel transcript — into the message tree at its
Workflow tool_use site, rendered on the existing nested DOM.

What this adds

• Run-tree splice. _splice_workflow_runs (the last pass in
  generate_template_messages) attaches a self-contained sub-tree under each
  Workflow tool_use: a WorkflowPhaseMessage per phase, a WorkflowAgentMessage
  per agent (model / state / tokens / tool-calls + result — StructuredOutput
  dicts pretty-printed as JSON, plain strings as Markdown), and each agent's
  side-channel transcript grafted beneath it. Renders in both HTML and Markdown.
• Synthetic-node indices are allocated via ctx.register (len(messages)),
  an inherently session-wide monotonic allocator, so multiple/concurrent
  workflows in one session never collide. Grafted side-channel nodes are
  re-registered into the main context and their pairing references remapped.
• Timeline parity. Dedicated workflow_phase / workflow_agent lanes plus
  detection branches placed before the generic tool_use match (the cards carry
  tool_use for transcript-filter visibility).
• Single-file rendering. claude-code-log <session>.jsonl now discovers the
  session's sibling subagents/workflows/ runs and splices them, matching the
  directory-load behavior.
• Pagination-robust linkage. Run↔tool_use linkage is resolved once at
  full-session scope (before pagination), so a Workflow tool_use links to its
  run even when its tool_result lands on a different page.

Verification

• Validated end-to-end on a real ~76k-message project: the run renders its
  phases + 42 agent cards via the directory, single-file, and
  cache+pagination paths.
• New tests cover the splice structure, side-channel grafting, index
  uniqueness, HTML + Markdown rendering, single-file rendering, the
  pagination-boundary case, and a Playwright fold test for the phase nodes.
• Non-workflow output is byte-identical (snapshot diff is only the added
  workflow CSS rules + timeline detection JS); full unit suite, browser tests,
  and pyright all green.

Closes #174.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Dynamic workflow phases and agents are rendered as interactive cards (metadata, model/tokens, results) and are spliced into transcripts.
  • Workflow header resolution prefers snapshot data; single-file transcripts now discover and render linked workflow runs.

• Bug Fixes

  • Improved cross-page/linkage handling so workflow run links are resolved at full-session scope to avoid pagination breakage.

• Tests

  • Added comprehensive rendering tests including browser folding behavior.

• Documentation

  • Updated design docs describing the splice/render strategy and verification.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b80bbaac-170d-43ab-b205-d47bb21fcad8

📥 Commits

Reviewing files that changed from the base of the PR and between 4a670d7 and adf9cee.

📒 Files selected for processing (3)

• claude_code_log/html/tool_formatters.py
• test/test_workflow_rendering.py
• work/dynamic-workflow-pr3-design.md

✅ Files skipped from review due to trivial changes (1)

• work/dynamic-workflow-pr3-design.md

🚧 Files skipped from review as they are similar to previous changes (2)

• claude_code_log/html/tool_formatters.py
• test/test_workflow_rendering.py

---

📝 Walkthrough

Walkthrough

This PR implements dynamic workflow rendering for transcripts by detecting and loading WorkflowRun data from the filesystem, linking runs to Workflow tool_use inputs via task IDs (or session mapping), and splicing phase/agent subtrees with side-channel entries into the rendered message tree using snapshot-first metadata resolution.

Changes

Dynamic Workflow Rendering

Layer / File(s)	Summary
Message content types and SessionTree data model claude_code_log/models.py, claude_code_log/dag.py	WorkflowPhaseMessage and WorkflowAgentMessage dataclasses added; SessionTree gains workflow_runs and workflow_links dicts to carry parsed runs and tool_use→run mappings.
Workflow loading, discovery, and tool_use linkage claude_code_log/workflow.py, claude_code_log/converter.py	Adds resolve_workflow_header(run, script) (snapshot-first), _runs_in_session_dir, load_session_workflow_runs, _tool_result_text, and map_workflow_runs_by_tool_use(entries, runs) to discover runs and link them to Workflow tool_use ids; converter populates SessionTree.workflow_runs/workflow_links for directory and single-file modes.
HTML formatter implementation for workflow components claude_code_log/html/tool_formatters.py	format_workflow_phase_content and format_workflow_agent_content render phase and agent cards (metadata, tokens/tool-call counts, result as pretty JSON/Markdown/preview); format_workflow_input now uses resolve_workflow_header.
Markdown formatter implementation for workflow components claude_code_log/markdown/renderer.py	Adds format_WorkflowPhaseMessage and format_WorkflowAgentMessage and updates format_WorkflowToolInput to use snapshot-first header resolution.
HTML renderer dispatch claude_code_log/html/renderer.py	HtmlRenderer imports workflow message types and adds format_WorkflowPhaseMessage / format_WorkflowAgentMessage delegating to HTML helpers.
HTML UI wiring: CSS, timeline classification, and utilities claude_code_log/html/templates/components/message_styles.css, claude_code_log/html/templates/components/timeline.html, claude_code_log/html/utils.py	Adds CSS classes for .workflow-phase / .workflow-agent metadata and previews; extends timeline messageTypeGroups and buildTimelineData() to explicitly detect workflow classes; registers CSS and emoji mappings.
Renderer splice and linkage passes claude_code_log/renderer.py	Adds _link_workflow_runs to attach WorkflowRun to WorkflowToolInput (via SessionTree mapping or task-id regex fallback), and _splice_workflow_runs which registers synthetic phase/agent TemplateMessages, grafts agent side-channel transcripts by re-running pipeline in sub-contexts with index/pair remapping, and updates child/descendant counts and titles for accurate fold controls.
Tests, snapshots, fixtures, and docs test/test_workflow_rendering.py, test/test_workflow_browser.py, test/__snapshots__/test_snapshot_html.ambr, test/test_data/workflow_basic/*.jsonl, scripts/gen_workflow_fixture.py, work/dynamic-workflow-pr3-design.md	Updates fixture payloads; adds unit and Playwright browser tests for header resolution, run↔tool_use linkage, splicing behavior, single-file discovery, and pagination boundary cases; updates repeated HTML snapshots and adds design documentation for the splice strategy and watch-points.

Sequence Diagram

sequenceDiagram
  participant Converter
  participant WorkflowModule
  participant SessionTree
  participant Renderer
  participant TemplateMessage
  Converter->>WorkflowModule: load_session_workflow_runs(transcript_path)
  WorkflowModule->>WorkflowModule: discover and parse WorkflowRun files
  WorkflowModule-->>Converter: list of WorkflowRun
  Converter->>WorkflowModule: map_workflow_runs_by_tool_use(entries, runs)
  WorkflowModule-->>Converter: {tool_use_id: WorkflowRun}
  Converter->>SessionTree: attach workflow_runs and workflow_links
  Renderer->>SessionTree: read workflow_runs and workflow_links
  Renderer->>Renderer: _link_workflow_runs(assign runs to WorkflowToolInput)
  Renderer->>Renderer: _splice_workflow_runs(register synthetic nodes)
  Renderer->>TemplateMessage: register phase/agent TemplateMessages
  Renderer->>TemplateMessage: graft agent side-channel entries + reindex
  Renderer->>TemplateMessage: update child/descendant counts

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• daaain/claude-code-log#203: Introduces WorkflowRun parsing and discovery infrastructure that this PR consumes for session-run loading and linking.
• daaain/claude-code-log#205: Shares changes to workflow header parsing/formatting (parse_workflow_meta → resolve_workflow_header) and early WorkflowToolInput rendering groundwork.
• daaain/claude-code-log#97: Related SessionTree/DAG pipeline changes that this PR extends by adding workflow_runs/workflow_links to SessionTree and leveraging them during rendering.

Poem

🐰
I stitched the runs into the log with care,
phases and agents springing out to share,
task IDs linked, snapshots guide the name,
fold bars fold and then unfold again,
a tiny rabbit cheers the render game.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: implementing workflow run tree rendering on the nested DOM, with the issue reference (#174 PR3) providing precise context.
Linked Issues check	✅ Passed	The PR fully addresses all coding requirements from issue #174: workflow run discovery/parsing, tool_use linkage, phase/agent/side-channel rendering in HTML/Markdown, single-file support, pagination robustness, and timeline parity.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with #174's objectives: workflow run data structures, linkage/splicing logic, renderer methods for workflow phases/agents, CSS/timeline updates, and comprehensive tests. CSS/timeline updates and snapshot changes are necessary for proper workflow rendering.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev/wf-tree-render

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

claude_code_log/html/templates/components/timeline.html (1)

322-323: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add workflow lanes to timeline group ordering

groupOrder doesn’t include the new workflow_phase and workflow_agent groups, so they resolve to -1 in indexOf and can appear in inconsistent positions.

Suggested fix

-                    const order = ['user', 'teammate', 'task-notification', 'system', 'slash-command', 'command-output', 'bash-input', 'bash-output', 'thinking', 'assistant', 'sidechain', 'memory', 'tool_use', 'tool_result', 'image'];
+                    const order = ['user', 'teammate', 'task-notification', 'system', 'slash-command', 'command-output', 'bash-input', 'bash-output', 'thinking', 'assistant', 'sidechain', 'memory', 'tool_use', 'workflow_phase', 'workflow_agent', 'tool_result', 'image'];

As per coding guidelines, “When adding new message types … ensure the timeline's message type detection logic in templates/components/timeline.html is updated accordingly”; the ordering list should include the new workflow lanes too.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@claude_code_log/html/templates/components/timeline.html` around lines 322 -
323, The timeline group ordering array (the const order in
templates/components/timeline.html used by the comparator that returns
order.indexOf(a.id) - order.indexOf(b.id)) is missing the new workflow lanes,
causing them to resolve to -1 and be ordered inconsistently; update the order
array to include 'workflow_phase' and 'workflow_agent' in the desired positions
(e.g., near other workflow/system items) so the comparator correctly ranks those
group ids when sorting timeline groups.

Sources: Coding guidelines, Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@claude_code_log/html/tool_formatters.py`:
- Around line 1280-1286: The current branch sends list-shaped results through
render_async_result_body(json.dumps(result,...)) but that helper only triggers
JSON-highlighting for object-shaped text, so lists fall back to markdown; fix by
detecting list results and wrapping them into an object before dumping (e.g.,
replace json.dumps(result, ...) with json.dumps({"list": result},
ensure_ascii=False) or similar) so render_async_result_body receives a
"{"-prefixed JSON string; update the code path using render_async_result_body
and json.dumps to wrap lists (keep dicts unchanged) and preserve any necessary
metadata if needed.

In `@work/dynamic-workflow-pr3-design.md`:
- Around line 212-214: The documentation contradicts the intended pipeline
order: update the description and placement of the splice pass in renderer.py so
that _splice_workflow_runs is described and invoked as the final pass (i.e.,
after _link_task_id_consumers), not before _link_async_notifications; change the
text that currently places it "AFTER _build_message_tree, BEFORE
_link_async_notifications" to state it runs after _link_task_id_consumers and
ensure the callsite ordering in the docs matches that final sequence.
- Around line 186-269: Replace the stale checklist-style "Step 3 implementation
map" with a past-tense summary of what was implemented and any follow-up notes:
state that WorkflowPhaseMessage and WorkflowAgentMessage dataclasses were added,
CSS_CLASS_REGISTRY entries were added, format_WorkflowPhaseMessage /
title_WorkflowPhaseMessage and format_WorkflowAgentMessage /
title_WorkflowAgentMessage were implemented in HtmlRenderer/MarkdownRenderer,
components/message_styles.css was updated, _splice_workflow_runs and
generate_template_messages were added for grafting/re-indexing, fold-state
fields and child-count helpers were set, messageTypeGroups and timeline
detection in components/timeline.html were extended, and tests
(test_workflow_rendering.py and the Playwright fold test) were added/updated;
remove the "EXACT NEXT ACTION" checklist or convert it into a short "Follow-ups
/ verification" list mentioning where to look (e.g., _splice_workflow_runs,
generate_template_messages, CSS_CLASS_REGISTRY, format_* methods,
messageTypeGroups) for any further tweaks.

---

Outside diff comments:
In `@claude_code_log/html/templates/components/timeline.html`:
- Around line 322-323: The timeline group ordering array (the const order in
templates/components/timeline.html used by the comparator that returns
order.indexOf(a.id) - order.indexOf(b.id)) is missing the new workflow lanes,
causing them to resolve to -1 and be ordered inconsistently; update the order
array to include 'workflow_phase' and 'workflow_agent' in the desired positions
(e.g., near other workflow/system items) so the comparator correctly ranks those
group ids when sorting timeline groups.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 550903ba-21a8-4522-a5cf-a4484c43d873

📥 Commits

Reviewing files that changed from the base of the PR and between 4fe6788 and 4a670d7.

📒 Files selected for processing (17)

• claude_code_log/converter.py
• claude_code_log/dag.py
• claude_code_log/html/renderer.py
• claude_code_log/html/templates/components/message_styles.css
• claude_code_log/html/templates/components/timeline.html
• claude_code_log/html/tool_formatters.py
• claude_code_log/html/utils.py
• claude_code_log/markdown/renderer.py
• claude_code_log/models.py
• claude_code_log/renderer.py
• claude_code_log/workflow.py
• scripts/gen_workflow_fixture.py
• test/__snapshots__/test_snapshot_html.ambr
• test/test_data/workflow_basic/11110000-0000-4000-8000-000000000001.jsonl
• test/test_workflow_browser.py
• test/test_workflow_rendering.py
• work/dynamic-workflow-pr3-design.md