Skip to main content

Documentation Index

Fetch the complete documentation index at: https://smithers.sh/llms.txt

Use this file to discover all available pages before exploring further.

SmithersEvent is a discriminated union of every lifecycle event the runtime emits. The full type definition lives in Types — that’s the source of truth for field shapes.

Subscribe via onProgress

import { runWorkflow } from "smithers-orchestrator";
import { Effect } from "effect";
import workflow from "./workflow";

await Effect.runPromise(runWorkflow(workflow, {
  input: { task: "fix bug" },
  onProgress: (event) => {
    if (event.type === "NodeStarted")  console.log(`▶ ${event.nodeId} (attempt ${event.attempt})`);
    if (event.type === "NodeFinished") console.log(`✓ ${event.nodeId}`);
    if (event.type === "NodeFailed")   console.error(`✗ ${event.nodeId}`, event.error);
  },
}));

Read from the NDJSON log

Events append to .smithers/executions/<runId>/logs/stream.ndjson (configure with logDir / --log-dir; disable with --no-log).
tail -f .smithers/executions/abc123/logs/stream.ndjson | jq .
cat .smithers/executions/abc123/logs/stream.ndjson | jq 'select(.type == "NodeFailed")'
cat .smithers/executions/abc123/logs/stream.ndjson | jq -r .type | sort | uniq -c | sort -rn
Or with the CLI:
bunx smithers-orchestrator events <run-id> --json
bunx smithers-orchestrator events <run-id> --type tool-call --node analyze

Common fields

type CommonFields    = { type: string; runId: string; timestampMs: number };
type NodeScoped      = CommonFields & { nodeId: string; iteration: number };
type AttemptScoped   = NodeScoped   & { attempt: number };
Every event includes type, runId, timestampMs. Node-scoped events add nodeId and iteration. Attempt-scoped add attempt.

Event categories

Used by bunx smithers-orchestrator events --type <category> and the metrics layer.
CategoryEvents
runRunAutoResumed, RunAutoResumeSkipped, RunStarted, RunStatusChanged, RunStateChanged, RunFinished, RunFailed, RunCancelled, RunContinuedAsNew, RunHijackRequested, RunHijacked, RetryTaskStarted, RetryTaskFinished, RunForked, ReplayStarted
frameFrameCommitted
nodeNodePending, NodeStarted, TaskHeartbeat, TaskHeartbeatTimeout, NodeFinished, NodeFailed, NodeCancelled, NodeSkipped, NodeRetrying, NodeWaitingApproval, NodeWaitingTimer
approvalApprovalRequested, ApprovalGranted, ApprovalAutoApproved, ApprovalDenied
tool-callToolCallStarted, ToolCallFinished
agentAgentEvent, AgentTraceEvent, AgentTraceSummary, AgentSessionEvent
outputNodeOutput
revertRevertStarted, RevertFinished, TimeTravelStarted, TimeTravelFinished, TimeTravelJumped
workflowWorkflowReloadDetected, WorkflowReloaded, WorkflowReloadFailed, WorkflowReloadUnsafe
scorerScorerStarted, ScorerFinished, ScorerFailed
tokenTokenUsageReported
timerTimerCreated, TimerFired, TimerCancelled
memoryMemoryFactSet, MemoryRecalled, MemoryMessageSaved
openapiOpenApiToolCalled
sandboxSandboxCreated, SandboxShipped, SandboxHeartbeat, SandboxBundleReceived, SandboxCompleted, SandboxFailed, SandboxDiffReviewRequested, SandboxDiffAccepted, SandboxDiffRejected
snapshotSnapshotCaptured
supervisorSupervisorStarted, SupervisorPollCompleted

Built-in metrics

EventMetric
RunStartedsmithers.runs.total
NodeStartedsmithers.nodes.started
NodeFinishedsmithers.nodes.finished
NodeFailedsmithers.nodes.failed
ApprovalGranted / ApprovalDeniedApproval counters
TokenUsageReportedToken usage counters per model/agent
trackSmithersEvent from smithers-orchestrator/observability exposes this mapping for custom integrations. See the observability fragment for the full OTLP/Prometheus setup.