confused-ai-core 0.1.0

package/src/execution/graph-builder.ts

@@ -0,0 +1,362 @@
+/**
+ * Execution Graph Builder
+ *
+ * Builds and manages execution graphs for task dependency resolution
+ */
+
+import {
+    ExecutionGraph,
+    ExecutionNode,
+    ExecutionNodeStatus,
+} from './types.js';
+import {
+    Plan,
+} from '../planner/types.js';
+import type { EntityId } from '../core/types.js';
+
+/**
+ * Options for building an execution graph
+ */
+export interface GraphBuildOptions {
+    readonly validateDependencies?: boolean;
+    readonly detectCycles?: boolean;
+}
+
+/**
+ * Graph validation error
+ */
+export class GraphValidationError extends Error {
+    constructor(message: string, public readonly details: unknown) {
+        super(message);
+        this.name = 'GraphValidationError';
+    }
+}
+
+/**
+ * Mutable execution graph for internal use
+ */
+interface MutableExecutionGraph extends ExecutionGraph {
+    nodes: Map<EntityId, MutableExecutionNode>;
+    readyQueue: EntityId[];
+    completedCount: number;
+    failedCount: number;
+}
+
+/**
+ * Mutable execution node for internal use
+ */
+interface MutableExecutionNode extends ExecutionNode {
+    status: ExecutionNodeStatus;
+    dependencies: Set<EntityId>;
+    dependents: Set<EntityId>;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+
+/**
+ * Execution graph builder
+ */
+export class ExecutionGraphBuilder {
+    private options: Required<GraphBuildOptions>;
+
+    constructor(options: GraphBuildOptions = {}) {
+        this.options = {
+            validateDependencies: true,
+            detectCycles: true,
+            ...options,
+        };
+    }
+
+    /**
+     * Build an execution graph from a plan
+     */
+    build(plan: Plan): ExecutionGraph {
+        const nodes = new Map<EntityId, MutableExecutionNode>();
+        const readyQueue: EntityId[] = [];
+
+        // Create nodes for all tasks
+        for (const task of plan.tasks) {
+            const node: MutableExecutionNode = {
+                task,
+                status: ExecutionNodeStatus.PENDING,
+                dependencies: new Set(task.dependencies),
+                dependents: new Set(),
+            };
+            nodes.set(task.id, node);
+
+            // Add to ready queue if no dependencies
+            if (task.dependencies.length === 0) {
+                readyQueue.push(task.id);
+            }
+        }
+
+        // Build reverse dependency map (dependents)
+        for (const [id, node] of nodes) {
+            for (const depId of node.dependencies) {
+                const depNode = nodes.get(depId);
+                if (depNode) {
+                    depNode.dependents.add(id);
+                } else if (this.options.validateDependencies) {
+                    throw new GraphValidationError(
+                        `Task ${id} has unknown dependency: ${depId}`,
+                        { taskId: id, dependencyId: depId }
+                    );
+                }
+            }
+        }
+
+        // Detect cycles if enabled
+        if (this.options.detectCycles) {
+            const cycle = this.detectCycle(nodes);
+            if (cycle) {
+                throw new GraphValidationError(
+                    `Circular dependency detected: ${cycle.join(' -> ')}`,
+                    { cycle }
+                );
+            }
+        }
+
+        const graph: MutableExecutionGraph = {
+            planId: plan.id,
+            nodes,
+            readyQueue,
+            completedCount: 0,
+            failedCount: 0,
+            totalCount: plan.tasks.length,
+        };
+
+        return graph as ExecutionGraph;
+    }
+
+    /**
+     * Detect cycles in the graph using DFS
+     */
+    private detectCycle(nodes: Map<EntityId, MutableExecutionNode>): EntityId[] | null {
+        const visited = new Set<EntityId>();
+        const recursionStack = new Set<EntityId>();
+        const path: EntityId[] = [];
+
+        const dfs = (nodeId: EntityId): EntityId[] | null => {
+            visited.add(nodeId);
+            recursionStack.add(nodeId);
+            path.push(nodeId);
+
+            const node = nodes.get(nodeId);
+            if (node) {
+                for (const dependentId of node.dependents) {
+                    if (!visited.has(dependentId)) {
+                        const cycle = dfs(dependentId);
+                        if (cycle) return cycle;
+                    } else if (recursionStack.has(dependentId)) {
+                        // Found a cycle
+                        const cycleStart = path.indexOf(dependentId);
+                        return [...path.slice(cycleStart), dependentId];
+                    }
+                }
+            }
+
+            path.pop();
+            recursionStack.delete(nodeId);
+            return null;
+        };
+
+        for (const nodeId of nodes.keys()) {
+            if (!visited.has(nodeId)) {
+                const cycle = dfs(nodeId);
+                if (cycle) return cycle;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Get tasks that are ready to execute (all dependencies completed)
+     */
+    getReadyTasks(graph: ExecutionGraph): EntityId[] {
+        const ready: EntityId[] = [];
+        const mutableGraph = graph as MutableExecutionGraph;
+
+        for (const [id, node] of mutableGraph.nodes) {
+            if (node.status !== ExecutionNodeStatus.PENDING) {
+                continue;
+            }
+
+            const allDepsCompleted = Array.from(node.dependencies).every(depId => {
+                const depNode = mutableGraph.nodes.get(depId);
+                return depNode?.status === ExecutionNodeStatus.COMPLETED;
+            });
+
+            if (allDepsCompleted) {
+                ready.push(id);
+            }
+        }
+
+        return ready;
+    }
+
+    /**
+     * Update node status and propagate to dependents
+     */
+    updateNodeStatus(
+        graph: ExecutionGraph,
+        nodeId: EntityId,
+        status: ExecutionNodeStatus
+    ): void {
+        const mutableGraph = graph as MutableExecutionGraph;
+        const node = mutableGraph.nodes.get(nodeId);
+        if (!node) {
+            return;
+        }
+
+        node.status = status;
+
+        // Update counters
+        if (status === ExecutionNodeStatus.COMPLETED) {
+            mutableGraph.completedCount++;
+        } else if (status === ExecutionNodeStatus.FAILED) {
+            mutableGraph.failedCount++;
+        }
+
+        // If completed or failed, check dependents
+        if (status === ExecutionNodeStatus.COMPLETED || status === ExecutionNodeStatus.FAILED) {
+            node.completedAt = new Date();
+
+            // Add ready dependents to queue
+            for (const dependentId of node.dependents) {
+                const dependent = mutableGraph.nodes.get(dependentId);
+                if (dependent && dependent.status === ExecutionNodeStatus.PENDING) {
+                    const allDepsCompleted = Array.from(dependent.dependencies).every(depId => {
+                        const depNode = mutableGraph.nodes.get(depId);
+                        return depNode?.status === ExecutionNodeStatus.COMPLETED;
+                    });
+
+                    if (allDepsCompleted && !mutableGraph.readyQueue.includes(dependentId)) {
+                        mutableGraph.readyQueue.push(dependentId);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Get the execution order (topological sort)
+     */
+    getExecutionOrder(graph: ExecutionGraph): EntityId[] {
+        const order: EntityId[] = [];
+        const visited = new Set<EntityId>();
+        const temp = new Set<EntityId>();
+        const mutableGraph = graph as MutableExecutionGraph;
+
+        const visit = (nodeId: EntityId): void => {
+            if (temp.has(nodeId)) {
+                throw new GraphValidationError('Cycle detected during topological sort', { nodeId });
+            }
+
+            if (visited.has(nodeId)) {
+                return;
+            }
+
+            temp.add(nodeId);
+            const node = mutableGraph.nodes.get(nodeId);
+
+            if (node) {
+                for (const depId of node.dependencies) {
+                    visit(depId);
+                }
+            }
+
+            temp.delete(nodeId);
+            visited.add(nodeId);
+            order.push(nodeId);
+        };
+
+        for (const nodeId of mutableGraph.nodes.keys()) {
+            if (!visited.has(nodeId)) {
+                visit(nodeId);
+            }
+        }
+
+        return order;
+    }
+
+    /**
+     * Clone a graph
+     */
+    clone(graph: ExecutionGraph): ExecutionGraph {
+        const mutableGraph = graph as MutableExecutionGraph;
+        const newNodes = new Map<EntityId, MutableExecutionNode>();
+
+        for (const [id, node] of mutableGraph.nodes) {
+            newNodes.set(id, {
+                task: node.task,
+                status: node.status,
+                dependencies: new Set(node.dependencies),
+                dependents: new Set(node.dependents),
+                result: node.result,
+                startedAt: node.startedAt,
+                completedAt: node.completedAt,
+            });
+        }
+
+        const newGraph: MutableExecutionGraph = {
+            planId: mutableGraph.planId,
+            nodes: newNodes,
+            readyQueue: [...mutableGraph.readyQueue],
+            completedCount: mutableGraph.completedCount,
+            failedCount: mutableGraph.failedCount,
+            totalCount: mutableGraph.totalCount,
+        };
+
+        return newGraph as ExecutionGraph;
+    }
+
+    /**
+     * Get graph statistics
+     */
+    getStats(graph: ExecutionGraph): {
+        total: number;
+        pending: number;
+        running: number;
+        completed: number;
+        failed: number;
+        cancelled: number;
+    } {
+        const mutableGraph = graph as MutableExecutionGraph;
+        let pending = 0;
+        let running = 0;
+        let completed = 0;
+        let failed = 0;
+        let cancelled = 0;
+
+        for (const node of mutableGraph.nodes.values()) {
+            switch (node.status) {
+                case ExecutionNodeStatus.PENDING:
+                case ExecutionNodeStatus.READY:
+                    pending++;
+                    break;
+                case ExecutionNodeStatus.RUNNING:
+                    running++;
+                    break;
+                case ExecutionNodeStatus.COMPLETED:
+                    completed++;
+                    break;
+                case ExecutionNodeStatus.FAILED:
+                    failed++;
+                    break;
+                case ExecutionNodeStatus.CANCELLED:
+                    cancelled++;
+                    break;
+            }
+        }
+
+        return {
+            total: mutableGraph.totalCount,
+            pending,
+            running,
+            completed,
+            failed,
+            cancelled,
+        };
+    }
+}

package/src/execution/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Execution module exports
+ */
+
+export * from './types.js';
+export { ExecutionEngineImpl } from './engine.js';
+export { ExecutionGraphBuilder } from './graph-builder.js';
+export { WorkerPool } from './worker-pool.js';

package/src/execution/types.ts

@@ -0,0 +1,257 @@
+/**
+ * Execution engine types and interfaces
+ */
+
+import type { EntityId } from '../core/types.js';
+import type { Task, TaskResult, Plan, PlanExecutionResult } from '../planner/types.js';
+
+/**
+ * Execution engine configuration
+ */
+export interface ExecutionEngineConfig {
+    readonly maxConcurrency: number;
+    readonly defaultTimeoutMs: number;
+    readonly enableParallelExecution: boolean;
+    readonly workerPoolSize?: number;
+    readonly retryPolicy?: ExecutionRetryPolicy;
+}
+
+/**
+ * Execution retry policy
+ */
+export interface ExecutionRetryPolicy {
+    readonly maxRetries: number;
+    readonly backoffStrategy: BackoffStrategy;
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+}
+
+/**
+ * Backoff strategies
+ */
+export enum BackoffStrategy {
+    FIXED = 'fixed',
+    LINEAR = 'linear',
+    EXPONENTIAL = 'exponential',
+}
+
+/**
+ * Execution context passed to tasks
+ */
+export interface ExecutionContext {
+    readonly executionId: EntityId;
+    readonly taskId: EntityId;
+    readonly planId: EntityId;
+    readonly inputs: Map<EntityId, unknown>;
+    readonly sharedState: Map<string, unknown>;
+    readonly metadata: TaskExecutionMetadata;
+}
+
+/**
+ * Task execution metadata
+ */
+export interface TaskExecutionMetadata {
+    readonly startedAt: Date;
+    readonly timeoutAt?: Date;
+    readonly attemptNumber: number;
+    readonly previousAttempts?: TaskResult[];
+}
+
+/**
+ * Task executor interface
+ */
+export interface TaskExecutor {
+    /**
+     * Execute a single task
+     */
+    execute(task: Task, context: ExecutionContext): Promise<TaskResult>;
+
+    /**
+     * Check if this executor can handle the task
+     */
+    canExecute(task: Task): boolean;
+}
+
+/**
+ * Execution graph node
+ */
+export interface ExecutionNode {
+    readonly task: Task;
+    readonly status: ExecutionNodeStatus;
+    readonly dependencies: Set<EntityId>;
+    readonly dependents: Set<EntityId>;
+    readonly result?: TaskResult;
+    readonly startedAt?: Date;
+    readonly completedAt?: Date;
+}
+
+/**
+ * Execution node status
+ */
+export enum ExecutionNodeStatus {
+    PENDING = 'pending',
+    READY = 'ready',
+    RUNNING = 'running',
+    COMPLETED = 'completed',
+    FAILED = 'failed',
+    CANCELLED = 'cancelled',
+}
+
+/**
+ * Execution graph representing task dependencies
+ */
+export interface ExecutionGraph {
+    readonly planId: EntityId;
+    readonly nodes: Map<EntityId, ExecutionNode>;
+    readonly readyQueue: EntityId[];
+    readonly completedCount: number;
+    readonly failedCount: number;
+    readonly totalCount: number;
+}
+
+/**
+ * Execution engine interface
+ */
+export interface ExecutionEngine {
+    /**
+     * Execute a plan
+     */
+    execute(plan: Plan, options?: ExecutionOptions): Promise<PlanExecutionResult>;
+
+    /**
+     * Cancel an ongoing execution
+     */
+    cancel(executionId: EntityId): Promise<boolean>;
+
+    /**
+     * Get execution status
+     */
+    getStatus(executionId: EntityId): ExecutionStatus | undefined;
+
+    /**
+     * Register a task executor
+     */
+    registerExecutor(executor: TaskExecutor): void;
+
+    /**
+     * Subscribe to execution events
+     */
+    on(event: ExecutionEventType, handler: ExecutionEventHandler): void;
+
+    /**
+     * Unsubscribe from execution events
+     */
+    off(event: ExecutionEventType, handler: ExecutionEventHandler): void;
+}
+
+/**
+ * Execution options
+ */
+export interface ExecutionOptions {
+    readonly executionId?: EntityId;
+    readonly timeoutMs?: number;
+    readonly onTaskStart?: (taskId: EntityId) => void;
+    readonly onTaskComplete?: (taskId: EntityId, result: TaskResult) => void;
+    readonly onTaskError?: (taskId: EntityId, error: Error) => void;
+}
+
+/**
+ * Execution status
+ */
+export interface ExecutionStatus {
+    readonly executionId: EntityId;
+    readonly planId: EntityId;
+    readonly state: ExecutionState;
+    readonly progress: ExecutionProgress;
+    readonly currentTasks: EntityId[];
+    readonly startedAt: Date;
+    readonly estimatedCompletionAt?: Date;
+}
+
+/**
+ * Execution state
+ */
+export enum ExecutionState {
+    PENDING = 'pending',
+    RUNNING = 'running',
+    PAUSED = 'paused',
+    COMPLETED = 'completed',
+    FAILED = 'failed',
+    CANCELLED = 'cancelled',
+}
+
+/**
+ * Execution progress
+ */
+export interface ExecutionProgress {
+    readonly total: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly pending: number;
+    readonly running: number;
+    readonly percentage: number;
+}
+
+/**
+ * Execution event types
+ */
+export type ExecutionEventType =
+    | 'execution:start'
+    | 'execution:complete'
+    | 'execution:fail'
+    | 'execution:cancel'
+    | 'task:start'
+    | 'task:complete'
+    | 'task:fail'
+    | 'task:retry';
+
+/**
+ * Execution event handler
+ */
+export type ExecutionEventHandler = (event: ExecutionEvent) => void;
+
+/**
+ * Execution event
+ */
+export interface ExecutionEvent {
+    readonly type: ExecutionEventType;
+    readonly executionId: EntityId;
+    readonly timestamp: Date;
+    readonly data: unknown;
+}
+
+/**
+ * Worker pool configuration
+ */
+export interface WorkerPoolConfig {
+    readonly minWorkers: number;
+    readonly maxWorkers: number;
+    readonly idleTimeoutMs: number;
+    readonly taskTimeoutMs: number;
+}
+
+/**
+ * Parallel executor interface
+ */
+export interface ParallelExecutor {
+    /**
+     * Execute multiple independent tasks in parallel
+     */
+    executeParallel(tasks: Task[], context: ExecutionContext): Promise<TaskResult[]>;
+
+    /**
+     * Get current pool status
+     */
+    getPoolStatus(): WorkerPoolStatus;
+}
+
+/**
+ * Worker pool status
+ */
+export interface WorkerPoolStatus {
+    readonly totalWorkers: number;
+    readonly activeWorkers: number;
+    readonly idleWorkers: number;
+    readonly pendingTasks: number;
+    readonly completedTasks: number;
+}