/smithers

name: smithers
description: >
  Drive Smithers durable flows for ordered agent stages, retries, approvals,
  bounded loops, and crash-safe work. Run existing flows or author TypeScript
  flows with Flow.make, Action.make, and Effect v4. If SMITHERS_INSIDE_RUN is
  set, do the assigned step directly; never launch or steer another run.

Smithers

A flow is ordinary TypeScript built from `Flow.make`, `Action.make`, and Effect. Completed actions are recorded; recovery resumes at the frontier. Use Effect `4.0.0-rc.115` and the Smithers 1.0 APIs. Read the owning package's README and docs before authoring. Never use JSX or 0.x APIs.

Rule 0: if you are already inside a run, do not use Smithers

Check `SMITHERS_INSIDE_RUN` before routing. If set, you are a worker executing one step. Do the assigned work with your ordinary tools and finish your turn. Never launch, steer, or poll another run from inside that step. Declare a `HumanTask` in the flow when a person must decide; do not improvise orchestration from inside an agent.

Route first: not every ask needs a flow

1. Clarify missing acceptance criteria before building. 2. Handle one clear goal directly, however large. 3. Use a flow for ordered stages with real gates, durability, approvals, bounded loops, or reusable work. 4. Run an existing flow before writing another.

The mental model

**Flow.** A tagged durable program with payload, success, and error schemas. Its body builds a plan; effects belong in action implementations.

**Action.** A named recorded side effect. Declare it with `Action.make` and attach its implementation with `Declared.toLayer`.

**Node.** The plan-time graph from `@smthrs/plan`. Compose nodes with `Node.map`, `Node.andThen`, `Node.bindPlanned`, `Node.branch`, and `Node.all`.

**Plan.** The compiled graph and approval envelope. Planning executes authoring callbacks; it does not sandbox untrusted JavaScript.

**Step key.** Persisted identity derived from declarations, dependencies, and callback captures. Change meaning deliberately; keep secrets out of payloads and captures.

Sixty seconds to the aha

smthrs flow list
smthrs flow plan hello --data '{"name":"world"}'
smthrs flow start hello --data '{"name":"world"}' --json
smthrs runs show <run-id>
smthrs runs logs <run-id> --follow

Read the run ID from the receipt. Admission is not completion. Check the run's actual result before reporting success. Use `smthrs <command> --help` or `--schema` for the installed command contract.

The flow directory

Put a file flow at `flows/<name>/flow.ts`. Default-export a literal tagged `Flow.make("<name>", { description, capabilities, effects, payload, success, error?, body })` from `@smthrs/flow`. Discovery reads metadata without executing that module. Keep metadata literal; helpers and computed metadata can hide an entry from discovery.

Export action implementations as the optional named `layer`: use `Declared.toLayer`, `AgentAction.layer`, or `Layer.mergeAll`. The local CLI/TUI host composes that layer with FileSystem, Path, ChildProcessSpawner, HttpClient, and agent services (#2923). Export implementations directly; the host owns `Action.Implementations`. Acquire extra dependencies during layer construction so missing services are refused at load.

Authoring checklist (learned from real flows)

• **Wire system actions explicitly.** `Sleep.action`, `WaitFor.action`, and

`HumanTask.action` carry no compile-time implementation requirement. Merge the corresponding `Sleep.layer`, `WaitFor.layer`, and `HumanTask.layer` into your implementations unless your host already provides them. A missing handler is refused as `unresolved_action`: `Action "system/sleep" has no implementation`.

• **Export the implementation layer.** A discovered `flow.ts` may

`export const layer = Layer.mergeAll(...)`. Include declared action layers and `AgentAction.layer`; use the host services above rather than rebuilding the host (#2923).

• **Separate admission from completion.** On the durable engine,

`Flow.start` and `Flow.ensure` return after admission and scheduling; the child runs detached (#2932). Give each logical launch a stable `ensure` key that includes its round or execution component. Reuse it only for retries of the same payload; different payloads raise `ExecutionIdentityConflict`. Fan out with `Effect.forEach(items, launch, { concurrency })`; wrap each launch in `Effect.exit` so one refusal does not fail the batch. Retain exits and execution IDs; inspect completion separately.

• **Declare the real capability envelope.** Grant only what the flow uses,

for example `["fs:read:**", "fs:write:**", "proc:spawn:*", "net:get:*", "net:post:*", "model:call:*"]`. `smthrs flow start` refuses to auto-approve `["*"]`.

• **Capture callback meaning.** Wrap bodies, branch predicates,

`Node.bindPlanned` builders, and other persisted callbacks in `Node.capture`. Declare every semantic closed-over value and an explicit version for imported behavior. Bump the version when topology or meaning changes; plan a new run. Captures must be inert data, not service or function objects.

• **Type recursive handoffs.** Give a flow that hands off to itself through

`.to` an explicit `Flow.Flow<...>` annotation to break recursive inference. For discovery, put the typed loop beside a literal `export default Flow.make(` entry that hands off to it. Keep the entry's description, capabilities, effects, payload, and success literal. Register the loop's interpreter in the exported layer.

• **Pin subscription seats.** Use `<seat>@<account>`, such as

`claude-code:opus@claude-9` or `sol@codex-3`. Check the selected login; never accidentally send subscription work through a paid API route. Unpinned Claude aliases select the API when an Anthropic key is available; explicit `claude-code:` seats refuse an unavailable subscription rather than falling back to a key.

• **Treat unavailable observa