Skip to content

events.md

Latest commit

 

History

History
135 lines (104 loc) · 4.85 KB

events.md

File metadata and controls

135 lines (104 loc) · 4.85 KB

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.