<Subflow>

import { Subflow } from "smthrs";

type SubflowProps = {
  id: string;
  workflow: SmithersWorkflow<unknown> | WorkflowFileRef;
  output: OutputTarget;
  input?: unknown;
  mode?: "childRun" | "inline"; // default "childRun"
  skipIf?: boolean;
  timeoutMs?: number;
  heartbeatTimeoutMs?: number;
  heartbeatTimeout?: number;
  retries?: number;
  retryPolicy?: RetryPolicy;
  continueOnFail?: boolean;
  cache?: CachePolicy;
  dependsOn?: string[];
  needs?: Record<string, string>;
  label?: string;
  meta?: Record<string, unknown>;
  key?: string;
  children?: React.ReactNode;
};

Subflow is a top-level export, unlike the typed components createSmithers(...) returns (Workflow, Task, Approval, Sandbox, Signal, Branch, Loop, Parallel): import it directly from "smthrs" for a child workflow boundary. The workflow prop takes a SmithersWorkflow value: a workflow file’s default export. Since smithers((ctx) => ...) returns one, a child workflow is just another createSmithers module:

// child.tsx - a normal workflow file. Its default export is a SmithersWorkflow.
import { createSmithers, Sequence, Task } from "smthrs";
import { z } from "zod";

const child = createSmithers({
  input: z.object({ repo: z.string() }),     // types ctx.input inside the child
  childResult: z.object({ summary: z.string() }),
});

const childWorkflow = child.smithers(
  (ctx) => (
    <child.Workflow name="scan-repo">
      <Sequence>
        <Task id="scan" output={child.outputs.childResult} agent={scanner}>
          {`Scan ${ctx.input.repo} and summarize.`}
        </Task>
      </Sequence>
    </child.Workflow>
  ),
  { output: child.outputs.childResult },
);

export default childWorkflow;

For a workflow module generated at runtime, pass a WorkflowFileRef instead: it must default-export a SmithersWorkflow, and its resolved path (including symlinks) must stay within approvedRoot (default: the parent run’s rootDir):

import type { WorkflowFileRef } from "smthrs";

const generated: WorkflowFileRef = {
  path: ".smithers/generated/child.tsx",
  approvedRoot: process.cwd(),
};

<Subflow id="generated-child" workflow={generated} output={outputs.childResult} />;

The second argument to smithers(build, { output }) declares which schema becomes the child’s RunResult.output, the value a parent <Subflow> persists: pass createSmithers(...).outputs.<key> (a string key or Drizzle table also works). Without it, the child result reads only from a schema key literally named output; a child writing elsewhere (like childResult here) yields an empty subflow result. Import that value into the parent and pass it to <Subflow workflow={...}>; the parent declares the schema it persists the result under (key need not match the child’s, but the shape must):

import { createSmithers, Sequence, Subflow, Task } from "smthrs";
import childWorkflow from "./child.tsx";
import { z } from "zod";

const parent = createSmithers({
  childSummary: z.object({ summary: z.string() }),
  finalResult: z.object({ title: z.string(), summary: z.string() }),
});

export default parent.smithers((ctx) => {
  const child = ctx.outputMaybe(parent.outputs.childSummary, { nodeId: "run-child" });

  return (
    <parent.Workflow name="parent-flow">
      <Sequence>
        <Subflow
          id="run-child"
          workflow={childWorkflow}
          input={{ repo: "acme/app" }}
          output={parent.outputs.childSummary}
          retries={2}
          timeoutMs={300_000}
        />

        {child ? (
          <Task id="summarize" output={parent.outputs.finalResult} agent={summarizer}>
            {`Summarize the child workflow result: ${child.summary}`}
          </Task>
        ) : null}
      </Sequence>
    </parent.Workflow>
  );
});

The child reads the input you pass via its own ctx.input, typed by giving the child’s createSmithers an input schema (above); without one, ctx.input is untyped and needs a guard per field (ctx.input?.repo ?? "."). Read the persisted subflow result in the parent like a task output: ctx.outputMaybe(parent.outputs.childSummary, { nodeId: "run-child" }), where nodeId is the <Subflow id>.

What `childRun` persists

With mode="childRun" (the default), <Subflow output> stores the child’s normalized RunResult.output: its last task result, not a table-keyed snapshot. When the child run finishes, the engine reads the rows written to its declared result schema (the smithers(build, { output }) argument above), strips the system columns (runId, nodeId, iteration), and normalizes:

One row (the common case: the child’s final task is the sole writer) unwraps to that plain object, like { summary: "..." } above.
Zero rows normalize to null.
Multiple rows (several tasks or loop iterations writing to the schema) persist as an array of stripped rows.

The parent gets one result value, not a { schemaKey: rows } map, validated against <Subflow output> like a task payload, so adding or changing the child’s final task changes the parent’s expected schema: renaming output columns, pointing the result at a different schema, or adding a writer (one row becomes an array) all change the shape the parent receives. Update <Subflow output> in the same change, or the subflow task fails output validation.

Single-file parent and child

For small examples and eval fixtures, define both factories in one .tsx file with separate createSmithers calls, so the child keeps its own ctx.input type and output refs, and the parent keeps its own output table for the subflow result:

/** @jsxImportSource smthrs */
import { createSmithers, Subflow } from "smthrs";
import { z } from "zod";

const child = createSmithers({
  input: z.object({ repo: z.string() }),
  scanResult: z.object({ summary: z.string() }),
});

const scanWorkflow = child.smithers(
  (ctx) => (
    <child.Workflow name="scan-child">
      <child.Task id="scan" output={child.outputs.scanResult}>
        {{ summary: `Scanned ${ctx.input.repo}` }}
      </child.Task>
    </child.Workflow>
  ),
  { output: child.outputs.scanResult },
);

const parent = createSmithers({
  input: z.object({ repo: z.string() }),
  childSummary: z.object({ summary: z.string() }),
  finalResult: z.object({ message: z.string() }),
});

export default parent.smithers((ctx) => {
  const childSummary = ctx.outputMaybe(parent.outputs.childSummary, {
    nodeId: "run-scan",
  });

  return (
    <parent.Workflow name="parent-flow">
      <parent.Sequence>
        <Subflow
          id="run-scan"
          workflow={scanWorkflow}
          input={{ repo: ctx.input.repo }}
          output={parent.outputs.childSummary}
        />

        {childSummary ? (
          <parent.Task id="finish" output={parent.outputs.finalResult}>
            {{ message: `Child said: ${childSummary.summary}` }}
          </parent.Task>
        ) : null}
      </parent.Sequence>
    </parent.Workflow>
  );
});

The parent’s input schema is optional but recommended whenever it reads ctx.input.repo, turning ctx.input from unknown into a typed object; the child has its own input schema and ctx.input, populated from the parent’s <Subflow input={...}> prop.

Notes

childRun (default) gives the child its own DB row for retry/cache/resume scope; the persisted result is the child’s last task row, not a table-keyed snapshot (see What childRun persists).
inline renders the child tree as siblings in the parent plan, sharing its scope.
Subflows compose; children may contain <Subflow> themselves.
Declare the child’s result via smithers(build, { output }) unless its schema is named output; that’s what a parent <Subflow> persists.

Start

Articles

Learn

Capabilities

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

What `childRun` persists

Single-file parent and child

Notes

​What childRun persists

​Single-file parent and child

​Notes

What `childRun` persists

Single-file parent and child

Notes