@inf-minds/coordination-modes 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { MindRef, GraphNode, GraphEdge, ExecutionGraph, ArtifactMapping, RoutingRules, CoordinationMode, ValidationResult, } from './types.js';
+export { validateGraph, isAcyclic, getTopologicalOrder, } from './validation.js';
+export { createPipelineMode, type PipelineOptions, type PipelineStep, createManagerWorkersMode, type ManagerWorkersOptions, } from './modes/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,OAAO,EACP,SAAS,EACT,SAAS,EACT,cAAc,EACd,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,SAAS,EACT,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// ABOUTME: Coordination modes package entry point
+// ABOUTME: Exports types, validation, and built-in modes
+// Validation exports
+export { validateGraph, isAcyclic, getTopologicalOrder, } from './validation.js';
+// Mode exports
+export { createPipelineMode, createManagerWorkersMode, } from './modes/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,yDAAyD;AAczD,qBAAqB;AACrB,OAAO,EACL,aAAa,EACb,SAAS,EACT,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,eAAe;AACf,OAAO,EACL,kBAAkB,EAGlB,wBAAwB,GAEzB,MAAM,kBAAkB,CAAC"}

package/dist/modes/index.d.ts

@@ -0,0 +1,3 @@
+export { createPipelineMode, type PipelineOptions, type PipelineStep } from './pipeline.js';
+export { createManagerWorkersMode, type ManagerWorkersOptions, } from './manager-workers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/modes/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC5F,OAAO,EACL,wBAAwB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC"}

package/dist/modes/index.js

@@ -0,0 +1,5 @@
+// ABOUTME: Built-in coordination modes
+// ABOUTME: Exports pipeline and manager-workers mode factories
+export { createPipelineMode } from './pipeline.js';
+export { createManagerWorkersMode, } from './manager-workers.js';
+//# sourceMappingURL=index.js.map

package/dist/modes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/modes/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,+DAA+D;AAE/D,OAAO,EAAE,kBAAkB,EAA2C,MAAM,eAAe,CAAC;AAC5F,OAAO,EACL,wBAAwB,GAEzB,MAAM,sBAAsB,CAAC"}

package/dist/modes/manager-workers.d.ts

@@ -0,0 +1,48 @@
+import type { CoordinationMode, MindRef } from '../types.js';
+/**
+ * Options for creating a manager-workers mode.
+ */
+export interface ManagerWorkersOptions {
+    /** Name of the mode */
+    name?: string;
+    /** Description of the mode */
+    description?: string;
+    /** Mind for the manager role */
+    managerMind: MindRef;
+    /** Mind for the worker role */
+    workerMind: MindRef;
+    /** Maximum iterations for the manager loop (default: 10) */
+    maxIterations?: number;
+    /**
+     * Exit condition for the manager.
+     * Evaluated against manager's output.
+     * Default: 'output.allTasksComplete'
+     */
+    exitCondition?: string;
+    /**
+     * Delegation condition.
+     * If true, manager delegates to worker.
+     * Default: 'output.delegatedTask'
+     */
+    delegationCondition?: string;
+}
+/**
+ * Create a manager-workers coordination mode.
+ *
+ * The manager orchestrates work by delegating tasks to workers.
+ * After each worker completes, control returns to the manager
+ * who decides whether to delegate more work or complete.
+ *
+ * ```
+ *      +--> worker --+
+ *      |             |
+ * --> manager <------+
+ *      |
+ *      +--> [exit when complete]
+ * ```
+ *
+ * @param options - Manager-workers configuration
+ * @returns A CoordinationMode for manager-workers pattern
+ */
+export declare function createManagerWorkersMode(options: ManagerWorkersOptions): CoordinationMode;
+//# sourceMappingURL=manager-workers.d.ts.map

package/dist/modes/manager-workers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-workers.d.ts","sourceRoot":"","sources":["../../src/modes/manager-workers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,+BAA+B;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,qBAAqB,GAAG,gBAAgB,CA8CzF"}

package/dist/modes/manager-workers.js

@@ -0,0 +1,59 @@
+// ABOUTME: Manager-workers coordination mode
+// ABOUTME: Central manager delegates tasks to workers in a loop
+/**
+ * Create a manager-workers coordination mode.
+ *
+ * The manager orchestrates work by delegating tasks to workers.
+ * After each worker completes, control returns to the manager
+ * who decides whether to delegate more work or complete.
+ *
+ * ```
+ *      +--> worker --+
+ *      |             |
+ * --> manager <------+
+ *      |
+ *      +--> [exit when complete]
+ * ```
+ *
+ * @param options - Manager-workers configuration
+ * @returns A CoordinationMode for manager-workers pattern
+ */
+export function createManagerWorkersMode(options) {
+    const { name = 'manager-workers', description, managerMind, workerMind, maxIterations = 10, exitCondition = 'output.allTasksComplete', delegationCondition = 'output.delegatedTask', } = options;
+    return {
+        name,
+        description,
+        graph: {
+            nodes: {
+                manager: {
+                    id: 'manager',
+                    mind: managerMind,
+                    maxIterations,
+                    exitCondition,
+                },
+                worker: {
+                    id: 'worker',
+                    mind: workerMind,
+                },
+            },
+            edges: [
+                {
+                    from: 'manager',
+                    to: 'worker',
+                    condition: delegationCondition,
+                },
+                {
+                    from: 'worker',
+                    to: 'manager',
+                },
+            ],
+            entryNode: 'manager',
+            exitNodes: ['manager'],
+        },
+        defaultRouting: {
+            defaultVisibility: 'session',
+            autoPropagateArtifacts: true,
+        },
+    };
+}
+//# sourceMappingURL=manager-workers.js.map

package/dist/modes/manager-workers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-workers.js","sourceRoot":"","sources":["../../src/modes/manager-workers.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,gEAAgE;AAgChE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAA8B;IACrE,MAAM,EACJ,IAAI,GAAG,iBAAiB,EACxB,WAAW,EACX,WAAW,EACX,UAAU,EACV,aAAa,GAAG,EAAE,EAClB,aAAa,GAAG,yBAAyB,EACzC,mBAAmB,GAAG,sBAAsB,GAC7C,GAAG,OAAO,CAAC;IAEZ,OAAO;QACL,IAAI;QACJ,WAAW;QACX,KAAK,EAAE;YACL,KAAK,EAAE;gBACL,OAAO,EAAE;oBACP,EAAE,EAAE,SAAS;oBACb,IAAI,EAAE,WAAW;oBACjB,aAAa;oBACb,aAAa;iBACd;gBACD,MAAM,EAAE;oBACN,EAAE,EAAE,QAAQ;oBACZ,IAAI,EAAE,UAAU;iBACjB;aACF;YACD,KAAK,EAAE;gBACL;oBACE,IAAI,EAAE,SAAS;oBACf,EAAE,EAAE,QAAQ;oBACZ,SAAS,EAAE,mBAAmB;iBAC/B;gBACD;oBACE,IAAI,EAAE,QAAQ;oBACd,EAAE,EAAE,SAAS;iBACd;aACF;YACD,SAAS,EAAE,SAAS;YACpB,SAAS,EAAE,CAAC,SAAS,CAAC;SACvB;QACD,cAAc,EAAE;YACd,iBAAiB,EAAE,SAAS;YAC5B,sBAAsB,EAAE,IAAI;SAC7B;KACF,CAAC;AACJ,CAAC"}

package/dist/modes/pipeline.d.ts

@@ -0,0 +1,36 @@
+import type { CoordinationMode, MindRef } from '../types.js';
+/**
+ * A step in the pipeline.
+ */
+export interface PipelineStep {
+    /** Unique identifier for this step */
+    id: string;
+    /** Mind to execute at this step */
+    mind: MindRef;
+}
+/**
+ * Options for creating a pipeline mode.
+ */
+export interface PipelineOptions {
+    /** Name of the pipeline */
+    name?: string;
+    /** Description of the pipeline */
+    description?: string;
+    /** Steps in the pipeline */
+    steps: PipelineStep[];
+}
+/**
+ * Create a pipeline coordination mode.
+ *
+ * A pipeline executes minds sequentially, passing artifacts
+ * from one step to the next.
+ *
+ * ```
+ * step1 -> step2 -> step3 -> ... -> stepN
+ * ```
+ *
+ * @param options - Pipeline configuration
+ * @returns A CoordinationMode for sequential execution
+ */
+export declare function createPipelineMode(options: PipelineOptions): CoordinationMode;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/modes/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/modes/pipeline.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAwB,MAAM,aAAa,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,gBAAgB,CA6C7E"}

package/dist/modes/pipeline.js

@@ -0,0 +1,57 @@
+// ABOUTME: Pipeline coordination mode
+// ABOUTME: Sequential execution of minds in a linear chain
+/**
+ * Create a pipeline coordination mode.
+ *
+ * A pipeline executes minds sequentially, passing artifacts
+ * from one step to the next.
+ *
+ * ```
+ * step1 -> step2 -> step3 -> ... -> stepN
+ * ```
+ *
+ * @param options - Pipeline configuration
+ * @returns A CoordinationMode for sequential execution
+ */
+export function createPipelineMode(options) {
+    const { steps, name = 'pipeline', description } = options;
+    if (steps.length === 0) {
+        throw new Error('Pipeline must have at least one step');
+    }
+    // Build nodes
+    const nodes = {};
+    for (const step of steps) {
+        nodes[step.id] = {
+            id: step.id,
+            mind: step.mind,
+        };
+    }
+    // Build edges (connect each step to the next)
+    const edges = [];
+    for (let i = 0; i < steps.length - 1; i++) {
+        const current = steps[i];
+        const next = steps[i + 1];
+        edges.push({
+            from: current.id,
+            to: next.id,
+        });
+    }
+    // Safe to assert since we checked steps.length > 0
+    const firstStep = steps[0];
+    const lastStep = steps[steps.length - 1];
+    return {
+        name,
+        description,
+        graph: {
+            nodes,
+            edges,
+            entryNode: firstStep.id,
+            exitNodes: [lastStep.id],
+        },
+        defaultRouting: {
+            defaultVisibility: 'session',
+            autoPropagateArtifacts: true,
+        },
+    };
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/modes/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/modes/pipeline.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,2DAA2D;AA0B3D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAwB;IACzD,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,UAAU,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAE1D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED,cAAc;IACd,MAAM,KAAK,GAA8B,EAAE,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG;YACf,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC;IACJ,CAAC;IAED,8CAA8C;IAC9C,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,OAAO,CAAC,EAAE;YAChB,EAAE,EAAE,IAAI,CAAC,EAAE;SACZ,CAAC,CAAC;IACL,CAAC;IAED,mDAAmD;IACnD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IAC5B,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IAE1C,OAAO;QACL,IAAI;QACJ,WAAW;QACX,KAAK,EAAE;YACL,KAAK;YACL,KAAK;YACL,SAAS,EAAE,SAAS,CAAC,EAAE;YACvB,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;SACzB;QACD,cAAc,EAAE;YACd,iBAAiB,EAAE,SAAS;YAC5B,sBAAsB,EAAE,IAAI;SAC7B;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+import type { MindConfig } from '@inf-minds/mindkit';
+/**
+ * Reference to a mind configuration.
+ * Can be inline (with full config) or registered (by name).
+ */
+export interface MindRef {
+    /** Type of reference */
+    type: 'inline' | 'registered';
+    /** Full mind configuration (for inline type) */
+    config?: MindConfig;
+    /** Name of registered mind type (for registered type) */
+    mindType?: string;
+}
+/**
+ * A node in the execution graph.
+ */
+export interface GraphNode {
+    /** Unique identifier for this node */
+    id: string;
+    /** Mind to execute at this node */
+    mind: MindRef;
+    /** Maximum iterations for loops (default: 1) */
+    maxIterations?: number;
+    /**
+     * Exit condition expression.
+     * Evaluated against the node's output.
+     * If true, the node exits normally.
+     * If false and maxIterations not reached, the node re-executes.
+     */
+    exitCondition?: string;
+}
+/**
+ * Artifact mapping for edge transitions.
+ */
+export interface ArtifactMapping {
+    /** Path patterns to include */
+    include?: string[];
+    /** Path patterns to exclude */
+    exclude?: string[];
+    /** Rename mappings (from -> to) */
+    rename?: Record<string, string>;
+}
+/**
+ * An edge connecting two nodes in the execution graph.
+ */
+export interface GraphEdge {
+    /** Source node ID */
+    from: string;
+    /** Target node ID */
+    to: string;
+    /**
+     * Condition expression for conditional routing.
+     * Evaluated against the source node's output.
+     * If true (or no condition), the edge is traversed.
+     */
+    condition?: string;
+    /** Artifact mapping for this edge */
+    artifactMapping?: ArtifactMapping;
+    /** Named channel for artifact routing */
+    channel?: string;
+}
+/**
+ * The complete execution graph.
+ */
+export interface ExecutionGraph {
+    /** All nodes in the graph */
+    nodes: Record<string, GraphNode>;
+    /** All edges connecting nodes */
+    edges: GraphEdge[];
+    /** ID of the entry node */
+    entryNode: string;
+    /** IDs of exit nodes (graph completes when one is reached) */
+    exitNodes: string[];
+}
+/**
+ * Default routing rules for artifacts.
+ */
+export interface RoutingRules {
+    /** Default visibility for artifacts */
+    defaultVisibility?: 'private' | 'session' | 'persistent';
+    /** Auto-propagate artifacts along edges */
+    autoPropagateArtifacts?: boolean;
+}
+/**
+ * A coordination mode defines how multiple minds work together.
+ */
+export interface CoordinationMode {
+    /** Mode name */
+    name: string;
+    /** Mode description */
+    description?: string;
+    /** The execution graph */
+    graph: ExecutionGraph;
+    /** Default routing rules */
+    defaultRouting?: RoutingRules;
+}
+/**
+ * Result of graph validation.
+ */
+export interface ValidationResult {
+    /** Whether the graph is valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: string[];
+    /** Validation warnings */
+    warnings: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,wBAAwB;IACxB,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC9B,gDAAgD;IAChD,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAC;IACd,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjC,iCAAiC;IACjC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC;IACzD,2CAA2C;IAC3C,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,KAAK,EAAE,cAAc,CAAC;IACtB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,YAAY,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,wBAAwB;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// ABOUTME: Core types for coordination modes
+// ABOUTME: Defines CoordinationMode, ExecutionGraph, GraphNode, GraphEdge
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,0EAA0E"}

package/dist/validation.d.ts

@@ -0,0 +1,30 @@
+import type { ExecutionGraph, ValidationResult } from './types.js';
+/**
+ * Validate an execution graph for correctness.
+ *
+ * Checks:
+ * - Entry node exists
+ * - All exit nodes exist
+ * - All edges reference valid nodes
+ * - All nodes are reachable from entry
+ * - No infinite cycles (cycles must have exit conditions)
+ *
+ * @param graph - The execution graph to validate
+ * @returns Validation result with errors and warnings
+ */
+export declare function validateGraph(graph: ExecutionGraph): ValidationResult;
+/**
+ * Check if a graph is acyclic.
+ *
+ * @param graph - The execution graph to check
+ * @returns true if the graph has no cycles
+ */
+export declare function isAcyclic(graph: ExecutionGraph): boolean;
+/**
+ * Get topological order of nodes in an acyclic graph.
+ *
+ * @param graph - The execution graph (must be acyclic)
+ * @returns Array of node IDs in topological order, or null if graph has cycles
+ */
+export declare function getTopologicalOrder(graph: ExecutionGraph): string[] | null;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB,CAmDrE;AA8GD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CA4BxD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,EAAE,GAAG,IAAI,CAwD1E"}

package/dist/validation.js

@@ -0,0 +1,236 @@
+// ABOUTME: Graph validation for execution graphs
+// ABOUTME: Validates structure, reachability, and detects problematic cycles
+/**
+ * Validate an execution graph for correctness.
+ *
+ * Checks:
+ * - Entry node exists
+ * - All exit nodes exist
+ * - All edges reference valid nodes
+ * - All nodes are reachable from entry
+ * - No infinite cycles (cycles must have exit conditions)
+ *
+ * @param graph - The execution graph to validate
+ * @returns Validation result with errors and warnings
+ */
+export function validateGraph(graph) {
+    const errors = [];
+    const warnings = [];
+    // Check entry node exists
+    if (!graph.nodes[graph.entryNode]) {
+        errors.push(`Entry node '${graph.entryNode}' not found in nodes`);
+    }
+    // Check exit nodes exist
+    for (const exitNode of graph.exitNodes) {
+        if (!graph.nodes[exitNode]) {
+            errors.push(`Exit node '${exitNode}' not found in nodes`);
+        }
+    }
+    // Check edges reference valid nodes
+    for (const edge of graph.edges) {
+        if (!graph.nodes[edge.from]) {
+            errors.push(`Edge references unknown source node '${edge.from}'`);
+        }
+        if (!graph.nodes[edge.to]) {
+            errors.push(`Edge references unknown target node '${edge.to}'`);
+        }
+    }
+    // Check all nodes are reachable from entry
+    const reachable = findReachableNodes(graph);
+    for (const nodeId of Object.keys(graph.nodes)) {
+        if (!reachable.has(nodeId)) {
+            warnings.push(`Node '${nodeId}' is not reachable from entry node`);
+        }
+    }
+    // Check for infinite cycles
+    const cycleIssues = detectInfiniteCycles(graph);
+    for (const issue of cycleIssues) {
+        errors.push(issue);
+    }
+    // Check that at least one exit node is reachable
+    const hasReachableExit = graph.exitNodes.some((exit) => reachable.has(exit));
+    if (!hasReachableExit && graph.exitNodes.length > 0) {
+        errors.push('No exit node is reachable from entry node');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Find all nodes reachable from the entry node.
+ */
+function findReachableNodes(graph) {
+    const reachable = new Set();
+    const queue = [graph.entryNode];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (reachable.has(current)) {
+            continue;
+        }
+        reachable.add(current);
+        // Find all edges from this node
+        for (const edge of graph.edges) {
+            if (edge.from === current && !reachable.has(edge.to)) {
+                queue.push(edge.to);
+            }
+        }
+        // Self-loops (nodes with maxIterations > 1)
+        const node = graph.nodes[current];
+        if (node?.maxIterations && node.maxIterations > 1) {
+            // Node can loop back to itself
+        }
+    }
+    return reachable;
+}
+/**
+ * Detect cycles that could cause infinite loops.
+ *
+ * A cycle is problematic if:
+ * - It has no conditional edges
+ * - Nodes in the cycle have no exit conditions
+ */
+function detectInfiniteCycles(graph) {
+    const issues = [];
+    const visited = new Set();
+    const recursionStack = new Set();
+    function dfs(nodeId, path) {
+        if (recursionStack.has(nodeId)) {
+            // Found a cycle - check if it's safe
+            const cycleStart = path.indexOf(nodeId);
+            const cycle = path.slice(cycleStart);
+            // Check if any node in the cycle has an exit condition
+            let hasSafeExit = false;
+            for (const cycleNodeId of cycle) {
+                const node = graph.nodes[cycleNodeId];
+                if (node?.exitCondition) {
+                    hasSafeExit = true;
+                    break;
+                }
+                // Check if node has limited iterations
+                if (node?.maxIterations && node.maxIterations > 1 && node.maxIterations < Infinity) {
+                    hasSafeExit = true;
+                    break;
+                }
+            }
+            // Check if any edge in the cycle is conditional
+            for (let i = 0; i < cycle.length; i++) {
+                const from = cycle[i];
+                const to = cycle[(i + 1) % cycle.length];
+                const edge = graph.edges.find((e) => e.from === from && e.to === to);
+                if (edge?.condition) {
+                    hasSafeExit = true;
+                    break;
+                }
+            }
+            if (!hasSafeExit) {
+                issues.push(`Potential infinite cycle detected: ${cycle.join(' -> ')} -> ${nodeId}`);
+            }
+            return;
+        }
+        if (visited.has(nodeId)) {
+            return;
+        }
+        visited.add(nodeId);
+        recursionStack.add(nodeId);
+        // Visit all successors
+        for (const edge of graph.edges) {
+            if (edge.from === nodeId) {
+                dfs(edge.to, [...path, nodeId]);
+            }
+        }
+        recursionStack.delete(nodeId);
+    }
+    // Start DFS from entry node
+    if (graph.nodes[graph.entryNode]) {
+        dfs(graph.entryNode, []);
+    }
+    return issues;
+}
+/**
+ * Check if a graph is acyclic.
+ *
+ * @param graph - The execution graph to check
+ * @returns true if the graph has no cycles
+ */
+export function isAcyclic(graph) {
+    const visited = new Set();
+    const recursionStack = new Set();
+    function hasCycle(nodeId) {
+        if (recursionStack.has(nodeId)) {
+            return true;
+        }
+        if (visited.has(nodeId)) {
+            return false;
+        }
+        visited.add(nodeId);
+        recursionStack.add(nodeId);
+        for (const edge of graph.edges) {
+            if (edge.from === nodeId) {
+                if (hasCycle(edge.to)) {
+                    return true;
+                }
+            }
+        }
+        recursionStack.delete(nodeId);
+        return false;
+    }
+    return !hasCycle(graph.entryNode);
+}
+/**
+ * Get topological order of nodes in an acyclic graph.
+ *
+ * @param graph - The execution graph (must be acyclic)
+ * @returns Array of node IDs in topological order, or null if graph has cycles
+ */
+export function getTopologicalOrder(graph) {
+    if (!isAcyclic(graph)) {
+        return null;
+    }
+    const inDegree = {};
+    const order = [];
+    // Initialize in-degree for all nodes
+    for (const nodeId of Object.keys(graph.nodes)) {
+        inDegree[nodeId] = 0;
+    }
+    // Count in-degrees
+    for (const edge of graph.edges) {
+        const currentDegree = inDegree[edge.to];
+        if (currentDegree !== undefined) {
+            inDegree[edge.to] = currentDegree + 1;
+        }
+    }
+    // Start with nodes that have no incoming edges
+    const queue = [];
+    for (const [nodeId, degree] of Object.entries(inDegree)) {
+        if (degree === 0) {
+            queue.push(nodeId);
+        }
+    }
+    // Process queue
+    while (queue.length > 0) {
+        const current = queue.shift();
+        order.push(current);
+        // Decrease in-degree for successors
+        for (const edge of graph.edges) {
+            if (edge.from === current) {
+                const currentDegree = inDegree[edge.to];
+                if (currentDegree !== undefined) {
+                    const newDegree = currentDegree - 1;
+                    inDegree[edge.to] = newDegree;
+                    if (newDegree === 0) {
+                        queue.push(edge.to);
+                    }
+                }
+            }
+        }
+    }
+    // If we processed all nodes, return order
+    if (order.length === Object.keys(graph.nodes).length) {
+        return order;
+    }
+    // Graph has a cycle (shouldn't happen since we checked isAcyclic)
+    return null;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@inf-minds/coordination-modes",
+  "version": "0.0.1",
+  "description": "Execution graph definitions for multi-mind coordination",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'No linter configured yet'"
+  },
+  "dependencies": {
+    "@inf-minds/mindkit": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// ABOUTME: Coordination modes package entry point
+// ABOUTME: Exports types, validation, and built-in modes
+
+// Type exports
+export type {
+  MindRef,
+  GraphNode,
+  GraphEdge,
+  ExecutionGraph,
+  ArtifactMapping,
+  RoutingRules,
+  CoordinationMode,
+  ValidationResult,
+} from './types.js';
+
+// Validation exports
+export {
+  validateGraph,
+  isAcyclic,
+  getTopologicalOrder,
+} from './validation.js';
+
+// Mode exports
+export {
+  createPipelineMode,
+  type PipelineOptions,
+  type PipelineStep,
+  createManagerWorkersMode,
+  type ManagerWorkersOptions,
+} from './modes/index.js';

package/src/modes/index.ts

@@ -0,0 +1,8 @@
+// ABOUTME: Built-in coordination modes
+// ABOUTME: Exports pipeline and manager-workers mode factories
+
+export { createPipelineMode, type PipelineOptions, type PipelineStep } from './pipeline.js';
+export {
+  createManagerWorkersMode,
+  type ManagerWorkersOptions,
+} from './manager-workers.js';

package/src/modes/manager-workers.ts

@@ -0,0 +1,98 @@
+// ABOUTME: Manager-workers coordination mode
+// ABOUTME: Central manager delegates tasks to workers in a loop
+
+import type { CoordinationMode, MindRef } from '../types.js';
+
+/**
+ * Options for creating a manager-workers mode.
+ */
+export interface ManagerWorkersOptions {
+  /** Name of the mode */
+  name?: string;
+  /** Description of the mode */
+  description?: string;
+  /** Mind for the manager role */
+  managerMind: MindRef;
+  /** Mind for the worker role */
+  workerMind: MindRef;
+  /** Maximum iterations for the manager loop (default: 10) */
+  maxIterations?: number;
+  /**
+   * Exit condition for the manager.
+   * Evaluated against manager's output.
+   * Default: 'output.allTasksComplete'
+   */
+  exitCondition?: string;
+  /**
+   * Delegation condition.
+   * If true, manager delegates to worker.
+   * Default: 'output.delegatedTask'
+   */
+  delegationCondition?: string;
+}
+
+/**
+ * Create a manager-workers coordination mode.
+ *
+ * The manager orchestrates work by delegating tasks to workers.
+ * After each worker completes, control returns to the manager
+ * who decides whether to delegate more work or complete.
+ *
+ * ```
+ *      +--> worker --+
+ *      |             |
+ * --> manager <------+
+ *      |
+ *      +--> [exit when complete]
+ * ```
+ *
+ * @param options - Manager-workers configuration
+ * @returns A CoordinationMode for manager-workers pattern
+ */
+export function createManagerWorkersMode(options: ManagerWorkersOptions): CoordinationMode {
+  const {
+    name = 'manager-workers',
+    description,
+    managerMind,
+    workerMind,
+    maxIterations = 10,
+    exitCondition = 'output.allTasksComplete',
+    delegationCondition = 'output.delegatedTask',
+  } = options;
+
+  return {
+    name,
+    description,
+    graph: {
+      nodes: {
+        manager: {
+          id: 'manager',
+          mind: managerMind,
+          maxIterations,
+          exitCondition,
+        },
+        worker: {
+          id: 'worker',
+          mind: workerMind,
+        },
+      },
+      edges: [
+        {
+          from: 'manager',
+          to: 'worker',
+          condition: delegationCondition,
+        },
+        {
+          from: 'worker',
+          to: 'manager',
+        },
+      ],
+      entryNode: 'manager',
+      exitNodes: ['manager'],
+    },
+    defaultRouting: {
+      defaultVisibility: 'session',
+      autoPropagateArtifacts: true,
+    },
+  };
+}

package/src/modes/pipeline.ts

@@ -0,0 +1,86 @@
+// ABOUTME: Pipeline coordination mode
+// ABOUTME: Sequential execution of minds in a linear chain
+
+import type { CoordinationMode, MindRef, GraphNode, GraphEdge } from '../types.js';
+
+/**
+ * A step in the pipeline.
+ */
+export interface PipelineStep {
+  /** Unique identifier for this step */
+  id: string;
+  /** Mind to execute at this step */
+  mind: MindRef;
+}
+
+/**
+ * Options for creating a pipeline mode.
+ */
+export interface PipelineOptions {
+  /** Name of the pipeline */
+  name?: string;
+  /** Description of the pipeline */
+  description?: string;
+  /** Steps in the pipeline */
+  steps: PipelineStep[];
+}
+
+/**
+ * Create a pipeline coordination mode.
+ *
+ * A pipeline executes minds sequentially, passing artifacts
+ * from one step to the next.
+ *
+ * ```
+ * step1 -> step2 -> step3 -> ... -> stepN
+ * ```
+ *
+ * @param options - Pipeline configuration
+ * @returns A CoordinationMode for sequential execution
+ */
+export function createPipelineMode(options: PipelineOptions): CoordinationMode {
+  const { steps, name = 'pipeline', description } = options;
+
+  if (steps.length === 0) {
+    throw new Error('Pipeline must have at least one step');
+  }
+
+  // Build nodes
+  const nodes: Record<string, GraphNode> = {};
+  for (const step of steps) {
+    nodes[step.id] = {
+      id: step.id,
+      mind: step.mind,
+    };
+  }
+
+  // Build edges (connect each step to the next)
+  const edges: GraphEdge[] = [];
+  for (let i = 0; i < steps.length - 1; i++) {
+    const current = steps[i]!;
+    const next = steps[i + 1]!;
+    edges.push({
+      from: current.id,
+      to: next.id,
+    });
+  }
+
+  // Safe to assert since we checked steps.length > 0
+  const firstStep = steps[0]!;
+  const lastStep = steps[steps.length - 1]!;
+
+  return {
+    name,
+    description,
+    graph: {
+      nodes,
+      edges,
+      entryNode: firstStep.id,
+      exitNodes: [lastStep.id],
+    },
+    defaultRouting: {
+      defaultVisibility: 'session',
+      autoPropagateArtifacts: true,
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,118 @@
+// ABOUTME: Core types for coordination modes
+// ABOUTME: Defines CoordinationMode, ExecutionGraph, GraphNode, GraphEdge
+
+import type { MindConfig } from '@inf-minds/mindkit';
+
+/**
+ * Reference to a mind configuration.
+ * Can be inline (with full config) or registered (by name).
+ */
+export interface MindRef {
+  /** Type of reference */
+  type: 'inline' | 'registered';
+  /** Full mind configuration (for inline type) */
+  config?: MindConfig;
+  /** Name of registered mind type (for registered type) */
+  mindType?: string;
+}
+
+/**
+ * A node in the execution graph.
+ */
+export interface GraphNode {
+  /** Unique identifier for this node */
+  id: string;
+  /** Mind to execute at this node */
+  mind: MindRef;
+  /** Maximum iterations for loops (default: 1) */
+  maxIterations?: number;
+  /**
+   * Exit condition expression.
+   * Evaluated against the node's output.
+   * If true, the node exits normally.
+   * If false and maxIterations not reached, the node re-executes.
+   */
+  exitCondition?: string;
+}
+
+/**
+ * Artifact mapping for edge transitions.
+ */
+export interface ArtifactMapping {
+  /** Path patterns to include */
+  include?: string[];
+  /** Path patterns to exclude */
+  exclude?: string[];
+  /** Rename mappings (from -> to) */
+  rename?: Record<string, string>;
+}
+
+/**
+ * An edge connecting two nodes in the execution graph.
+ */
+export interface GraphEdge {
+  /** Source node ID */
+  from: string;
+  /** Target node ID */
+  to: string;
+  /**
+   * Condition expression for conditional routing.
+   * Evaluated against the source node's output.
+   * If true (or no condition), the edge is traversed.
+   */
+  condition?: string;
+  /** Artifact mapping for this edge */
+  artifactMapping?: ArtifactMapping;
+  /** Named channel for artifact routing */
+  channel?: string;
+}
+
+/**
+ * The complete execution graph.
+ */
+export interface ExecutionGraph {
+  /** All nodes in the graph */
+  nodes: Record<string, GraphNode>;
+  /** All edges connecting nodes */
+  edges: GraphEdge[];
+  /** ID of the entry node */
+  entryNode: string;
+  /** IDs of exit nodes (graph completes when one is reached) */
+  exitNodes: string[];
+}
+
+/**
+ * Default routing rules for artifacts.
+ */
+export interface RoutingRules {
+  /** Default visibility for artifacts */
+  defaultVisibility?: 'private' | 'session' | 'persistent';
+  /** Auto-propagate artifacts along edges */
+  autoPropagateArtifacts?: boolean;
+}
+
+/**
+ * A coordination mode defines how multiple minds work together.
+ */
+export interface CoordinationMode {
+  /** Mode name */
+  name: string;
+  /** Mode description */
+  description?: string;
+  /** The execution graph */
+  graph: ExecutionGraph;
+  /** Default routing rules */
+  defaultRouting?: RoutingRules;
+}
+
+/**
+ * Result of graph validation.
+ */
+export interface ValidationResult {
+  /** Whether the graph is valid */
+  valid: boolean;
+  /** Validation errors */
+  errors: string[];
+  /** Validation warnings */
+  warnings: string[];
+}

package/src/validation.ts

@@ -0,0 +1,278 @@
+// ABOUTME: Graph validation for execution graphs
+// ABOUTME: Validates structure, reachability, and detects problematic cycles
+
+import type { ExecutionGraph, ValidationResult } from './types.js';
+
+/**
+ * Validate an execution graph for correctness.
+ *
+ * Checks:
+ * - Entry node exists
+ * - All exit nodes exist
+ * - All edges reference valid nodes
+ * - All nodes are reachable from entry
+ * - No infinite cycles (cycles must have exit conditions)
+ *
+ * @param graph - The execution graph to validate
+ * @returns Validation result with errors and warnings
+ */
+export function validateGraph(graph: ExecutionGraph): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Check entry node exists
+  if (!graph.nodes[graph.entryNode]) {
+    errors.push(`Entry node '${graph.entryNode}' not found in nodes`);
+  }
+
+  // Check exit nodes exist
+  for (const exitNode of graph.exitNodes) {
+    if (!graph.nodes[exitNode]) {
+      errors.push(`Exit node '${exitNode}' not found in nodes`);
+    }
+  }
+
+  // Check edges reference valid nodes
+  for (const edge of graph.edges) {
+    if (!graph.nodes[edge.from]) {
+      errors.push(`Edge references unknown source node '${edge.from}'`);
+    }
+    if (!graph.nodes[edge.to]) {
+      errors.push(`Edge references unknown target node '${edge.to}'`);
+    }
+  }
+
+  // Check all nodes are reachable from entry
+  const reachable = findReachableNodes(graph);
+  for (const nodeId of Object.keys(graph.nodes)) {
+    if (!reachable.has(nodeId)) {
+      warnings.push(`Node '${nodeId}' is not reachable from entry node`);
+    }
+  }
+
+  // Check for infinite cycles
+  const cycleIssues = detectInfiniteCycles(graph);
+  for (const issue of cycleIssues) {
+    errors.push(issue);
+  }
+
+  // Check that at least one exit node is reachable
+  const hasReachableExit = graph.exitNodes.some((exit) => reachable.has(exit));
+  if (!hasReachableExit && graph.exitNodes.length > 0) {
+    errors.push('No exit node is reachable from entry node');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Find all nodes reachable from the entry node.
+ */
+function findReachableNodes(graph: ExecutionGraph): Set<string> {
+  const reachable = new Set<string>();
+  const queue: string[] = [graph.entryNode];
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+
+    if (reachable.has(current)) {
+      continue;
+    }
+
+    reachable.add(current);
+
+    // Find all edges from this node
+    for (const edge of graph.edges) {
+      if (edge.from === current && !reachable.has(edge.to)) {
+        queue.push(edge.to);
+      }
+    }
+
+    // Self-loops (nodes with maxIterations > 1)
+    const node = graph.nodes[current];
+    if (node?.maxIterations && node.maxIterations > 1) {
+      // Node can loop back to itself
+    }
+  }
+
+  return reachable;
+}
+
+/**
+ * Detect cycles that could cause infinite loops.
+ *
+ * A cycle is problematic if:
+ * - It has no conditional edges
+ * - Nodes in the cycle have no exit conditions
+ */
+function detectInfiniteCycles(graph: ExecutionGraph): string[] {
+  const issues: string[] = [];
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+
+  function dfs(nodeId: string, path: string[]): void {
+    if (recursionStack.has(nodeId)) {
+      // Found a cycle - check if it's safe
+      const cycleStart = path.indexOf(nodeId);
+      const cycle = path.slice(cycleStart);
+
+      // Check if any node in the cycle has an exit condition
+      let hasSafeExit = false;
+      for (const cycleNodeId of cycle) {
+        const node = graph.nodes[cycleNodeId];
+        if (node?.exitCondition) {
+          hasSafeExit = true;
+          break;
+        }
+        // Check if node has limited iterations
+        if (node?.maxIterations && node.maxIterations > 1 && node.maxIterations < Infinity) {
+          hasSafeExit = true;
+          break;
+        }
+      }
+
+      // Check if any edge in the cycle is conditional
+      for (let i = 0; i < cycle.length; i++) {
+        const from = cycle[i];
+        const to = cycle[(i + 1) % cycle.length];
+        const edge = graph.edges.find((e) => e.from === from && e.to === to);
+        if (edge?.condition) {
+          hasSafeExit = true;
+          break;
+        }
+      }
+
+      if (!hasSafeExit) {
+        issues.push(`Potential infinite cycle detected: ${cycle.join(' -> ')} -> ${nodeId}`);
+      }
+      return;
+    }
+
+    if (visited.has(nodeId)) {
+      return;
+    }
+
+    visited.add(nodeId);
+    recursionStack.add(nodeId);
+
+    // Visit all successors
+    for (const edge of graph.edges) {
+      if (edge.from === nodeId) {
+        dfs(edge.to, [...path, nodeId]);
+      }
+    }
+
+    recursionStack.delete(nodeId);
+  }
+
+  // Start DFS from entry node
+  if (graph.nodes[graph.entryNode]) {
+    dfs(graph.entryNode, []);
+  }
+
+  return issues;
+}
+
+/**
+ * Check if a graph is acyclic.
+ *
+ * @param graph - The execution graph to check
+ * @returns true if the graph has no cycles
+ */
+export function isAcyclic(graph: ExecutionGraph): boolean {
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+
+  function hasCycle(nodeId: string): boolean {
+    if (recursionStack.has(nodeId)) {
+      return true;
+    }
+    if (visited.has(nodeId)) {
+      return false;
+    }
+
+    visited.add(nodeId);
+    recursionStack.add(nodeId);
+
+    for (const edge of graph.edges) {
+      if (edge.from === nodeId) {
+        if (hasCycle(edge.to)) {
+          return true;
+        }
+      }
+    }
+
+    recursionStack.delete(nodeId);
+    return false;
+  }
+
+  return !hasCycle(graph.entryNode);
+}
+
+/**
+ * Get topological order of nodes in an acyclic graph.
+ *
+ * @param graph - The execution graph (must be acyclic)
+ * @returns Array of node IDs in topological order, or null if graph has cycles
+ */
+export function getTopologicalOrder(graph: ExecutionGraph): string[] | null {
+  if (!isAcyclic(graph)) {
+    return null;
+  }
+
+  const inDegree: Record<string, number> = {};
+  const order: string[] = [];
+
+  // Initialize in-degree for all nodes
+  for (const nodeId of Object.keys(graph.nodes)) {
+    inDegree[nodeId] = 0;
+  }
+
+  // Count in-degrees
+  for (const edge of graph.edges) {
+    const currentDegree = inDegree[edge.to];
+    if (currentDegree !== undefined) {
+      inDegree[edge.to] = currentDegree + 1;
+    }
+  }
+
+  // Start with nodes that have no incoming edges
+  const queue: string[] = [];
+  for (const [nodeId, degree] of Object.entries(inDegree)) {
+    if (degree === 0) {
+      queue.push(nodeId);
+    }
+  }
+
+  // Process queue
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    order.push(current);
+
+    // Decrease in-degree for successors
+    for (const edge of graph.edges) {
+      if (edge.from === current) {
+        const currentDegree = inDegree[edge.to];
+        if (currentDegree !== undefined) {
+          const newDegree = currentDegree - 1;
+          inDegree[edge.to] = newDegree;
+          if (newDegree === 0) {
+            queue.push(edge.to);
+          }
+        }
+      }
+    }
+  }
+
+  // If we processed all nodes, return order
+  if (order.length === Object.keys(graph.nodes).length) {
+    return order;
+  }
+
+  // Graph has a cycle (shouldn't happen since we checked isAcyclic)
+  return null;
+}