@cogitator-ai/workflows 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cogitator Contributors
+
+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/README.md

@@ -0,0 +1,97 @@
+# @cogitator-ai/workflows
+
+DAG-based workflow engine for Cogitator agents. Build complex multi-step workflows with branching, loops, and checkpoints.
+
+## Installation
+
+```bash
+pnpm add @cogitator-ai/workflows
+```
+
+## Usage
+
+### Basic Workflow
+
+```typescript
+import { WorkflowBuilder, WorkflowExecutor } from '@cogitator-ai/workflows';
+
+const workflow = new WorkflowBuilder<{ count: number }>('counter')
+  .initialState({ count: 0 })
+  .addNode('increment', async (ctx) => ({
+    state: { count: ctx.state.count + 1 },
+  }))
+  .addNode('done', async (ctx) => ({
+    output: `Final count: ${ctx.state.count}`,
+  }))
+  .build();
+
+const executor = new WorkflowExecutor(cogitator);
+const result = await executor.execute(workflow);
+```
+
+### Conditional Branching
+
+```typescript
+const workflow = new WorkflowBuilder('approval')
+  .addNode('review', reviewNode)
+  .addConditional('check', (state) => state.approved, {
+    after: ['review'],
+  })
+  .addNode('approve', approveNode, { after: ['check:true'] })
+  .addNode('reject', rejectNode, { after: ['check:false'] })
+  .build();
+```
+
+### Loops
+
+```typescript
+const workflow = new WorkflowBuilder('retry')
+  .addNode('attempt', attemptNode)
+  .addLoop('check', {
+    condition: (state) => !state.success && state.attempts < 3,
+    back: 'attempt',
+    exit: 'done',
+    after: ['attempt'],
+  })
+  .addNode('done', doneNode)
+  .build();
+```
+
+### Checkpoints
+
+Resume workflows from saved state:
+
+```typescript
+import { FileCheckpointStore } from '@cogitator-ai/workflows';
+
+const store = new FileCheckpointStore('./checkpoints');
+
+// Save checkpoint
+await executor.execute(workflow, {
+  checkpointStore: store,
+  checkpointInterval: 5000,
+});
+
+// Resume from checkpoint
+const result = await executor.resume(checkpointId, store);
+```
+
+### Pre-built Nodes
+
+```typescript
+import { agentNode, toolNode, functionNode } from '@cogitator-ai/workflows';
+
+const workflow = new WorkflowBuilder('pipeline')
+  .addNode('analyze', agentNode(analyzerAgent))
+  .addNode('transform', toolNode('json-transform', { mapping: '...' }))
+  .addNode('validate', functionNode(async (ctx) => ({ valid: true })))
+  .build();
+```
+
+## Documentation
+
+See the [Cogitator documentation](https://github.com/eL1fe/cogitator) for full API reference.
+
+## License
+
+MIT

package/dist/builder.d.ts

@@ -0,0 +1,39 @@
+/**
+ * WorkflowBuilder - Fluent API for constructing workflows
+ */
+import type { Workflow, WorkflowState, NodeFn, AddNodeOptions, AddConditionalOptions, AddLoopOptions } from '@cogitator-ai/types';
+export declare class WorkflowBuilder<S extends WorkflowState = WorkflowState> {
+    private name;
+    private state;
+    private nodes;
+    private conditionals;
+    private loops;
+    private entryPointName;
+    constructor(name: string);
+    /**
+     * Set the initial state for the workflow
+     */
+    initialState(state: S): this;
+    /**
+     * Set explicit entry point (first node to execute)
+     */
+    entryPoint(nodeName: string): this;
+    /**
+     * Add a node to the workflow
+     */
+    addNode(name: string, fn: NodeFn<S>, options?: AddNodeOptions): this;
+    /**
+     * Add a conditional routing node
+     */
+    addConditional(name: string, condition: (state: S) => string | string[], options?: AddConditionalOptions): this;
+    /**
+     * Add a loop construct
+     */
+    addLoop(name: string, options: AddLoopOptions): this;
+    /**
+     * Build and validate the workflow
+     */
+    build(): Workflow<S>;
+    private validate;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,aAAa,EACb,MAAM,EAEN,cAAc,EACd,qBAAqB,EACrB,cAAc,EAEf,MAAM,qBAAqB,CAAC;AAuB7B,qBAAa,eAAe,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IAClE,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,cAAc,CAAuB;gBAEjC,IAAI,EAAE,MAAM;IAKxB;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAK5B;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKlC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI;IAUpE;;OAEG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,EAAE,EAC1C,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI;IASP;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAWpD;;OAEG;IACH,KAAK,IAAI,QAAQ,CAAC,CAAC,CAAC;IAuIpB,OAAO,CAAC,QAAQ;CAwCjB"}

package/dist/builder.js

@@ -0,0 +1,224 @@
+/**
+ * WorkflowBuilder - Fluent API for constructing workflows
+ */
+export class WorkflowBuilder {
+    name;
+    state;
+    nodes = [];
+    conditionals = [];
+    loops = [];
+    entryPointName = null;
+    constructor(name) {
+        this.name = name;
+        this.state = {};
+    }
+    /**
+     * Set the initial state for the workflow
+     */
+    initialState(state) {
+        this.state = state;
+        return this;
+    }
+    /**
+     * Set explicit entry point (first node to execute)
+     */
+    entryPoint(nodeName) {
+        this.entryPointName = nodeName;
+        return this;
+    }
+    /**
+     * Add a node to the workflow
+     */
+    addNode(name, fn, options) {
+        this.nodes.push({
+            name,
+            fn,
+            config: options?.config,
+            after: options?.after ?? [],
+        });
+        return this;
+    }
+    /**
+     * Add a conditional routing node
+     */
+    addConditional(name, condition, options) {
+        this.conditionals.push({
+            name,
+            condition,
+            after: options?.after ?? [],
+        });
+        return this;
+    }
+    /**
+     * Add a loop construct
+     */
+    addLoop(name, options) {
+        this.loops.push({
+            name,
+            condition: options.condition,
+            back: options.back,
+            exit: options.exit,
+            after: options.after ?? [],
+        });
+        return this;
+    }
+    /**
+     * Build and validate the workflow
+     */
+    build() {
+        const nodesMap = new Map();
+        for (const node of this.nodes) {
+            nodesMap.set(node.name, {
+                name: node.name,
+                fn: node.fn,
+                config: node.config,
+            });
+        }
+        for (const cond of this.conditionals) {
+            nodesMap.set(cond.name, {
+                name: cond.name,
+                fn: async (ctx) => ({ output: ctx.state }),
+                config: undefined,
+            });
+        }
+        for (const loop of this.loops) {
+            nodesMap.set(loop.name, {
+                name: loop.name,
+                fn: async (ctx) => ({ output: ctx.state }),
+                config: undefined,
+            });
+        }
+        const edges = [];
+        const conditionalNames = new Set(this.conditionals.map((c) => c.name));
+        const loopNames = new Set(this.loops.map((l) => l.name));
+        for (const node of this.nodes) {
+            for (const dep of node.after) {
+                if (conditionalNames.has(dep) || loopNames.has(dep)) {
+                    continue;
+                }
+                edges.push({
+                    type: 'sequential',
+                    from: dep,
+                    to: node.name,
+                });
+            }
+        }
+        for (const cond of this.conditionals) {
+            for (const dep of cond.after) {
+                edges.push({
+                    type: 'sequential',
+                    from: dep,
+                    to: cond.name,
+                });
+            }
+            const targets = [];
+            for (const node of this.nodes) {
+                if (node.after.includes(cond.name)) {
+                    targets.push(node.name);
+                }
+            }
+            if (targets.length > 0) {
+                edges.push({
+                    type: 'conditional',
+                    from: cond.name,
+                    condition: cond.condition,
+                    targets,
+                });
+            }
+        }
+        for (const loop of this.loops) {
+            for (const dep of loop.after) {
+                edges.push({
+                    type: 'sequential',
+                    from: dep,
+                    to: loop.name,
+                });
+            }
+            edges.push({
+                type: 'loop',
+                from: loop.name,
+                condition: loop.condition,
+                back: loop.back,
+                exit: loop.exit,
+            });
+        }
+        let entryPoint = this.entryPointName;
+        if (!entryPoint) {
+            const allDeps = new Set();
+            for (const node of this.nodes) {
+                for (const dep of node.after) {
+                    allDeps.add(dep);
+                }
+            }
+            for (const cond of this.conditionals) {
+                for (const dep of cond.after) {
+                    allDeps.add(dep);
+                }
+            }
+            const roots = [];
+            for (const node of this.nodes) {
+                if (node.after.length === 0 && !allDeps.has(node.name)) {
+                    roots.push(node.name);
+                }
+            }
+            if (roots.length === 0) {
+                entryPoint = this.nodes[0]?.name;
+            }
+            else if (roots.length === 1) {
+                entryPoint = roots[0];
+            }
+            else {
+                entryPoint = roots[0];
+            }
+        }
+        if (!entryPoint) {
+            throw new Error('Workflow has no nodes');
+        }
+        this.validate(nodesMap, edges, entryPoint);
+        return {
+            name: this.name,
+            initialState: this.state,
+            nodes: nodesMap,
+            edges,
+            entryPoint,
+        };
+    }
+    validate(nodes, edges, entryPoint) {
+        if (!nodes.has(entryPoint)) {
+            throw new Error(`Entry point '${entryPoint}' not found in nodes`);
+        }
+        for (const edge of edges) {
+            if (!nodes.has(edge.from)) {
+                throw new Error(`Edge references unknown node '${edge.from}'`);
+            }
+            if (edge.type === 'sequential') {
+                if (!nodes.has(edge.to)) {
+                    throw new Error(`Edge references unknown node '${edge.to}'`);
+                }
+            }
+            else if (edge.type === 'parallel') {
+                for (const to of edge.to) {
+                    if (!nodes.has(to)) {
+                        throw new Error(`Edge references unknown node '${to}'`);
+                    }
+                }
+            }
+            else if (edge.type === 'conditional') {
+                for (const target of edge.targets) {
+                    if (!nodes.has(target)) {
+                        throw new Error(`Conditional references unknown node '${target}'`);
+                    }
+                }
+            }
+            else if (edge.type === 'loop') {
+                if (!nodes.has(edge.back)) {
+                    throw new Error(`Loop references unknown back node '${edge.back}'`);
+                }
+                if (!nodes.has(edge.exit)) {
+                    throw new Error(`Loop references unknown exit node '${edge.exit}'`);
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}

package/dist/checkpoint.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Checkpoint stores for workflow resume support
+ */
+import type { WorkflowCheckpoint, CheckpointStore } from '@cogitator-ai/types';
+/**
+ * In-memory checkpoint store (for testing and short-lived workflows)
+ */
+export declare class InMemoryCheckpointStore implements CheckpointStore {
+    private checkpoints;
+    save(checkpoint: WorkflowCheckpoint): Promise<void>;
+    load(id: string): Promise<WorkflowCheckpoint | null>;
+    list(workflowName: string): Promise<WorkflowCheckpoint[]>;
+    delete(id: string): Promise<void>;
+    clear(): void;
+}
+/**
+ * File-based checkpoint store (persists to disk)
+ */
+export declare class FileCheckpointStore implements CheckpointStore {
+    private directory;
+    constructor(directory?: string);
+    private ensureDirectory;
+    private getFilePath;
+    save(checkpoint: WorkflowCheckpoint): Promise<void>;
+    load(id: string): Promise<WorkflowCheckpoint | null>;
+    list(workflowName: string): Promise<WorkflowCheckpoint[]>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * Create a new checkpoint ID
+ */
+export declare function createCheckpointId(): string;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAK/E;;GAEG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAC7D,OAAO,CAAC,WAAW,CAAyC;IAEtD,IAAI,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAKpD,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAUzD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,KAAK,IAAI,IAAI;CAGd;AAED;;GAEG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,SAAS,CAAS;gBAEd,SAAS,CAAC,EAAE,MAAM;YAIhB,eAAe;IAO7B,OAAO,CAAC,WAAW;IAIb,IAAI,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnD,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAUpD,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA2BzD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOxC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/checkpoint.js

@@ -0,0 +1,108 @@
+/**
+ * Checkpoint stores for workflow resume support
+ */
+import { nanoid } from 'nanoid';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+/**
+ * In-memory checkpoint store (for testing and short-lived workflows)
+ */
+export class InMemoryCheckpointStore {
+    checkpoints = new Map();
+    async save(checkpoint) {
+        this.checkpoints.set(checkpoint.id, { ...checkpoint });
+    }
+    async load(id) {
+        const checkpoint = this.checkpoints.get(id);
+        return checkpoint ? { ...checkpoint } : null;
+    }
+    async list(workflowName) {
+        const result = [];
+        for (const checkpoint of this.checkpoints.values()) {
+            if (checkpoint.workflowName === workflowName) {
+                result.push({ ...checkpoint });
+            }
+        }
+        return result.sort((a, b) => b.timestamp - a.timestamp);
+    }
+    async delete(id) {
+        this.checkpoints.delete(id);
+    }
+    clear() {
+        this.checkpoints.clear();
+    }
+}
+/**
+ * File-based checkpoint store (persists to disk)
+ */
+export class FileCheckpointStore {
+    directory;
+    constructor(directory) {
+        this.directory = directory ?? '.cogitator/checkpoints';
+    }
+    async ensureDirectory() {
+        try {
+            await fs.mkdir(this.directory, { recursive: true });
+        }
+        catch {
+        }
+    }
+    getFilePath(id) {
+        return path.join(this.directory, `${id}.json`);
+    }
+    async save(checkpoint) {
+        await this.ensureDirectory();
+        const filePath = this.getFilePath(checkpoint.id);
+        await fs.writeFile(filePath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+    }
+    async load(id) {
+        try {
+            const filePath = this.getFilePath(id);
+            const content = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async list(workflowName) {
+        await this.ensureDirectory();
+        try {
+            const files = await fs.readdir(this.directory);
+            const checkpoints = [];
+            for (const file of files) {
+                if (!file.endsWith('.json'))
+                    continue;
+                const filePath = path.join(this.directory, file);
+                try {
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    const checkpoint = JSON.parse(content);
+                    if (checkpoint.workflowName === workflowName) {
+                        checkpoints.push(checkpoint);
+                    }
+                }
+                catch {
+                }
+            }
+            return checkpoints.sort((a, b) => b.timestamp - a.timestamp);
+        }
+        catch {
+            return [];
+        }
+    }
+    async delete(id) {
+        try {
+            const filePath = this.getFilePath(id);
+            await fs.unlink(filePath);
+        }
+        catch {
+        }
+    }
+}
+/**
+ * Create a new checkpoint ID
+ */
+export function createCheckpointId() {
+    return `ckpt_${nanoid(12)}`;
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"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"}

package/dist/executor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * WorkflowExecutor - Main execution engine for workflows
+ */
+import type { Workflow, WorkflowState, WorkflowResult, WorkflowExecuteOptions, WorkflowEvent, CheckpointStore } from '@cogitator-ai/types';
+import type { Cogitator } from '@cogitator-ai/core';
+export declare class WorkflowExecutor {
+    private cogitator;
+    private checkpointStore;
+    private scheduler;
+    constructor(cogitator: Cogitator, checkpointStore?: CheckpointStore);
+    /**
+     * Execute a workflow
+     */
+    execute<S extends WorkflowState>(workflow: Workflow<S>, input?: Partial<S>, options?: WorkflowExecuteOptions): Promise<WorkflowResult<S>>;
+    /**
+     * Resume a workflow from a checkpoint
+     */
+    resume<S extends WorkflowState>(workflow: Workflow<S>, checkpointId: string, options?: WorkflowExecuteOptions): Promise<WorkflowResult<S>>;
+    /**
+     * Stream workflow execution events
+     */
+    stream<S extends WorkflowState>(workflow: Workflow<S>, input?: Partial<S>, options?: Omit<WorkflowExecuteOptions, 'onNodeStart' | 'onNodeComplete' | 'onNodeError'>): AsyncIterable<WorkflowEvent>;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,cAAc,EACd,sBAAsB,EACtB,aAAa,EACb,eAAe,EAEhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAQpD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,SAAS,CAAoB;gBAEzB,SAAS,EAAE,SAAS,EAAE,eAAe,CAAC,EAAE,eAAe;IAMnE;;OAEG;IACG,OAAO,CAAC,CAAC,SAAS,aAAa,EACnC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IA8I7B;;OAEG;IACG,MAAM,CAAC,CAAC,SAAS,aAAa,EAClC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAsC7B;;OAEG;IACI,MAAM,CAAC,CAAC,SAAS,aAAa,EACnC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,GAAG,gBAAgB,GAAG,aAAa,CAAC,GACvF,aAAa,CAAC,aAAa,CAAC;CAiDhC"}