Package Configuration

This page covers: CLI binary usage, subpath export map, TypeScript compiler options, Bun preload and test config, and npm scripts.

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. Entry files in this table are relative to the published smithers-orchestrator package; in the repository they live under packages/smithers/.

Import path	Entry file	Purpose
`smithers-orchestrator`	`./src/index.js`	Core API: `createSmithers`, `openSmithersBackend`, 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/*`	`./src/*.js`	Wildcard-backed facade wrappers for additional public subpaths

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 workspace packages below are listed for advanced integrations, custom clients, framework development, and monorepo orientation. Some app workspaces are private and are not published packages.

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/electric-proxy`	ElectricSQL shape proxy for cloud sync, scoped shape access, rate limits, stripped auth forwarding, and shape metrics	Production Hardening, Gateway
`@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/jj-darwin-arm64`	Vendored jj (Jujutsu) binary for darwin-arm64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly	VCS Guide
`@smithers-orchestrator/jj-darwin-x64`	Vendored jj (Jujutsu) binary for darwin-x64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly	VCS Guide
`@smithers-orchestrator/jj-linux-arm64`	Vendored jj (Jujutsu) binary for linux-arm64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly	VCS Guide
`@smithers-orchestrator/jj-linux-x64`	Vendored jj (Jujutsu) binary for linux-x64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly	VCS Guide
`@smithers-orchestrator/jj-win32-x64`	Vendored jj (Jujutsu) binary for win32-x64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly	VCS Guide
`@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, Tools
`@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/review`	Private code review app: review flow plus story-form HTML walkthrough, exposed through the `smithers-review` bin	CLI Overview
`@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/tool-context`	AsyncLocalStorage tool-execution context (run/node/idempotency keys, durability snapshot hook) shared by the engine and `smithers-orchestrator` without a dependency cycle	Execution Model
`@smithers-orchestrator/usage`	Account quota and rate-limit usage reporting for Smithers providers	CLI Overview
`@smithers-orchestrator/vcs`	VCS discovery and jj workspace operations such as `runJj`, `workspaceAdd`, `workspaceList`, and pointer reverts	VCS Helpers, VCS Guide

Usage

// Core API
import { createSmithers, openSmithersBackend, 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.js)
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": ["./packages/smithers/src/types", "./node_modules/@types"]

The ./packages/smithers/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.js"]

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 = "."
preload = ["./preload.js"]

Key	Value	Purpose
`root`	`.`	Bun discovers test files from the repository root
`preload`	`["./preload.js"]`	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:

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`
`typecheck:evals`	`tsc -p evals/tsconfig.json --noEmit`	Type-check the agent-fluency eval suite under `evals/` against its own config
`lint`	`oxlint --react-plugin --node-plugin --import-plugin --ignore-path .gitignore -A react/no-children-prop -A unicorn/no-thenable --ignore-pattern 'packages//src//.d.ts' packages//src packages//tests`	Lint package source and tests with oxlint
`lint:fix`	`oxlint --react-plugin --node-plugin --import-plugin --ignore-path .gitignore -A react/no-children-prop -A unicorn/no-thenable --ignore-pattern 'packages//src//.d.ts' --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
`generate:init-pack`	`bun scripts/generate-workflow-pack.ts`	Regenerate the local workflow pack used by `bunx smithers-orchestrator init`
`test`	`node scripts/check-single-effect-version.mjs && node scripts/check-dependency-boundaries.mjs && node scripts/check-docs.mjs && node scripts/check-llms.mjs && node scripts/check-smithers-test-script.mjs && pnpm -r --no-bail test`	Run docs/config guards, dependency guards, llms guards, and each package test script (no-bail so every failing package is reported)
`coverage`	`node scripts/coverage.mjs`	Generate a test coverage report across the workspace
`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
`check:docs`	`node scripts/check-docs.mjs`	Verify documentation style and API drift guards
`check:llms`	`node scripts/check-llms.mjs`	Verify generated llms docs are current
`fetch:jj`	`node scripts/fetch-jj-binaries.mjs`	Fetch vendored jj binaries for supported platforms
`docs:components`	`node scripts/generate-component-source.mjs`	Embed composite component source as tabs in their docs pages
`docs:llms`	`bun scripts/generate-llms.ts && bun scripts/optimize-llms-full.ts`	Regenerate `llms-core.txt` and `llms-full.txt`
`docs`	`cd docs && bunx mintlify dev`	Start the Mintlify docs dev server for local preview
`release:content`	`bunx smithers-orchestrator up .smithers/workflows/release-content.tsx`	Run the release-content workflow (changelog, tweet thread, blog) in dry-run mode
`release:content:approve`	`bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":false}'`	Generate release content for real but stop before publishing
`release:content:publish`	`bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":true}'`	Generate and publish the release content
`release:workflow`	`bunx smithers-orchestrator up .smithers/workflows/release.tsx`	Run the end-to-end release workflow
`release:workflow:gated`	`bunx smithers-orchestrator up .smithers/workflows/release.tsx --input '{"requireMarketingContent":true}'`	Run the release workflow but require marketing content before publishing
`marketing:thread`	`bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"channels":{"changelog":false,"tweetThread":true,"blogPost":false},"skip":{"changelog":true,"blogPost":true,"publishX":true,"publishBlog":true,"publishChangelog":true}}'`	Generate just the tweet thread in dry-run mode, skipping changelog and blog
`marketing:thread:write`	`bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":true,"allowUnreviewedPublish":true,"channels":{"changelog":false,"tweetThread":true,"blogPost":false},"skip":{"changelog":true,"blogPost":true,"approval":true,"publishX":true,"publishBlog":true,"publishChangelog":true}}'`	Generate and publish just the tweet thread, skipping changelog, blog, and the approval gate
`version`	`node scripts/bump.mjs`	Bump package versions using the release helper
`release`	`node scripts/publish.mjs`	Publish packages using the release helper
`sandbox:up`	`bun scripts/sandbox.ts up`	Create a disposable GCP sandbox VM and open an SSH session into it
`sandbox:down`	`bun scripts/sandbox.ts down`	Delete the sandbox VM created by `sandbox:up`

For end-user projects

When scaffolding your own project (with bunx smithers-orchestrator init or manually), add a typecheck script:

{
  "scripts": {
    "typecheck": "tsc --noEmit"
  }
}

See Production Project Structure for a complete user-project package.json example.

​Binary

​Subpath Exports

​Workspace Packages

​Usage

​TypeScript Configuration

​JSX Import Source

​Path Aliases

​Local Type Root Shims

​Bun Configuration

​Runtime Preload

​Test Configuration

​npm Scripts

​For end-user projects