Authoring API

A Smithers workflow is built from a single factory call. 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 cover what it can’t: Postgres/PGlite backends, environment-resolved backends, store migration, and non-JSX (external) build functions.

import {
  createSmithers,
  createSmithersPostgres,
  openSmithersBackend,
  migrateSmithersStore,
  createExternalSmithers,
} from "smthrs";

The factory returns smithers, useCtx, outputs, tables, db, and workflow-context-bound component primitives like Workflow and Task; those primitives are also exported from smthrs directly. The Components reference covers that component set; 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>;

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.

CreateSmithersOptions

Optional metadata and storage configuration.

Show CreateSmithersOptions

string

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

string

One-line description surfaced alongside the name.

SmithersAlertPolicy

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

string

default:".smithers/smithers.db"

Path to the SQLite database file.

string

default:"WAL"

SQLite journal mode passed through to the adapter.

"sqlite" | "pglite" | "postgres"

default:"\"sqlite\""

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

object

The typed authoring surface.

Show members

(build, opts?) => SmithersWorkflow

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

component

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

() => SmithersCtx<Schema>

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

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

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

{ [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 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> }>;

Record<string, ZodObject>

required

Same as createSmithers.

CreateSmithersPostgresOptions

Extends CreateSmithersOptions with the backend connection: a discriminated union on provider.

Show provider: postgres (default)

string

Postgres connection URL.

object

Connection object passed to the driver instead of a URL.

Show provider: "pglite"

string

On-disk directory for the embedded PGlite database.

object

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

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

const api = await createSmithersPostgres(schemas, {
  provider: "pglite",
  dataDir: ".smithers/pgdata",
});

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> }>;

Record<string, ZodObject>

Optional output schemas; omit to open the backend without registering tables.

OpenSmithersBackendOptions

Extends CreateSmithersOptions.

Show OpenSmithersBackendOptions

"sqlite" | "pglite" | "postgres"

Force a backend instead of resolving from config.

string

Directory to resolve config and relative paths from.

string

Explicit path to the Smithers config file.

Record<string, string | undefined>

Environment overrides used during resolution.

string

Postgres URL when the resolved backend is postgres.

object

Postgres connection object alternative to connectionString.

string

Data directory when the resolved backend is pglite.

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>;

MigrateSmithersStoreOptions

Show MigrateSmithersStoreOptions

string

Directory to resolve paths and config from.

string

Source SQLite path; defaults to the resolved store path.

"pglite" | "postgres"

Target backend.

string

Target connection URL for Postgres.

Record<string, string | undefined>

Environment overrides.

string

Target data directory for PGlite.

boolean

default:"false"

Keep the source SQLite file after a successful copy.

number

Rows copied per batch.

(event) => void | Promise<void>

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

object

Show SmithersMigrationResult

"pglite" | "postgres"

The backend migrated to.

string

Source SQLite path that was read.

string

Path of the written migration marker.

{ backend, dataDir?, url? }

Resolved target descriptor.

number

Number of runs copied.

string

Schema version stamped into the target.

number

Total wall-clock duration.

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

Per-table copy report.

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 mapping 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 };

ExternalSmithersConfig<S>

required

Show ExternalSmithersConfig

required

Output schemas, same as createSmithers.

Record<string, AgentLike>

required

Named agents the build function references by id.

(ctx: SerializedCtx) => HostNodeJson

required

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

string

SQLite path, same default as createSmithers.

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.

Overview

Core API

Runtime

Types & errors

Gateway RPC

createSmithers

createSmithersPostgres

openSmithersBackend

migrateSmithersStore

createExternalSmithers

​createSmithers

​createSmithersPostgres

​openSmithersBackend

​migrateSmithersStore

​createExternalSmithers

createSmithers

createSmithersPostgres

openSmithersBackend

migrateSmithersStore

createExternalSmithers