Effect API

The Effect API is a lower-level authoring surface for teams already modeling application logic with Effect, Layer, and Schema. It shares the JSX runtime (SQLite persistence, no rerun of completed work on resume, schema-validated outputs, dependency-driven scheduling), differing only in authoring style: every step, approval, sequence, parallel block, match, branch, loop, worktree, and scope is an ordinary value you can export, return from a function, or compose with others. Use JSX for most workflows; use the Effect API inside an Effect service, when step bodies should return Effect values directly, or for a React-free API over generated workflow definitions.

Minimal workflow

import { Smithers } from "smthrs";
import { Effect, Schema } from "effect";

const inputSchema = Schema.Struct({
  repo: Schema.String,
  sha: Schema.String,
});

const analysisSchema = Schema.Struct({
  summary: Schema.String,
  risk: Schema.Literals(["low", "medium", "high"]),
});

const reportSchema = Schema.Struct({
  markdown: Schema.String,
});

const G = Smithers.workflow({
  name: "repo-review",
  input: inputSchema,
});

const analyze = G.step("analyze", {
  output: analysisSchema,
  timeout: "2m",
  retry: { maxAttempts: 3, backoff: "exponential", initialDelay: "1s" },
  run: ({ input, heartbeat }) =>
    Effect.gen(function* () {
      heartbeat({ phase: "analyzing" });
      yield* Effect.log(`Reviewing ${input.repo}@${input.sha}`);
      return { summary: "Found one risky migration.", risk: "medium" as const };
    }),
});

const report = G.step("report", {
  needs: { analyze },
  output: reportSchema,
  run: ({ analyze }) => ({
    markdown: `# Review\n\n${analyze.summary}\n\nRisk: ${analyze.risk}`,
  }),
});

export const reviewWorkflow = G.from(G.sequence(analyze, report));

const result = await Effect.runPromise(
  reviewWorkflow
    .execute(
      { repo: "acme/api", sha: "abc123" },
      { runId: "review-abc123" },
    )
    .pipe(Effect.provide(Smithers.sqlite({ filename: "smithers.db" }))),
);

Smithers.workflow(opts) returns a typed handle G. Every constructor (G.step, G.approval, G.sequence, G.parallel, G.match, G.branch, G.loop, G.worktree, G.scope) returns a graph value. G.from(graph) finalizes the workflow into an executable one. execute() returns an Effect whose success value is the decoded output of the final graph node: a step’s own output, a sequence’s last child, a parallel block’s tuple. If it stops on an approval or timer instead, the value is a RunResult with waiting status.

Steps and dependencies

Steps are values:

const analyze = G.step("analyze", {
  output: analysisSchema,
  run: ({ input }) => analyzeRepo(input.repo, input.sha),
});

input is typed from the workflow’s input schema; the step’s output type is inferred from output and flows into anything listing this step in needs:

const report = G.step("report", {
  needs: { analyze },
  output: reportSchema,
  run: ({ analyze }) => ({
    markdown: renderReport(analyze.summary, analyze.risk),
  }),
});

Step IDs are durable: changing one creates a new task and leaves the old persisted output behind. A step may return a plain value, Promise, or Effect; Smithers decodes the result with the step’s output schema before writing it. Step context: input, dependency values, executionId, stepId, attempt, iteration, signal, heartbeat(data), and lastHeartbeat.

Control flow

G.sequence(...nodes) runs ordered work; G.parallel(...nodes, { maxConcurrency }) runs concurrent work and returns a tuple of child results. G.match(source, { when, then, else }) selects between two statically-known branches based on a completed step’s output; both compile into the graph, but only the matching one executes. G.branch({ condition, needs, then, else }) is G.match for an arbitrary needs context instead of a single source step. G.loop({ id, children, until, maxIterations, onMaxReached }) repeats a fragment (not nestable) until the predicate returns true. onMaxReached ('fail' or 'return-last') governs maxIterations overflow; the default returns the last iteration’s outputs rather than failing.

export const reviewWorkflow = G.from(
  G.sequence(
    analyze,
    G.match(analyze, {
      when: (analysis) => analysis.risk === "high",
      then: G.approval("approve-high-risk", {
        needs: { analyze },
        request: ({ analyze }) => ({
          title: "Approve high-risk review",
          summary: analyze.summary,
        }),
        onDeny: "fail",
      }),
      // else: report (omitting `else` means the match falls through to the next sibling in the sequence)
    }),
    report,
  ),
);

Worktrees

G.worktree({ id, path, branch, skipIf, needs, children }) runs children inside a git worktree, created beforehand and torn down after.

G.worktree({
  id: "review-shard",
  path: "scratch/review",
  children: G.sequence(read, summarize),
});

Reuse

Static reuse is a graph value:

const reviewShard = G.sequence(read, summarize);

Parameterized reuse is a function returning a graph value:

const makeReviewShard = (params: { path: string }) =>
  G.sequence(
    G.step("read", {
      output: diffSchema,
      run: ({ input }) => readDiff(input.repo, params.path),
    }),
    G.step("summarize", {
      needs: { read },
      output: summarySchema,
      run: ({ read }) => summarizeDiff(read),
    }),
  );

Multi-mount reuse is G.scope(instanceId, fragment): the compiler prefixes every step and approval ID in the fragment with instanceId., so G.scope('api', makeReviewShard(...)) produces api.read and api.summarize. The same fragment mounts under multiple scopes without collision:

G.parallel(
  G.scope("api", makeReviewShard({ path: "packages/api" })),
  G.scope("web", makeReviewShard({ path: "apps/web" })),
);

Cross-workflow fragments

Fragments that need to live across workflows with different inputs are built with Smithers.fragment(inputSchema):

const F = Smithers.fragment(diffInputSchema);

const readDiff = F.step("read-diff", {
  output: diffSchema,
  run: ({ input }) => readDiff(input.path),
});

const summarize = F.step("summarize", {
  needs: { readDiff },
  output: summarySchema,
  run: ({ readDiff }) => summarizeDiff(readDiff),
});

export const reviewShard = F.sequence(readDiff, summarize);

Smithers.fragment exposes the same constructors as a workflow handle (step, approval, sequence, parallel, match, branch, loop, worktree, scope) but no from: fragments are values, compiled only once mounted into a real workflow:

const G = Smithers.workflow({ name: "repo-review", input: workflowInputSchema });

export const reviewWorkflow = G.from(
  G.parallel(
    G.scope("api", reviewShard),
    G.scope("web", reviewShard),
  ),
);

A fragment’s input schema lets TypeScript infer each step’s input type; at runtime it’s never read or validated, since steps receive the host workflow’s input directly. That input must be assignable to the fragment’s schema, or TypeScript errors at compile time when mounting a fragment with fields the host input doesn’t satisfy.

Operational notes

Provide exactly one persistence layer with Effect.provide(Smithers.sqlite({ filename })).
Keep step IDs stable across releases; use new IDs for materially different work.
Use heartbeat() in long-running steps and honor signal in external calls.
Use retry, retryPolicy, timeout, skipIf, and cache as on JSX tasks (see JSX Task options for the shared option shape).
All graph values support .pipe(...fns) for future data-last combinators.
Prefer idempotent step bodies: for external side effects, use executionId, stepId, and attempt when constructing idempotency keys.
G.match selects graph topology: both branches must be statically knowable so durable IDs stay stable across resume, unlike Effect’s Match module, which does runtime value pattern matching.

Start

Articles

Learn

Capabilities

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

Minimal workflow

Steps and dependencies

Control flow

Worktrees

Reuse

Cross-workflow fragments

Operational notes

​Minimal workflow

​Steps and dependencies

​Control flow

​Worktrees

​Reuse

​Cross-workflow fragments

​Operational notes

Minimal workflow

Steps and dependencies

Control flow

Worktrees

Reuse

Cross-workflow fragments

Operational notes