openclaw/acpx
openclaw/acpx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity
main
acpx/examples/flows/replay-viewer/README.md
Onur Solmaz 48ae9011dc
feat: stream replay viewer runs live (#205) 
* feat: stream replay viewer runs live

* fix: keep replay bootstrap stable during live updates

* fix: streamline replay viewer recent runs

* feat: add first-class replay viewer scripts

* docs: adopt json patch plus spec

* docs: pin live transport decisions

* feat: stream live replay session updates

* fix: harden replay viewer live sync

* fix: guard replay viewer recent-run races

* fix: refresh replay snapshots from source

* fix: tint replay runs by status

* fix: render live replay sessions directly

* fix: harden replay viewer live runs sync

* fix: preserve replay viewer conversation order

* fix: settle completed terminal replay nodes

* feat: compact replay viewer tool cards

* refactor: simplify replay viewer tool event chrome

* refactor: flatten replay viewer tool events

* fix: reveal replay tool calls before step completion

* fix: make replay viewer follow sticky to bottom

* fix: detach replay viewer follow on upward scroll

* fix: rename replay viewer part discriminators
2026-04-02 01:06:15 +02:00

2.3 KiB
Raw Permalink Blame History

Flow Replay Viewer

This example app visualizes one saved flow run bundle at a time.

For the viewer semantics and UX/layout rules, see docs/2026-03-27-flow-replay-viewer.md. For the live viewer transport and state-sync model, see docs/2026-03-31-flow-replay-live-transport.md.

It is separate from the acpx CLI surface on purpose:

  • acpx writes replayable run bundles under ~/.acpx/flows/runs/
  • this viewer reads those bundles and renders them in the browser

The viewer uses:

  • the run bundle manifest and projections
  • the trace log
  • bundled ACP session snapshots and raw session events
  • React Flow for the graph

Run it

From the repo root:

pnpm viewer

Then open http://127.0.0.1:4173.

The local viewer server always uses that fixed port. If another replay viewer is already running there, the command reuses it instead of bouncing to a random new port.

Useful helper commands:

pnpm viewer:open
pnpm viewer:status
pnpm viewer:stop

The main path is the built-in Recent runs list sourced from:

~/.acpx/flows/runs/<run-id>/

If the viewer starts before any runs exist, it stays empty and waits for the first real run instead of falling back to a demo bundle. New runs appear in the left sidebar automatically, and the first recent run opens on its own.

When a recent run is still active, the sidebar and the selected run view update live over the viewer WebSocket transport. The viewer keeps the accumulated history locally, so you can still rewind while new steps continue to arrive.

What it shows

  • the flow graph, with replay progression over the saved step attempts
  • selected step prompt, raw response, parsed output, and action receipts
  • the ACP conversation slice for the selected ACP step
  • the raw bundled ACP event slice for that step

The full flow definition remains the main graph. The run is shown as an overlay on that graph rather than replacing it with an execution-only path.

Included sample

The bundled sample under public/sample-run/ still exists for development and test fixtures. It comes from a real run of examples/flows/two-turn.flow.ts against the repo's mock ACP agent, with the machine-specific paths sanitized for readability.