Skip to main content
SmithersEvent is the discriminated union emitted by the runtime, persisted to the event log, passed to runWorkflow({ onProgress }), streamed by Gateway, and filtered by smithers events --type <category>. Every variant has type, runId, and timestampMs. Node-scoped variants add nodeId and iteration. Attempt-scoped variants add attempt. For subscription examples, CLI usage, and built-in metrics, see Events.

​
Status Types

type RunStatus =
  | "running"
  | "waiting-approval"
  | "waiting-event"
  | "waiting-timer"
  | "finished"
  | "continued"
  | "failed"
  | "cancelled";

type RunState =
  | "running"
  | "waiting-approval"
  | "waiting-event"
  | "waiting-timer"
  | "recovering"
  | "stale"
  | "orphaned"
  | "failed"
  | "cancelled"
  | "succeeded"
  | "unknown";

​
Event Variants

Discriminate on the type field — e.g. event.type === "NodeFailed" — to handle specific lifecycle moments.
EventTop-level fields
SupervisorStartedrunId, pollIntervalMs, staleThresholdMs, timestampMs
SupervisorPollCompletedrunId, staleCount, resumedCount, skippedCount, durationMs, timestampMs
RunAutoResumedrunId, lastHeartbeatAtMs, staleDurationMs, timestampMs
RunAutoResumeSkippedrunId, reason, timestampMs
RunStartedrunId, timestampMs
RunStatusChangedrunId, status, timestampMs
RunStateChangedrunId, before, after, timestampMs
RunFinishedrunId, timestampMs
RunFailedrunId, error, timestampMs
RunCancelledrunId, timestampMs
RunContinuedAsNewrunId, newRunId, iteration, carriedStateSize, ancestryDepth?, timestampMs
RunHijackRequestedrunId, target?, timestampMs
RunHijackedrunId, nodeId, iteration, attempt, engine, mode, resume?, cwd, timestampMs
SandboxCreatedrunId, sandboxId, runtime, configJson, timestampMs
SandboxShippedrunId, sandboxId, runtime, bundleSizeBytes, timestampMs
SandboxHeartbeatrunId, sandboxId, remoteRunId?, progress?, timestampMs
SandboxBundleReceivedrunId, sandboxId, bundleSizeBytes, patchCount, hasOutputs, timestampMs
SandboxCompletedrunId, sandboxId, remoteRunId?, runtime, status, durationMs, timestampMs
SandboxFailedrunId, sandboxId, runtime, error, timestampMs
SandboxDiffReviewRequestedrunId, sandboxId, patchCount, totalDiffLines, timestampMs
SandboxDiffAcceptedrunId, sandboxId, patchCount, timestampMs
SandboxDiffRejectedrunId, sandboxId, reason?, timestampMs
FrameCommittedrunId, frameNo, xmlHash, timestampMs
NodePendingrunId, nodeId, iteration, timestampMs
NodeStartedrunId, nodeId, iteration, attempt, timestampMs
TaskHeartbeatrunId, nodeId, iteration, attempt, hasData, dataSizeBytes, intervalMs?, timestampMs
TaskHeartbeatTimeoutrunId, nodeId, iteration, attempt, lastHeartbeatAtMs, timeoutMs, timestampMs
NodeFinishedrunId, nodeId, iteration, attempt, timestampMs
NodeFailedrunId, nodeId, iteration, attempt, error, timestampMs
NodeCancelledrunId, nodeId, iteration, attempt?, reason?, timestampMs
NodeSkippedrunId, nodeId, iteration, timestampMs
NodeRetryingrunId, nodeId, iteration, attempt, timestampMs
NodeWaitingApprovalrunId, nodeId, iteration, timestampMs
NodeWaitingTimerrunId, nodeId, iteration, firesAtMs, timestampMs
ApprovalRequestedrunId, nodeId, iteration, timestampMs
ApprovalGrantedrunId, nodeId, iteration, timestampMs
ApprovalAutoApprovedrunId, nodeId, iteration, timestampMs
ApprovalDeniedrunId, nodeId, iteration, timestampMs
ToolCallStartedrunId, nodeId, iteration, attempt, toolCallId, toolName, seq, timestampMs
ToolCallFinishedrunId, nodeId, iteration, attempt, toolCallId, toolName, seq, status, timestampMs
NodeOutputrunId, nodeId, iteration, attempt, text, stream, timestampMs
AgentEventrunId, nodeId, iteration, attempt, engine, event, timestampMs
RetryTaskStartedrunId, nodeId, iteration, resetDependents, resetNodes, timestampMs
RetryTaskFinishedrunId, nodeId, iteration, resetNodes, success, error?, timestampMs
RevertStartedrunId, nodeId, iteration, attempt, jjPointer, timestampMs
RevertFinishedrunId, nodeId, iteration, attempt, jjPointer, success, error?, timestampMs
TimeTravelStartedrunId, nodeId, iteration, attempt, jjPointer?, timestampMs
TimeTravelFinishedrunId, nodeId, iteration, attempt, jjPointer?, success, vcsRestored, resetNodes, error?, timestampMs
TimeTravelJumpedrunId, fromFrameNo, toFrameNo, timestampMs, caller?
WorkflowReloadDetectedrunId, changedFiles, timestampMs
WorkflowReloadedrunId, generation, changedFiles, timestampMs
WorkflowReloadFailedrunId, error, changedFiles, timestampMs
WorkflowReloadUnsaferunId, reason, changedFiles, timestampMs
ScorerStartedrunId, nodeId, scorerId, scorerName, timestampMs
ScorerFinishedrunId, nodeId, scorerId, scorerName, score, timestampMs
ScorerFailedrunId, nodeId, scorerId, scorerName, error, timestampMs
TokenUsageReportedrunId, nodeId, iteration, attempt, model, agent, inputTokens, outputTokens, cacheReadTokens?, cacheWriteTokens?, reasoningTokens?, timestampMs
SnapshotCapturedrunId, frameNo, contentHash, timestampMs
RunForkedrunId, parentRunId, parentFrameNo, branchLabel?, timestampMs
ReplayStartedrunId, parentRunId, parentFrameNo, restoreVcs, timestampMs
MemoryFactSetrunId, namespace, key, timestampMs
MemoryRecalledrunId, namespace, query, resultCount, timestampMs
MemoryMessageSavedrunId, threadId, role, timestampMs
OpenApiToolCalledrunId, operationId, method, path, durationMs, status, timestampMs
TimerCreatedrunId, timerId, firesAtMs, timerType, timestampMs
TimerFiredrunId, timerId, firesAtMs, firedAtMs, delayMs, timestampMs
TimerCancelledrunId, timerId, timestampMs
AgentTraceEventrunId, nodeId, iteration, attempt, trace, timestampMs
AgentTraceSummaryrunId, nodeId, iteration, attempt, summary, timestampMs
AgentSessionEventrunId, nodeId, iteration, attempt, transcript, timestampMs

​
Agent Event Payload

This type describes the .event field of the AgentEvent variant above. For structured traces, prefer AgentTraceEvent, AgentTraceSummary, and AgentSessionEvent. AgentEvent.event is the normalized CLI-agent event payload: 
type AgentCliEvent =
  | { type: "started"; engine: string; title: string; resume?: string; detail?: Record<string, unknown> }
  | {
      type: "action";
      engine: string;
      phase: "started" | "updated" | "completed";
      entryType?: "thought" | "message";
      action: { id: string; kind: AgentCliActionKind; title: string; detail?: Record<string, unknown> };
      message?: string;
      ok?: boolean;
      level?: "debug" | "info" | "warning" | "error";
    }
  | { type: "completed"; engine: string; ok: boolean; answer?: string; error?: string; resume?: string; usage?: Record<string, unknown> };