Event Types

SmithersEvent is the discriminated union the runtime and observability layer understand. Runtime-emitted variants are persisted to the event log, passed to runWorkflow({ onProgress }), streamed by Gateway, and filtered by bunx smithers-orchestrator events --type <category>. Reserved variants appear here typed but not yet emitted. 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"
  | "waiting-quota"
  | "paused"
  | "finished"
  | "continued"
  | "failed"
  | "cancelled";

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

Event Variants

Discriminate on the type field, e.g. event.type === "NodeFailed", to handle specific lifecycle moments.

Browser UIs see a different shape. useGatewayRunEvents and the vanilla streamRunEventsResilient yield GatewayEventFrame objects, not raw SmithersEvents: the event NAME is frame.event, and every other field lives under frame.payload. Client-side equivalent:

const { events } = useGatewayRunEvents(runId, { afterSeq: 0 });
for (const frame of events) {
  if (frame.event === "NodeFailed") {
    const { nodeId, error } = frame.payload;   // NOT frame.type / frame.nodeId
    // error is the errorToJson value: read error.message
  }
}

Use frame.event === "NodeStarted" | "NodeFinished" | "NodeFailed" to build a per-node status view, keyed by frame.payload.nodeId. The table below lists each variant’s fields; in a UI those live under frame.payload. Frames reconstructed from persisted rows also carry an optional timestampMs (epoch millis from the stored row) and surface stateVersion: 0.

Event	Top-level fields
`SupervisorStarted`	`runId`, `pollIntervalMs`, `staleThresholdMs`, `timestampMs`
`SupervisorPollCompleted`	`runId`, `staleCount`, `resumedCount`, `skippedCount`, `durationMs`, `timestampMs`
`RunAutoResumed`	`runId`, `lastHeartbeatAtMs`, `staleDurationMs`, `resumeAttempt`, `timestampMs`
`RunAutoResumeSkipped`	`runId`, `reason`, `timestampMs`
`RunStarted`	`runId`, `timestampMs`
`RunStatusChanged`	`runId`, `status`, `timestampMs`
`RunStateChanged`	`runId`, `before`, `after`, `timestampMs`
`RunFinished`	`runId`, `timestampMs`
`RunFailed`	`runId`, `error`, `timestampMs`
`RunCancelled`	`runId`, `timestampMs`
`RunContinuedAsNew`	`runId`, `newRunId`, `iteration`, `carriedStateSize`, `ancestryDepth?`, `timestampMs`
`RunHijackRequested`	`runId`, `target?`, `timestampMs`
`RunHijacked`	`runId`, `nodeId`, `iteration`, `attempt`, `engine`, `mode`, `resume?`, `cwd`, `timestampMs`
`SandboxCreated`	`runId`, `sandboxId`, `runtime`, `configJson`, `timestampMs`
`SandboxShipped`	`runId`, `sandboxId`, `runtime`, `bundleSizeBytes`, `timestampMs`
`SandboxHeartbeat`	`runId`, `sandboxId`, `remoteRunId?`, `progress?`, `timestampMs`
`SandboxBundleReceived`	`runId`, `sandboxId`, `bundleSizeBytes`, `patchCount`, `hasOutputs`, `timestampMs`
`SandboxCompleted`	`runId`, `sandboxId`, `remoteRunId?`, `runtime`, `status`, `durationMs`, `timestampMs`
`SandboxFailed`	`runId`, `sandboxId`, `runtime`, `error`, `timestampMs`
`SandboxDiffReviewRequested`	`runId`, `sandboxId`, `patchCount`, `totalDiffLines`, `timestampMs`
`SandboxDiffAccepted`	`runId`, `sandboxId`, `patchCount`, `timestampMs`
`SandboxDiffRejected`	`runId`, `sandboxId`, `reason?`, `timestampMs`
`FrameCommitted`	`runId`, `frameNo`, `xmlHash`, `timestampMs`
`NodePending`	`runId`, `nodeId`, `iteration`, `timestampMs`
`NodeStarted`	`runId`, `nodeId`, `iteration`, `attempt`, `timestampMs`
`TaskHeartbeat`	`runId`, `nodeId`, `iteration`, `attempt`, `hasData`, `dataSizeBytes`, `intervalMs?`, `timestampMs`
`TaskHeartbeatTimeout`	`runId`, `nodeId`, `iteration`, `attempt`, `lastHeartbeatAtMs`, `timeoutMs`, `timestampMs`
`NodeFinished`	`runId`, `nodeId`, `iteration`, `attempt`, `timestampMs`
`NodeFailed`	`runId`, `nodeId`, `iteration`, `attempt`, `error`, `timestampMs`
`NodeCancelled`	`runId`, `nodeId`, `iteration`, `attempt?`, `reason?`, `timestampMs`
`NodeSkipped`	`runId`, `nodeId`, `iteration`, `timestampMs`
`NodeRetrying`	`runId`, `nodeId`, `iteration`, `attempt`, `timestampMs`
`NodeWaitingApproval`	`runId`, `nodeId`, `iteration`, `timestampMs`
`NodeWaitingTimer`	`runId`, `nodeId`, `iteration`, `firesAtMs`, `timestampMs`
`ApprovalRequested`	`runId`, `nodeId`, `iteration`, `timestampMs`
`ApprovalGranted`	`runId`, `nodeId`, `iteration`, `timestampMs`
`ApprovalAutoApproved`	`runId`, `nodeId`, `iteration`, `timestampMs`
`ApprovalDenied`	`runId`, `nodeId`, `iteration`, `timestampMs`
`ToolCallStarted`	`runId`, `nodeId`, `iteration`, `attempt`, `toolCallId`, `toolName`, `seq`, `timestampMs`
`ToolCallFinished`	`runId`, `nodeId`, `iteration`, `attempt`, `toolCallId`, `toolName`, `seq`, `status`, `timestampMs`
`NodeOutput`	`runId`, `nodeId`, `iteration`, `attempt`, `text`, `stream`, `timestampMs`
`AgentEvent`	`runId`, `nodeId`, `iteration`, `attempt`, `engine`, `event`, `timestampMs`
`RetryTaskStarted`	`runId`, `nodeId`, `iteration`, `resetDependents`, `resetNodes`, `timestampMs`
`RetryTaskFinished`	`runId`, `nodeId`, `iteration`, `resetNodes`, `success`, `error?`, `timestampMs`
`RevertStarted`	`runId`, `nodeId`, `iteration`, `attempt`, `jjPointer`, `timestampMs`
`RevertFinished`	`runId`, `nodeId`, `iteration`, `attempt`, `jjPointer`, `success`, `error?`, `timestampMs`
`TimeTravelStarted`	`runId`, `nodeId`, `iteration`, `attempt`, `jjPointer?`, `timestampMs`
`TimeTravelFinished`	`runId`, `nodeId`, `iteration`, `attempt`, `jjPointer?`, `success`, `vcsRestored`, `resetNodes`, `error?`, `timestampMs`
`TimeTravelJumped`	`runId`, `fromFrameNo`, `toFrameNo`, `timestampMs`, `caller?`
`EffectRevertStarted`	`runId`, `operation`, `kind`, `toolName`, `nodeId`, `iteration`, `attempt`, `seq`, `effectStatus`, `timestampMs`
`EffectRevertFinished`	`runId`, `operation`, `kind`, `toolName`, `nodeId`, `iteration`, `attempt`, `seq`, `timestampMs`
`EffectRevertFailed`	`runId`, `operation`, `kind`, `toolName`, `nodeId`, `iteration`, `attempt`, `seq`, `error`, `timestampMs`
`SideEffectBoundaryCrossed`	`runId`, `opId`, `operation`, `report`, `parentRunId?`, `warningOnly?`, `lateCompletion?`, `archivedByOp?`, `timestampMs`
`WorkflowReloadDetected`	`runId`, `changedFiles`, `timestampMs`
`WorkflowReloaded`	`runId`, `generation`, `changedFiles`, `timestampMs`
`WorkflowReloadFailed`	`runId`, `error`, `changedFiles`, `timestampMs`
`WorkflowReloadUnsafe`	`runId`, `reason`, `changedFiles`, `timestampMs`
`ScorerStarted`	`runId`, `nodeId`, `scorerId`, `scorerName`, `timestampMs`
`ScorerFinished`	`runId`, `nodeId`, `scorerId`, `scorerName`, `score`, `timestampMs`
`ScorerFailed`	`runId`, `nodeId`, `scorerId`, `scorerName`, `error`, `timestampMs`
`TokenUsageReported`	`runId`, `nodeId`, `iteration`, `attempt`, `model`, `agent`, `inputTokens`, `outputTokens`, `cacheReadTokens?`, `cacheWriteTokens?`, `reasoningTokens?`, `timestampMs`
`SnapshotCaptured`	`runId`, `frameNo`, `contentHash`, `timestampMs`
`RunForked`	`runId`, `parentRunId`, `parentFrameNo`, `branchLabel?`, `timestampMs`
`ReplayStarted`	`runId`, `parentRunId`, `parentFrameNo`, `restoreVcs`, `timestampMs`
`MemoryFactSet`	`runId`, `namespace`, `key`, `timestampMs`
`MemoryRecalled`	`runId`, `namespace`, `query`, `resultCount`, `timestampMs`
`MemoryMessageSaved`	`runId`, `threadId`, `role`, `timestampMs`
`OpenApiToolCalled`	`runId`, `operationId`, `method`, `path`, `durationMs`, `status`, `timestampMs`
`TimerCreated`	`runId`, `timerId`, `firesAtMs`, `timerType`, `timestampMs`
`TimerFired`	`runId`, `timerId`, `firesAtMs`, `firedAtMs`, `delayMs`, `timestampMs`
`TimerCancelled`	`runId`, `timerId`, `timestampMs`
`AgentTraceEvent`	`runId`, `nodeId`, `iteration`, `attempt`, `trace`, `timestampMs`
`AgentTraceSummary`	`runId`, `nodeId`, `iteration`, `attempt`, `summary`, `timestampMs`
`AgentSessionEvent`	`runId`, `nodeId`, `iteration`, `attempt`, `transcript`, `timestampMs`

RunStateChanged is typed and categorized for forward compatibility, but the current runtime does not emit it. Read derived run state with getRun or computeRunState, and watch RunStatusChanged for persisted status transitions. OpenApiToolCalled is typed and categorized for forward compatibility, but the current OpenAPI tool factory records Effect metrics and log spans rather than emitting that event onto the run event bus.

Agent Event Payload

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> };

Overview

Core API

Runtime

Types & errors

Gateway RPC

Status Types

Event Variants

Agent Event Payload

​Status Types

​Event Variants

​Agent Event Payload

Status Types

Event Variants

Agent Event Payload