Add timeline report: render folded execution as self-contained HTML

[contrasam]

Summary

Implements the v0.2 timeline UI exit criterion (spec §12): a new catalyst-timeline module that renders an execution's folded state as a read-only, self-contained HTML report. The report displays execution status, token/cost roll-ups from timelineView(), and a step-by-step trajectory table with latencies and recorded payloads.

Key Changes

• New module catalyst-timeline with TimelineReport class:

  • TimelineReport.html(ExecutionState) — renders a complete HTML document with inline styles, no external references
  • TimelineReport.writeTo(ExecutionState, Path) — writes the report to a file, creating parent directories as needed
  • All log content (task types, tool names, effect labels, payloads, error strings) is HTML-escaped to prevent injection

• Design constraints enforced:

  • Read-only and post-hoc: consumes a folded ExecutionState, installs no runtime hook; the log remains the only source of truth
  • Self-contained: no external scripts, stylesheets, images, or fonts; all styles are inline CSS; can be attached to tickets, committed as artifacts, or opened from file:// URLs
  • Deterministic: the same execution always produces the same HTML (pure function of the fold), making reports diffable and safe to version-control
  • Zero dependencies beyond catalyst-core: no templating engine, no web server, no Jackson beyond what core already uses

• Report structure:

  • Header with execution ID, task type, status badge, attempt/retry counts, and error message (if failed)
  • Summary section with tiles: model calls, tool calls, prompt/completion tokens, cost, boundary latency, wall clock, step count
  • Timeline table with columns: sequence number, boundary kind (color-coded), label, offset from start, latency, and collapsed detail block for payloads
  • Payloads over 2,000 characters are elided to prevent large completions from bloating the page

• Comprehensive test coverage:

  • TimelineReportTest: unit tests for HTML generation, escaping, determinism, payload elision, file writing
  • TimelineAcceptanceTest: end-to-end test rendering a mixed execution (model calls, tool calls, effects, memory writes) and verifying self-containment and determinism

• Integration:

  • Added to Demo class with timeline subcommand demonstrating the full workflow
  • CI workflow updated with v0.2 timeline exit demo (verifies self-contained and deterministic properties)
  • Documentation updated in README and ROADMAP

Implementation Details

• HTML escaping covers the five dangerous characters (&, <, >, ", ') applied uniformly to all interpolated values
• Status and kind badges use semantic color coding (green for success, red for failure, yellow for warnings, blue for running/model/tool)
• The timeline table scrolls horizontally within its own container to prevent oversized payloads or labels from forcing page-level horizontal scroll
• Payload details use HTML <details> elements for collapsible display, with character count and elision indicator
• Time formatting converts milliseconds to human-readable strings (e.g., "1.23 s" for values ≥ 1 second)

https://claude.ai/code/session_01G54yVgLZGZ3mzBv4kPc9F3

[greptile-apps]

Greptile Summary

Adds a self-contained HTML timeline report for folded execution state.

• Introduces catalyst-timeline with deterministic report rendering and file output.
• Displays execution metadata, aggregate metrics, and recorded timeline-step details.
• Integrates the report into the API demo, CI exit criteria, tests, documentation, and Maven reactor.
• Correctly preserves Unicode surrogate-pair boundaries while eliding oversized payloads.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported Unicode truncation defect is corrected by backing up cuts that split surrogate pairs and is covered by focused boundary tests.

Important Files Changed

Filename	Overview
catalyst-timeline/src/main/java/com/cajunsystems/catalyst/timeline/TimelineReport.java	Implements escaped, deterministic HTML rendering and safely truncates payload details at Unicode code-point boundaries.
catalyst-timeline/src/test/java/com/cajunsystems/catalyst/timeline/TimelineReportTest.java	Covers rendering, escaping, determinism, elision, file output, failures, and surrogate-boundary preservation.
catalyst-api/src/test/java/com/cajunsystems/catalyst/api/TimelineAcceptanceTest.java	Verifies the complete folded-execution reporting workflow and its self-contained output.
catalyst-api/src/main/java/com/cajunsystems/catalyst/api/Demo.java	Adds the timeline exit demo using a mixed execution with model, tool, memory, and effect boundaries.
.github/workflows/ci.yml	Adds CI assertions for self-contained and deterministic timeline output.
pom.xml	Registers and manages the new timeline module within the Maven reactor.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Execution event log] --> B[ExecutionState fold]
    B --> C[TimelineReport.html]
    C --> D[Self-contained HTML document]
    C --> E[TimelineReport.writeTo]
    E --> F[Portable report file]

Loading

_{Reviews (3): Last reviewed commit: "CI: restore the streaming step's run blo..." | Re-trigger Greptile}