Session replay: canonical schema + `replay_events` table + `/api/replay-tree` endpoint + renderer skeleton

[vivekchand]

Context

The transcript viewer is a single flat renderer driven by one endpoint (/api/transcript/<id>) that assumes a linear message list. It's runtime-blind — every runtime (Claude Code with its 40+ sidechain Task/Agent/Workflow fanouts, OpenClaw with its subagent_runs + flow_runs tree, Codex with per-turn approval_policy, Antigravity with cascade_id sub-trajectories, n8n as a workflow-first DAG…) is coerced into the same flat shape. Sub-agent trees collapse. Workflow fanouts collapse. Mode changes vanish. Approvals never render.

This meta issue lands the neutral foundation everything else builds on.

Deliverables

1. Canonical replay-event schema — new module clawmetry/replay_schema.py. Every adapter maps its native events into this shape:

ReplayEvent = {
    "ts": float,                # unix seconds
    "kind": str,                # see enum below
    "span_id": str,             # stable id for this event
    "parent_span_id": str|None, # tree edge (delegation parent, NOT transcript-chain parent)
    "session_id": str,
    "runtime": str,             # "claude_code" | "openclaw" | ...
    "payload": dict,            # kind-specific
    "mode": {                   # None if unchanged
        "permission": str|None, # "default"|"acceptEdits"|"plan"|"bypassPermissions"|"yolo"|None
        "sandbox": str|None,    # "read-only"|"workspace-write"|"danger-full-access"|None
        "collaboration": str|None,
    } | None,
    "approval": {               # only on kind=approval.*
        "status": str,          # "requested"|"approved"|"denied"|"edited"|"timeout"
        "decision_reason": str|None,
        "resolver": str|None,   # "user"|"hook"|"policy"
        "edit_diff": dict|None, # {"before": args, "after": args} — new field
    } | None,
}

kind enum: llm.call | llm.response | tool.call | tool.result | agent.spawn | agent.return | workflow.start | workflow.stage | workflow.end | approval.requested | approval.decided | mode.changed | thinking | compaction.

2. DuckDB table replay_events in clawmetry/local_store.py. Indices on (session_id, ts), (parent_span_id), (runtime, kind). Written by the sync daemon (writer lock owned by daemon per feedback_local_store_fetch_takes_writelock.md).

3. Endpoint /api/replay-tree/<session_id> in routes/sessions.py — returns a nested structure:

{
  "session_id": ...,
  "runtime": ...,
  "mode": {...},              # latest resolved
  "turns": [
    {
      "turn_id": ...,
      "events": [...],        # kind=llm.*/tool.*/thinking
      "delegations": [        # kind=agent.spawn, nested
        {"span_id": ..., "child_session_id": ..., "events": [...], "delegations": [...]}
      ],
      "approvals": [...]      # kind=approval.*, aligned to the turn
    }
  ],
  "workflows": [ ... ]        # top-level workflow fanouts (Claude Code Workflow tool, OpenClaw flow_runs)
}

Reads from DuckDB via routes/local_query.py — per feedback_daemon_proxy_pattern.md, no direct writer-lock grab.

4. Renderer skeleton in clawmetry/static/js/app.js — new _renderReplayTree seam. Extends _renderTurnChapter (currently at app.js:15600) with a delegations prop and a new _renderSubagentBlock that renders nested children inline with indent + collapse. Runtime dispatcher in the same pattern as the Harness tab template system at app.js:16729.

Out of scope

• Runtime-specific iter_replay_events() mappers — those are per-runtime follow-ups (Claude Code, OpenClaw, and 13 more in clawmetry-pro).
• Mode + approvals ingest — separate OSS issue.
• Hook lifecycle contract — separate OSS issue.

Acceptance

• replay_events table lands in DuckDB migrations
• /api/replay-tree/<id> returns the nested shape (empty delegations/workflows OK until mappers land)
• Renderer skeleton loads without regressing the existing session-trace redesign (PR [RELEASE] feat(sessions): turn-anchored trace UI with collapsed tools + jump-to-turn TOC #4802, 0.12.694) — old flat renderer stays as fallback until a runtime declares runtime_kind on its events

Gotchas

• "parent" is overloaded — transcript-chain parent (OpenClaw v3 parentId is a chain not a tree — reference_openclaw_v3_parentid_is_chain.md), delegation parent, and branch parent (Pi). Schema uses parent_span_id for the delegation edge only.
• Sidechain files can outnumber the parent 40:1 for Claude Code. Endpoint MUST support lazy child expansion — do not fetch all sidechains eagerly.
• SQLite runtimes (Hermes, opencode, Goose, Antigravity, OpenClaw, deepagents) actively write while we read — every read path uses mode=ro.

References

• Audit: session-trace redesign extension points at clawmetry/static/js/app.js:15420, :15600, :15676
• Endpoint patterns: routes/sessions.py:4338 (api_transcript), :4575 (api_transcript_events)
• DuckDB conventions: clawmetry/local_store.py:534 (run_ledger), :888 (spans)
• CLAUDE.md → routes/local_query.py bridge rules

[vivekchand]

Hi @vivekchand! Took a careful look at this issue. Here's the plan:

The problem
The transcript viewer coerces every AI runtime's execution tree into a flat message list, erasing sub-agent delegations, workflow fanouts, and mode changes that are essential for understanding what actually happened in a multi-agent session.

Approach

1. clawmetry/replay_schema.py (new file, ~65 LOC) — Define the canonical ReplayEvent TypedDict with the 14-member kind enum (llm.call | llm.response | tool.call | tool.result | agent.spawn | agent.return | workflow.start | workflow.stage | workflow.end | approval.requested | approval.decided | mode.changed | thinking | compaction). Keep it a pure data contract with no Flask or DuckDB imports so it's importable anywhere, including tests.

2. clawmetry/local_store.py (around line 534 near run_ledger, line 888 near spans) — Add the replay_events table in the DuckDB migrations block. Schema from the issue spec; indices on (session_id, ts), (parent_span_id), and (runtime, kind). This goes in the same CREATE TABLE IF NOT EXISTS pattern already used for spans and run_ledger, so the daemon picks it up automatically on next start with no manual migration step (~35 LOC).

3. routes/sessions.py (new endpoint near api_transcript at ~:4338, following the _dispatch / local_query.py bridge pattern from CLAUDE.md) — /api/replay-tree/<session_id> that queries replay_events via routes/local_query.py and assembles the nested { session_id, runtime, mode, turns: [...], workflows: [...] } response. Key gotcha: parent_span_id is the delegation edge only — not the transcript chain parent — so the tree walk must group by delegation, not by parentId. Must support lazy child expansion (no eager sidechain fetch) because Claude Code sidechains can outnumber the parent 40:1. Empty delegations/workflows arrays are fine until runtime mappers land (~90 LOC).

4. clawmetry/static/js/app.js (extending _renderTurnChapter at ~:15600, using the runtime-dispatch pattern from the Harness tab at ~:16729) — Add _renderReplayTree(session, replayData) entry point and _renderSubagentBlock(delegation, depth) for recursive nested rendering with indent + collapse toggle. Falls back to the existing flat renderer if /api/replay-tree/ returns 404 or delegations is absent, so the old renderer stays live until a runtime declares runtime_kind on its events (~75 LOC).

Test plan

• Unit test for replay_schema.py: fixture ReplayEvent dicts round-trip through the schema shape validator.
• Integration test: POST synthetic events into replay_events via the DuckDB writer, call /api/replay-tree/<session_id>, assert nested structure matches expected tree (delegation within a turn, empty workflows).
• Regression: existing /api/transcript/ endpoint and _renderTurnChapter path unchanged — current session-trace tests (PR [RELEASE] feat(sessions): turn-anchored trace UI with collapsed tools + jump-to-turn TOC #4802 regression suite) remain green.
• Verify the 4318 OTLP port (landed in feat(otel): OTLP receiver that works out of the box (JSON without protobuf, port 4318, hex ids) #4785) and existing brain/subagent views are unaffected.

Estimated change
~265 lines across 4 files: clawmetry/replay_schema.py (new), clawmetry/local_store.py, routes/sessions.py, clawmetry/static/js/app.js.

---

This one's bigger than I'm comfortable autonomously shipping — it touches a DB schema migration, complex tree-walk logic (the "parent is overloaded" gotcha is genuinely subtle), and frontend rendering that needs visual verification. Leaving the plan here for your review. If you want me to proceed, comment bot-go and I'll pick it up next run.

---

Generated by Claude Code