Authoring API - Smithers

A Smithers workflow is built from a single factory call. You hand it Zod schemas; it owns the storage layer and hands back a typed set of JSX components plus the smithers() wrapper that produces a runnable SmithersWorkflow. createSmithers is synchronous and SQLite-only. The other factories exist for the cases it cannot serve: Postgres/PGlite backends, environment-resolved backends, store migration, and non-JSX (external) build functions.

import {
  createSmithers,
  createSmithersPostgres,
  openSmithersBackend,
  migrateSmithersStore,
  createExternalSmithers,
} from "smithers-orchestrator";

smithers, Workflow, Task, useCtx, outputs, tables, and db are returned by the factory, not imported. The component set is documented in the Components reference; this page covers the factories themselves.

createSmithers

Schema-driven workflow API over a local SQLite database. The schemas you pass become both the output tables and the typed outputs accessor. This is the default entry point for almost every workflow.

function createSmithers<Schemas extends Record<string, ZodObject>>(
  schemas: Schemas,
  opts?: CreateSmithersOptions,
): CreateSmithersApi<Schemas>;

schemas

Record<string, ZodObject>

required

A map of output name to Zod object schema. Each key becomes a property on outputs and a backing table. Use the reserved input key to type the workflow’s run input.

opts

CreateSmithersOptions

Optional metadata and storage configuration.

Show CreateSmithersOptions

readableName

string

Human-readable workflow name surfaced in the UI and run metadata.

description

string

One-line description surfaced alongside the name.

alertPolicy

SmithersAlertPolicy

Default alert routing for slow or stuck nodes. See Alerting.

dbPath

string

default:".smithers/smithers.db"

Path to the SQLite database file.

journalMode

string

default:"WAL"

SQLite journal mode passed through to the adapter.

backend

"sqlite" | "pglite" | "postgres"

default:"\"sqlite\""

The backend the API was resolved to. createSmithers serves only "sqlite"; "pglite"/"postgres" fail loud here and require openSmithersBackend or createSmithersPostgres.

CreateSmithersApi

object

The typed authoring surface.

Show members

smithers

(build, opts?) => SmithersWorkflow

Wraps a (ctx) => JSX.Element build function into a runnable workflow. The default export of a workflow module.

Workflow / Task / Sequence / Parallel / Branch / Loop / ...

component

The full typed JSX component set. See the Components reference.

useCtx

() => SmithersCtx<Schema>

Hook to read the run context (input, outputs, runId, iteration) inside a component. See SmithersCtx.

outputs

{ [K in keyof Schemas]: Schemas[K] }

Typed output targets to pass to a component’s output prop.

tables

{ [K in keyof Schemas]: Table }

The Drizzle tables backing each output schema.

BunSQLiteDatabase

The underlying Drizzle database handle.

const { Workflow, Task, smithers, outputs } = createSmithers({
  input: z.object({ topic: z.string() }),
  research: z.object({ findings: z.string() }),
});

export default smithers((ctx) => (
  <Workflow name="research">
    <Task id="research" output={outputs.research} agent={myAgent}>
      {`Research ${ctx.input.topic}`}
    </Task>
  </Workflow>
));

Source create.js · CreateSmithersApi.ts · Tests create-unit.test.js · See also Get started, JSX overview

createSmithersPostgres

PostgreSQL or PGlite equivalent of createSmithers. Asynchronous because it opens a connection, and it returns an extra close(). Reach for it when a run must outlive a single process or be shared across hosts.

function createSmithersPostgres<Schemas extends Record<string, ZodObject>>(
  schemas: Schemas,
  opts?: CreateSmithersPostgresOptions,
): Promise<CreateSmithersApi<Schemas> & { close: () => Promise<void> }>;

schemas

Record<string, ZodObject>

required

Same as createSmithers.

opts

CreateSmithersPostgresOptions

Extends CreateSmithersOptions with the backend connection. A discriminated union on provider.

Show provider: postgres (default)

connectionString

string

Postgres connection URL.

connection

object

Connection object passed to the driver instead of a URL.

Show provider: "pglite"

dataDir

string

On-disk directory for the embedded PGlite database.

Promise<CreateSmithersApi & { close }>

object

The same API as createSmithers, plus close() to release the connection pool. Call it when the process is done with the backend.

const api = await createSmithersPostgres(schemas, {
  provider: "postgres",
  connectionString: process.env.DATABASE_URL,
});

Source create.js · See also Control-plane deployment, migrateSmithersStore

openSmithersBackend

Resolve the backend from the environment instead of hard-coding it. Reads smithers.config / env vars and returns whichever of SQLite, PGlite, or Postgres they select. Use it in shared CLIs and servers that should honor a deployment’s configured store.

function openSmithersBackend<Schemas extends Record<string, ZodObject>>(
  schemas?: Schemas,
  opts?: OpenSmithersBackendOptions,
): Promise<CreateSmithersApi<Schemas> & { close?: () => Promise<void> }>;

schemas

Record<string, ZodObject>

Optional output schemas. Omit to open the backend without registering tables.

opts

OpenSmithersBackendOptions

Extends CreateSmithersOptions.

Show OpenSmithersBackendOptions

backend

"sqlite" | "pglite" | "postgres"

Force a backend instead of resolving from config.

cwd

string

Directory to resolve config and relative paths from.

configPath

string

Explicit path to the Smithers config file.

env

Record<string, string | undefined>

Environment overrides used during resolution.

connectionString

string

Postgres URL when the resolved backend is postgres.

connection

object

Postgres connection object alternative to connectionString.

pgliteDataDir

string

Data directory when the resolved backend is pglite.

Promise<CreateSmithersApi & { close? }>

object

The authoring API for the resolved backend. close() is present when the backend holds a connection (PGlite/Postgres).

Source openSmithersBackend.js · Tests openSmithersBackend.test.js · See also Package configuration

migrateSmithersStore

Copy an existing SQLite store into PGlite or Postgres, table by table, and write a migration marker. Use it once when graduating a project from the local SQLite default to a shared backend.

function migrateSmithersStore(
  opts?: MigrateSmithersStoreOptions,
): Promise<SmithersMigrationResult>;

opts

MigrateSmithersStoreOptions

Show MigrateSmithersStoreOptions

cwd

string

Directory to resolve paths and config from.

dbPath

string

Source SQLite path. Defaults to the resolved store path.

"pglite" | "postgres"

Target backend.

url

string

Target connection URL for Postgres.

env

Record<string, string | undefined>

Environment overrides.

pgliteDataDir

string

Target data directory for PGlite.

keepSqlite

boolean

default:"false"

Keep the source SQLite file after a successful copy.

batchSize

number

Rows copied per batch.

onProgress

(event) => void | Promise<void>

Progress callback. Receives table-start, table-copied, and done events with row counts and durations.

Promise<SmithersMigrationResult>

object

Show SmithersMigrationResult

backend

"pglite" | "postgres"

The backend migrated to.

dbPath

string

Source SQLite path that was read.

markerPath

string

Path of the written migration marker.

target

{ backend, dataDir?, url? }

Resolved target descriptor.

runCount

number

Number of runs copied.

schemaVersion

string

Schema version stamped into the target.

durationMs

number

Total wall-clock duration.

tables

Array<{ table, sourceRows, targetRows, durationMs }>

Per-table copy report.

sqliteRemoved

boolean

Whether the source SQLite file was deleted (the inverse of keepSqlite).

Source migrateSmithersStore.js · Tests migrateSmithersStore.test.js

createExternalSmithers

Build a SmithersWorkflow from a plain build function instead of JSX. The build function returns a HostNodeJson tree that maps 1:1 to what the JSX renderer produces, so a workflow can be authored in any language that can emit that JSON.

function createExternalSmithers<S extends Record<string, ZodObject>>(
  config: ExternalSmithersConfig<S>,
): SmithersWorkflow<S> & { tables: Record<string, any>; cleanup: () => void };

config

ExternalSmithersConfig<S>

required

Show ExternalSmithersConfig

schemas

required

Output schemas, same as createSmithers.

agents

Record<string, AgentLike>

required

Named agents the build function references by id.

buildFn

(ctx: SerializedCtx) => HostNodeJson

required

Pure function that returns the host-node tree for a given serialized context. See HostNodeJson.

dbPath

string

SQLite path, same default as createSmithers.

SmithersWorkflow & { tables, cleanup }

object

A runnable workflow plus its backing tables and a cleanup() to release the database.

Source external/index.js · Tests create-unit.test.js · See also SerializedCtx, HostNodeJson

Once you have a SmithersWorkflow, run it with the Runtime API or the CLI. For the full type surface, see the Types reference.

​createSmithers

​createSmithersPostgres

​openSmithersBackend

​migrateSmithersStore

​createExternalSmithers

createSmithers

createSmithersPostgres

openSmithersBackend

migrateSmithersStore

createExternalSmithers