Skip to main content
Signature:
Both RunOptions and RunResult are defined in Types.

Concurrency

When opts.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 original runId 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.
The original input row is loaded from durable state; pass {} for input. The workflow file hash and VCS root must match the original run.

Cancel via AbortSignal

All in-flight attempts are marked cancelled and 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:
Controllers and monitors must not open SQLite/PGlite/Postgres or query output and _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, runWorkflow acquires a caffeinate lock to prevent idle sleep and releases it on completion. On other platforms this is a no-op.
  • Set SMITHERS_LOG_LEVEL=debug to enable verbose engine logging.
  • For lifecycle events, pass onProgress (see Events).