​

0.15.0

​

Gateway — Deploy Workflows as a Service

​

Quick start

import { SmithersGateway } from "smithers-orchestrator/gateway";

const gateway = new SmithersGateway({
  auth: {
    mode: "token",
    tokens: {
      "my-secret-token": { role: "operator", scopes: ["*"] },
    },
  },
});

gateway.register("deploy", deployWorkflow);
gateway.register("code-review", codeReviewWorkflow);
await gateway.listen({ port: 7331 });

// Start a run
ws.send(JSON.stringify({
  type: "req", id: "1", method: "runs.create",
  params: { workflow: "deploy", input: { env: "production" } },
}));

// Server streams real-time events
// → { type: "event", event: "node.started", payload: { nodeId: "build" } }
// → { type: "event", event: "approval.requested", payload: { nodeId: "confirm" } }

// Approve a gate
ws.send(JSON.stringify({
  type: "req", id: "2", method: "approvals.decide",
  params: { runId: "abc123", nodeId: "confirm", decision: "approved" },
}));

​

HTTP fallback

curl -X POST http://localhost:7331/rpc \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"method": "runs.create", "params": {"workflow": "deploy", "input": {"env": "staging"}}}'

​

Authentication

​

Access control

​

Cron scheduling

gateway.register("nightly-report", reportWorkflow, {
  schedule: "0 2 * * *",
});

​

Approval modes

​

Durability

​

Infinite retry by default

{/* Retries forever until it succeeds */}
<Task id="analyze" output={outputs.analysis} agent={analyst}>
  Analyze the codebase.
</Task>

{/* Opt out explicitly */}
<Task id="quick-check" output={outputs.check} agent={checker} noRetry>
  One-shot validation.
</Task>

​

Side-effect safety

​

Resume contract hardening

• Live owner protection — A running run will not be resumed if its recorded owner PID is still alive, even when --force is used.
• Stricter code drift detection — Resume compatibility now checks both the workflow entry file hash and the local import graph hash. Changing an imported workflow module invalidates resume the same way changing the entry file does.
• Child workflow provenance — Subflows now inherit workflow identity/root provenance so the same resume safety checks apply to child runs.
• Retry exhaustion stays terminal — Failed tasks with no retries remaining stay failed on resume unless the workflow definition now allows more retries.

​

Deterministic durable outputs

​

New Components & APIs

• <Signal> — Typed wrapper over <WaitForEvent>. Validates the incoming payload against a Zod schema and passes typed data to children.
  <Signal id="feedback" schema={z.object({ rating: z.number() })}>
    {(data) => <Task id="process" output={outputs.result}>Rate: {data.rating}</Task>}
  </Signal>
  
• defineTool() — First-class custom tool authoring with automatic event logging, idempotency keys, and side-effect tracking.
  const deploy = defineTool({
    name: "deploy",
    schema: z.object({ env: z.string() }),
    sideEffect: true,
    async execute(args, ctx) {
      return await pushBuild(args.env, ctx.idempotencyKey);
    },
  });
  
• usePatched() — Workflow versioning hook. Returns true for new runs, false for replaying runs. Enables safe rolling deployments.
• Task-level allowTools — Restrict which CLI tools an agent can invoke per task. Combine with cliAgentToolsDefault: "explicit-only" for fine-grained agent sandboxing.
• Semantic MCP tools — Stable agent-facing tool surface: list_workflows, run_workflow, get_run, resolve_approval, revert_attempt, and more.
• IDE integration — smithers-ide MCP surface for editor tooling: open files, show diffs, run terminals, ask the user, render webviews.

​

CLI

• smithers signal — Deliver structured data to a <Signal> or <WaitForEvent> node from the command line.
• smithers retry-task — Retry a specific task without time travel. Resets the node and dependents, re-executes only what changed.
• smithers timetravel — Revert to a previous task state. Optionally restore the VCS filesystem and resume immediately.
• smithers ask diagnostics — --dump-prompt, --tool-surface, --list-agents, --print-bootstrap for debugging agent bootstrap.

​

Engine Redesign

• Task execution is now wrapped in Effect Activities with structured retries, heartbeat propagation, and idempotency keys
• Approvals and signals are backed by DurableDeferred for replay-safe resolution
• The scheduler loop is wrapped in Workflow.make() with parent-child linkage
• Internal tables route through SqlMessageStorage (@effect/sql-sqlite-bun) instead of raw drizzle — user output tables are unchanged
• Task dispatch routes through a worker entity model (in-process by default, zero overhead), enabling future multi-process and remote execution
• Sandbox execution routes through entity-based runners with crash recovery

​

Observability

• Prometheus context-window usage buckets — Agent token reporting now emits smithers_tokens_context_window_per_call plus smithers_tokens_context_window_bucket_total{bucket=...} so you can alert on prompt/context size ranges: <50k, 50k-100k, 100k-200k, 200k-500k, 500k-1m, and >=1m.

​

Breaking Changes

• Zod v3 support removed. The zodV3Compat.ts shim has been deleted. All schema handling uses Zod v4 natively. If your workflows import from "zod", you’re already on v4 and nothing changes. If you were on Zod v3, upgrade before adopting 0.15.0.

​

Run Status Reclassification

• Stale runs surfaced as continued — Runs whose heartbeat has gone stale now appear as "continued" instead of "running" in getRun, listRuns, and the API. Filtering by status=running also includes continued for backwards compatibility.

​

New Run Status

• waiting-event — paused on a <WaitForEvent> or <Signal> node

​

New Workflows

• <Sweep> — Cross-topic feature auditing workflow. Scans multiple areas of the codebase in a single pass to surface inconsistencies and missing coverage.

​

Fixes

• Failed resume no longer corrupts run state — If resume is rejected before the run is durably claimed and activated, smithers now leaves the existing run record untouched instead of marking it failed.
• Child process cleanup on cancel — Agents now spawn with detached: true and kill the entire process group on abort. Fixes zombie accumulation.
• Input schema table generation — Input tables now get a run_id-only primary key instead of the composite task key.
• OpenAI schema sanitization — sanitizeForOpenAI() fixes Zod v4 JSON Schema output for OpenAI’s response_format constraints.
• Codex resume flag — --output-schema omitted when resuming Codex sessions.
• Heartbeat timeouts — Raised from 60s/120s to 300s/300s. CLI agents need time to think.
• picocolors dependency — Now declared explicitly in package.json.
• Stop retrying invalid heartbeat payloads — Heartbeats with malformed data no longer trigger infinite retry loops.
• Stop retrying deterministic invalid outputs — Tasks that fail with non-transient output validation errors are no longer retried.
• HTTP request metrics deterministic — Prometheus HTTP request metrics no longer drift due to timing races in tests.
• Kanban column retry configuration — Kanban columns can now configure per-task retry behavior.
• Preserve devtools hook instrumentation — DevTools hooks are no longer stripped during engine teardown.
• Settle aborted tasks before cancelling runs — Aborted tasks are now awaited before the run is marked cancelled, preventing orphaned state.
• Continue-on-fail tasks default to single-shot — Tasks with continueOnFail now default to noRetry to avoid masking permanent failures.

​

Tooling

• oxlint — Added as a fast lint pass. Existing autofixable issues resolved.

​

Error Codes

• Added: EXTERNAL_BUILD_FAILED, SCHEMA_DISCOVERY_FAILED