confused-ai-core 0.1.0

package/src/planner/validator.ts

@@ -0,0 +1,297 @@
+/**
+ * Plan validator implementation
+ */
+
+import {
+    ValidationResult,
+    ValidationError,
+    Plan,
+    Task,
+    TaskStatus,
+} from './types.js';
+import type { EntityId } from '../core/types.js';
+
+/**
+ * Plan validator with comprehensive checks
+ */
+export class PlanValidator {
+    private customRules: ValidationRule[] = [];
+
+    /**
+     * Validate a plan comprehensively
+     */
+    validate(plan: Plan): ValidationResult {
+        const errors: ValidationError[] = [];
+
+        // Check for empty plan
+        if (plan.tasks.length === 0) {
+            errors.push({
+                message: 'Plan contains no tasks',
+                severity: 'error',
+            });
+        }
+
+        // Check for duplicate task IDs
+        errors.push(...this.checkDuplicateIds(plan.tasks));
+
+        // Check for circular dependencies
+        errors.push(...this.checkCircularDependencies(plan.tasks));
+
+        // Check for orphaned tasks
+        errors.push(...this.checkOrphanedTasks(plan.tasks));
+
+        // Check for missing dependencies
+        errors.push(...this.checkMissingDependencies(plan.tasks));
+
+        // Check task validity
+        for (const task of plan.tasks) {
+            errors.push(...this.validateTask(task));
+        }
+
+        // Apply custom rules
+        for (const rule of this.customRules) {
+            const ruleErrors = rule(plan);
+            errors.push(...ruleErrors);
+        }
+
+        return {
+            valid: errors.filter(e => e.severity === 'error').length === 0,
+            errors,
+        };
+    }
+
+    /**
+     * Add a custom validation rule
+     */
+    addRule(rule: ValidationRule): void {
+        this.customRules.push(rule);
+    }
+
+    /**
+     * Remove a custom validation rule
+     */
+    removeRule(rule: ValidationRule): void {
+        const index = this.customRules.indexOf(rule);
+        if (index > -1) {
+            this.customRules.splice(index, 1);
+        }
+    }
+
+    /**
+     * Check for duplicate task IDs
+     */
+    private checkDuplicateIds(tasks: Task[]): ValidationError[] {
+        const errors: ValidationError[] = [];
+        const seenIds = new Set<EntityId>();
+
+        for (const task of tasks) {
+            if (seenIds.has(task.id)) {
+                errors.push({
+                    taskId: task.id,
+                    message: `Duplicate task ID: ${task.id}`,
+                    severity: 'error',
+                });
+            }
+            seenIds.add(task.id);
+        }
+
+        return errors;
+    }
+
+    /**
+     * Check for circular dependencies using DFS
+     */
+    private checkCircularDependencies(tasks: Task[]): ValidationError[] {
+        const errors: ValidationError[] = [];
+        const visited = new Set<EntityId>();
+        const recursionStack = new Set<EntityId>();
+
+        const hasCycle = (taskId: EntityId, path: EntityId[], taskMap: Map<EntityId, Task>): boolean => {
+            visited.add(taskId);
+            recursionStack.add(taskId);
+
+            const task = taskMap.get(taskId);
+            if (task) {
+                for (const depId of task.dependencies) {
+                    if (!visited.has(depId)) {
+                        if (hasCycle(depId, [...path, depId], taskMap)) {
+                            return true;
+                        }
+                    } else if (recursionStack.has(depId)) {
+                        // Found cycle
+                        const cycleStart = path.indexOf(depId);
+                        const cycle = path.slice(cycleStart).concat([taskId]);
+                        errors.push({
+                            taskId,
+                            message: `Circular dependency detected: ${cycle.join(' -> ')}`,
+                            severity: 'error',
+                        });
+                        return true;
+                    }
+                }
+            }
+
+            recursionStack.delete(taskId);
+            return false;
+        };
+
+        for (const task of tasks) {
+            if (!visited.has(task.id)) {
+                // Create task map for cycle detection
+                const taskMapForCycle = new Map(tasks.map(t => [t.id, t]));
+                hasCycle(task.id, [task.id], taskMapForCycle);
+            }
+        }
+
+        return errors;
+    }
+
+    /**
+     * Check for orphaned tasks (tasks not reachable from any root)
+     */
+    private checkOrphanedTasks(tasks: Task[]): ValidationError[] {
+        const errors: ValidationError[] = [];
+        const reachable = new Set<EntityId>();
+
+        // Find all root tasks (no dependencies)
+        const roots = tasks.filter(t => t.dependencies.length === 0);
+
+        // BFS from roots to find all reachable tasks
+        const queue = [...roots];
+        while (queue.length > 0) {
+            const task = queue.shift()!;
+            reachable.add(task.id);
+
+            // Find tasks that depend on this task
+            for (const otherTask of tasks) {
+                if (otherTask.dependencies.includes(task.id) && !reachable.has(otherTask.id)) {
+                    queue.push(otherTask);
+                }
+            }
+        }
+
+        // Check for unreachable tasks
+        for (const task of tasks) {
+            if (!reachable.has(task.id)) {
+                errors.push({
+                    taskId: task.id,
+                    message: `Orphaned task: ${task.name} is not reachable from any root task`,
+                    severity: 'warning',
+                });
+            }
+        }
+
+        return errors;
+    }
+
+    /**
+     * Check for missing dependencies
+     */
+    private checkMissingDependencies(tasks: Task[]): ValidationError[] {
+        const errors: ValidationError[] = [];
+        const taskIds = new Set(tasks.map(t => t.id));
+
+        for (const task of tasks) {
+            for (const depId of task.dependencies) {
+                if (!taskIds.has(depId)) {
+                    errors.push({
+                        taskId: task.id,
+                        message: `Missing dependency: ${depId} does not exist in the plan`,
+                        severity: 'error',
+                    });
+                }
+            }
+        }
+
+        return errors;
+    }
+
+    /**
+     * Validate a single task
+     */
+    private validateTask(task: Task): ValidationError[] {
+        const errors: ValidationError[] = [];
+
+        // Check name
+        if (!task.name || task.name.trim().length === 0) {
+            errors.push({
+                taskId: task.id,
+                message: 'Task name is required',
+                severity: 'error',
+            });
+        } else if (task.name.length > 100) {
+            errors.push({
+                taskId: task.id,
+                message: 'Task name exceeds 100 characters',
+                severity: 'warning',
+            });
+        }
+
+        // Check description
+        if (!task.description || task.description.trim().length === 0) {
+            errors.push({
+                taskId: task.id,
+                message: 'Task description is required',
+                severity: 'warning',
+            });
+        }
+
+        // Check estimated duration
+        if (task.estimatedDurationMs !== undefined) {
+            if (task.estimatedDurationMs <= 0) {
+                errors.push({
+                    taskId: task.id,
+                    message: 'Estimated duration must be positive',
+                    severity: 'error',
+                });
+            } else if (task.estimatedDurationMs > 86400000) { // 24 hours
+                errors.push({
+                    taskId: task.id,
+                    message: 'Estimated duration exceeds 24 hours, consider breaking into smaller tasks',
+                    severity: 'warning',
+                });
+            }
+        }
+
+        // Check metadata
+        if (task.metadata.maxRetries !== undefined && task.metadata.maxRetries < 0) {
+            errors.push({
+                taskId: task.id,
+                message: 'Max retries must be non-negative',
+                severity: 'error',
+            });
+        }
+
+        if (task.metadata.timeoutMs !== undefined && task.metadata.timeoutMs <= 0) {
+            errors.push({
+                taskId: task.id,
+                message: 'Timeout must be positive',
+                severity: 'error',
+            });
+        }
+
+        return errors;
+    }
+
+    /**
+     * Validate task execution result
+     */
+    validateTaskResult(task: Task, result: { status: TaskStatus; error?: { message: string } }): ValidationError[] {
+        const errors: ValidationError[] = [];
+
+        if (result.status === TaskStatus.FAILED && !result.error) {
+            errors.push({
+                taskId: task.id,
+                message: 'Failed task result must include error information',
+                severity: 'error',
+            });
+        }
+
+        return errors;
+    }
+}
+
+/**
+ * Custom validation rule type
+ */
+type ValidationRule = (plan: Plan) => ValidationError[];

package/src/production/circuit-breaker.ts

@@ -0,0 +1,290 @@
+/**
+ * Circuit Breaker Pattern - Agno-style Production Resilience
+ *
+ * Prevents cascading failures by tracking error rates and temporarily
+ * blocking calls to failing services. Supports:
+ * - Configurable failure thresholds
+ * - Automatic recovery with half-open state
+ * - Metrics integration for observability
+ * - Event callbacks for monitoring
+ */
+
+import type { MetricsCollector } from '../observability/types.js';
+
+/** Circuit breaker states */
+export enum CircuitState {
+    /** Normal operation - requests pass through */
+    CLOSED = 'CLOSED',
+    /** Circuit tripped - requests are rejected immediately */
+    OPEN = 'OPEN',
+    /** Testing recovery - limited requests allowed */
+    HALF_OPEN = 'HALF_OPEN',
+}
+
+/** Circuit breaker configuration */
+export interface CircuitBreakerConfig {
+    /** Unique name for this circuit (for metrics/logging) */
+    readonly name: string;
+    /** Number of failures before opening circuit (default: 5) */
+    readonly failureThreshold?: number;
+    /** Number of successes in half-open before closing (default: 2) */
+    readonly successThreshold?: number;
+    /** Time in ms before attempting recovery (default: 30000) */
+    readonly resetTimeoutMs?: number;
+    /** Time window in ms for counting failures (default: 60000) */
+    readonly failureWindowMs?: number;
+    /** Optional metrics collector for observability */
+    readonly metrics?: MetricsCollector;
+    /** Callback when state changes */
+    readonly onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+
+/** Circuit breaker execution result */
+export interface CircuitBreakerResult<T> {
+    readonly success: boolean;
+    readonly value?: T;
+    readonly error?: Error;
+    readonly state: CircuitState;
+    readonly executionTimeMs: number;
+}
+
+/** Error thrown when circuit is open */
+export class CircuitOpenError extends Error {
+    readonly circuitName: string;
+    readonly state: CircuitState;
+    readonly resetAt: Date;
+
+    constructor(name: string, resetAt: Date) {
+        super(`Circuit '${name}' is OPEN. Retry after ${resetAt.toISOString()}`);
+        this.name = 'CircuitOpenError';
+        this.circuitName = name;
+        this.state = CircuitState.OPEN;
+        this.resetAt = resetAt;
+        Object.setPrototypeOf(this, CircuitOpenError.prototype);
+    }
+}
+
+/** Failure record for sliding window */
+interface FailureRecord {
+    readonly timestamp: number;
+    readonly error: Error;
+}
+
+/**
+ * Circuit Breaker implementation with sliding window failure tracking.
+ *
+ * @example
+ * const breaker = new CircuitBreaker({
+ *   name: 'openai-api',
+ *   failureThreshold: 5,
+ *   resetTimeoutMs: 30000,
+ * });
+ *
+ * const result = await breaker.execute(() => openai.chat(...));
+ * if (result.success) {
+ *   console.log(result.value);
+ * } else {
+ *   console.error('Blocked or failed:', result.error);
+ * }
+ */
+export class CircuitBreaker {
+    private state: CircuitState = CircuitState.CLOSED;
+    private failures: FailureRecord[] = [];
+    private successCount = 0;
+    private lastFailureTime = 0;
+    private openedAt = 0;
+
+    private readonly config: Required<
+        Omit<CircuitBreakerConfig, 'metrics' | 'onStateChange'>
+    > & Pick<CircuitBreakerConfig, 'metrics' | 'onStateChange'>;
+
+    constructor(config: CircuitBreakerConfig) {
+        this.config = {
+            name: config.name,
+            failureThreshold: config.failureThreshold ?? 5,
+            successThreshold: config.successThreshold ?? 2,
+            resetTimeoutMs: config.resetTimeoutMs ?? 30_000,
+            failureWindowMs: config.failureWindowMs ?? 60_000,
+            metrics: config.metrics,
+            onStateChange: config.onStateChange,
+        };
+    }
+
+    /** Get current circuit state */
+    getState(): CircuitState {
+        return this.state;
+    }
+
+    /** Get circuit name */
+    getName(): string {
+        return this.config.name;
+    }
+
+    /** Check if circuit allows requests */
+    isAllowed(): boolean {
+        this.checkStateTransition();
+        return this.state !== CircuitState.OPEN;
+    }
+
+    /** Get time until circuit resets (if open) */
+    getResetTime(): Date | null {
+        if (this.state !== CircuitState.OPEN) return null;
+        return new Date(this.openedAt + this.config.resetTimeoutMs);
+    }
+
+    /**
+     * Execute a function through the circuit breaker.
+     * Tracks success/failure and manages state transitions.
+     */
+    async execute<T>(fn: () => Promise<T>): Promise<CircuitBreakerResult<T>> {
+        const startTime = Date.now();
+
+        // Check if we should allow this request
+        this.checkStateTransition();
+
+        if (this.state === CircuitState.OPEN) {
+            const resetAt = this.getResetTime()!;
+            this.recordMetric('circuit_rejected', 1);
+            return {
+                success: false,
+                error: new CircuitOpenError(this.config.name, resetAt),
+                state: this.state,
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+
+        try {
+            const value = await fn();
+            this.recordSuccess();
+            return {
+                success: true,
+                value,
+                state: this.state,
+                executionTimeMs: Date.now() - startTime,
+            };
+        } catch (error) {
+            this.recordFailure(error as Error);
+            return {
+                success: false,
+                error: error as Error,
+                state: this.state,
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+    }
+
+    /** Force reset the circuit to closed state */
+    reset(): void {
+        this.transitionTo(CircuitState.CLOSED);
+        this.failures = [];
+        this.successCount = 0;
+        this.lastFailureTime = 0;
+        this.openedAt = 0;
+    }
+
+    /** Get current failure count within window */
+    getFailureCount(): number {
+        this.pruneOldFailures();
+        return this.failures.length;
+    }
+
+    /** Get circuit statistics */
+    getStats(): {
+        state: CircuitState;
+        failureCount: number;
+        successCount: number;
+        lastFailure: Date | null;
+    } {
+        return {
+            state: this.state,
+            failureCount: this.getFailureCount(),
+            successCount: this.successCount,
+            lastFailure: this.lastFailureTime > 0 ? new Date(this.lastFailureTime) : null,
+        };
+    }
+
+    // --- Private methods ---
+
+    private checkStateTransition(): void {
+        const now = Date.now();
+
+        if (this.state === CircuitState.OPEN) {
+            // Check if reset timeout has passed
+            if (now - this.openedAt >= this.config.resetTimeoutMs) {
+                this.transitionTo(CircuitState.HALF_OPEN);
+                this.successCount = 0;
+            }
+        }
+    }
+
+    private recordSuccess(): void {
+        this.recordMetric('circuit_success', 1);
+
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.successCount++;
+            if (this.successCount >= this.config.successThreshold) {
+                this.transitionTo(CircuitState.CLOSED);
+                this.failures = [];
+            }
+        }
+    }
+
+    private recordFailure(error: Error): void {
+        const now = Date.now();
+        this.lastFailureTime = now;
+        this.failures.push({ timestamp: now, error });
+        this.recordMetric('circuit_failure', 1);
+
+        this.pruneOldFailures();
+
+        if (this.state === CircuitState.HALF_OPEN) {
+            // Any failure in half-open immediately opens
+            this.transitionTo(CircuitState.OPEN);
+            this.openedAt = now;
+        } else if (this.state === CircuitState.CLOSED) {
+            if (this.failures.length >= this.config.failureThreshold) {
+                this.transitionTo(CircuitState.OPEN);
+                this.openedAt = now;
+            }
+        }
+    }
+
+    private pruneOldFailures(): void {
+        const cutoff = Date.now() - this.config.failureWindowMs;
+        this.failures = this.failures.filter(f => f.timestamp > cutoff);
+    }
+
+    private transitionTo(newState: CircuitState): void {
+        if (this.state === newState) return;
+
+        const oldState = this.state;
+        this.state = newState;
+
+        this.recordMetric('circuit_state_change', 1, { from: oldState, to: newState });
+        this.config.onStateChange?.(oldState, newState);
+    }
+
+    private recordMetric(name: string, value: number, labels: Record<string, string> = {}): void {
+        this.config.metrics?.counter(`${this.config.name}.${name}`, value, {
+            circuit: this.config.name,
+            ...labels,
+        });
+    }
+}
+
+/**
+ * Create a circuit breaker with common defaults for LLM providers.
+ */
+export function createLLMCircuitBreaker(
+    name: string,
+    options?: Partial<CircuitBreakerConfig>
+): CircuitBreaker {
+    return new CircuitBreaker({
+        name,
+        failureThreshold: 3,
+        successThreshold: 2,
+        resetTimeoutMs: 30_000,
+        failureWindowMs: 60_000,
+        ...options,
+    });
+}