@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/core/task-runner/store.js

@@ -0,0 +1,126 @@
+// File-backed durable store for tasks.
+// Single JSON document { version: 1, tasks: Task[] }, written atomically
+// (tmp file + rename) so a crash mid-write never leaves a torn store.
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { TaskError } from './types.js';
+const STORE_VERSION = 1;
+function isTaskDocument(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const doc = value;
+    return doc['version'] === STORE_VERSION && Array.isArray(doc['tasks']);
+}
+/**
+ * TaskStore persists tasks to a single JSON file with atomic writes.
+ * `load()` MUST be called before any other method.
+ */
+export class TaskStore {
+    filePath;
+    tasks = [];
+    loadedFlag = false;
+    persistQueue = Promise.resolve();
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    /** Read the store file into memory. Must be called before any other method. */
+    async load() {
+        let raw;
+        try {
+            raw = await readFile(this.filePath, 'utf8');
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT') {
+                // No store file yet — start empty.
+                this.tasks = [];
+                this.loadedFlag = true;
+                return;
+            }
+            throw new TaskError('STORAGE', `Failed to read task store at ${this.filePath}`, {
+                cause: err,
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new TaskError('STORAGE', `Task store at ${this.filePath} is corrupt (invalid JSON)`, {
+                cause: err,
+            });
+        }
+        if (!isTaskDocument(parsed)) {
+            throw new TaskError('STORAGE', `Task store at ${this.filePath} has an unexpected schema (expected { version: 1, tasks: [] })`);
+        }
+        this.tasks = parsed.tasks;
+        this.loadedFlag = true;
+    }
+    requireLoaded() {
+        if (!this.loadedFlag) {
+            throw new TaskError('STORAGE', 'TaskStore.load() must be called before use');
+        }
+    }
+    /** Atomically persist the whole document: write tmp file, then rename. */
+    persist() {
+        const doc = { version: STORE_VERSION, tasks: this.tasks };
+        const payload = JSON.stringify(doc, null, 2);
+        const tmpPath = `${this.filePath}.${randomUUID()}.tmp`;
+        const write = this.persistQueue.then(async () => {
+            try {
+                await mkdir(dirname(this.filePath), { recursive: true });
+                await writeFile(tmpPath, payload, 'utf8');
+                await rename(tmpPath, this.filePath);
+            }
+            catch (err) {
+                // Best-effort cleanup of the tmp file; never mask the original error.
+                await rm(tmpPath, { force: true }).catch(() => undefined);
+                throw new TaskError('STORAGE', `Failed to write task store at ${this.filePath}`, {
+                    cause: err,
+                });
+            }
+        });
+        this.persistQueue = write.catch(() => undefined);
+        return write;
+    }
+    /** Insert a new task. */
+    async create(task) {
+        this.requireLoaded();
+        if (this.tasks.some((t) => t.id === task.id)) {
+            throw new TaskError('STORAGE', `Task with id ${task.id} already exists`);
+        }
+        this.tasks.push(structuredClone(task));
+        await this.persist();
+    }
+    /** Upsert a task (insert or replace by id). */
+    async save(task) {
+        this.requireLoaded();
+        const idx = this.tasks.findIndex((t) => t.id === task.id);
+        if (idx === -1) {
+            this.tasks.push(structuredClone(task));
+        }
+        else {
+            this.tasks[idx] = structuredClone(task);
+        }
+        await this.persist();
+    }
+    get(id) {
+        this.requireLoaded();
+        const found = this.tasks.find((t) => t.id === id);
+        return found === undefined ? null : structuredClone(found);
+    }
+    list() {
+        this.requireLoaded();
+        return structuredClone(this.tasks);
+    }
+    async remove(id) {
+        this.requireLoaded();
+        this.tasks = this.tasks.filter((t) => t.id !== id);
+        await this.persist();
+    }
+}
+/** Factory for {@link TaskStore} (options-object style, matches gateway wiring). */
+export function createTaskStore(options) {
+    return new TaskStore(options.storagePath);
+}

package/dist/node_modules/@boombot/core/task-runner/types.d.ts

@@ -0,0 +1,138 @@
+/** Lifecycle state of a task. */
+export type TaskStatus = 'queued' | 'running' | 'paused' | 'awaiting_approval' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
+/** Lifecycle state of a single step. */
+export type StepStatus = 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+/** One unit of work inside a task — executed as a single LLM turn. */
+export interface TaskStep {
+    id: string;
+    /** Position in the task's steps array (stable, 0-based). */
+    index: number;
+    kind: 'turn';
+    prompt: string;
+    status: StepStatus;
+    /** How many times this step has been started. Preserved across retries. */
+    attempts: number;
+    output?: string;
+    error?: string;
+    startedAt?: string;
+    endedAt?: string;
+}
+/** Durable record that a step completed successfully. */
+export interface TaskCheckpoint {
+    stepIndex: number;
+    at: string;
+}
+/** A background task: an ordered sequence of turn-steps with durable state. */
+export interface Task {
+    id: string;
+    title: string;
+    /** Conversation shared by every completed step in this task. */
+    sessionId?: string;
+    status: TaskStatus;
+    steps: TaskStep[];
+    /** Index of the step the loop is currently working on (or will next). */
+    currentStepIndex: number;
+    checkpoints: TaskCheckpoint[];
+    /** Redirect messages queued by the user; drained before the next step. */
+    messageQueue: string[];
+    /** Pending HITL approval info; present only while awaiting_approval. */
+    approval?: {
+        runId: string;
+        toolName: string;
+        args: Record<string, unknown>;
+        reason: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    /** Terminal failure / cancellation detail. */
+    error?: string;
+}
+/** Input accepted by createAndStart. */
+export interface TaskInput {
+    title: string;
+    steps: Array<{
+        prompt: string;
+    }>;
+}
+/** Event a turn can emit while it is in flight. */
+export type TurnRunnerEvent = {
+    type: 'approval_required';
+    runId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    reason: string;
+};
+/**
+ * Transport-agnostic turn executor, injected by the host (e.g. the gateway
+ * implements it on top of the real turn service). The runner never calls
+ * any @boombot package directly.
+ */
+export interface TurnRunner {
+    runTurn(input: {
+        prompt: string;
+        sessionId?: string;
+        signal: AbortSignal;
+        onEvent?: (e: TurnRunnerEvent) => void;
+    }): Promise<{
+        status: 'completed' | 'failed';
+        sessionId?: string;
+        output?: string;
+        error?: string;
+    }>;
+    /** Optional: resume a turn paused on approval_required. */
+    approveTurn?(runId: string, approved: boolean, editedArgs?: Record<string, unknown>): Promise<boolean>;
+}
+/** Task lifecycle / progress notifications emitted by the runner. */
+export type TaskEvent = {
+    type: 'task.created' | 'task.paused' | 'task.resumed' | 'task.completed' | 'task.cancelled' | 'task.interrupted';
+    taskId: string;
+} | {
+    type: 'task.failed';
+    taskId: string;
+    error: string;
+} | {
+    type: 'task.progress';
+    taskId: string;
+    stepIndex: number;
+    totalSteps: number;
+    detail?: string;
+} | {
+    type: 'task.checkpoint';
+    taskId: string;
+    stepIndex: number;
+} | {
+    type: 'task.awaiting_approval';
+    taskId: string;
+    runId: string;
+    toolName: string;
+    reason: string;
+};
+/** Error thrown by the runner for expected domain failures. */
+export declare class TaskError extends Error {
+    readonly code: 'NOT_FOUND' | 'INVALID_STATE' | 'STORAGE';
+    constructor(code: TaskError['code'], message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Public API of the task runner. */
+export interface TaskRunner {
+    /** Create a task, persist it, and start the background loop (non-blocking). */
+    createAndStart(input: TaskInput): Promise<Task>;
+    get(id: string): Promise<Task | null>;
+    list(): Promise<Task[]>;
+    pause(id: string): Promise<Task>;
+    resume(id: string, decision?: {
+        approved: boolean;
+        editedArgs?: Record<string, unknown>;
+    }): Promise<Task>;
+    cancel(id: string): Promise<Task>;
+    /** Queue a redirect message to be prepended to the next step's prompt. */
+    redirect(id: string, message: string): Promise<Task>;
+    /** Reset steps from `fromStep` (default: first failed / first non-done) and re-run. */
+    retry(id: string, fromStep?: number): Promise<Task>;
+    /**
+     * Crash recovery: mark every task found in running/paused/awaiting_approval
+     * as interrupted. Call once at boot. Interrupted tasks can be retried.
+     */
+    recover(): Promise<void>;
+}

package/dist/node_modules/@boombot/core/task-runner/types.js

@@ -0,0 +1,11 @@
+// Core domain types for @boombot/core.
+// Zero dependencies on @boombot/* — only node builtins (used in runner/store).
+/** Error thrown by the runner for expected domain failures. */
+export class TaskError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'TaskError';
+        this.code = code;
+    }
+}

package/dist/node_modules/@boombot/core/workflow/dag.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DAG Validation and Execution Wave Resolution.
+ *
+ * Implements Kahn's algorithm for topological sorting and cycle detection,
+ * then groups independent nodes into parallel execution waves.
+ */
+import { type WorkflowNode } from './types.js';
+export interface DAGAnalysis<TContext = unknown, TOutput = unknown> {
+    readonly sortedNodeIds: readonly string[];
+    readonly waves: readonly (readonly WorkflowNode<TContext, TOutput>[])[];
+}
+/**
+ * Validates graph integrity and partitions nodes into waves.
+ * All nodes in wave `i` only depend on nodes in waves `< i` and can run concurrently.
+ */
+export declare function analyzeWorkflowDAG<TContext, TOutput>(nodes: readonly WorkflowNode<TContext, TOutput>[]): DAGAnalysis<TContext, TOutput>;

package/dist/node_modules/@boombot/core/workflow/dag.js

@@ -0,0 +1,109 @@
+/**
+ * DAG Validation and Execution Wave Resolution.
+ *
+ * Implements Kahn's algorithm for topological sorting and cycle detection,
+ * then groups independent nodes into parallel execution waves.
+ */
+import { CycleDetectedError, WorkflowError } from './types.js';
+/**
+ * Validates graph integrity and partitions nodes into waves.
+ * All nodes in wave `i` only depend on nodes in waves `< i` and can run concurrently.
+ */
+export function analyzeWorkflowDAG(nodes) {
+    if (nodes.length === 0) {
+        return { sortedNodeIds: [], waves: [] };
+    }
+    const nodeMap = new Map();
+    for (const node of nodes) {
+        if (nodeMap.has(node.id)) {
+            throw new WorkflowError(`Duplicate node id in workflow: '${node.id}'`);
+        }
+        nodeMap.set(node.id, node);
+    }
+    // Verify all dependencies reference existing nodes
+    for (const node of nodes) {
+        for (const depId of node.dependencies) {
+            if (!nodeMap.has(depId)) {
+                throw new WorkflowError(`Node '${node.id}' references non-existent dependency '${depId}'`);
+            }
+            if (depId === node.id) {
+                throw new CycleDetectedError([node.id, node.id]);
+            }
+        }
+    }
+    // Build in-degree map and adjacency list (upstream -> downstream)
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const node of nodes) {
+        inDegree.set(node.id, node.dependencies.length);
+        dependents.set(node.id, []);
+    }
+    for (const node of nodes) {
+        for (const depId of node.dependencies) {
+            dependents.get(depId).push(node.id);
+        }
+    }
+    // Kahn's algorithm with wave partitioning
+    const sortedNodeIds = [];
+    const waves = [];
+    // Initial wave: in-degree == 0
+    let currentWaveIds = Array.from(inDegree.entries())
+        .filter(([_, deg]) => deg === 0)
+        .map(([id]) => id);
+    while (currentWaveIds.length > 0) {
+        const currentWaveNodes = currentWaveIds.map((id) => nodeMap.get(id));
+        waves.push(currentWaveNodes);
+        sortedNodeIds.push(...currentWaveIds);
+        const nextWaveIds = [];
+        for (const id of currentWaveIds) {
+            for (const dependentId of dependents.get(id) ?? []) {
+                const nextDeg = (inDegree.get(dependentId) ?? 1) - 1;
+                inDegree.set(dependentId, nextDeg);
+                if (nextDeg === 0) {
+                    nextWaveIds.push(dependentId);
+                }
+            }
+        }
+        currentWaveIds = nextWaveIds;
+    }
+    // If not all nodes were visited, a cycle exists
+    if (sortedNodeIds.length < nodes.length) {
+        const unvisited = nodes.filter((n) => (inDegree.get(n.id) ?? 0) > 0);
+        // Find cycle path for diagnostic
+        const cyclePath = traceCycle(unvisited, nodeMap);
+        throw new CycleDetectedError(cyclePath);
+    }
+    return { sortedNodeIds, waves };
+}
+function traceCycle(unvisited, nodeMap) {
+    const visited = new Set();
+    const stack = [];
+    function dfs(currentId) {
+        visited.add(currentId);
+        stack.push(currentId);
+        const node = nodeMap.get(currentId);
+        if (node) {
+            for (const depId of node.dependencies) {
+                const index = stack.indexOf(depId);
+                if (index !== -1) {
+                    return [...stack.slice(index), depId];
+                }
+                if (!visited.has(depId)) {
+                    const res = dfs(depId);
+                    if (res)
+                        return res;
+                }
+            }
+        }
+        stack.pop();
+        return null;
+    }
+    for (const node of unvisited) {
+        if (!visited.has(node.id)) {
+            const cycle = dfs(node.id);
+            if (cycle)
+                return cycle;
+        }
+    }
+    return unvisited.map((n) => n.id);
+}

package/dist/node_modules/@boombot/core/workflow/engine.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Workflow Engine.
+ *
+ * Coordinates execution of DAG workflow waves, handles retries, timeouts,
+ * feeds upstream outputs into downstream inputs, and enforces isolation.
+ */
+import { type SFTDatasetRecord, type WorkflowNode, type WorkflowResult, type WorkflowTrajectory } from './types.js';
+export interface WorkflowEngineOptions {
+    /** Maximum concurrent tasks across a wave. Defaults to Infinity. */
+    readonly concurrency?: number;
+    /** Stop entire workflow on first node failure. Default true. */
+    readonly failFast?: boolean;
+    /** Unique ID for the workflow run, used in trajectory recording. Defaults to auto-generated ID. */
+    readonly workflowId?: string;
+    /** Whether to record detailed trajectories for MASS dataset harvesting. Defaults to true. */
+    readonly recordTrajectories?: boolean;
+    /** Minimum score threshold to mark a trajectory as golden. Defaults to 0.85. */
+    readonly minGoldenScore?: number;
+}
+export declare class WorkflowEngine<TContext = unknown, TOutput = unknown> {
+    private readonly options;
+    constructor(options?: WorkflowEngineOptions);
+    execute(nodes: readonly WorkflowNode<TContext, TOutput>[], context: TContext, signal?: AbortSignal): Promise<WorkflowResult<TOutput>>;
+    private executeNode;
+    private buildNodeTrajectory;
+    /**
+     * Harvest golden trajectories and convert them into SFT fine-tuning records (MASS RSI format).
+     */
+    static exportGoldenDataset(trajectories: readonly WorkflowTrajectory[], minScore?: number): readonly SFTDatasetRecord[];
+    /**
+     * Export golden dataset directly to JSONL string for Unsloth / HuggingFace fine-tuning.
+     */
+    static exportDatasetAsJSONL(trajectories: readonly WorkflowTrajectory[], minScore?: number): string;
+}