Skip to main content
runWorkflow is the primary entry point for executing a workflow. It accepts a compiled SmithersWorkflow object and a RunOptions bag, drives the render-schedule-execute loop until completion, and returns a RunResult.

​
Basic Usage

import { createSmithers, Task, runWorkflow } from "smithers-orchestrator";
import { z } from "zod";

const { Workflow, smithers } = createSmithers({
  analysis: z.object({ summary: z.string() }),
});

const workflow = smithers((ctx) => (
  <Workflow name="example">
    <Task id="analyze" output="analysis" agent={myAgent}>
      {`Analyze: ${ctx.input.description}`}
    </Task>
  </Workflow>
));

const result = await runWorkflow(workflow, {
  input: { description: "Auth tokens expire silently" },
});

console.log(result.status); // "finished" | "failed" | "cancelled" | "waiting-approval"

​
Signature

function runWorkflow<Schema>(
  workflow: SmithersWorkflow<Schema>,
  opts: RunOptions,
): Promise<RunResult>;

​
RunOptions

FieldTypeDefaultDescription
inputRecord<string, unknown>(required)Input data for the run. Must be a JSON object. In the manual API it should match the input table schema; in the schema-driven API it is stored as a JSON payload. The runId key is injected automatically.
runIdstringAuto-generatedProvide a deterministic run ID. If omitted, a new unique ID is generated.
resumebooleanfalseResume an existing run instead of starting a new one. Requires runId. Skips already-completed tasks and picks up from the last checkpoint.
maxConcurrencynumber4Maximum number of tasks that can execute in parallel at any given time. Also respects per-group limits set by <Parallel maxConcurrency>.
onProgress(e: SmithersEvent) => voidundefinedCallback invoked for every lifecycle event. See Events.
signalAbortSignalundefinedStandard AbortSignal to cancel the run. When aborted, the run finishes with status "cancelled".
workflowPathstringundefinedAbsolute or relative path to the workflow .tsx file. Used to resolve the default rootDir and stored in the run metadata.
rootDirstringWorkflow file’s directoryRoot directory for the tool sandbox. All file-system tools (read, edit, write, bash, grep) are confined to this directory.
logDirstring | null.smithers/executions/<runId>/logsDirectory for NDJSON event log files. Set to null to disable log file output entirely. Relative paths are resolved from rootDir.
allowNetworkbooleanfalseWhether the bash tool is permitted to make network requests.
maxOutputBytesnumber200000Maximum number of bytes a single tool call can return. Output is truncated beyond this limit.
toolTimeoutMsnumber60000Maximum wall-clock time (in milliseconds) for a single tool call before it is killed.

​
RunResult

type RunResult = {
  runId: string;
  status: "finished" | "failed" | "cancelled" | "waiting-approval";
  output?: unknown;
  error?: unknown;
};
FieldTypeDescription
runIdstringThe run identifier (either provided or auto-generated).
statusstringTerminal status of the run.
outputunknownRows from the output table in the schema, if the workflow finished successfully and the schema includes an output table.
errorunknownError information if the run failed. Contains a serialized error object with code, message, and optional details.

​
Status Values

StatusMeaning
"finished"All tasks completed successfully.
"failed"A task failed (after exhausting retries) and continueOnFail was not set.
"cancelled"The run was cancelled via AbortSignal.
"waiting-approval"At least one task requires human approval before the run can continue. Use smithers approve or smithers deny to unblock.

​
Resuming a Run

To resume a previously paused or crashed run, pass resume: true along with the original runId. Smithers reads the persisted state from SQLite, skips tasks that already have valid output rows, and continues executing from the first pending task. 
const result = await runWorkflow(workflow, {
  input: {},
  runId: "my-run-123",
  resume: true,
});
When resuming:
  • The original input row is loaded from the database. You do not need to provide input data again (pass an empty object).
  • Stale in-progress attempts older than 15 minutes are automatically cancelled and retried.
  • Tasks with valid persisted outputs are skipped.

​
Cancellation

Pass an AbortSignal to cancel a running workflow: 
const controller = new AbortController();

// Cancel after 5 minutes
setTimeout(() => controller.abort(), 5 * 60 * 1000);

const result = await runWorkflow(workflow, {
  input: { description: "Long task" },
  signal: controller.signal,
});

if (result.status === "cancelled") {
  console.log("Run was cancelled");
}
When cancelled, all in-progress task attempts are marked as cancelled in the database and NodeCancelled events are emitted.

​
Event Monitoring

Use the onProgress callback to receive real-time events as the run progresses: 
const result = await runWorkflow(workflow, {
  input: { description: "Fix bug" },
  onProgress: (event) => {
    switch (event.type) {
      case "NodeStarted":
        console.log(`Task ${event.nodeId} started (attempt ${event.attempt})`);
        break;
      case "NodeFinished":
        console.log(`Task ${event.nodeId} finished`);
        break;
      case "NodeFailed":
        console.error(`Task ${event.nodeId} failed:`, event.error);
        break;
      case "ApprovalRequested":
        console.log(`Task ${event.nodeId} needs approval`);
        break;
    }
  },
});
See Events for the full list of event types and their fields.

​
Idle Sleep Prevention

On macOS, runWorkflow automatically acquires a caffeinate lock to prevent the system from idle-sleeping while a workflow is running. The lock is released when the run finishes, fails, or is cancelled. This is a no-op on other platforms.

​
Error Handling

If an unhandled exception occurs inside the engine (outside of individual task execution), the run is marked as "failed" and the error is serialized into RunResult.error. Individual task failures are handled by the retry and continueOnFail mechanisms. Set SMITHERS_DEBUG=1 in your environment to print engine-level errors to stderr.
  • Events — All event types emitted during a run.
  • renderFrame — Preview the workflow graph without executing.
  • CLI — Run workflows from the command line.
  • Resumability — How durable state and crash recovery work.