Build and package configuration shipped withDocumentation Index
Fetch the complete documentation index at: https://smithers.sh/llms.txt
Use this file to discover all available pages before exploring further.
smithers-orchestrator. Use it when setting up a new project, debugging import resolution, or understanding why your tsconfig.json needs specific options.
Binary
Usebunx 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 path | Entry file | Purpose |
|---|---|---|
smithers-orchestrator | ./src/index.js | Core API: createSmithers, components, runWorkflow, renderMdx, errors |
smithers-orchestrator/gateway | ./src/gateway.js | Gateway server primitives from @smithers-orchestrator/server/gateway |
smithers-orchestrator/gateway-client | ./src/gateway-client.js | Typed client helpers from @smithers-orchestrator/gateway-client |
smithers-orchestrator/gateway-react | ./src/gateway-react.js | React hooks and providers for gateway-backed UIs |
smithers-orchestrator/sandbox | ./src/sandbox.js | Sandbox provider contracts, bundles, and execution helpers |
smithers-orchestrator/jsx-runtime | ./src/jsx-runtime.js | JSX runtime (auto-resolved by jsxImportSource) |
smithers-orchestrator/jsx-dev-runtime | ./src/jsx-runtime.js | JSX dev runtime (auto-resolved in dev mode) |
smithers-orchestrator/tools | ./src/tools.js | Tool sandbox: defineTool, read, grep, bash, edit, write |
smithers-orchestrator/server | ./src/server.js | HTTP server for run management and event streaming |
smithers-orchestrator/observability | ./src/observability.js | OpenTelemetry traces, metrics, and Prometheus integration |
smithers-orchestrator/mdx-plugin | ./src/mdx-plugin.js | Bun preload plugin for .mdx imports |
smithers-orchestrator/dom/renderer | ./src/dom/renderer.js | Internal renderer (advanced use) |
smithers-orchestrator/serve | ./src/serve.js | Single-workflow HTTP server via createServeApp |
smithers-orchestrator/scorers | ./src/scorers.js | Eval scorers: createScorer, llmJudge, aggregateScores |
smithers-orchestrator/memory | ./src/memory.js | Cross-run facts, message history, processors, and metrics |
smithers-orchestrator/openapi | ./src/openapi.js | Generate AI SDK tools from OpenAPI specs |
smithers-orchestrator/control-plane | ./src/control-plane.js | Organization, project, billing, usage, secret-reference, and audit primitives |
@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 fromsmithers-orchestrator. The scoped workspace packages below are published for advanced integrations, custom clients, and framework development.
| Package | Primary surface | Related docs |
|---|---|---|
smithers-orchestrator | Public facade for workflow authoring, components, agents, tools, server helpers, memory, OpenAPI tools, scorers, and JSX runtime setup | This page, Types |
@smithers-orchestrator/cli | CLI entrypoint, MCP server, local workflow pack, account registry commands, DevTools commands, cron, alerts, and server commands | CLI Overview, MCP Server |
@smithers-orchestrator/accounts | Subscription and API-key account registry helpers: listAccounts, addAccount, removeAccount, getAccount, accountToProviderEnv | CLI Agents |
@smithers-orchestrator/agents | AI SDK and CLI agent adapters, CLI capability reports, agent contracts, and tool capability registry | CLI Agents, SDK Agents |
@smithers-orchestrator/components | JSX workflow components such as Task, Workflow, Approval, Sandbox, Timer, Signal, and control-flow components | Components |
@smithers-orchestrator/control-plane | Durable organization, project, team, billing, usage, secret-reference, and audit primitives for hosted deployments | Control Plane |
@smithers-orchestrator/db | SQLite/Drizzle adapter, table setup, run-state derivation, schema helpers, and output tables | Data Model, Run State |
@smithers-orchestrator/devtools | Snapshot, tree, diff, node lookup, task collection, and DevTools run-store helpers behind the CLI inspect commands | Debugging, CLI Overview |
@smithers-orchestrator/driver | Runtime driver contracts: RunOptions, RunResult, RunStatus, SmithersCtx, outputs, task runtime, interop, and child process helpers | Run Workflow, Execution Model |
@smithers-orchestrator/engine | Workflow rendering/execution API: runWorkflow, renderFrame, workflow, Smithers, fragment, signals, and Effect versioning | Render Frame, Run Workflow |
@smithers-orchestrator/errors | Error definitions, known codes, JSON serialization, docs URLs, and type guards | Errors |
@smithers-orchestrator/gateway | Stable Gateway RPC contracts, auth scopes, deployment metadata, and generated OpenAPI schema | Gateway, RPC |
@smithers-orchestrator/gateway-client | Browser/client SDK for Gateway RPC requests and event streams | Gateway |
@smithers-orchestrator/gateway-react | React hooks and root helpers for Gateway-backed UIs | Gateway |
@smithers-orchestrator/graph | Framework-neutral workflow graph model, XML nodes, task descriptors, and graph snapshots | Planner Internals, Types |
@smithers-orchestrator/memory | Cross-run facts, message history, processors, namespaces, service layer, and metrics | Memory, Memory Quickstart |
@smithers-orchestrator/observability | Event types, logging, tracing, metrics, Prometheus rendering, and runtime observability layers | Events, Event Types |
@smithers-orchestrator/openapi | OpenAPI parsing, operation extraction, AI SDK tool generation, schema conversion, and metrics | OpenAPI Tools, OpenAPI Quickstart |
@smithers-orchestrator/pi-plugin | PI extension runtime, views, API wrappers, and workflow inspection integration | PI Integration |
@smithers-orchestrator/protocol | Shared contracts, small value types, and protocol-level errors for cross-package use | Types, Errors |
@smithers-orchestrator/react-reconciler | Custom React reconciler, host context, DOM renderer, DevTools preload, driver, and JSX runtime internals | Why React, Render Frame |
@smithers-orchestrator/sandbox | Sandbox bundle, execute, and transport primitives used by the Sandbox component | Sandbox |
@smithers-orchestrator/scheduler | Pure workflow state machine: task state, scheduler decisions, retry/cache policies, wait reasons, and workflow session services | Workflow State, Suspend and Resume |
@smithers-orchestrator/scorers | Scorer definitions, LLM judges, batch execution, aggregation, persistence schema, and metrics | Evals, Evals Quickstart |
@smithers-orchestrator/server | HTTP, WebSocket, Gateway, cron, webhook, metrics, and single-workflow serving APIs | Server, Serve |
@smithers-orchestrator/time-travel | Snapshots, diffs, forks, replay, timelines, VCS tags, rewind locks/audits, and time-travel metrics | Time Travel, Time Travel Quickstart |
@smithers-orchestrator/vcs | VCS discovery and jj workspace operations such as runJj, workspaceAdd, workspaceList, and pointer reverts | VCS Helpers, VCS Guide |
Usage
TypeScript Configuration
JSX Import Source
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 thesmithers-orchestrator monorepo, the root tsconfig.json defines path aliases so source imports resolve without a build step:
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
./src/types directory contains ambient type declarations that fill gaps in third-party packages. One shim ships today:
react-dom-server.d.ts— Declares thereact-dom/servermodule so TypeScript doesn’t error when server-side rendering types are referenced.
@types/react-dom to devDependencies instead of relying on this shim.
Bun Configuration
Runtime Preload
.mdx files can be imported as JSX components at runtime. See MDX Prompts for details.
Test Configuration
| Key | Value | Purpose |
|---|---|---|
root | ./tests | Bun 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 |
[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 rootpackage.json for development:
| Script | Command | Purpose |
|---|---|---|
typecheck | tsc --noEmit | Type-check the src/ and tests/ trees against tsconfig.json |
typecheck:examples | tsc -p examples/tsconfig.json --noEmit | Type-check example files against a separate config that maps smithers-orchestrator to examples-entry.js |
lint | oxlint ... packages/*/src packages/*/tests | Lint package source and tests with oxlint |
lint:fix | oxlint ... --fix --fix-suggestions packages/*/src packages/*/tests | Apply supported oxlint fixes |
cli | bun run apps/cli/src/index.js | Run the local development CLI entrypoint |
test | node scripts/check-single-effect-version.mjs && node scripts/check-dependency-boundaries.mjs && pnpm -r test | Run dependency guard checks and each package test script |
check:effect | node scripts/check-single-effect-version.mjs | Verify the workspace resolves a single Effect version |
check:deps | node scripts/check-dependency-boundaries.mjs | Verify package dependency boundaries |
docs | cd docs && bunx mintlify dev | Start the Mintlify docs dev server for local preview |
version | node scripts/bump.mjs | Bump package versions using the release helper |
release | node scripts/publish.mjs | Publish packages using the release helper |
For end-user projects
When scaffolding your own project (withsmithers init or manually), add a typecheck script:
package.json example.