Skip to main content
Fabro captures a structured event for every significant action during a workflow run. These events cover stage execution, agent tool calls, retries, routing, sandbox lifecycle, git checkpoints, retro generation, and more.

​
Event stream

Every workflow run emits a sequence of canonical run event envelopes that are:
  • Stored durably in the run store
  • Broadcast over SSE to connected API clients
  • Stored for later analysis and retro generation
  • Rendered by CLI progress and log tooling
  • Optionally materialized into JSONL by export/debug paths

​
Event names

Event names use lowercase dot notation, for example:
  • run.started
  • stage.started
  • stage.completed
  • agent.tool.started
  • agent.tool.completed
  • sandbox.ready
  • parallel.branch.completed

​
Envelope format

Each serialized event envelope has a stable JSON shape: 
{
  "id": "01960d0c-5d16-7d6e-8f61-9fd6f4a532b5",
  "ts": "2026-03-30T12:00:01.000Z",
  "run_id": "01JQ...",
  "event": "agent.tool.started",
  "session_id": "ses_child",
  "parent_session_id": "ses_parent",
  "node_id": "implement",
  "node_label": "Implement",
  "properties": {
    "tool_name": "shell",
    "tool_call_id": "call_1",
    "arguments": {"command": "cargo test"}
  }
}
Envelope fields:
FieldDescription
idUnique event id
tsUTC timestamp
run_idWorkflow run id
eventEvent name
session_idSession that emitted the event, when applicable
parent_session_idImmediate parent session for forwarded child events
node_idNode or branch id, when applicable
node_labelHuman-facing label for node_id, when applicable
propertiesEvent-specific payload
Only id, ts, run_id, and event are always present. Optional fields are omitted when they do not apply.

​
Reading the event stream

Because event payload lives in properties, most shell queries should look there. 
# Count tool calls in a run
fabro logs 01JKXYZ... | jq -r 'select(.event == "agent.tool.started") | .properties.tool_name' | wc -l

# Find stage failures
fabro logs 01JKXYZ... | jq 'select(.event == "stage.failed")'

# See which edges were taken
jq '{from: .properties.from_node, to: .properties.to_node, label: .properties.label}' \
  <(fabro logs 01JKXYZ...) | head
If you need files on disk for offline analysis, fabro dump exports events.jsonl plus run-state projections.

​
Event categories

Common categories include:
CategoryExample events
Run lifecyclerun.started, run.completed, run.failed, run.notice
Stage lifecyclestage.started, stage.completed, stage.failed, stage.retrying
Agent activityagent.message, agent.tool.started, agent.warning, agent.sub.spawned
Routingedge.selected, loop.restart, parallel.started
Git and checkpointscheckpoint.completed, git.commit, git.push
Setup and sandboxsandbox.initializing, sandbox.ready, setup.started
Retroretro.started, retro.completed, retro.failed

​
Sub-agent visibility

Sub-agent activity now appears as normal agent events with session linkage:
  • session_id identifies the child session
  • parent_session_id identifies its immediate parent
Lifecycle events such as agent.sub.spawned and agent.sub.completed are emitted by the parent session. Tool calls and other child activity are forwarded with their original session_id.

​
Real-time monitoring

​
API: Server-Sent Events

When running workflows through the API server, subscribe to the run events endpoint. Each SSE payload is a serialized run event envelope in the same shape used by fabro logs and events.jsonl exports.

​
Web UI

The web frontend consumes the SSE stream automatically and shows stage progress, tool calls, and human interaction as they happen.
Fabro web UI run stages showing agent conversation with tool calls

​
CLI progress

The CLI renders live progress from the same envelope format. This is written to stderr so stdout remains pipe-friendly.

​
Post-run analysis

Post-run analysis surfaces include:
SurfaceDescription
fabro logs <RUN>Full event envelope stream as NDJSON
fabro inspect <RUN>Current durable run state, including run/start/checkpoint/conclusion records
fabro dump --output <DIR> <RUN>Exported events.jsonl plus reconstructed JSON and node files
See retros, stages, and turns for higher-level analysis views built on top of this event stream.