Event Format Reference

Wave emits structured NDJSON (Newline-Delimited JSON) events to stdout on every state transition during pipeline execution. Events are both human-readable in the terminal and machine-parseable for CI/CD integration.

Event Schema

Every event contains these fields:

Field	Type	Always Present	Description
timestamp	string	yes	ISO 8601 timestamp with timezone.
pipeline_id	string	yes	UUID for this pipeline execution instance.
step_id	string	no	Step identifier within the pipeline.
state	string	yes	Event state (see Event States below).
duration_ms	int64	no	Milliseconds elapsed since step started.
message	string	no	Human-readable status message.
persona	string	no	Persona executing the step.
artifacts	[]string	when completed	List of output artifact paths.
tokens_used	int	when completed	Total token count for the step.
tokens_in	int	when completed	Input token count.
tokens_out	int	when completed	Output token count.
progress	int	no	Percentage progress (0-100).
current_action	string	no	Current action description.
total_steps	int	when started	Total pipeline steps.
completed_steps	int	no	Number of completed steps.
estimated_time_ms	int64	yes (0 = no estimate)	Estimated remaining time in milliseconds.
validation_phase	string	no	Current contract validation phase.
compaction_stats	string	no	Relay compaction statistics.
failure_reason	string	when failed	Detailed failure reason.
remediation	string	when failed	Suggested fix for the failure.
tool_name	string	no	Tool being used (for stream_activity events).
tool_target	string	no	Tool target path or argument.
model	string	no	LLM model used for the step.
adapter	string	no	Adapter used (e.g., "claude").
temperature	float	no	Temperature setting used.
recovery_hints	[]object	when failed	Recovery hint suggestions.
outcomes	object	when completed	Step outcome summary.

Event States

State	Description
started	Pipeline or step has begun execution.
running	Step is actively executing.
completed	Step or pipeline finished successfully.
failed	Step or pipeline failed.
retrying	Step is being retried after validation failure.
step_progress	Progress update within a running step.
eta_updated	Estimated time of completion updated.
contract_validating	Contract validation is in progress.
compaction_progress	Relay compaction is in progress.
stream_activity	Real-time tool activity from the adapter.
skipped	Step was skipped (condition not met or dependency failed).

Event Examples

Pipeline Start

{"timestamp":"2026-02-01T10:00:00.500Z","pipeline_id":"a1b2c3d4","step_id":"navigate","state":"started","message":"Starting navigator persona","persona":"navigator"}

Step Completed

{"timestamp":"2026-02-01T10:01:30.000Z","pipeline_id":"a1b2c3d4","step_id":"navigate","state":"completed","duration_ms":90000,"message":"Navigation complete","persona":"navigator","artifacts":["output/analysis.json"],"tokens_used":3200}

Step Failed

{"timestamp":"2026-02-01T10:08:00.000Z","pipeline_id":"a1b2c3d4","step_id":"implement","state":"failed","duration_ms":480000,"message":"Step failed after 3 retries","persona":"craftsman"}

Output Modes

JSON (default)

One JSON object per line. Machine-parseable.

wave run flow "task" 2>/dev/null

Text

Human-friendly format with color and formatting.

wave run flow "task" -o text

Text output example:

[10:00:01] → navigate (navigator)
[10:00:01]   navigate: Executing agent
[10:01:30] ✓ navigate completed (89.0s, 3.2k tokens)
[10:01:31] → specify (philosopher)
[10:01:31]   specify: Executing agent

Consuming Events

Pipe to jq

wave run flow "task" | jq 'select(.state == "failed")'

CI Integration

# Exit code reflects pipeline status
wave run flow "task" > events.jsonl
EXIT_CODE=$?

# Parse events for reporting
cat events.jsonl | jq -r 'select(.state == "completed") | "\(.step_id): \(.duration_ms)ms"'

Real-time Monitoring

wave run flow "task" | while IFS= read -r event; do
  state=$(echo "$event" | jq -r '.state')
  step=$(echo "$event" | jq -r '.step_id')
  echo "Step $step is now $state"
done

Event Ordering Guarantees

1. Each step emits a started event before work begins.
2. completed and failed are terminal — no further events for that step.
3. Events within a step are strictly ordered by timestamp.