Trace Events

Trace events give real-time visibility into task execution over the WebSocket stream. Each event represents an action, state change, or milestone during a run.

Event Structure

{
  "id": "unique_event_id",
  "event_type": "step_start_dag",
  "scope": "step",
  "action": "start",
  "category": "dag",
  "timestamp": 1234567890.123,
  "task_id": "task_123",
  "step_id": "step_456",
  "data": { "step_name": "Web Search" },
  "parent_id": "parent_event_id"
}

Fields

Field	Description
`id`	Unique event identifier.
`event_type`	Specific event, e.g. `step_start_dag`, `action_end_llm`.
`scope`	`task`, `step`, `action`, or `system`.
`action`	`start`, `end`, `error`, `info`, or `update`.
`category`	`dag`, `react`, `general`, `tool`, `llm`, `memory`, `visualization`, `compact` (context-compaction events).
`timestamp`	Unix timestamp with milliseconds.
`task_id` / `step_id`	Associated task and step.
`data`	Event-specific payload.
`parent_id`	Parent event id for hierarchical events.

Scopes

Scope	Covers
`task`	Whole-task milestones — DAG/ReAct start and end, task errors.
`step`	Individual execution steps within a task.
`action`	Atomic actions within a step — tool calls, LLM calls, memory ops.
`system`	System-level info, including visualization (DAG) updates.

Categories & Actions

Combine scope + action + category to route events. For example, an action/end/llm event reports token usage, while a step/start/dag event announces a new step. Actions are start, end, error, info, and update.

ws.onmessage = (event) => {
  const e = JSON.parse(event.data);
  switch (e.scope) {
    case "task":   handleTaskEvent(e);   break;
    case "step":   handleStepEvent(e);   break;
    case "action": handleActionEvent(e); break;
    case "system": handleSystemEvent(e); break;
  }
};

Error Events

Task-level and step-level failures are normalized into a single public shape before being sent to widget/browser clients: event_type is always reported as trace_error, regardless of which internal error event produced it (task_error_general, step_error_general, or the legacy trace_error event type). The event's data is redacted to a fixed set of fields plus a generic, non-identifying message:

{
  "event_type": "trace_error",
  "data": {
    "status": "failed",
    "execution_id": "exec_123",
    "pattern": "dag",
    "stream_message_id": "msg_456",
    "success": false,
    "turn_id": "turn_789",
    "error_message": "Task execution failed."
  }
}

error_message is always the fixed string "Task execution failed." — the underlying exception text, stack trace, and any internal details are never included in this public event.

Failed Pattern-End Events

A DAG or ReAct run that ends in failure (dag_execute_end, react_task_end, task_end_react) is also redacted before reaching public clients — but keeps its own event_type rather than being renamed. Only these fields are kept on data: status, success, execution_id, pattern, stream_message_id, turn_id, iteration, task_preview, step_id. If data.result is present, only its success and status fields are kept — everything else on result (including error detail) is dropped. A successful pattern-end event is unaffected and keeps its normal shape.