Skip to main content
SmithersEvent is the discriminated union understood by the runtime and observability layer. 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 are documented here when they are typed but not currently 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"
  | "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
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

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