smithers-orchestrator 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithers-orchestrator",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Public Smithers facade for durable coding-agent workflows and Gateway operation",
   "type": "module",
   "sideEffects": false,
@@ -61,27 +61,33 @@
     "incur": "^0.4.1",
     "react": "^19.2.5",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/components": "0.21.0",
-    "@smithers-orchestrator/agents": "0.21.0",
-    "@smithers-orchestrator/cli": "0.21.0",
-    "@smithers-orchestrator/db": "0.21.0",
-    "@smithers-orchestrator/control-plane": "0.21.0",
-    "@smithers-orchestrator/driver": "0.21.0",
-    "@smithers-orchestrator/engine": "0.21.0",
-    "@smithers-orchestrator/errors": "0.21.0",
-    "@smithers-orchestrator/gateway-client": "0.21.0",
-    "@smithers-orchestrator/gateway-react": "0.21.0",
-    "@smithers-orchestrator/graph": "0.21.0",
-    "@smithers-orchestrator/memory": "0.21.0",
-    "@smithers-orchestrator/openapi": "0.21.0",
-    "@smithers-orchestrator/observability": "0.21.0",
-    "@smithers-orchestrator/sandbox": "0.21.0",
-    "@smithers-orchestrator/react-reconciler": "0.21.0",
-    "@smithers-orchestrator/scheduler": "0.21.0",
-    "@smithers-orchestrator/scorers": "0.21.0",
-    "@smithers-orchestrator/server": "0.21.0",
-    "@smithers-orchestrator/time-travel": "0.21.0",
-    "@smithers-orchestrator/vcs": "0.21.0"
+    "@smithers-orchestrator/components": "0.23.0",
+    "@smithers-orchestrator/cli": "0.23.0",
+    "@smithers-orchestrator/db": "0.23.0",
+    "@smithers-orchestrator/control-plane": "0.23.0",
+    "@smithers-orchestrator/driver": "0.23.0",
+    "@smithers-orchestrator/engine": "0.23.0",
+    "@smithers-orchestrator/errors": "0.23.0",
+    "@smithers-orchestrator/gateway-react": "0.23.0",
+    "@smithers-orchestrator/memory": "0.23.0",
+    "@smithers-orchestrator/graph": "0.23.0",
+    "@smithers-orchestrator/openapi": "0.23.0",
+    "@smithers-orchestrator/observability": "0.23.0",
+    "@smithers-orchestrator/react-reconciler": "0.23.0",
+    "@smithers-orchestrator/sandbox": "0.23.0",
+    "@smithers-orchestrator/scheduler": "0.23.0",
+    "@smithers-orchestrator/scorers": "0.23.0",
+    "@smithers-orchestrator/server": "0.23.0",
+    "@smithers-orchestrator/time-travel": "0.23.0",
+    "@smithers-orchestrator/tool-context": "0.23.0",
+    "@smithers-orchestrator/gateway-client": "0.23.0",
+    "@smithers-orchestrator/agents": "0.23.0",
+    "@smithers-orchestrator/vcs": "0.23.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,6 +14,8 @@ 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 { SmithersDb } from "@smithers-orchestrator/db/adapter";
+import { POSTGRES } from "@smithers-orchestrator/db/dialect";
 import { resolve } from "node:path";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 /** @typedef {import("@smithers-orchestrator/components").ApprovalProps<any, any>} ApprovalProps */
@@ -173,43 +175,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,76 +196,38 @@ 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.on("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;
+ * }} config
+ */
+function buildSmithersApi(config) {
+    const { db, tables, schemaRegistry, outputs, zodToKeyName, ambiguousZodSchemas, opts } = config;
+    const { SmithersContext: RuntimeSmithersContext, useCtx } = createSmithersContext();
     const ctxRef = { current: null };
     let moduleAlertPolicy = opts?.alertPolicy;
     /**
@@ -351,9 +286,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 = {
@@ -401,9 +335,116 @@ 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) {
+    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 + 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,
+    });
     if (process.env.SMITHERS_HOT === "1") {
         const sig = computeSchemaSig(schemas, absDbPath);
         hotCache.set(absDbPath, {
@@ -414,3 +455,116 @@ 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,
+        });
+    }
+    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/external/create-external-smithers.js

@@ -127,8 +127,9 @@ export function createExternalSmithers(config) {
             sqlite.close();
         }
         catch { }
+        process.removeListener("exit", closeDb);
     };
-    process.on("exit", closeDb);
+    process.once("exit", closeDb);
     const inputTable = sqliteTable("input", {
         runId: text("run_id").primaryKey(),
         payload: text("payload", { mode: "json" }).$type(),

package/src/index.d.ts

@@ -56,7 +56,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, KimiAgent, OpenAIAgent, OpenCodeAgent, PiAgent } from '@smithers-orchestrator/agents';
+export { AmpAgent, AnthropicAgent, AntigravityAgent, ClaudeCodeAgent, CodexAgent, ForgeAgent, GeminiAgent, HermesAgent, KimiAgent, OpenAIAgent, OpenCodeAgent, PiAgent } 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';
@@ -331,6 +331,7 @@ type MemoryStore = _smithers_memory.MemoryStore;
 type MemoryThread = _smithers_memory.MemoryThread;
 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 OpenApiAuth = _smithers_openapi.OpenApiAuth;
 type OpenApiSpec = _smithers_openapi.OpenApiSpec;
@@ -407,4 +408,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 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 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 };

package/src/index.js

@@ -68,6 +68,11 @@
  * @template [TOOLS=import("ai").ToolSet]
  * @typedef {import("@smithers-orchestrator/agents").OpenAIAgentOptions<CALL_OPTIONS, TOOLS>} OpenAIAgentOptions
  */
+/**
+ * @template [CALL_OPTIONS=never]
+ * @template [TOOLS=import("ai").ToolSet]
+ * @typedef {import("@smithers-orchestrator/agents").HermesAgentOptions<CALL_OPTIONS, TOOLS>} HermesAgentOptions
+ */
 /** @typedef {import("@smithers-orchestrator/openapi").OpenApiAuth} OpenApiAuth */
 /** @typedef {import("@smithers-orchestrator/openapi").OpenApiSpec} OpenApiSpec */
 /** @typedef {import("@smithers-orchestrator/openapi").OpenApiToolsOptions} OpenApiToolsOptions */
@@ -166,11 +171,11 @@ 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, 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, 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 {
   fragment,
   renderFrame,

package/src/tools/bash.js

@@ -100,29 +100,36 @@ function validateBashInvocation(cmd, args, opts, ctx) {
   }
 }
 
+function tokenExecutableName(token) {
+  const stripped = token.split(/[/\\]/).pop() ?? token;
+  return stripped;
+}
+
 function assertNetworkAllowed(cmd, args, allowNetwork) {
   if (allowNetwork) {
     return;
   }
-  const hay = [cmd, ...(args ?? [])].join(" ");
-  const networkCommands = [
-    "curl",
-    "wget",
-    "http://",
-    "https://",
-    "npm",
-    "bun",
-    "pip",
-  ];
-  if (networkCommands.some((fragment) => hay.includes(fragment))) {
+  const tokens = [cmd, ...(args ?? [])].flatMap((part) =>
+    String(part).split(/\s+/).filter(Boolean),
+  );
+  const executables = new Set(tokens.map(tokenExecutableName));
+  const networkExecutables = ["curl", "wget", "npm", "bun", "pip"];
+  const hasNetworkExecutable = networkExecutables.some((name) =>
+    executables.has(name),
+  );
+  const urlSchemes = ["http://", "https://"];
+  const hasUrlToken = tokens.some((token) =>
+    urlSchemes.some((scheme) => token.startsWith(scheme)),
+  );
+  if (hasNetworkExecutable || hasUrlToken) {
     throw new SmithersError(
       "TOOL_NETWORK_DISABLED",
       "Network access is disabled for bash tool",
     );
   }
-  if (hay.includes("git")) {
-    const gitRemoteOps = ["push", "pull", "fetch", "clone", "remote"];
-    if (gitRemoteOps.some((op) => hay.includes(op))) {
+  if (executables.has("git")) {
+    const gitRemoteOps = new Set(["push", "pull", "fetch", "clone", "remote"]);
+    if (tokens.some((token) => gitRemoteOps.has(token))) {
       throw new SmithersError(
         "TOOL_GIT_REMOTE_DISABLED",
         "Git remote operations are disabled for bash tool",

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;
     },
   });
 

package/src/tools/utils.js

@@ -27,12 +27,25 @@ export function sha256Hex(value) {
   return createHash("sha256").update(value).digest("hex");
 }
 
+function utf8BoundaryLength(buf, byteLength) {
+  let end = Math.min(byteLength, buf.length);
+  if (end >= buf.length) {
+    return buf.length;
+  }
+  // If the cut lands on a continuation byte, back up to the lead byte of the
+  // partial sequence so we never decode an incomplete codepoint.
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) {
+    end -= 1;
+  }
+  return end;
+}
+
 export function truncateToBytes(text, maxBytes) {
   const buf = Buffer.from(text, "utf8");
   if (buf.length <= maxBytes) {
     return text;
   }
-  return buf.subarray(0, maxBytes).toString("utf8");
+  return buf.subarray(0, utf8BoundaryLength(buf, maxBytes)).toString("utf8");
 }
 
 export async function resolveToolPath(rootDir, inputPath) {
@@ -72,8 +85,11 @@ function appendLimited(chunks, state, chunk, maxBytes) {
     state.storedBytes += buffer.length;
     return;
   }
-  chunks.push(buffer.subarray(0, remaining));
-  state.storedBytes += remaining;
+  const accepted = utf8BoundaryLength(buffer, remaining);
+  if (accepted > 0) {
+    chunks.push(buffer.subarray(0, accepted));
+    state.storedBytes += accepted;
+  }
   state.truncated = true;
 }
 
@@ -91,7 +107,12 @@ export function captureProcess(
   return new Promise((resolve, reject) => {
     const stdoutChunks = [];
     const stderrChunks = [];
-    const state = {
+    const stdoutState = {
+      storedBytes: 0,
+      totalBytes: 0,
+      truncated: false,
+    };
+    const stderrState = {
       storedBytes: 0,
       totalBytes: 0,
       truncated: false,
@@ -149,10 +170,10 @@ export function captureProcess(
     }
 
     child.stdout.on("data", (chunk) => {
-      appendLimited(stdoutChunks, state, chunk, maxOutputBytes);
+      appendLimited(stdoutChunks, stdoutState, chunk, maxOutputBytes);
     });
     child.stderr.on("data", (chunk) => {
-      appendLimited(stderrChunks, state, chunk, maxOutputBytes);
+      appendLimited(stderrChunks, stderrState, chunk, maxOutputBytes);
     });
     child.on("error", (error) => {
       finish(() =>
@@ -167,7 +188,7 @@ export function captureProcess(
     });
     child.on("close", (exitCode, signal) => {
       finish(() => {
-        resolve({ exitCode: exitCode ?? (signal ? 1 : 0), signal, stdout: Buffer.concat(stdoutChunks).toString("utf8"), stderr: Buffer.concat(stderrChunks).toString("utf8"), truncated: state.truncated, totalBytes: state.totalBytes });
+        resolve({ exitCode: exitCode ?? (signal ? 1 : 0), signal, stdout: Buffer.concat(stdoutChunks).toString("utf8"), stderr: Buffer.concat(stderrChunks).toString("utf8"), truncated: stdoutState.truncated || stderrState.truncated, totalBytes: stdoutState.totalBytes + stderrState.totalBytes });
       });
     });
   });