@smithers-orchestrator/engine 0.16.0

package/src/hot/OverlayOptions.ts

@@ -0,0 +1,4 @@
+export type OverlayOptions = {
+	/** Directory basenames to exclude from overlay */
+	exclude?: string[];
+};

package/src/hot/WatchTreeOptions.ts

@@ -0,0 +1,6 @@
+export type WatchTreeOptions = {
+	/** Patterns to ignore (directory basenames) */
+	ignore?: string[];
+	/** Debounce interval in ms (default: 100) */
+	debounceMs?: number;
+};

package/src/hot/index.js

@@ -0,0 +1,9 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./HotReloadEvent.ts").HotReloadEvent} HotReloadEvent */
+/** @typedef {import("./OverlayOptions.ts").OverlayOptions} OverlayOptions */
+/** @typedef {import("./WatchTreeOptions.ts").WatchTreeOptions} WatchTreeOptions */
+// @smithers-type-exports-end
+
+export { WatchTree } from "./watch.js";
+export { buildOverlay, cleanupGenerations, resolveOverlayEntry } from "./overlay.js";
+export { HotWorkflowController } from "./HotWorkflowController.js";

package/src/hot/overlay.js

@@ -0,0 +1,177 @@
+import { readdir, mkdir, link, copyFile, rm } from "node:fs/promises";
+import { resolve, relative, join, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+/** @typedef {import("./OverlayOptions.ts").OverlayOptions} OverlayOptions */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+
+const DEFAULT_EXCLUDE = [
+    "node_modules",
+    ".git",
+    ".jj",
+    ".smithers",
+    ".DS_Store",
+];
+/**
+ * Build a generation overlay by hardlinking (or copying) the hot root
+ * tree into a new generation directory.
+ *
+ * Returns the absolute path to the overlay directory.
+ *
+ * @param {string} hotRoot
+ * @param {string} outDir
+ * @param {number} generation
+ * @param {OverlayOptions} [opts]
+ * @returns {Effect.Effect<string, SmithersError>}
+ */
+export function buildOverlayEffect(hotRoot, outDir, generation, opts) {
+    const exclude = new Set(opts?.exclude ?? DEFAULT_EXCLUDE);
+    const genDir = join(outDir, `gen-${generation}`);
+    return Effect.gen(function* () {
+        yield* Effect.tryPromise({
+            try: () => mkdir(genDir, { recursive: true }),
+            catch: (cause) => toSmithersError(cause, "create hot overlay generation dir", {
+                code: "HOT_OVERLAY_FAILED",
+                details: { hotRoot, outDir, generation },
+            }),
+        });
+        yield* mirrorTreeEffect(hotRoot, genDir, exclude);
+        return genDir;
+    }).pipe(Effect.annotateLogs({
+        hotRoot,
+        outDir,
+        generation,
+        excludeCount: exclude.size,
+    }), Effect.withLogSpan("hot:build-overlay"));
+}
+/**
+ * @param {string} hotRoot
+ * @param {string} outDir
+ * @param {number} generation
+ * @param {OverlayOptions} [opts]
+ * @returns {Promise<string>}
+ */
+export async function buildOverlay(hotRoot, outDir, generation, opts) {
+    return Effect.runPromise(buildOverlayEffect(hotRoot, outDir, generation, opts));
+}
+/**
+ * Recursively mirror `src` into `dest`, using hardlinks where possible
+ * and falling back to copy. Skips excluded directory basenames.
+ */
+function mirrorTreeEffect(src, dest, exclude) {
+    return Effect.gen(function* () {
+        const entries = yield* Effect.tryPromise({
+            try: () => readdir(src, { withFileTypes: true }),
+            catch: (cause) => toSmithersError(cause, "read hot overlay source dir", {
+                code: "HOT_OVERLAY_FAILED",
+                details: { src, dest },
+            }),
+        });
+        for (const entry of entries) {
+            if (exclude.has(entry.name))
+                continue;
+            if (entry.name.startsWith("."))
+                continue;
+            const srcPath = join(src, entry.name);
+            const destPath = join(dest, entry.name);
+            if (entry.isDirectory()) {
+                yield* Effect.tryPromise({
+                    try: () => mkdir(destPath, { recursive: true }),
+                    catch: (cause) => toSmithersError(cause, "create mirrored hot overlay dir", {
+                        code: "HOT_OVERLAY_FAILED",
+                        details: { srcPath, destPath },
+                    }),
+                });
+                yield* mirrorTreeEffect(srcPath, destPath, exclude);
+            }
+            else if (entry.isFile()) {
+                const linked = yield* Effect.either(Effect.tryPromise({
+                    try: () => link(srcPath, destPath),
+                    catch: (cause) => toSmithersError(cause, "hardlink overlay file", {
+                        code: "HOT_OVERLAY_FAILED",
+                        details: { srcPath, destPath },
+                    }),
+                }));
+                if (linked._tag === "Left") {
+                    yield* Effect.tryPromise({
+                        try: () => mkdir(dirname(destPath), { recursive: true }),
+                        catch: (cause) => toSmithersError(cause, "create overlay file parent dir", {
+                            code: "HOT_OVERLAY_FAILED",
+                            details: { srcPath, destPath },
+                        }),
+                    });
+                    yield* Effect.tryPromise({
+                        try: () => copyFile(srcPath, destPath),
+                        catch: (cause) => toSmithersError(cause, "copy overlay file", {
+                            code: "HOT_OVERLAY_FAILED",
+                            details: { srcPath, destPath },
+                        }),
+                    });
+                }
+            }
+        }
+    });
+}
+/**
+ * Remove old generation directories, keeping only the last `keepLast`.
+ *
+ * @param {string} outDir
+ * @param {number} keepLast
+ * @returns {Effect.Effect<void, SmithersError>}
+ */
+export function cleanupGenerationsEffect(outDir, keepLast) {
+    return Effect.gen(function* () {
+        if (!existsSync(outDir))
+            return;
+        const entries = yield* Effect.tryPromise({
+            try: () => readdir(outDir, { withFileTypes: true }),
+            catch: (cause) => toSmithersError(cause, "read hot overlay generations", {
+                code: "HOT_OVERLAY_FAILED",
+                details: { outDir, keepLast },
+            }),
+        });
+        const genDirs = entries
+            .filter((e) => e.isDirectory() && e.name.startsWith("gen-"))
+            .map((e) => {
+            const num = parseInt(e.name.slice(4), 10);
+            return { name: e.name, num: isNaN(num) ? -1 : num };
+        })
+            .filter((e) => e.num >= 0)
+            .sort((a, b) => a.num - b.num);
+        const toRemove = genDirs.slice(0, Math.max(0, genDirs.length - keepLast));
+        for (const dir of toRemove) {
+            yield* Effect.either(Effect.tryPromise({
+                try: () => rm(join(outDir, dir.name), { recursive: true, force: true }),
+                catch: (cause) => toSmithersError(cause, "remove stale hot overlay generation", {
+                    code: "HOT_OVERLAY_FAILED",
+                    details: { outDir, generationDir: dir.name },
+                }),
+            }));
+        }
+    }).pipe(Effect.annotateLogs({
+        outDir,
+        keepLast,
+    }), Effect.withLogSpan("hot:cleanup-generations"));
+}
+/**
+ * @param {string} outDir
+ * @param {number} keepLast
+ * @returns {Promise<void>}
+ */
+export async function cleanupGenerations(outDir, keepLast) {
+    await Effect.runPromise(cleanupGenerationsEffect(outDir, keepLast));
+}
+/**
+ * Resolve the overlay entry path given the original entry path,
+ * the hot root, and the overlay generation directory.
+ *
+ * @param {string} entryPath
+ * @param {string} hotRoot
+ * @param {string} genDir
+ * @returns {string}
+ */
+export function resolveOverlayEntry(entryPath, hotRoot, genDir) {
+    const rel = relative(hotRoot, entryPath);
+    return resolve(genDir, rel);
+}

package/src/hot/watch.js

@@ -0,0 +1,174 @@
+import { watch } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { resolve, relative } from "node:path";
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { logDebug, logInfo } from "@smithers-orchestrator/observability/logging";
+/** @typedef {import("./WatchTreeOptions.ts").WatchTreeOptions} WatchTreeOptions */
+
+const DEFAULT_IGNORE = [
+    "node_modules",
+    ".git",
+    ".jj",
+    ".smithers",
+];
+export class WatchTree {
+    watchers = [];
+    rootDir;
+    ignore;
+    debounceMs;
+    changedFiles = new Set();
+    debounceTimer = null;
+    waitResolve = null;
+    closed = false;
+    /**
+   * @param {string} rootDir
+   * @param {WatchTreeOptions} [opts]
+   */
+    constructor(rootDir, opts) {
+        this.rootDir = resolve(rootDir);
+        this.ignore = opts?.ignore ?? DEFAULT_IGNORE;
+        this.debounceMs = opts?.debounceMs ?? 100;
+    }
+    /** Start watching. Call once. */
+    async start() {
+        await Effect.runPromise(this.startEffect());
+    }
+    /**
+     * Returns a promise that resolves with changed file paths
+     * the next time file changes are detected (after debounce).
+     * Can be called repeatedly.
+     */
+    wait() {
+        // If there are already buffered changes, resolve immediately
+        if (this.changedFiles.size > 0) {
+            const files = [...this.changedFiles];
+            this.changedFiles.clear();
+            return Promise.resolve(files);
+        }
+        return Effect.runPromise(this.waitEffect());
+    }
+    /** Stop all watchers and clean up. */
+    close() {
+        this.closed = true;
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        for (const w of this.watchers) {
+            try {
+                w.close();
+            }
+            catch { }
+        }
+        this.watchers = [];
+        // Resolve any pending wait with empty array
+        if (this.waitResolve) {
+            this.waitResolve([]);
+            this.waitResolve = null;
+        }
+        logInfo("closed hot watch tree", {
+            rootDir: this.rootDir,
+        }, "hot:watch");
+    }
+    startEffect() {
+        return Effect.tryPromise({
+            try: () => this.watchDir(this.rootDir),
+            catch: (cause) => toSmithersError(cause, "start hot watch tree"),
+        }).pipe(Effect.annotateLogs({
+            rootDir: this.rootDir,
+            debounceMs: this.debounceMs,
+        }), Effect.withLogSpan("hot:watch-start"));
+    }
+    waitEffect() {
+        return Effect.async((resume) => {
+            if (this.changedFiles.size > 0) {
+                const files = [...this.changedFiles];
+                this.changedFiles.clear();
+                resume(Effect.succeed(files));
+                return;
+            }
+            this.waitResolve = (files) => {
+                resume(Effect.succeed(files));
+            };
+            return Effect.sync(() => {
+                if (this.waitResolve) {
+                    this.waitResolve = null;
+                }
+            });
+        }).pipe(Effect.annotateLogs({
+            rootDir: this.rootDir,
+        }), Effect.withLogSpan("hot:watch-wait"));
+    }
+    /**
+   * @param {string} name
+   * @returns {boolean}
+   */
+    shouldIgnore(name) {
+        return this.ignore.includes(name) || name.startsWith(".");
+    }
+    /**
+   * @param {string} dir
+   * @returns {Promise<void>}
+   */
+    async watchDir(dir) {
+        if (this.closed)
+            return;
+        const baseName = dir.split("/").pop() ?? "";
+        if (baseName && this.shouldIgnore(baseName) && dir !== this.rootDir)
+            return;
+        try {
+            const watcher = watch(dir, (eventType, filename) => {
+                if (!filename || this.closed)
+                    return;
+                // Ignore hidden files and ignored dirs
+                const parts = filename.split("/");
+                if (parts.some((p) => this.shouldIgnore(p)))
+                    return;
+                const fullPath = resolve(dir, filename);
+                logDebug("hot watch tree observed file change", {
+                    rootDir: this.rootDir,
+                    eventType,
+                    fullPath,
+                }, "hot:watch");
+                this.onFileChange(fullPath);
+            });
+            this.watchers.push(watcher);
+            // Recursively watch subdirectories
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory() && !this.shouldIgnore(entry.name)) {
+                    await this.watchDir(resolve(dir, entry.name));
+                }
+            }
+        }
+        catch {
+            // Directory may have been deleted; ignore
+        }
+    }
+    /**
+   * @param {string} filePath
+   */
+    onFileChange(filePath) {
+        this.changedFiles.add(filePath);
+        // Debounce: reset timer on each change
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            this.flush();
+        }, this.debounceMs);
+    }
+    flush() {
+        if (this.changedFiles.size === 0)
+            return;
+        const files = [...this.changedFiles];
+        this.changedFiles.clear();
+        logInfo("flushing hot watch changes", {
+            rootDir: this.rootDir,
+            changedFileCount: files.length,
+            changedFiles: files.join(","),
+        }, "hot:watch");
+        if (this.waitResolve) {
+            this.waitResolve(files);
+            this.waitResolve = null;
+        }
+    }
+}

package/src/human-requests.js

@@ -0,0 +1,120 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./HumanRequestKind.ts").HumanRequestKind} HumanRequestKind */
+/** @typedef {import("./HumanRequestStatus.ts").HumanRequestStatus} HumanRequestStatus */
+// @smithers-type-exports-end
+
+import { jsonSchemaToZod } from "./external/json-schema-to-zod.js";
+/**
+ * @typedef {{ ok: true; } | { ok: false; code: "HUMAN_REQUEST_SCHEMA_INVALID" | "HUMAN_REQUEST_VALIDATION_FAILED"; message: string; }} HumanRequestSchemaValidation
+ */
+
+/** @type {readonly ["ask", "confirm", "select", "json"]} */
+export const HUMAN_REQUEST_KINDS = ["ask", "confirm", "select", "json"];
+/** @type {readonly ["pending", "answered", "cancelled", "expired"]} */
+export const HUMAN_REQUEST_STATUSES = [
+    "pending",
+    "answered",
+    "cancelled",
+    "expired",
+];
+/**
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ * @returns {string}
+ */
+export function buildHumanRequestId(runId, nodeId, iteration) {
+    return `human:${runId}:${nodeId}:${iteration}`;
+}
+/**
+ * @param {Record<string, unknown> | null | undefined} meta
+ * @returns {boolean}
+ */
+export function isHumanTaskMeta(meta) {
+    return Boolean(meta?.humanTask);
+}
+/**
+ * @param {Record<string, unknown> | null | undefined} meta
+ * @param {string} fallback
+ * @returns {string}
+ */
+export function getHumanTaskPrompt(meta, fallback) {
+    const prompt = meta?.prompt;
+    return typeof prompt === "string" && prompt.trim().length > 0
+        ? prompt
+        : fallback;
+}
+/**
+ * @param {{ timeoutAtMs?: number | null } | null | undefined} request
+ * @returns {boolean}
+ */
+export function isHumanRequestPastTimeout(request, nowMs = Date.now()) {
+    return (typeof request?.timeoutAtMs === "number" &&
+        Number.isFinite(request.timeoutAtMs) &&
+        request.timeoutAtMs <= nowMs);
+}
+/**
+ * @param {{ issues?: Array<{ path?: PropertyKey[]; message?: string }> }} error
+ */
+function formatValidationIssues(error) {
+    const issues = error.issues ?? [];
+    if (issues.length === 0) {
+        return "unknown validation error";
+    }
+    return issues
+        .map((issue) => {
+        const path = Array.isArray(issue.path) && issue.path.length > 0
+            ? issue.path.join(".")
+            : "(root)";
+        return `${path}: ${issue.message ?? "invalid value"}`;
+    })
+        .join("; ");
+}
+/**
+ * @param {{ requestId: string; schemaJson: string | null }} request
+ * @param {unknown} value
+ * @returns {HumanRequestSchemaValidation}
+ */
+export function validateHumanRequestValue(request, value) {
+    if (!request.schemaJson) {
+        return { ok: true };
+    }
+    let schema;
+    try {
+        schema = JSON.parse(request.schemaJson);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: "HUMAN_REQUEST_SCHEMA_INVALID",
+            message: `Stored schema for ${request.requestId} is not valid JSON: ${err?.message ?? String(err)}`,
+        };
+    }
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        return {
+            ok: false,
+            code: "HUMAN_REQUEST_SCHEMA_INVALID",
+            message: `Stored schema for ${request.requestId} is not a JSON object.`,
+        };
+    }
+    let validator;
+    try {
+        validator = jsonSchemaToZod(schema);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: "HUMAN_REQUEST_SCHEMA_INVALID",
+            message: `Stored schema for ${request.requestId} could not be loaded for validation: ${err?.message ?? String(err)}`,
+        };
+    }
+    const result = validator.safeParse(value);
+    if (!result.success) {
+        return {
+            ok: false,
+            code: "HUMAN_REQUEST_VALIDATION_FAILED",
+            message: `Human request ${request.requestId} does not match the stored schema: ${formatValidationIssues(result.error)}`,
+        };
+    }
+    return { ok: true };
+}