@smithers-orchestrator/driver 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@smithers-orchestrator/driver",
+  "version": "0.16.0",
+  "description": "Workflow execution driver — runs tasks, acts on EngineDecisions, reports results",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./interop": {
+      "types": "./src/index.d.ts",
+      "import": "./src/interop.js",
+      "default": "./src/interop.js"
+    },
+    "./RunOptions": {
+      "types": "./src/index.d.ts"
+    },
+    "./RunResult": {
+      "types": "./src/index.d.ts"
+    },
+    "./RunStatus": {
+      "types": "./src/index.d.ts"
+    },
+    "./RunAuthContext": {
+      "types": "./src/index.d.ts"
+    },
+    "./SmithersCtx": {
+      "types": "./src/index.d.ts",
+      "import": "./src/SmithersCtx.js",
+      "default": "./src/SmithersCtx.js"
+    },
+    "./OutputAccessor": {
+      "types": "./src/index.d.ts"
+    },
+    "./OutputKey": {
+      "types": "./src/index.d.ts"
+    },
+    "./workflow-types": {
+      "types": "./src/index.d.ts"
+    },
+    "./task-runtime": {
+      "types": "./src/index.d.ts",
+      "import": "./src/task-runtime.js",
+      "default": "./src/task-runtime.js"
+    },
+    "./child-process": {
+      "types": "./src/index.d.ts",
+      "import": "./src/child-process.js",
+      "default": "./src/child-process.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "effect": "^3.21.0",
+    "zod": "^4.3.6",
+    "@smithers-orchestrator/db": "0.16.0",
+    "@smithers-orchestrator/graph": "0.16.0",
+    "@smithers-orchestrator/errors": "0.16.0",
+    "@smithers-orchestrator/scheduler": "0.16.0",
+    "@smithers-orchestrator/observability": "0.16.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsup --dts-only"
+  }
+}

package/src/ContinueAsNewHandler.ts

@@ -0,0 +1,7 @@
+import type { RunOptions } from "./RunOptions.ts";
+import type { RunResult } from "./RunResult.ts";
+
+export type ContinueAsNewHandler = (
+  transition: unknown,
+  context: { runId: string; options: RunOptions },
+) => Promise<RunResult> | RunResult;

package/src/CreateWorkflowSession.ts

@@ -0,0 +1,5 @@
+import type { CreateWorkflowSessionOptions } from "./CreateWorkflowSessionOptions.ts";
+
+export type CreateWorkflowSession = (
+  opts: CreateWorkflowSessionOptions,
+) => unknown;

package/src/CreateWorkflowSessionOptions.ts

@@ -0,0 +1,9 @@
+import type { RunOptions } from "./RunOptions.ts";
+
+export type CreateWorkflowSessionOptions = {
+  db?: unknown;
+  runId: string;
+  rootDir?: string;
+  workflowPath?: string | null;
+  options: RunOptions;
+};

package/src/OutputAccessor.ts

@@ -0,0 +1,20 @@
+import type { z } from "zod";
+
+export type InferRow<TTable> = TTable extends { $inferSelect: infer R } ? R : never;
+
+export type InferOutputEntry<T> = T extends z.ZodTypeAny
+  ? z.infer<T>
+  : T extends { $inferSelect: unknown }
+    ? InferRow<T>
+    : never;
+
+type FallbackTableName<Schema> = [keyof Schema & string] extends [never]
+  ? string
+  : never;
+
+export type OutputAccessor<Schema, TRow = unknown> = {
+  (table: FallbackTableName<Schema>): Array<TRow>;
+  <K extends keyof Schema & string>(table: K): Array<InferOutputEntry<Schema[K]>>;
+} & {
+  [K in keyof Schema & string]: Array<InferOutputEntry<Schema[K]>>;
+};

package/src/OutputKey.ts

@@ -0,0 +1 @@
+export type OutputKey = { nodeId: string; iteration?: number };

package/src/OutputSnapshot.ts

@@ -0,0 +1,3 @@
+export type OutputSnapshot<TFallback = unknown> = {
+  [tableName: string]: Array<TFallback>;
+};

package/src/RunAuthContext.ts

@@ -0,0 +1,6 @@
+export type RunAuthContext = {
+  triggeredBy: string;
+  scopes: string[];
+  role: string;
+  createdAt: string;
+};

package/src/RunOptions.ts

@@ -0,0 +1,42 @@
+import type { RunAuthContext } from "./RunAuthContext.ts";
+import type { SmithersEvent } from "@smithers-orchestrator/observability/SmithersEvent";
+
+export type HotReloadOptions = {
+  /** Root directory to watch for changes (default: auto-detect from workflow entry) */
+  rootDir?: string;
+  /** Directory for generation overlays (default: .smithers/hmr/<runId>) */
+  outDir?: string;
+  /** Max overlay generations to keep (default: 3) */
+  maxGenerations?: number;
+  /** Whether to cancel tasks that become unmounted after hot reload (default: false) */
+  cancelUnmounted?: boolean;
+  /** Debounce interval in ms for file change events (default: 100) */
+  debounceMs?: number;
+};
+
+export type RunOptions = {
+  runId?: string;
+  parentRunId?: string | null;
+  input: Record<string, unknown>;
+  maxConcurrency?: number;
+  onProgress?: (e: SmithersEvent) => void;
+  signal?: AbortSignal;
+  resume?: boolean;
+  force?: boolean;
+  workflowPath?: string;
+  rootDir?: string;
+  logDir?: string | null;
+  allowNetwork?: boolean;
+  maxOutputBytes?: number;
+  toolTimeoutMs?: number;
+  hot?: boolean | HotReloadOptions;
+  auth?: RunAuthContext | null;
+  config?: Record<string, unknown>;
+  cliAgentToolsDefault?: "all" | "explicit-only";
+  resumeClaim?: {
+    claimOwnerId: string;
+    claimHeartbeatAtMs: number;
+    restoreRuntimeOwnerId?: string | null;
+    restoreHeartbeatAtMs?: number | null;
+  };
+};

package/src/RunResult.ts

@@ -0,0 +1,9 @@
+import type { RunStatus } from "./RunStatus.ts";
+
+export type RunResult = {
+  readonly runId: string;
+  readonly status: RunStatus;
+  readonly output?: unknown;
+  readonly error?: unknown;
+  readonly nextRunId?: string;
+};

package/src/RunStatus.ts

@@ -0,0 +1,9 @@
+export type RunStatus =
+  | "running"
+  | "waiting-approval"
+  | "waiting-event"
+  | "waiting-timer"
+  | "finished"
+  | "continued"
+  | "failed"
+  | "cancelled";

package/src/SafeParser.ts

@@ -0,0 +1,5 @@
+export type SafeParser = {
+  safeParse(value: unknown):
+    | { success: true; data: unknown }
+    | { success: false; error?: unknown };
+};

package/src/SchedulerWaitHandler.ts

@@ -0,0 +1,6 @@
+import type { TaskDescriptor } from "@smithers-orchestrator/graph/types";
+
+export type SchedulerWaitHandler = (
+  durationMs: number,
+  context: { runId: string; tasks: readonly TaskDescriptor[] },
+) => Promise<void> | void;

package/src/SmithersCtx.js

@@ -0,0 +1,195 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { buildCurrentScopes } from "./buildCurrentScopes.js";
+import { filterRowsByNodeId } from "./filterRowsByNodeId.js";
+import { normalizeInputRow } from "./normalizeInputRow.js";
+import { withLogicalIterationShortcuts } from "./withLogicalIterationShortcuts.js";
+/** @typedef {import("./OutputKey.ts").OutputKey} OutputKey */
+/** @typedef {import("./SafeParser.ts").SafeParser} SafeParser */
+/** @typedef {import("./SmithersCtxOptions.ts").SmithersCtxOptions} SmithersCtxOptions */
+/** @typedef {import("./RunAuthContext.ts").RunAuthContext} RunAuthContext */
+/** @typedef {import("./SmithersRuntimeConfig.ts").SmithersRuntimeConfig} SmithersRuntimeConfig */
+/** @typedef {unknown} TableRef */
+/** @typedef {Record<string, unknown> & { iteration?: number; nodeId?: string }} OutputRow */
+/**
+ * @template Schema
+ * @typedef {import("./OutputAccessor.ts").OutputAccessor<Schema>} OutputAccessor
+ */
+
+/**
+ * @param {TableRef} table
+ * @returns {string | undefined}
+ */
+function resolveDrizzleName(table) {
+    if (!table || typeof table !== "object")
+        return undefined;
+    const tableObj = /** @type {Record<string, unknown>} */ (table);
+    const tableMeta = tableObj._;
+    if (tableMeta &&
+        typeof tableMeta === "object" &&
+        typeof (/** @type {Record<string, unknown>} */ (tableMeta)).name === "string") {
+        return /** @type {string} */ ((/** @type {Record<string, unknown>} */ (tableMeta)).name);
+    }
+    if (typeof tableObj.name === "string")
+        return /** @type {string} */ (tableObj.name);
+    return undefined;
+}
+
+/**
+ * @template {unknown} [Schema=unknown]
+ */
+export class SmithersCtx {
+    /** @type {string} */
+    runId;
+    /** @type {number} */
+    iteration;
+    /** @type {Record<string, number> | undefined} */
+    iterations;
+    /** @type {Schema extends { input: infer T } ? T : unknown} */
+    input;
+    /** @type {RunAuthContext | null} */
+    auth;
+    /** @type {SmithersRuntimeConfig | null | undefined} */
+    __smithersRuntime;
+    /** @type {OutputAccessor<Schema>} */
+    outputs;
+    /** @type {import("./OutputSnapshot.ts").OutputSnapshot} */
+    _outputs;
+    /** @type {Map<unknown, string> | undefined} */
+    _zodToKeyName;
+    /** @type {Set<string>} */
+    _currentScopes;
+    /**
+     * @param {SmithersCtxOptions} opts
+     */
+    constructor(opts) {
+        this.runId = opts.runId;
+        this.iteration = opts.iteration;
+        this.iterations = withLogicalIterationShortcuts(opts.iterations);
+        this.input = /** @type {Schema extends { input: infer T } ? T : unknown} */ (normalizeInputRow(opts.input));
+        this.auth = opts.auth ?? null;
+        this.__smithersRuntime = opts.runtimeConfig ?? null;
+        this._outputs = opts.outputs;
+        this._zodToKeyName = opts.zodToKeyName;
+        this._currentScopes = buildCurrentScopes(this.iterations);
+        /**
+         * @param {string} table
+         */
+        const outputsFn = (table) => opts.outputs[table] ?? [];
+        for (const [name, rows] of Object.entries(opts.outputs)) {
+            outputsFn[name] = rows;
+        }
+        this.outputs = /** @type {OutputAccessor<Schema>} */ (/** @type {unknown} */ (outputsFn));
+    }
+    /**
+     * @param {TableRef} table
+     * @param {OutputKey} key
+     * @returns {OutputRow}
+     */
+    output(table, key) {
+        const row = this.resolveRow(table, key);
+        if (!row) {
+            throw new SmithersError("MISSING_OUTPUT", `Missing output for nodeId=${key.nodeId} iteration=${key.iteration ?? 0}`, { nodeId: key.nodeId, iteration: key.iteration ?? 0 });
+        }
+        return row;
+    }
+    /**
+     * @param {TableRef} table
+     * @param {OutputKey} key
+     * @returns {OutputRow | undefined}
+     */
+    outputMaybe(table, key) {
+        return this.resolveRow(table, key);
+    }
+    /**
+     * @param {TableRef} table
+     * @param {string} nodeId
+     * @returns {OutputRow | undefined}
+     */
+    latest(table, nodeId) {
+        const tableName = this.resolveTableName(table);
+        const rows = this._outputs[tableName] ?? [];
+        const matching = filterRowsByNodeId(rows, nodeId, this._currentScopes);
+        /** @type {OutputRow | undefined} */
+        let best = undefined;
+        let bestIteration = -Infinity;
+        for (const row of matching) {
+            const iter = Number.isFinite(Number(row.iteration))
+                ? Number(row.iteration)
+                : 0;
+            if (!best || iter >= bestIteration) {
+                best = row;
+                bestIteration = iter;
+            }
+        }
+        return best;
+    }
+    /**
+     * @param {unknown} value
+     * @param {SafeParser} schema
+     * @returns {unknown[]}
+     */
+    latestArray(value, schema) {
+        if (value == null)
+            return [];
+        let arr;
+        if (typeof value === "string") {
+            try {
+                const parsed = JSON.parse(value);
+                arr = Array.isArray(parsed) ? parsed : [parsed];
+            }
+            catch {
+                return [];
+            }
+        }
+        else {
+            arr = Array.isArray(value) ? value : [value];
+        }
+        return arr.flatMap((item) => {
+            const parsed = schema.safeParse(item);
+            return parsed.success ? [parsed.data] : [];
+        });
+    }
+    /**
+     * @param {TableRef} table
+     * @param {string} nodeId
+     * @returns {number}
+     */
+    iterationCount(table, nodeId) {
+        const tableName = this.resolveTableName(table);
+        const rows = this._outputs[tableName] ?? [];
+        const matching = filterRowsByNodeId(rows, nodeId, this._currentScopes);
+        const seen = new Set();
+        for (const row of matching) {
+            const iter = Number.isFinite(Number(row.iteration))
+                ? Number(row.iteration)
+                : 0;
+            seen.add(iter);
+        }
+        return seen.size;
+    }
+    /**
+     * @param {TableRef} table
+     * @returns {string}
+     */
+    resolveTableName(table) {
+        if (typeof table === "string")
+            return table;
+        const zodKey = this._zodToKeyName?.get(table);
+        if (zodKey)
+            return zodKey;
+        return resolveDrizzleName(table) ?? String(table);
+    }
+    /**
+     * @param {TableRef} table
+     * @param {OutputKey} key
+     * @returns {OutputRow | undefined}
+     */
+    resolveRow(table, key) {
+        const tableName = this.resolveTableName(table);
+        const rows = this._outputs[tableName] ?? [];
+        const matching = filterRowsByNodeId(rows, key.nodeId, this._currentScopes);
+        return matching.find((row) => {
+            return (row.iteration ?? 0) === (key.iteration ?? this.iteration);
+        });
+    }
+}

package/src/SmithersCtxOptions.ts

@@ -0,0 +1,14 @@
+import type { OutputSnapshot } from "./OutputSnapshot.ts";
+import type { RunAuthContext } from "./RunAuthContext.ts";
+import type { SmithersRuntimeConfig } from "./SmithersRuntimeConfig.ts";
+
+export type SmithersCtxOptions = {
+  runId: string;
+  iteration: number;
+  iterations?: Record<string, number>;
+  input: unknown;
+  auth?: RunAuthContext | null;
+  outputs: OutputSnapshot;
+  zodToKeyName?: Map<any, string>;
+  runtimeConfig?: SmithersRuntimeConfig;
+};

package/src/SmithersRuntimeConfig.ts

@@ -0,0 +1,3 @@
+export type SmithersRuntimeConfig = {
+  cliAgentToolsDefault?: "all" | "explicit-only";
+};

package/src/SmithersTaskRuntime.ts

@@ -0,0 +1,22 @@
+/**
+ * Structural stand-in for the full `SmithersDb` class exported from
+ * `@smithers-orchestrator/db/adapter`. The generated `@smithers-orchestrator/db` index.d.ts does not
+ * expose `SmithersDb` as a named export (it emits `SmithersDb$1` plus a
+ * non-exported alias), and the package's wildcard subpath mapping sends every
+ * `@smithers-orchestrator/db/<sub>` type lookup back to that same bundle. Until the db
+ * package fixes its public type surface, we keep the runtime `db` handle typed
+ * as a branded record so consumers cannot treat it as arbitrary `any` while
+ * still allowing a real `SmithersDb` instance to flow through.
+ */
+type SmithersDb = Record<string, unknown> & { readonly __smithersDbBrand?: never };
+
+export type SmithersTaskRuntime = {
+  runId: string;
+  stepId: string;
+  attempt: number;
+  iteration: number;
+  signal: AbortSignal;
+  db: SmithersDb;
+  heartbeat: (data?: unknown) => void;
+  lastHeartbeat: unknown | null;
+};

package/src/SpawnCaptureOptions.ts

@@ -0,0 +1,12 @@
+export type SpawnCaptureOptions = {
+  cwd: string;
+  env?: Record<string, string | undefined>;
+  input?: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  idleTimeoutMs?: number;
+  maxOutputBytes?: number;
+  detached?: boolean;
+  onStdout?: (chunk: string) => void;
+  onStderr?: (chunk: string) => void;
+};

package/src/SpawnCaptureResult.ts

@@ -0,0 +1,5 @@
+export type SpawnCaptureResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+};

package/src/TaskCompletedEvent.ts

@@ -0,0 +1,5 @@
+export type TaskCompletedEvent = {
+  nodeId: string;
+  iteration: number;
+  output: unknown;
+};

package/src/TaskExecutor.ts

@@ -0,0 +1,7 @@
+import type { TaskDescriptor } from "@smithers-orchestrator/graph/types";
+import type { TaskExecutorContext } from "./TaskExecutorContext.ts";
+
+export type TaskExecutor = (
+  task: TaskDescriptor,
+  context: TaskExecutorContext,
+) => Promise<unknown> | unknown;

package/src/TaskExecutorContext.ts

@@ -0,0 +1,7 @@
+import type { RunOptions } from "./RunOptions.ts";
+
+export type TaskExecutorContext = {
+  runId: string;
+  options: RunOptions;
+  signal?: AbortSignal;
+};

package/src/TaskFailedEvent.ts

@@ -0,0 +1,5 @@
+export type TaskFailedEvent = {
+  nodeId: string;
+  iteration: number;
+  error: unknown;
+};

package/src/WaitHandler.ts

@@ -0,0 +1,8 @@
+import type { RunOptions } from "./RunOptions.ts";
+import type { RunResult } from "./RunResult.ts";
+import type { EngineDecision, WaitReason } from "@smithers-orchestrator/scheduler";
+
+export type WaitHandler = (
+  reason: WaitReason,
+  context: { runId: string; options: RunOptions },
+) => Promise<EngineDecision | RunResult> | EngineDecision | RunResult;

package/src/WorkflowDefinition.ts

@@ -0,0 +1,16 @@
+import type { SmithersWorkflowOptions } from "@smithers-orchestrator/scheduler/SmithersWorkflowOptions";
+import type { SchemaRegistryEntry } from "@smithers-orchestrator/db/SchemaRegistryEntry";
+import type { z } from "zod";
+import type { WorkflowElement } from "./WorkflowElement.ts";
+
+type WorkflowSmithersCtx<Schema = unknown> = import("./SmithersCtx.js").SmithersCtx<Schema>;
+
+export type WorkflowDefinition<Schema = unknown> = {
+  readableName?: string;
+  description?: string;
+  db?: unknown;
+  build: (ctx: WorkflowSmithersCtx<Schema>) => WorkflowElement;
+  opts: SmithersWorkflowOptions;
+  schemaRegistry?: Map<string, SchemaRegistryEntry>;
+  zodToKeyName?: Map<z.ZodObject<z.ZodRawShape>, string>;
+};