Skip to main content

Documentation Index

Fetch the complete documentation index at: https://smithers.sh/llms.txt

Use this file to discover all available pages before exploring further.

Build and package configuration shipped with smithers-orchestrator. Use it when setting up a new project, debugging import resolution, or understanding why your tsconfig.json needs specific options.

​
Binary

Use bunx smithers-orchestrator <command> for CLI commands. The repository root keeps a private development bin that points at apps/cli/src/index.js; application code should import from the package exports below.

​
Subpath Exports

Use the subpath form to import only the surface you need.
Import pathEntry filePurpose
smithers-orchestrator./src/index.jsCore API: createSmithers, components, runWorkflow, renderMdx, errors
smithers-orchestrator/gateway./src/gateway.jsGateway server primitives from @smithers-orchestrator/server/gateway
smithers-orchestrator/gateway-client./src/gateway-client.jsTyped client helpers from @smithers-orchestrator/gateway-client
smithers-orchestrator/gateway-react./src/gateway-react.jsReact hooks and providers for gateway-backed UIs
smithers-orchestrator/sandbox./src/sandbox.jsSandbox provider contracts, bundles, and execution helpers
smithers-orchestrator/jsx-runtime./src/jsx-runtime.jsJSX runtime (auto-resolved by jsxImportSource)
smithers-orchestrator/jsx-dev-runtime./src/jsx-runtime.jsJSX dev runtime (auto-resolved in dev mode)
smithers-orchestrator/tools./src/tools.jsTool sandbox: defineTool, read, grep, bash, edit, write
smithers-orchestrator/server./src/server.jsHTTP server for run management and event streaming
smithers-orchestrator/observability./src/observability.jsOpenTelemetry traces, metrics, and Prometheus integration
smithers-orchestrator/mdx-plugin./src/mdx-plugin.jsBun preload plugin for .mdx imports
smithers-orchestrator/dom/renderer./src/dom/renderer.jsInternal renderer (advanced use)
smithers-orchestrator/serve./src/serve.jsSingle-workflow HTTP server via createServeApp
smithers-orchestrator/scorers./src/scorers.jsEval scorers: createScorer, llmJudge, aggregateScores
smithers-orchestrator/memory./src/memory.jsCross-run facts, message history, processors, and metrics
smithers-orchestrator/openapi./src/openapi.jsGenerate AI SDK tools from OpenAPI specs
smithers-orchestrator/control-plane./src/control-plane.jsOrganization, project, billing, usage, secret-reference, and audit primitives
The PI plugin is published as the separate @smithers-orchestrator/pi-plugin package. The old smithers-orchestrator/pi-plugin and smithers-orchestrator/pi-extension subpaths are no longer exported.

​
Workspace Packages

Most applications should import from smithers-orchestrator. The scoped workspace packages below are published for advanced integrations, custom clients, and framework development.
PackagePrimary surfaceRelated docs
smithers-orchestratorPublic facade for workflow authoring, components, agents, tools, server helpers, memory, OpenAPI tools, scorers, and JSX runtime setupThis page, Types
@smithers-orchestrator/cliCLI entrypoint, MCP server, local workflow pack, account registry commands, DevTools commands, cron, alerts, and server commandsCLI Overview, MCP Server
@smithers-orchestrator/accountsSubscription and API-key account registry helpers: listAccounts, addAccount, removeAccount, getAccount, accountToProviderEnvCLI Agents
@smithers-orchestrator/agentsAI SDK and CLI agent adapters, CLI capability reports, agent contracts, and tool capability registryCLI Agents, SDK Agents
@smithers-orchestrator/componentsJSX workflow components such as Task, Workflow, Approval, Sandbox, Timer, Signal, and control-flow componentsComponents
@smithers-orchestrator/control-planeDurable organization, project, team, billing, usage, secret-reference, and audit primitives for hosted deploymentsControl Plane
@smithers-orchestrator/dbSQLite/Drizzle adapter, table setup, run-state derivation, schema helpers, and output tablesData Model, Run State
@smithers-orchestrator/devtoolsSnapshot, tree, diff, node lookup, task collection, and DevTools run-store helpers behind the CLI inspect commandsDebugging, CLI Overview
@smithers-orchestrator/driverRuntime driver contracts: RunOptions, RunResult, RunStatus, SmithersCtx, outputs, task runtime, interop, and child process helpersRun Workflow, Execution Model
@smithers-orchestrator/engineWorkflow rendering/execution API: runWorkflow, renderFrame, workflow, Smithers, fragment, signals, and Effect versioningRender Frame, Run Workflow
@smithers-orchestrator/errorsError definitions, known codes, JSON serialization, docs URLs, and type guardsErrors
@smithers-orchestrator/gatewayStable Gateway RPC contracts, auth scopes, deployment metadata, and generated OpenAPI schemaGateway, RPC
@smithers-orchestrator/gateway-clientBrowser/client SDK for Gateway RPC requests and event streamsGateway
@smithers-orchestrator/gateway-reactReact hooks and root helpers for Gateway-backed UIsGateway
@smithers-orchestrator/graphFramework-neutral workflow graph model, XML nodes, task descriptors, and graph snapshotsPlanner Internals, Types
@smithers-orchestrator/memoryCross-run facts, message history, processors, namespaces, service layer, and metricsMemory, Memory Quickstart
@smithers-orchestrator/observabilityEvent types, logging, tracing, metrics, Prometheus rendering, and runtime observability layersEvents, Event Types
@smithers-orchestrator/openapiOpenAPI parsing, operation extraction, AI SDK tool generation, schema conversion, and metricsOpenAPI Tools, OpenAPI Quickstart
@smithers-orchestrator/pi-pluginPI extension runtime, views, API wrappers, and workflow inspection integrationPI Integration
@smithers-orchestrator/protocolShared contracts, small value types, and protocol-level errors for cross-package useTypes, Errors
@smithers-orchestrator/react-reconcilerCustom React reconciler, host context, DOM renderer, DevTools preload, driver, and JSX runtime internalsWhy React, Render Frame
@smithers-orchestrator/sandboxSandbox bundle, execute, and transport primitives used by the Sandbox componentSandbox
@smithers-orchestrator/schedulerPure workflow state machine: task state, scheduler decisions, retry/cache policies, wait reasons, and workflow session servicesWorkflow State, Suspend and Resume
@smithers-orchestrator/scorersScorer definitions, LLM judges, batch execution, aggregation, persistence schema, and metricsEvals, Evals Quickstart
@smithers-orchestrator/serverHTTP, WebSocket, Gateway, cron, webhook, metrics, and single-workflow serving APIsServer, Serve
@smithers-orchestrator/time-travelSnapshots, diffs, forks, replay, timelines, VCS tags, rewind locks/audits, and time-travel metricsTime Travel, Time Travel Quickstart
@smithers-orchestrator/vcsVCS discovery and jj workspace operations such as runJj, workspaceAdd, workspaceList, and pointer revertsVCS Helpers, VCS Guide

​
Usage

// Core API
import { createSmithers, runWorkflow } from "smithers-orchestrator";

// Tools
import { defineTool, bash, read, write } from "smithers-orchestrator/tools";

// Scorers
import { createScorer, llmJudge } from "smithers-orchestrator/scorers";

// MDX plugin (in preload.ts)
import { mdxPlugin } from "smithers-orchestrator/mdx-plugin";

// Control-plane primitives
import { ControlPlaneStore } from "smithers-orchestrator/control-plane";

​
TypeScript Configuration

​
JSX Import Source

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "smithers-orchestrator"
  }
}
This tells TypeScript to resolve JSX transforms from smithers-orchestrator/jsx-runtime instead of react/jsx-runtime. The Smithers JSX runtime re-exports React’s runtime, so component behavior is identical — this setting enables proper type resolution for Smithers workflow components. See JSX Installation for the complete TypeScript setup.

​
Path Aliases

When developing inside the smithers-orchestrator monorepo, the root tsconfig.json defines path aliases so source imports resolve without a build step: 
"paths": {
  "smithers-orchestrator": ["./packages/smithers/src/index.js"],
  "smithers-orchestrator/jsx-runtime": ["./packages/smithers/src/jsx-runtime.js"],
  "smithers-orchestrator/jsx-dev-runtime": ["./packages/smithers/src/jsx-runtime.js"],
  "smithers-orchestrator/tools": ["./packages/smithers/src/tools.js"],
  "smithers-orchestrator/*": [
    "./packages/smithers/src/*.js",
    "./packages/smithers/src/*/index.js"
  ],
  "smithers-orchestrator/scorers": ["./packages/scorers/src/index.js"],
  "@smithers-orchestrator/agents": ["./packages/agents/src/index.js"],
  "@smithers-orchestrator/gateway-client": ["./packages/gateway-client/src/index.ts"],
  "@smithers-orchestrator/gateway-react": ["./packages/gateway-react/src/index.ts"],
  "@smithers-orchestrator/pi-plugin": ["./packages/pi-plugin/src/index.ts"],
  "@smithers-orchestrator/server": ["./packages/server/src/index.js"]
  // The root tsconfig includes the same style of alias for each workspace package.
}
The root package is a private smithers-monorepo; smithers-orchestrator resolves to packages/smithers. End users do not need path aliases — only framework developers do. Installing smithers-orchestrator as a dependency lets Node/Bun module resolution handle import paths automatically.

​
Local Type Root Shims

"typeRoots": ["./src/types", "./node_modules/@types"]
The ./src/types directory contains ambient type declarations that fill gaps in third-party packages. One shim ships today:
  • react-dom-server.d.ts — Declares the react-dom/server module so TypeScript doesn’t error when server-side rendering types are referenced.
End users should add @types/react-dom to devDependencies instead of relying on this shim.

​
Bun Configuration

​
Runtime Preload

# bunfig.toml
preload = ["./preload.ts"]
The preload script registers the MDX esbuild plugin with Bun’s bundler so .mdx files can be imported as JSX components at runtime. See MDX Prompts for details.

​
Test Configuration

[test]
root = "./tests"
preload = ["./preload.ts"]
KeyValuePurpose
root./testsBun discovers test files from this directory instead of scanning the entire project
preload["./preload.ts"]Registers the MDX plugin for test files so .mdx imports work in tests
The test preload is separate from the runtime preload. Both point to the same file, but Bun’s [test] section only applies when running bun test. Without it, tests that import .mdx files fail with a module resolution error.

​
npm Scripts

Defined in the root package.json for development:
ScriptCommandPurpose
typechecktsc --noEmitType-check the src/ and tests/ trees against tsconfig.json
typecheck:examplestsc -p examples/tsconfig.json --noEmitType-check example files against a separate config that maps smithers-orchestrator to examples-entry.js
lintoxlint ... packages/*/src packages/*/testsLint package source and tests with oxlint
lint:fixoxlint ... --fix --fix-suggestions packages/*/src packages/*/testsApply supported oxlint fixes
clibun run apps/cli/src/index.jsRun the local development CLI entrypoint
testnode scripts/check-single-effect-version.mjs && node scripts/check-dependency-boundaries.mjs && pnpm -r testRun dependency guard checks and each package test script
check:effectnode scripts/check-single-effect-version.mjsVerify the workspace resolves a single Effect version
check:depsnode scripts/check-dependency-boundaries.mjsVerify package dependency boundaries
docscd docs && bunx mintlify devStart the Mintlify docs dev server for local preview
versionnode scripts/bump.mjsBump package versions using the release helper
releasenode scripts/publish.mjsPublish packages using the release helper

​
For end-user projects

When scaffolding your own project (with smithers init or manually), add a typecheck script: 
{
  "scripts": {
    "typecheck": "tsc --noEmit"
  }
}
See Production Project Structure for a complete user-project package.json example.