smithers-orchestrator 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithers-orchestrator",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Public Smithers facade for durable coding-agent workflows and Gateway operation",
   "type": "module",
   "sideEffects": false,
@@ -35,15 +35,20 @@
       "import": "./src/control-plane.js",
       "default": "./src/control-plane.js"
     },
-    "./*": {
-      "types": "./src/index.d.ts",
-      "import": "./src/*.js",
-      "default": "./src/*.js"
+    "./jsx-runtime": {
+      "types": "./src/jsx-runtime.d.ts",
+      "import": "./src/jsx-runtime.js",
+      "default": "./src/jsx-runtime.js"
     },
     "./jsx-dev-runtime": {
-      "types": "./src/index.d.ts",
+      "types": "./src/jsx-runtime.d.ts",
       "import": "./src/jsx-runtime.js",
       "default": "./src/jsx-runtime.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
     }
   },
   "files": [
@@ -61,27 +66,33 @@
     "incur": "^0.4.1",
     "react": "^19.2.5",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/agents": "0.22.0",
-    "@smithers-orchestrator/cli": "0.22.0",
-    "@smithers-orchestrator/components": "0.22.0",
-    "@smithers-orchestrator/control-plane": "0.22.0",
-    "@smithers-orchestrator/driver": "0.22.0",
-    "@smithers-orchestrator/engine": "0.22.0",
-    "@smithers-orchestrator/gateway-client": "0.22.0",
-    "@smithers-orchestrator/errors": "0.22.0",
-    "@smithers-orchestrator/gateway-react": "0.22.0",
-    "@smithers-orchestrator/graph": "0.22.0",
-    "@smithers-orchestrator/db": "0.22.0",
-    "@smithers-orchestrator/memory": "0.22.0",
-    "@smithers-orchestrator/observability": "0.22.0",
-    "@smithers-orchestrator/openapi": "0.22.0",
-    "@smithers-orchestrator/react-reconciler": "0.22.0",
-    "@smithers-orchestrator/sandbox": "0.22.0",
-    "@smithers-orchestrator/scorers": "0.22.0",
-    "@smithers-orchestrator/scheduler": "0.22.0",
-    "@smithers-orchestrator/server": "0.22.0",
-    "@smithers-orchestrator/time-travel": "0.22.0",
-    "@smithers-orchestrator/vcs": "0.22.0"
+    "@smithers-orchestrator/agents": "0.24.0",
+    "@smithers-orchestrator/components": "0.24.0",
+    "@smithers-orchestrator/control-plane": "0.24.0",
+    "@smithers-orchestrator/driver": "0.24.0",
+    "@smithers-orchestrator/db": "0.24.0",
+    "@smithers-orchestrator/engine": "0.24.0",
+    "@smithers-orchestrator/errors": "0.24.0",
+    "@smithers-orchestrator/gateway-client": "0.24.0",
+    "@smithers-orchestrator/gateway-react": "0.24.0",
+    "@smithers-orchestrator/graph": "0.24.0",
+    "@smithers-orchestrator/memory": "0.24.0",
+    "@smithers-orchestrator/observability": "0.24.0",
+    "@smithers-orchestrator/openapi": "0.24.0",
+    "@smithers-orchestrator/react-reconciler": "0.24.0",
+    "@smithers-orchestrator/sandbox": "0.24.0",
+    "@smithers-orchestrator/scheduler": "0.24.0",
+    "@smithers-orchestrator/scorers": "0.24.0",
+    "@smithers-orchestrator/server": "0.24.0",
+    "@smithers-orchestrator/time-travel": "0.24.0",
+    "@smithers-orchestrator/vcs": "0.24.0",
+    "@smithers-orchestrator/tool-context": "0.24.0",
+    "@smithers-orchestrator/cli": "0.24.0"
+  },
+  "optionalDependencies": {
+    "@electric-sql/pglite": "0.5.1",
+    "@electric-sql/pglite-socket": "0.2.1",
+    "pg": "^8.13.1"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/__type-tests__/task-fork-jsx.test.tsx

@@ -0,0 +1,19 @@
+import { createSmithers } from "../index.js";
+import { z } from "zod";
+import type { AgentLike } from "@smithers-orchestrator/agents";
+
+const agent = {
+  generate: async () => ({ ok: true }),
+} satisfies AgentLike;
+
+const { Task, outputs } = createSmithers({
+  next: z.object({
+    ok: z.boolean(),
+  }),
+});
+
+const _TaskForkJsx = (
+  <Task id="next" output={outputs.next} agent={agent} fork="source">
+    Continue from the source task.
+  </Task>
+);

package/src/create.js

@@ -14,8 +14,11 @@ import { Approval as BaseApproval, Workflow as BaseWorkflow, Task as BaseTask, S
 import { zodToTable } from "@smithers-orchestrator/db/zodToTable";
 import { zodToCreateTableSQL, syncZodTableSchema } from "@smithers-orchestrator/db/zodToCreateTableSQL";
 import { camelToSnake } from "@smithers-orchestrator/db/utils/camelToSnake";
-import { resolve } from "node:path";
+import { SmithersDb } from "@smithers-orchestrator/db/adapter";
+import { POSTGRES } from "@smithers-orchestrator/db/dialect";
+import { resolve, join } from "node:path";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { findSmithersAnchorDir } from "./findSmithersAnchorDir.js";
 /** @typedef {import("@smithers-orchestrator/components").ApprovalProps<any, any>} ApprovalProps */
 /** @typedef {import("@smithers-orchestrator/components").SandboxProps} SandboxProps */
 /** @typedef {import("@smithers-orchestrator/components").SignalProps<any>} SignalProps */
@@ -173,43 +176,14 @@ function mergeAlertPolicies(base, override) {
     return merged;
 }
 /**
- * Schema-driven API — users define only Zod schemas, the framework owns the entire storage layer.
- *
- * @template {Record<string, import("zod").ZodObject<any>>} Schemas
- * @param {Schemas} schemas
- * @param {CreateSmithersOptions} [opts]
- * @returns {import("./CreateSmithersApi.ts").CreateSmithersApi<Schemas>}
- *
- * @example
- * ```ts
- * const { Workflow, Task, smithers, outputs } = createSmithers({
- *   discover: discoverOutputSchema,
- *   research: researchOutputSchema,
- * });
+ * Generate the Drizzle table metadata, schema registry, and output refs shared by
+ * every backend. The Drizzle tables carry only column/name metadata — the actual
+ * storage is created per-dialect by the caller; dialect-aware engine reads consult
+ * these objects via getTableColumns/getTableName, never to issue SQLite queries.
  *
- * export default smithers((ctx) => (
- *   <Workflow name="my-workflow">
- *     <Task id="discover" output={outputs.discover} agent={myAgent}>...</Task>
- *   </Workflow>
- * ));
- * ```
+ * @param {Record<string, any>} schemas
  */
-export function createSmithers(schemas, opts) {
-    const dbPath = opts?.dbPath ?? "./smithers.db";
-    const absDbPath = resolve(process.cwd(), dbPath);
-    if (process.env.SMITHERS_HOT === "1") {
-        const sig = computeSchemaSig(schemas, absDbPath);
-        const cached = hotCache.get(absDbPath);
-        if (cached) {
-            if (cached.schemaSig !== sig) {
-                throw new SmithersError("SCHEMA_CHANGE_HOT", "[smithers hot] Schema change detected; restart required to apply schema changes.");
-            }
-            cached.setModuleAlertPolicy(opts?.alertPolicy);
-            return cached.api;
-        }
-        // Will cache after creating the API below
-    }
-    // 1. Generate Drizzle tables from Zod schemas
+function prepareSmithersTables(schemas) {
     const tables = {};
     const inputTable = schemas.input
         ? zodToTable("input", schemas.input, { isInput: true })
@@ -223,77 +197,39 @@ export function createSmithers(schemas, opts) {
         const tableName = camelToSnake(name);
         tables[name] = zodToTable(tableName, zodSchema);
     }
-    // 2. Create SQLite db
-    const sqlite = new Database(dbPath);
-    sqlite.run(`PRAGMA journal_mode = ${opts?.journalMode ?? "WAL"}`);
-    // 30s timeout: concurrent worktrees each spawn agent processes that all write
-    // to smithers.db simultaneously. 5s is too short and causes SQLITE_IOERR_VNODE
-    // on macOS when the VFS can't acquire the WAL shared-memory lock in time.
-    sqlite.run("PRAGMA busy_timeout = 30000");
-    // NORMAL is safe in WAL mode (no data loss on crash) and reduces fsync
-    // stalls that contribute to WAL checkpoint contention across processes.
-    sqlite.run("PRAGMA synchronous = NORMAL");
-    // Ensure no exclusive lock is held, allowing multiple readers/writers.
-    sqlite.run("PRAGMA locking_mode = NORMAL");
-    sqlite.run("PRAGMA foreign_keys = ON");
-    // Register a process-exit hook to explicitly close the Database.
-    // bun:sqlite's GC finalizer calls sqlite3_close() which fatally aborts if
-    // Drizzle's cached prepared statements haven't been finalized first.
-    // Calling close() ourselves lets sqlite3 finalize everything gracefully.
-    let dbClosed = false;
-    const closeDb = () => {
-        if (dbClosed)
-            return;
-        dbClosed = true;
-        try {
-            sqlite.close();
-        }
-        catch { }
-        process.removeListener("exit", closeDb);
-    };
-    process.once("exit", closeDb);
-    // 3. Auto-create tables, and ALTER any existing tables to add columns the
-    // current schema introduced (CREATE TABLE IF NOT EXISTS would silently
-    // skip the columns and a later upsert would fail with "no column named X").
-    if (schemas.input) {
-        syncZodTableSchema(sqlite, "input", schemas.input, { isInput: true });
-    }
-    else {
-        sqlite.exec(`CREATE TABLE IF NOT EXISTS "input" (run_id TEXT PRIMARY KEY, payload TEXT)`);
-        try {
-            const cols = sqlite.query(`PRAGMA table_info("input")`).all();
-            const hasPayload = cols.some((col) => col?.name === "payload");
-            if (!hasPayload) {
-                sqlite.run(`ALTER TABLE "input" ADD COLUMN payload TEXT`);
-            }
-        }
-        catch {
-            // ignore - older SQLite or permission issues; input payload remains best-effort
-        }
-    }
-    for (const [name, zodSchema] of Object.entries(schemas)) {
-        if (name === "input")
-            continue;
-        const tableName = camelToSnake(name);
-        syncZodTableSchema(sqlite, tableName, zodSchema);
-    }
-    // 4. Create Drizzle instance with all tables in the schema
     const drizzleSchema = { input: inputTable };
     for (const [key, table] of Object.entries(tables)) {
         drizzleSchema[key] = table;
     }
-    const db = drizzle(sqlite, { schema: drizzleSchema });
-    // 5. Build schema registry for engine resolution of string output keys
     const schemaRegistry = new Map();
     for (const [name, zodSchema] of Object.entries(schemas)) {
         if (name === "input")
             continue;
         schemaRegistry.set(name, { table: tables[name], zodSchema });
     }
-    // 6. Build output refs and reverse lookup: ZodObject reference → schema key name
     const { outputs, zodToKeyName, ambiguousZodSchemas } = prepareOutputSchemas(schemas);
-    // 7. Context + hooks
-    const { SmithersContext: RuntimeSmithersContext, useCtx, } = createSmithersContext();
+    return { tables, inputTable, drizzleSchema, schemaRegistry, outputs, zodToKeyName, ambiguousZodSchemas };
+}
+/**
+ * Construct the public createSmithers API object around a prepared database
+ * handle and shared table metadata. Backend-agnostic: `db` is either a Drizzle
+ * bun:sqlite instance or a Postgres descriptor; every engine read/write below it
+ * is dialect-aware.
+ *
+ * @param {{
+ *   db: unknown;
+ *   tables: Record<string, unknown>;
+ *   schemaRegistry: Map<string, unknown>;
+ *   outputs: Record<string, unknown>;
+ *   zodToKeyName: Map<unknown, string>;
+ *   ambiguousZodSchemas: Set<unknown>;
+ *   opts?: CreateSmithersOptions;
+ *   inputSchema?: unknown;
+ * }} config
+ */
+function buildSmithersApi(config) {
+    const { db, tables, schemaRegistry, outputs, zodToKeyName, ambiguousZodSchemas, opts, inputSchema } = config;
+    const { SmithersContext: RuntimeSmithersContext, useCtx } = createSmithersContext();
     const ctxRef = { current: null };
     let moduleAlertPolicy = opts?.alertPolicy;
     /**
@@ -352,9 +288,8 @@ export function createSmithers(schemas, opts) {
         });
     }
     /**
-   * @param {(ctx: SmithersCtx<Schemas>) => React.ReactElement} build
+   * @param {(ctx: SmithersCtx<any>) => React.ReactElement} build
    * @param {SmithersWorkflowOptions} [smithersOpts]
-   * @returns {SmithersWorkflow<Schemas>}
    */
     function boundSmithers(build, smithersOpts) {
         const workflowOpts = {
@@ -372,6 +307,7 @@ export function createSmithers(schemas, opts) {
                 return React.createElement(RuntimeSmithersContext.Provider, { value: ctxRef.current }, React.createElement(GlobalSmithersContext.Provider, { value: ctxRef.current }, build(ctx)));
             },
             opts: workflowOpts,
+            inputSchema,
             schemaRegistry,
             zodToKeyName,
             ambiguousZodSchemas,
@@ -402,9 +338,122 @@ export function createSmithers(schemas, opts) {
         useCtx,
         smithers: boundSmithers,
         db,
-        tables: tables,
+        tables,
         outputs,
     };
+    return { api, setModuleAlertPolicy };
+}
+/**
+ * Schema-driven API — users define only Zod schemas, the framework owns the entire storage layer.
+ *
+ * @template {Record<string, import("zod").ZodObject<any>>} Schemas
+ * @param {Schemas} schemas
+ * @param {CreateSmithersOptions} [opts]
+ * @returns {import("./CreateSmithersApi.ts").CreateSmithersApi<Schemas>}
+ *
+ * @example
+ * ```ts
+ * const { Workflow, Task, smithers, outputs } = createSmithers({
+ *   discover: discoverOutputSchema,
+ *   research: researchOutputSchema,
+ * });
+ *
+ * export default smithers((ctx) => (
+ *   <Workflow name="my-workflow">
+ *     <Task id="discover" output={outputs.discover} agent={myAgent}>...</Task>
+ *   </Workflow>
+ * ));
+ * ```
+ */
+export function createSmithers(schemas, opts) {
+    // Resolve the DB path from the nearest .smithers/ anchor so that running a
+    // workflow from a subdirectory always creates/uses the project-root DB, not
+    // a new one at CWD. An explicit opts.dbPath overrides this entirely.
+    const anchorDir = findSmithersAnchorDir(process.cwd());
+    const defaultDbPath = anchorDir ? join(anchorDir, "smithers.db") : "./smithers.db";
+    const dbPath = opts?.dbPath ?? defaultDbPath;
+    const absDbPath = resolve(process.cwd(), dbPath);
+    if (process.env.SMITHERS_HOT === "1") {
+        const sig = computeSchemaSig(schemas, absDbPath);
+        const cached = hotCache.get(absDbPath);
+        if (cached) {
+            if (cached.schemaSig !== sig) {
+                throw new SmithersError("SCHEMA_CHANGE_HOT", "[smithers hot] Schema change detected; restart required to apply schema changes.");
+            }
+            cached.setModuleAlertPolicy(opts?.alertPolicy);
+            return cached.api;
+        }
+        // Will cache after creating the API below
+    }
+    // 1. Generate Drizzle tables + schema metadata from Zod schemas.
+    const { tables, drizzleSchema, schemaRegistry, outputs, zodToKeyName, ambiguousZodSchemas } = prepareSmithersTables(schemas);
+    // 2. Create SQLite db
+    const sqlite = new Database(dbPath);
+    sqlite.run(`PRAGMA journal_mode = ${opts?.journalMode ?? "WAL"}`);
+    // 30s timeout: concurrent worktrees each spawn agent processes that all write
+    // to smithers.db simultaneously. 5s is too short and causes SQLITE_IOERR_VNODE
+    // on macOS when the VFS can't acquire the WAL shared-memory lock in time.
+    sqlite.run("PRAGMA busy_timeout = 30000");
+    // NORMAL is safe in WAL mode (no data loss on crash) and reduces fsync
+    // stalls that contribute to WAL checkpoint contention across processes.
+    sqlite.run("PRAGMA synchronous = NORMAL");
+    // Ensure no exclusive lock is held, allowing multiple readers/writers.
+    sqlite.run("PRAGMA locking_mode = NORMAL");
+    sqlite.run("PRAGMA foreign_keys = ON");
+    // Register a process-exit hook to explicitly close the Database.
+    // bun:sqlite's GC finalizer calls sqlite3_close() which fatally aborts if
+    // Drizzle's cached prepared statements haven't been finalized first.
+    // Calling close() ourselves lets sqlite3 finalize everything gracefully.
+    let dbClosed = false;
+    const closeDb = () => {
+        if (dbClosed)
+            return;
+        dbClosed = true;
+        try {
+            sqlite.close();
+        }
+        catch { }
+        process.removeListener("exit", closeDb);
+    };
+    process.once("exit", closeDb);
+    // 3. Auto-create tables, and ALTER any existing tables to add columns the
+    // current schema introduced (CREATE TABLE IF NOT EXISTS would silently
+    // skip the columns and a later upsert would fail with "no column named X").
+    if (schemas.input) {
+        syncZodTableSchema(sqlite, "input", schemas.input, { isInput: true });
+    }
+    else {
+        sqlite.exec(`CREATE TABLE IF NOT EXISTS "input" (run_id TEXT PRIMARY KEY, payload TEXT)`);
+        try {
+            const cols = sqlite.query(`PRAGMA table_info("input")`).all();
+            const hasPayload = cols.some((col) => col?.name === "payload");
+            if (!hasPayload) {
+                sqlite.run(`ALTER TABLE "input" ADD COLUMN payload TEXT`);
+            }
+        }
+        catch {
+            // ignore - older SQLite or permission issues; input payload remains best-effort
+        }
+    }
+    for (const [name, zodSchema] of Object.entries(schemas)) {
+        if (name === "input")
+            continue;
+        const tableName = camelToSnake(name);
+        syncZodTableSchema(sqlite, tableName, zodSchema);
+    }
+    // 4. Create Drizzle instance with all tables in the schema
+    const db = drizzle(sqlite, { schema: drizzleSchema });
+    // 5. Build the public API around the prepared db + table metadata.
+    const { api, setModuleAlertPolicy } = buildSmithersApi({
+        db,
+        tables,
+        schemaRegistry,
+        outputs,
+        zodToKeyName,
+        ambiguousZodSchemas,
+        opts,
+        inputSchema: schemas.input,
+    });
     if (process.env.SMITHERS_HOT === "1") {
         const sig = computeSchemaSig(schemas, absDbPath);
         hotCache.set(absDbPath, {
@@ -415,3 +464,117 @@ export function createSmithers(schemas, opts) {
     }
     return api;
 }
+/**
+ * PostgreSQL/PGlite-backed equivalent of {@link createSmithers}. Asynchronous
+ * because connecting and provisioning schema over the wire is async (unlike the
+ * synchronous bun:sqlite path). Boots a node-postgres connection (`provider:
+ * "postgres"`) or an embedded PGlite over a local socket (`provider: "pglite"`),
+ * provisions the durable engine schema + the per-Zod-schema output tables with
+ * Postgres-typed DDL, and returns the same createSmithers API surface plus a
+ * `close()` teardown for the connection.
+ *
+ * @template {Record<string, import("zod").ZodObject<any>>} Schemas
+ * @param {Schemas} schemas
+ * @param {CreateSmithersOptions & ({ provider: "postgres"; connectionString?: string; connection?: object } | { provider: "pglite"; dataDir?: string })} opts
+ * @returns {Promise<import("./CreateSmithersApi.ts").CreateSmithersApi<Schemas> & { close: () => Promise<void> }>}
+ */
+export async function createSmithersPostgres(schemas, opts) {
+    const provider = opts?.provider ?? "postgres";
+    // 1. Generate Drizzle tables + schema metadata from Zod schemas (shared).
+    const { tables, drizzleSchema, schemaRegistry, outputs, zodToKeyName, ambiguousZodSchemas } = prepareSmithersTables(schemas);
+    // 2. Boot the Postgres/PGlite connection.
+    const pgModule = await import("pg");
+    const pg = pgModule.default ?? pgModule;
+    // BIGINT (ms timestamps, counters) → JS number, matching SQLite's behavior.
+    pg.types.setTypeParser(20, (value) => (value === null ? null : Number(value)));
+    /** @type {Array<() => Promise<void>>} */
+    const teardown = [];
+    let connectionString = opts?.connectionString;
+    if (provider === "pglite") {
+        const { PGlite } = await import("@electric-sql/pglite");
+        const { PGLiteSocketServer } = await import("@electric-sql/pglite-socket");
+        const pglite = await PGlite.create(opts?.dataDir || undefined);
+        const port = await findFreePgPort();
+        const server = new PGLiteSocketServer({ db: pglite, host: "127.0.0.1", port, maxConnections: 5 });
+        await server.start();
+        teardown.push(async () => {
+            await server.stop().catch(() => {});
+            await pglite.close().catch(() => {});
+        });
+        connectionString = `postgres://postgres@127.0.0.1:${port}/postgres`;
+    }
+    const client = new pg.Client(connectionString ? { connectionString } : opts?.connection);
+    /** @type {{ api: import("./CreateSmithersApi.ts").CreateSmithersApi<Schemas> }} */
+    let built;
+    try {
+        await client.connect();
+        teardown.push(async () => {
+            await client.end().catch(() => {});
+        });
+        // 3. Postgres descriptor consumed by the engine + adapter. The Drizzle table
+        // objects (snake_case columns identical to the DDL below) are attached only
+        // for column/name metadata; the engine's reads/writes against this descriptor
+        // are dialect-aware and go through the @effect/sql adapter or raw $n queries.
+        const descriptor = { dialect: "postgres", connection: client, schema: drizzleSchema };
+        const adapter = new SmithersDb(descriptor);
+        // 4. Durable engine schema (idempotent), then the input + output tables with
+        // Postgres-typed DDL derived from the Zod schemas.
+        await adapter.internalStorage.ensureSchema();
+        if (schemas.input) {
+            await client.query({ text: zodToCreateTableSQL("input", schemas.input, { isInput: true, dialect: POSTGRES }) });
+        }
+        else {
+            await client.query({ text: `CREATE TABLE IF NOT EXISTS "input" (run_id TEXT PRIMARY KEY, payload TEXT)` });
+        }
+        for (const [name, zodSchema] of Object.entries(schemas)) {
+            if (name === "input")
+                continue;
+            const tableName = camelToSnake(name);
+            await client.query({ text: zodToCreateTableSQL(tableName, zodSchema, { dialect: POSTGRES }) });
+        }
+        // 5. Build the public API around the descriptor + table metadata.
+        built = buildSmithersApi({
+            db: descriptor,
+            tables,
+            schemaRegistry,
+            outputs,
+            zodToKeyName,
+            ambiguousZodSchemas,
+            opts,
+            inputSchema: schemas.input,
+        });
+    }
+    catch (e) {
+        // Drain any teardown registered so far (socket server, pg client) so a
+        // failure after boot does not leak the port / connection.
+        for (const fn of teardown.reverse()) {
+            await fn().catch(() => {});
+        }
+        throw e;
+    }
+    const { api } = built;
+    return {
+        ...api,
+        close: async () => {
+            for (const fn of teardown.reverse()) {
+                await fn();
+            }
+        },
+    };
+}
+/**
+ * @returns {Promise<number>}
+ */
+async function findFreePgPort() {
+    const net = await import("node:net");
+    return new Promise((resolveFn, reject) => {
+        const srv = net.createServer();
+        srv.unref();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const address = srv.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            srv.close(() => resolveFn(port));
+        });
+    });
+}

package/src/findSmithersAnchorDir.js

@@ -0,0 +1,38 @@
+import { resolve, dirname, join } from "node:path";
+import { existsSync, statSync } from "node:fs";
+
+/**
+ * Walk upward from `from` and return the nearest directory that contains a
+ * `.smithers/` subdirectory, or `undefined` if none is found before the
+ * filesystem root.
+ *
+ * Directories at or above $HOME are excluded: a `~/.smithers` global pack
+ * must not be treated as a project anchor, so the DB would incorrectly land
+ * in the user's home directory.
+ *
+ * @param {string} from
+ * @returns {string | undefined}
+ */
+export function findSmithersAnchorDir(from) {
+    let dir = resolve(from);
+    const fsRoot = resolve("/");
+    const home = process.env.HOME ? resolve(process.env.HOME) : undefined;
+    while (true) {
+        // Stop at or above HOME — anchors must be proper project directories
+        // strictly below the user's home directory.
+        // Use startsWith rather than length comparison so that symlinks and
+        // unusual mount points (e.g. /home2) don't produce false positives.
+        if (home && (dir === home || !dir.startsWith(home + "/"))) {
+            return undefined;
+        }
+        // Guard: never scan the filesystem root itself.
+        if (dir === fsRoot) {
+            return undefined;
+        }
+        const candidate = join(dir, ".smithers");
+        if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+            return dir;
+        }
+        dir = dirname(dir);
+    }
+}

package/src/index.d.ts

@@ -2,6 +2,7 @@ import * as ai from 'ai';
 import { Tool } from 'ai';
 import * as _smithers_graph_XmlNode from '@smithers-orchestrator/graph/XmlNode';
 import * as _smithers_time_travel_timetravel from '@smithers-orchestrator/time-travel/timetravel';
+export { timeTravel } from '@smithers-orchestrator/time-travel/timetravel';
 import * as _smithers_graph_TaskDescriptor from '@smithers-orchestrator/graph/TaskDescriptor';
 import * as _smithers_components_SmithersWorkflow from '@smithers-orchestrator/components/SmithersWorkflow';
 import { SmithersWorkflow as SmithersWorkflow$1 } from '@smithers-orchestrator/components/SmithersWorkflow';
@@ -24,6 +25,7 @@ import * as _smithers_driver_RunStatus from '@smithers-orchestrator/driver/RunSt
 import * as _smithers_driver_RunResult from '@smithers-orchestrator/driver/RunResult';
 import * as _smithers_driver_RunOptions from '@smithers-orchestrator/driver/RunOptions';
 import * as _smithers_time_travel_revert from '@smithers-orchestrator/time-travel/revert';
+export { revertToAttempt } from '@smithers-orchestrator/time-travel/revert';
 import * as _smithers_observability from '@smithers-orchestrator/observability';
 export { SmithersObservability, activeNodes, activeRuns, approvalsDenied, approvalsGranted, approvalsRequested, attemptDuration, cacheHits, cacheMisses, createSmithersObservabilityLayer, createSmithersOtelLayer, createSmithersRuntimeLayer, dbQueryDuration, dbRetries, dbTransactionDuration, dbTransactionRetries, dbTransactionRollbacks, externalWaitAsyncPending, hotReloadDuration, hotReloadFailures, hotReloads, httpRequestDuration, httpRequests, nodeDuration, nodesFailed, nodesFinished, nodesStarted, prometheusContentType, renderPrometheusMetrics, resolveSmithersObservabilityOptions, runsTotal, sandboxActive, sandboxBundleSizeBytes, sandboxCompletedTotal, sandboxCreatedTotal, sandboxDurationMs, sandboxPatchCount, sandboxTransportDurationMs, schedulerQueueDepth, smithersMetrics, timerDelayDuration, timersCancelled, timersCreated, timersFired, timersPending, toolCallsTotal, toolDuration, trackSmithersEvent, vcsDuration } from '@smithers-orchestrator/observability';
 import * as _smithers_driver_OutputKey from '@smithers-orchestrator/driver/OutputKey';
@@ -56,7 +58,7 @@ import { WorkflowProps } from '@smithers-orchestrator/components/components/Work
 import * as _smithers_server_gateway from '@smithers-orchestrator/server/gateway';
 export { Gateway } from '@smithers-orchestrator/server/gateway';
 import * as _smithers_agents from '@smithers-orchestrator/agents';
-export { AmpAgent, AnthropicAgent, AntigravityAgent, ClaudeCodeAgent, CodexAgent, ForgeAgent, GeminiAgent, HermesAgent, KimiAgent, OpenAIAgent, OpenCodeAgent, PiAgent } from '@smithers-orchestrator/agents';
+export { AmpAgent, AnthropicAgent, AntigravityAgent, ClaudeCodeAgent, CodexAgent, ForgeAgent, GeminiAgent, HermesAgent, KimiAgent, OpenAIAgent, OpenCodeAgent, PiAgent, VibeAgent } from '@smithers-orchestrator/agents';
 import * as _smithers_scorers from '@smithers-orchestrator/scorers';
 export { aggregateScores, createScorer, faithfulnessScorer, latencyScorer, llmJudge, relevancyScorer, runScorersAsync, runScorersBatch, schemaAdherenceScorer, smithersScorers, toxicityScorer } from '@smithers-orchestrator/scorers';
 import * as _smithers_agents_capability_registry from '@smithers-orchestrator/agents/capability-registry';
@@ -70,6 +72,9 @@ export { isSmithersError } from '@smithers-orchestrator/errors/isSmithersError';
 export { knownSmithersErrorCodes } from '@smithers-orchestrator/errors/knownSmithersErrorCodes';
 export { signalRun } from '@smithers-orchestrator/engine/signals';
 export { usePatched } from '@smithers-orchestrator/engine/effect/versioning';
+import { SmithersDb } from '@smithers-orchestrator/db/adapter';
+export { SmithersDb } from '@smithers-orchestrator/db/adapter';
+export { loadOutputs, loadOutputsEffect } from '@smithers-orchestrator/db';
 export { ensureSmithersTables } from '@smithers-orchestrator/db/ensure';
 export { markdownComponents } from '@smithers-orchestrator/components/markdownComponents';
 export { renderMdx } from '@smithers-orchestrator/components/renderMdx';
@@ -78,8 +83,8 @@ export { syncZodTableSchema, zodSchemaColumns, zodToCreateTableSQL } from '@smit
 export { camelToSnake } from '@smithers-orchestrator/db/utils/camelToSnake';
 export { unwrapZodType } from '@smithers-orchestrator/db/unwrapZodType';
 export { zodSchemaToJsonExample } from '@smithers-orchestrator/components/zod-to-example';
-export { BuilderApi, BuiltSmithersWorkflow, Smithers, StepOptions, fragment, renderFrame, runWorkflow, workflow } from '@smithers-orchestrator/engine';
-import { SmithersDb } from '@smithers-orchestrator/db/adapter';
+export { BuilderApi, BuiltSmithersWorkflow, Smithers, StepOptions, approveNode, denyNode, fragment, getRun, listRuns, renderFrame, runWorkflow, workflow } from '@smithers-orchestrator/engine';
+export { resolveWorktreePath } from '@smithers-orchestrator/graph';
 
 type SerializedCtx$1 = {
     runId: string;
@@ -173,7 +178,20 @@ type CreateSmithersOptions$1 = {
  * ```
  */
 declare function createSmithers<Schemas extends Record<string, zod.ZodObject<any>>>(schemas: Schemas, opts?: CreateSmithersOptions): CreateSmithersApi$1<Schemas>;
-type CreateSmithersOptions = CreateSmithersOptions$1;
+type CreateSmithersPostgresOptions = CreateSmithersOptions & ({
+    provider?: "postgres";
+    connectionString?: string;
+    connection?: object;
+} | {
+    provider: "pglite";
+    dataDir?: string;
+});
+/**
+ * PostgreSQL/PGlite-backed equivalent of createSmithers.
+ */
+declare function createSmithersPostgres<Schemas extends Record<string, zod.ZodObject<any>>>(schemas: Schemas, opts?: CreateSmithersPostgresOptions): Promise<CreateSmithersApi$1<Schemas> & {
+    close: () => Promise<void>;
+}>;
 
 /**
  * Create a SmithersWorkflow from an external build function.
@@ -301,13 +319,20 @@ type ConnectRequest = _smithers_server_gateway.ConnectRequest;
 type ContinueAsNewProps = _smithers_components.ContinueAsNewProps;
 type CreateScorerConfig = _smithers_scorers.CreateScorerConfig;
 type CreateSmithersApi<Schema> = CreateSmithersApi$1<Schema>;
+type CreateSmithersOptions = CreateSmithersOptions$1;
 type DepsSpec = _smithers_components.DepsSpec;
 type EventFrame = _smithers_server_gateway.EventFrame;
 type ExternalSmithersConfig<S> = ExternalSmithersConfig$2<S>;
 type GatewayAuthConfig = _smithers_server_gateway.GatewayAuthConfig;
 type GatewayDefaults = _smithers_server_gateway.GatewayDefaults;
+type GatewayOperatorUiConfig = _smithers_server_gateway.GatewayOperatorUiConfig;
 type GatewayOptions = _smithers_server_gateway.GatewayOptions;
+type GatewayRegisterOptions = _smithers_server_gateway.GatewayRegisterOptions;
 type GatewayTokenGrant = _smithers_server_gateway.GatewayTokenGrant;
+type GatewayUiConfig = _smithers_server_gateway.GatewayUiConfig;
+type GatewayWebhookConfig = _smithers_server_gateway.GatewayWebhookConfig;
+type GatewayWebhookRunConfig = _smithers_server_gateway.GatewayWebhookRunConfig;
+type GatewayWebhookSignalConfig = _smithers_server_gateway.GatewayWebhookSignalConfig;
 type GraphSnapshot = _smithers_graph_GraphSnapshot.GraphSnapshot;
 type HelloResponse = _smithers_server_gateway.HelloResponse;
 type HostContainer = _smithers_react_reconciler_dom_renderer.HostContainer;
@@ -333,6 +358,7 @@ type MessageHistoryConfig = _smithers_memory.MessageHistoryConfig;
 type OpenAIAgentOptions<CALL_OPTIONS = never, TOOLS = ai.ToolSet> = _smithers_agents.OpenAIAgentOptions<CALL_OPTIONS, TOOLS>;
 type HermesAgentOptions<CALL_OPTIONS = never, TOOLS = ai.ToolSet> = _smithers_agents.HermesAgentOptions<CALL_OPTIONS, TOOLS>;
 type OpenCodeAgentOptions = _smithers_agents.OpenCodeAgentOptions;
+type VibeAgentOptions = _smithers_agents.VibeAgentOptions;
 type OpenApiAuth = _smithers_openapi.OpenApiAuth;
 type OpenApiSpec = _smithers_openapi.OpenApiSpec;
 type OpenApiToolsOptions = _smithers_openapi.OpenApiToolsOptions;
@@ -408,4 +434,4 @@ type XmlElement = _smithers_graph_XmlNode.XmlElement;
 type XmlNode = _smithers_graph_XmlNode.XmlNode;
 type XmlText = _smithers_graph_XmlNode.XmlText;
 
-export { type AgentCapabilityRegistry, type AgentLike, type AgentToolDescriptor, type AggregateOptions, type AggregateScore, type AnthropicAgentOptions, type ApprovalAutoApprove, type ApprovalDecision, type ApprovalMode, type ApprovalOption, type ApprovalProps, type ApprovalRanking, type ApprovalRequest, type ApprovalSelection, type ColumnDef, type ConnectRequest, type ContinueAsNewProps, type CreateScorerConfig, type CreateSmithersApi, type DepsSpec, type EventFrame, type ExternalSmithersConfig, type GatewayAuthConfig, type GatewayDefaults, type GatewayOptions, type GatewayTokenGrant, type GraphSnapshot, type HelloResponse, type HermesAgentOptions, type HostContainer, type HostNodeJson, type InferDeps, type InferOutputEntry, type InferRow, type JjRevertResult, type KanbanProps, type KnownSmithersErrorCode, type LlmJudgeConfig, type MemoryFact, type MemoryLayerConfig, type MemoryMessage, type MemoryNamespace, type MemoryNamespaceKind, type MemoryProcessor, type MemoryProcessorConfig, type MemoryServiceApi, type MemoryStore, type MemoryThread, type MessageHistoryConfig, type OpenAIAgentOptions, type OpenApiAuth, type OpenApiSpec, type OpenApiToolsOptions, type OpenCodeAgentOptions, type OutputAccessor, type OutputKey, type OutputTarget, type PiAgentOptions, type PiExtensionUiRequest, type PiExtensionUiResponse, type PollerProps, type RequestFrame, type ResolvedSmithersObservabilityOptions, type ResponseFrame, type RevertOptions, type RevertResult, type RunJjOptions, type RunJjResult, type RunOptions, type RunResult, type RunStatus, type SagaProps, type SagaStepDef, type SagaStepProps, type SamplingConfig, type SandboxProps, type SandboxRuntime, type SandboxVolumeMount, type SandboxWorkspaceSpec, type SchemaRegistryEntry, type ScoreResult, type ScoreRow, type Scorer, type ScorerBinding, type ScorerContext, type ScorerFn, type ScorerInput, type ScorersMap, type SemanticRecallConfig, type SerializedCtx, type ServeOptions, type ServerOptions, type SignalProps, type SmithersAlertLabels, type SmithersAlertPolicy, type SmithersAlertPolicyDefaults, type SmithersAlertPolicyRule, type SmithersAlertReaction, type SmithersAlertReactionKind, type SmithersAlertReactionRef, type SmithersAlertSeverity, type SmithersCtx, type SmithersError, type SmithersErrorCode, type SmithersEvent, type SmithersLogFormat, type SmithersObservabilityOptions, type SmithersObservabilityService, type SmithersWorkflow, type SmithersWorkflowOptions, type TaskDescriptor, type TaskMemoryConfig, type TaskProps, type TimeTravelOptions, type TimeTravelResult, type TimerProps, type TryCatchFinallyProps, type WaitForEventProps, type WorkingMemoryConfig, type WorkspaceAddOptions, type WorkspaceInfo, type WorkspaceResult, type XmlElement, type XmlNode, type XmlText, bash, createExternalSmithers, createSmithers, defineTool, edit, getDefinedToolMetadata, grep, mdxPlugin, read, tools, write };
+export { type AgentCapabilityRegistry, type AgentLike, type AgentToolDescriptor, type AggregateOptions, type AggregateScore, type AnthropicAgentOptions, type ApprovalAutoApprove, type ApprovalDecision, type ApprovalMode, type ApprovalOption, type ApprovalProps, type ApprovalRanking, type ApprovalRequest, type ApprovalSelection, type ColumnDef, type ConnectRequest, type ContinueAsNewProps, type CreateScorerConfig, type CreateSmithersApi, type CreateSmithersOptions, type DepsSpec, type EventFrame, type ExternalSmithersConfig, type GatewayAuthConfig, type GatewayDefaults, type GatewayOperatorUiConfig, type GatewayOptions, type GatewayRegisterOptions, type GatewayTokenGrant, type GatewayUiConfig, type GatewayWebhookConfig, type GatewayWebhookRunConfig, type GatewayWebhookSignalConfig, type GraphSnapshot, type HelloResponse, type HermesAgentOptions, type HostContainer, type HostNodeJson, type InferDeps, type InferOutputEntry, type InferRow, type JjRevertResult, type KanbanProps, type KnownSmithersErrorCode, type LlmJudgeConfig, type MemoryFact, type MemoryLayerConfig, type MemoryMessage, type MemoryNamespace, type MemoryNamespaceKind, type MemoryProcessor, type MemoryProcessorConfig, type MemoryServiceApi, type MemoryStore, type MemoryThread, type MessageHistoryConfig, type OpenAIAgentOptions, type OpenApiAuth, type OpenApiSpec, type OpenApiToolsOptions, type OpenCodeAgentOptions, type OutputAccessor, type OutputKey, type OutputTarget, type PiAgentOptions, type PiExtensionUiRequest, type PiExtensionUiResponse, type PollerProps, type RequestFrame, type ResolvedSmithersObservabilityOptions, type ResponseFrame, type RevertOptions, type RevertResult, type RunJjOptions, type RunJjResult, type RunOptions, type RunResult, type RunStatus, type SagaProps, type SagaStepDef, type SagaStepProps, type SamplingConfig, type SandboxProps, type SandboxRuntime, type SandboxVolumeMount, type SandboxWorkspaceSpec, type SchemaRegistryEntry, type ScoreResult, type ScoreRow, type Scorer, type ScorerBinding, type ScorerContext, type ScorerFn, type ScorerInput, type ScorersMap, type SemanticRecallConfig, type SerializedCtx, type ServeOptions, type ServerOptions, type SignalProps, type SmithersAlertLabels, type SmithersAlertPolicy, type SmithersAlertPolicyDefaults, type SmithersAlertPolicyRule, type SmithersAlertReaction, type SmithersAlertReactionKind, type SmithersAlertReactionRef, type SmithersAlertSeverity, type SmithersCtx, type SmithersError, type SmithersErrorCode, type SmithersEvent, type SmithersLogFormat, type SmithersObservabilityOptions, type SmithersObservabilityService, type SmithersWorkflow, type SmithersWorkflowOptions, type TaskDescriptor, type TaskMemoryConfig, type TaskProps, type TimeTravelOptions, type TimeTravelResult, type TimerProps, type TryCatchFinallyProps, type VibeAgentOptions, type WaitForEventProps, type WorkingMemoryConfig, type WorkspaceAddOptions, type WorkspaceInfo, type WorkspaceResult, type XmlElement, type XmlNode, type XmlText, bash, createExternalSmithers, createSmithers, createSmithersPostgres, defineTool, edit, getDefinedToolMetadata, grep, mdxPlugin, read, tools, write };

package/src/index.js

@@ -25,6 +25,7 @@
  * @template Schema
  * @typedef {import("./CreateSmithersApi.ts").CreateSmithersApi<Schema>} CreateSmithersApi
  */
+/** @typedef {import("./CreateSmithersOptions.ts").CreateSmithersOptions} CreateSmithersOptions */
 /** @typedef {import("@smithers-orchestrator/components").DepsSpec} DepsSpec */
 /** @typedef {import("@smithers-orchestrator/server/gateway").EventFrame} EventFrame */
 /**
@@ -33,8 +34,14 @@
  */
 /** @typedef {import("@smithers-orchestrator/server/gateway").GatewayAuthConfig} GatewayAuthConfig */
 /** @typedef {import("@smithers-orchestrator/server/gateway").GatewayDefaults} GatewayDefaults */
+/** @typedef {import("@smithers-orchestrator/server/gateway").GatewayOperatorUiConfig} GatewayOperatorUiConfig */
 /** @typedef {import("@smithers-orchestrator/server/gateway").GatewayOptions} GatewayOptions */
+/** @typedef {import("@smithers-orchestrator/server/gateway").GatewayRegisterOptions} GatewayRegisterOptions */
 /** @typedef {import("@smithers-orchestrator/server/gateway").GatewayTokenGrant} GatewayTokenGrant */
+/** @typedef {import("@smithers-orchestrator/server/gateway").GatewayUiConfig} GatewayUiConfig */
+/** @typedef {import("@smithers-orchestrator/server/gateway").GatewayWebhookConfig} GatewayWebhookConfig */
+/** @typedef {import("@smithers-orchestrator/server/gateway").GatewayWebhookRunConfig} GatewayWebhookRunConfig */
+/** @typedef {import("@smithers-orchestrator/server/gateway").GatewayWebhookSignalConfig} GatewayWebhookSignalConfig */
 /** @typedef {import("@smithers-orchestrator/graph/GraphSnapshot").GraphSnapshot} GraphSnapshot */
 /** @typedef {import("@smithers-orchestrator/server/gateway").HelloResponse} HelloResponse */
 /** @typedef {import("@smithers-orchestrator/react-reconciler/dom/renderer").HostContainer} HostContainer */
@@ -86,6 +93,7 @@
 /** @typedef {import("@smithers-orchestrator/agents").PiExtensionUiRequest} PiExtensionUiRequest */
 /** @typedef {import("@smithers-orchestrator/agents").PiExtensionUiResponse} PiExtensionUiResponse */
 /** @typedef {import("@smithers-orchestrator/agents").OpenCodeAgentOptions} OpenCodeAgentOptions */
+/** @typedef {import("@smithers-orchestrator/agents").VibeAgentOptions} VibeAgentOptions */
 /** @typedef {import("@smithers-orchestrator/components").PollerProps} PollerProps */
 /** @typedef {import("@smithers-orchestrator/server/gateway").RequestFrame} RequestFrame */
 /** @typedef {import("@smithers-orchestrator/observability").ResolvedSmithersObservabilityOptions} ResolvedSmithersObservabilityOptions */
@@ -171,18 +179,23 @@ export { knownSmithersErrorCodes } from "@smithers-orchestrator/errors/knownSmit
 // Components
 export { Approval, ApprovalGate, Aspects, Branch, CheckSuite, ClassifyAndRoute, ContentPipeline, ContinueAsNew, Debate, DecisionTable, DriftDetector, EscalationChain, GatherAndSynthesize, HumanTask, Kanban, Loop, MergeQueue, Optimizer, Panel, Parallel, Poller, Ralph, ReviewLoop, Runbook, Saga, Sandbox, ScanFixVerify, Sequence, Signal, Subflow, SuperSmithers, Supervisor, Task, Timer, TryCatchFinally, WaitForEvent, Workflow, Worktree, approvalDecisionSchema, approvalRankingSchema, approvalSelectionSchema, continueAsNew, } from "@smithers-orchestrator/components";
 // Agents
-export { AnthropicAgent, OpenAIAgent, HermesAgent, AmpAgent, AntigravityAgent, ClaudeCodeAgent, CodexAgent, GeminiAgent, PiAgent, KimiAgent, ForgeAgent, OpenCodeAgent, } from "@smithers-orchestrator/agents";
+export { AnthropicAgent, OpenAIAgent, HermesAgent, AmpAgent, AntigravityAgent, ClaudeCodeAgent, CodexAgent, GeminiAgent, PiAgent, KimiAgent, ForgeAgent, VibeAgent, OpenCodeAgent, } from "@smithers-orchestrator/agents";
 // VCS
 export { runJj, getJjPointer, revertToJjPointer, isJjRepo, workspaceAdd, workspaceList, workspaceClose, } from "@smithers-orchestrator/vcs/jj";
 // Core API
-export { createSmithers } from "./create.js";
+export { createSmithers, createSmithersPostgres } from "./create.js";
 export {
+  approveNode,
+  denyNode,
   fragment,
+  getRun,
+  listRuns,
   renderFrame,
   runWorkflow,
   Smithers,
   workflow,
 } from "@smithers-orchestrator/engine";
+export { resolveWorktreePath } from "@smithers-orchestrator/graph";
 export { signalRun } from "@smithers-orchestrator/engine/signals";
 export { usePatched } from "@smithers-orchestrator/engine/effect/versioning";
 // Tools
@@ -204,7 +217,8 @@ export { createServeApp } from "@smithers-orchestrator/server/serve";
 // Observability
 export { SmithersObservability, createSmithersObservabilityLayer, createSmithersOtelLayer, createSmithersRuntimeLayer, smithersMetrics, trackSmithersEvent, activeNodes, activeRuns, externalWaitAsyncPending, approvalsDenied, approvalsGranted, approvalsRequested, timerDelayDuration, timersCancelled, timersCreated, timersFired, timersPending, attemptDuration, cacheHits, cacheMisses, dbQueryDuration, dbRetries, dbTransactionDuration, dbTransactionRetries, dbTransactionRollbacks, hotReloadDuration, hotReloadFailures, hotReloads, httpRequestDuration, httpRequests, nodeDuration, nodesFailed, nodesFinished, nodesStarted, prometheusContentType, renderPrometheusMetrics, resolveSmithersObservabilityOptions, runsTotal, sandboxActive, sandboxBundleSizeBytes, sandboxCompletedTotal, sandboxCreatedTotal, sandboxDurationMs, sandboxPatchCount, sandboxTransportDurationMs, schedulerQueueDepth, toolCallsTotal, toolDuration, vcsDuration, } from "@smithers-orchestrator/observability";
 // DB
-export { SmithersDb } from "@smithers-orchestrator/db/adapter";
+export { SmithersDb } from "@smithers-orchestrator/db";
+export { loadOutputs, loadOutputsEffect } from "@smithers-orchestrator/db";
 export { ensureSmithersTables } from "@smithers-orchestrator/db/ensure";
 // Renderer
 export { SmithersRenderer } from "@smithers-orchestrator/react-reconciler/dom/renderer";

package/src/jsx-runtime.d.ts

@@ -0,0 +1,25 @@
+import type { ReactElement } from "react";
+
+/** Element key accepted by the JSX runtime factories. */
+export type JsxRuntimeKey = string | number | undefined;
+
+/**
+ * Smithers JSX runtime factories — the target of
+ * `jsxImportSource: "smithers-orchestrator"` and what `<Workflow/>`, `<Task/>`,
+ * etc. compile to. They are deliberately typed wide (`type`/`props` as
+ * `unknown`): components validate their own props, and keeping these signatures
+ * loose avoids expanding Smithers' deep workflow types during type-checking,
+ * which is otherwise expensive. Callers that build trees programmatically can
+ * use these directly, e.g. `jsx(Task, { id, output, agent, children }, key)`.
+ */
+export function jsx(type: unknown, props: unknown, key?: JsxRuntimeKey): ReactElement;
+export function jsxs(type: unknown, props: unknown, key?: JsxRuntimeKey): ReactElement;
+export function jsxDEV(
+  type: unknown,
+  props: unknown,
+  key?: JsxRuntimeKey,
+  isStaticChildren?: boolean,
+  source?: unknown,
+  self?: unknown,
+): ReactElement;
+export const Fragment: unknown;

package/src/tools/bash.js

@@ -175,7 +175,7 @@ export async function bashTool(cmd, args = [], opts = undefined) {
 
 export const bash = defineTool({
   name: "bash",
-  description: "Execute a shell command",
+  description: "Run an executable with arguments",
   schema: z.object({
     cmd: z.string(),
     args: z.array(z.string()).optional(),

package/src/tools/context.js

@@ -1,29 +1,10 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-
-const storage = new AsyncLocalStorage();
-
-export function runWithToolContext(ctx, fn) {
-  return storage.run(ctx, fn);
-}
-
-export function getToolContext() {
-  return storage.getStore();
-}
-
-export function getToolIdempotencyKey(ctx = getToolContext()) {
-  if (!ctx) {
-    return null;
-  }
-  if (typeof ctx.idempotencyKey === "string" && ctx.idempotencyKey.length > 0) {
-    return ctx.idempotencyKey;
-  }
-  if (!ctx.runId || !ctx.nodeId) {
-    return null;
-  }
-  return `smithers:${ctx.runId}:${ctx.nodeId}:${ctx.iteration ?? 0}`;
-}
-
-export function nextToolSeq(ctx) {
-  ctx.seq = (ctx.seq ?? 0) + 1;
-  return ctx.seq;
-}
+// The tool-execution context now lives in its own low-level package so both the
+// engine and smithers can depend on it without a cycle (the engine needs
+// runWithToolContext to give in-process agent tools their run context). This file
+// stays as a re-export so existing relative importers keep working.
+export {
+  runWithToolContext,
+  getToolContext,
+  getToolIdempotencyKey,
+  nextToolSeq,
+} from "@smithers-orchestrator/tool-context";

package/src/tools/defineTool.js

@@ -26,6 +26,8 @@ function defaultToolContext() {
     maxOutputBytes: 200_000,
     timeoutMs: 60_000,
     seq: 0,
+    // No-op unless the engine populated a real durability handle (flag on).
+    durabilitySnapshot: async () => ({ skipped: true }),
   };
 }
 
@@ -48,14 +50,28 @@ export function defineTool(options) {
     inputSchema: zodSchema(options.schema),
     execute: async (args) => {
       const toolContext = getToolContext();
+      // Merge the ambient context OVER the defaults, so a partial context from the
+      // engine (run/node/cwd + durabilitySnapshot) overrides what it sets and keeps
+      // sane defaults for the rest.
       const definedContext = {
-        ...(toolContext ?? defaultToolContext()),
+        ...defaultToolContext(),
+        ...(toolContext ?? {}),
         idempotencyKey: getToolIdempotencyKey(toolContext),
         toolName: options.name,
         sideEffect,
         idempotent,
       };
-      return options.execute(args, definedContext);
+      const result = await options.execute(args, definedContext);
+      // Strict Tier 1 snapshot at this tool boundary, before the agent proceeds.
+      // No-op by default; never delays past one jj snapshot and never fails the tool.
+      if (sideEffect && typeof definedContext.durabilitySnapshot === "function") {
+        try {
+          await definedContext.durabilitySnapshot(options.name, definedContext.toolUseId);
+        } catch {
+          /* snapshot failures never fail the tool */
+        }
+      }
+      return result;
     },
   });