RunOptions and RunResult are defined in Types.
Concurrency
Whenopts.maxConcurrency is omitted, a run starts with a cap of 4 concurrent
tasks. Smithers can raise that cap as work queues, up to the positive-integer
SMITHERS_AUTO_MAX_CONCURRENCY_CEILING environment setting (16 by default).
A wider declared <Parallel maxConcurrency> or subtreeConcurrency also raises
an unpinned run’s initial cap and is not limited by that automatic ceiling.
Providing opts.maxConcurrency explicitly pins the cap. It disables automatic
raises, including declared-width raises, and the run cannot exceed the supplied
value. The supplied value can itself be larger than the automatic ceiling.
Resume
Pass the originalrunId plus resume: true. State loads from the configured durable store, completed tasks are skipped, in-progress attempts older than 15 minutes are abandoned and retried.
{} for input. The workflow file hash and VCS root must match the original run.
Cancel via AbortSignal
NodeCancelled events are emitted.
Hijack handoff
If a CLI hijack happens mid-run (bunx smithers-orchestrator hijack RUN_ID), the run ends "cancelled" and the latest attempt metadata stores hijackHandoff. On resume: true, Smithers waits for a safe handoff point and continues with the persisted CLI session id (see CLI Agents) or the persisted message history (SDK agents).
result.output
Populated only when the schema passed to createSmithers() has a key literally named output. Inside a workflow, consume other typed rows through ctx.output, ctx.latest, or ctx.outputs. Outside the workflow, expose the run through the workspace Gateway and fetch a node’s typed output through getNodeOutput:
_smithers_* tables directly. The Gateway preserves auth, ownership,
invalidation, event emission, and backend independence. Direct storage access is
reserved for runtime implementation, migration, backend tests, and maintainer
diagnostics.
Notes
- On macOS,
runWorkflowacquires acaffeinatelock to prevent idle sleep and releases it on completion. On other platforms this is a no-op. - Set
SMITHERS_LOG_LEVEL=debugto enable verbose engine logging. - For lifecycle events, pass
onProgress(see Events).