Replay Debugger

The replay debugger lets you reconstruct an agent's execution timeline from its audit log entries and workspace snapshots. It is useful for post-incident analysis and debugging complex multi-step agent failures.

Viewing the Timeline

ash replay timeline <agent-id>

Outputs a merged chronological timeline of:

  • Lifecycle state transitions
  • Tool invocations (with inputs and outputs)
  • Observation log entries
  • Workspace snapshot events
  • Anomaly events
  • Audit entries
2026-02-22T12:00:00Z  [Init]    agent spawned
2026-02-22T12:00:01Z  [Plan]    plan declared: ["search web", "summarize", "write report"]
2026-02-22T12:00:02Z  [Act]     web.search({"query": "renewable energy 2026"}) → 5 results
2026-02-22T12:00:03Z  [Act]     lm.complete({"prompt": "Summarize..."}) → 300 tokens
2026-02-22T12:00:05Z  [Obs]     observed: "summary generated"
2026-02-22T12:00:06Z  [Act]     fs.write({"path": "/workspace/report.md"}) → 1.2KB written
2026-02-22T12:00:07Z  [Snapshot] workspace snapshot 1 taken
2026-02-22T12:00:08Z  [Terminate] agent exited cleanly

Filtering by Time Range

ash replay timeline <agent-id> --since 2026-02-22T12:00:00Z
ash replay timeline <agent-id> --until 2026-02-22T12:00:05Z
ash replay timeline <agent-id> --since 2026-02-22T12:00:00Z --until 2026-02-22T12:00:05Z

Rolling Back Workspace

To restore the agent's workspace to a previous snapshot for inspection:

ash replay rollback <agent-id> <snapshot-index>

This is identical to ash workspace rollback but surfaced in the replay subcommand for convenience.

Combining with Observation Logs

For the full picture, combine the replay timeline with the observation log:

# Timeline
ash replay timeline <agent-id>

# Detailed observations
ash obs query <agent-id> --limit 100

Use Cases

  • Post-incident analysis - understand exactly what an agent did before it failed or was terminated
  • Debugging prompt injection - trace the tool calls that resulted from an unexpected prompt
  • Regression testing - compare timelines between runs to identify behavioral changes
  • Training data generation - export successful agent traces for fine-tuning