confused-ai-core 0.1.0

package/src/execution/worker-pool.ts

@@ -0,0 +1,308 @@
+/**
+ * Worker Pool for Parallel Task Execution
+ *
+ * Manages a pool of workers for executing tasks concurrently
+ */
+
+import {
+    WorkerPoolConfig,
+    WorkerPoolStatus,
+    ParallelExecutor,
+    ExecutionContext,
+} from './types.js';
+import {
+    Task,
+    TaskResult,
+    TaskStatus,
+} from '../planner/types.js';
+
+/**
+ * Worker task wrapper
+ */
+interface WorkerTask {
+    readonly task: Task;
+    readonly context: ExecutionContext;
+    readonly resolve: (result: TaskResult) => void;
+    readonly reject: (error: Error) => void;
+    readonly enqueuedAt: number;
+}
+
+/**
+ * Worker state
+ */
+interface Worker {
+    readonly id: number;
+    busy: boolean;
+    currentTask?: WorkerTask;
+    lastActiveAt: number;
+}
+
+/**
+ * Worker pool implementation
+ */
+export class WorkerPool implements ParallelExecutor {
+    private config: Required<WorkerPoolConfig>;
+    private workers: Worker[] = [];
+    private taskQueue: WorkerTask[] = [];
+    private completedTasks = 0;
+    private shutdown = false;
+    private idleTimeoutId?: ReturnType<typeof setTimeout>;
+
+    constructor(config: WorkerPoolConfig) {
+        this.config = {
+            minWorkers: config.minWorkers ?? 2,
+            maxWorkers: config.maxWorkers ?? 8,
+            idleTimeoutMs: config.idleTimeoutMs ?? 60000,
+            taskTimeoutMs: config.taskTimeoutMs ?? 30000,
+        };
+
+        // Initialize minimum workers
+        this.ensureMinWorkers();
+        this.startIdleCleanup();
+    }
+
+    /**
+     * Execute multiple tasks in parallel
+     */
+    async executeParallel(tasks: Task[], context: ExecutionContext): Promise<TaskResult[]> {
+        if (this.shutdown) {
+            throw new Error('Worker pool is shutting down');
+        }
+
+        const promises = tasks.map(task => this.enqueueTask(task, context));
+        return Promise.all(promises);
+    }
+
+    /**
+     * Get current pool status
+     */
+    getPoolStatus(): WorkerPoolStatus {
+        const activeWorkers = this.workers.filter(w => w.busy).length;
+        return {
+            totalWorkers: this.workers.length,
+            activeWorkers,
+            idleWorkers: this.workers.length - activeWorkers,
+            pendingTasks: this.taskQueue.length,
+            completedTasks: this.completedTasks,
+        };
+    }
+
+    /**
+     * Shutdown the worker pool
+     */
+    async shutdownPool(waitForTasks = true): Promise<void> {
+        this.shutdown = true;
+
+        if (this.idleTimeoutId) {
+            clearTimeout(this.idleTimeoutId);
+        }
+
+        if (waitForTasks) {
+            // Wait for queued tasks to complete
+            while (this.taskQueue.length > 0 || this.workers.some(w => w.busy)) {
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+        } else {
+            // Reject all pending tasks
+            for (const task of this.taskQueue) {
+                task.reject(new Error('Worker pool is shutting down'));
+            }
+            this.taskQueue = [];
+        }
+
+        this.workers = [];
+    }
+
+    /**
+     * Enqueue a task for execution
+     */
+    private enqueueTask(task: Task, context: ExecutionContext): Promise<TaskResult> {
+        return new Promise((resolve, reject) => {
+            const workerTask: WorkerTask = {
+                task,
+                context,
+                resolve,
+                reject,
+                enqueuedAt: Date.now(),
+            };
+
+            this.taskQueue.push(workerTask);
+            this.processQueue();
+        });
+    }
+
+    /**
+     * Process the task queue
+     */
+    private processQueue(): void {
+        if (this.shutdown) return;
+
+        while (this.taskQueue.length > 0) {
+            const worker = this.getAvailableWorker();
+            if (!worker) break;
+
+            const task = this.taskQueue.shift()!;
+            this.executeTask(worker, task);
+        }
+
+        // Scale up if needed
+        if (this.taskQueue.length > 0 && this.workers.length < this.config.maxWorkers) {
+            this.createWorker();
+            this.processQueue();
+        }
+    }
+
+    /**
+     * Get an available worker
+     */
+    private getAvailableWorker(): Worker | undefined {
+        // Find idle worker
+        const idleWorker = this.workers.find(w => !w.busy);
+        if (idleWorker) return idleWorker;
+
+        // Create new worker if under max
+        if (this.workers.length < this.config.maxWorkers) {
+            return this.createWorker();
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Create a new worker
+     */
+    private createWorker(): Worker {
+        const worker: Worker = {
+            id: this.workers.length + 1,
+            busy: false,
+            lastActiveAt: Date.now(),
+        };
+        this.workers.push(worker);
+        return worker;
+    }
+
+    /**
+     * Execute a task on a worker
+     */
+    private async executeTask(worker: Worker, workerTask: WorkerTask): Promise<void> {
+        worker.busy = true;
+        worker.currentTask = workerTask;
+        worker.lastActiveAt = Date.now();
+
+        const { task, context, resolve, reject } = workerTask;
+
+        try {
+            // Create timeout promise
+            const timeoutPromise = new Promise<never>((_, timeoutReject) => {
+                setTimeout(() => {
+                    timeoutReject(new Error(`Task ${task.id} timed out after ${this.config.taskTimeoutMs}ms`));
+                }, this.config.taskTimeoutMs);
+            });
+
+            // Execute task with timeout
+            const result = await Promise.race([
+                this.runTask(task, context),
+                timeoutPromise,
+            ]);
+
+            this.completedTasks++;
+            resolve(result);
+        } catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            reject(err);
+        } finally {
+            worker.busy = false;
+            worker.currentTask = undefined;
+            worker.lastActiveAt = Date.now();
+
+            // Process more tasks
+            this.processQueue();
+        }
+    }
+
+    /**
+     * Run a task (to be overridden by actual implementation)
+     */
+    private async runTask(task: Task, _context: ExecutionContext): Promise<TaskResult> {
+        // This is a placeholder - actual task execution would be provided
+        // by the execution engine or a task executor
+        const startTime = Date.now();
+
+        try {
+            // Simulate task execution
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            return {
+                taskId: task.id,
+                status: TaskStatus.COMPLETED,
+                output: { message: `Task ${task.name} completed` },
+                executionTimeMs: Date.now() - startTime,
+                startedAt: new Date(startTime),
+                completedAt: new Date(),
+            };
+        } catch (error) {
+            return {
+                taskId: task.id,
+                status: TaskStatus.FAILED,
+                error: {
+                    code: 'EXECUTION_ERROR',
+                    message: error instanceof Error ? error.message : String(error),
+                    retryable: true,
+                },
+                executionTimeMs: Date.now() - startTime,
+                startedAt: new Date(startTime),
+                completedAt: new Date(),
+            };
+        }
+    }
+
+    /**
+     * Ensure minimum number of workers
+     */
+    private ensureMinWorkers(): void {
+        while (this.workers.length < this.config.minWorkers) {
+            this.createWorker();
+        }
+    }
+
+    /**
+     * Start idle worker cleanup
+     */
+    private startIdleCleanup(): void {
+        const cleanup = () => {
+            if (this.shutdown) return;
+
+            const now = Date.now();
+            const toRemove: Worker[] = [];
+
+            // Find idle workers that have been idle too long
+            for (const worker of this.workers) {
+                if (!worker.busy &&
+                    this.workers.length > this.config.minWorkers &&
+                    now - worker.lastActiveAt > this.config.idleTimeoutMs) {
+                    toRemove.push(worker);
+                }
+            }
+
+            // Remove excess idle workers
+            for (const worker of toRemove) {
+                if (this.workers.length <= this.config.minWorkers) break;
+                const index = this.workers.indexOf(worker);
+                if (index > -1) {
+                    this.workers.splice(index, 1);
+                }
+            }
+
+            this.idleTimeoutId = setTimeout(cleanup, this.config.idleTimeoutMs);
+        };
+
+        this.idleTimeoutId = setTimeout(cleanup, this.config.idleTimeoutMs);
+    }
+}
+
+/**
+ * Create a new worker pool
+ */
+export function createWorkerPool(config: WorkerPoolConfig): WorkerPool {
+    return new WorkerPool(config);
+}

package/src/extensions/index.ts

@@ -0,0 +1,123 @@
+/**
+ * Extension points for production-grade, multi-agent frameworks.
+ *
+ * Plug any DB (session/memory), any tools (or ToolRegistry), cross-tool middleware,
+ * and use high-level agents (createAgent / Agent) with Orchestrator, Supervisor, Pipeline.
+ */
+
+import type { SessionStore } from '../session/types.js';
+import type { MemoryStore } from '../memory/types.js';
+import type { Tool, ToolRegistry, ToolMiddleware } from '../tools/types.js';
+import type { LLMProvider } from '../llm/types.js';
+import type { GuardrailEngine } from '../guardrails/types.js';
+import { Agent, AgentState } from '../core/types.js';
+import type { AgentInput, AgentOutput, AgentContext } from '../core/types.js';
+import type { AgentRunOptions } from '../create-agent.js';
+import type { AgenticRunResult } from '../agentic/types.js';
+
+// Re-export extension types and tool provider for convenience
+export type { SessionStore, MemoryStore, Tool, ToolRegistry, ToolMiddleware, LLMProvider, GuardrailEngine };
+export { toToolRegistry, type ToolProvider } from '../tools/registry.js';
+
+/**
+ * Create a tool middleware that logs tool calls and results (easy cross-tool integration).
+ * Pass to createAgent({ toolMiddleware: [createLoggingToolMiddleware(logger)] }) or Agent({ toolMiddleware: [...] }).
+ */
+export function createLoggingToolMiddleware(
+    log: (msg: string, meta?: Record<string, unknown>) => void = (msg, meta) => console.log(`[tool] ${msg}`, meta ?? {})
+): ToolMiddleware {
+    return {
+        beforeExecute(tool, params) {
+            log('tool.before', { tool: tool.name, params });
+        },
+        afterExecute(tool, result, ctx) {
+            log('tool.after', {
+                tool: tool.name,
+                success: result.success,
+                executionTimeMs: result.executionTimeMs,
+                agentId: ctx.agentId,
+                sessionId: ctx.sessionId,
+            });
+        },
+        onError(tool, error, ctx) {
+            log('tool.error', {
+                tool: tool.name,
+                error: error.message,
+                agentId: ctx.agentId,
+                sessionId: ctx.sessionId,
+            });
+        },
+    };
+}
+
+/**
+ * Session store provider: plug any DB (SQLite, Postgres, Redis, etc.).
+ * Implement SessionStore and pass to createAgent({ sessionStore }) or Agent({ db }).
+ */
+export type SessionStoreProvider = SessionStore;
+
+/**
+ * Memory store provider: plug any vector/RAG store for long-term knowledge.
+ * Implement MemoryStore and pass via agent options when supported.
+ */
+export type MemoryStoreProvider = MemoryStore;
+
+/**
+ * Minimal interface for high-level agents (createAgent return value or Agent class).
+ * Use with wrapAgentForOrchestration so both work in Orchestrator, Supervisor, Pipeline.
+ */
+export interface RunnableHighLevelAgent {
+    readonly name: string;
+    readonly instructions: string;
+    run(prompt: string, options?: AgentRunOptions): Promise<AgenticRunResult>;
+}
+
+/**
+ * Wrap a high-level agent (createAgent / Agent) so it can be used with
+ * Orchestrator, Supervisor, and Pipeline (core.Agent with run(AgentInput, AgentContext) => AgentOutput).
+ *
+ * @example
+ * const highLevelAgent = createAgent({ name: 'Researcher', instructions: '...' });
+ * const coreAgent = wrapAgentForOrchestration(highLevelAgent);
+ * const pipeline = createPipeline({ name: 'Research', agents: [coreAgent, writerAgent] });
+ *
+ * @example
+ * const agent = new Agent({ instructions: '...' });
+ * const coreAgent = wrapAgentForOrchestration(agent);
+ */
+export function wrapAgentForOrchestration(agent: RunnableHighLevelAgent): Agent {
+    return new OrchestrationAgentAdapter(agent);
+}
+
+class OrchestrationAgentAdapter extends Agent {
+    constructor(private readonly delegate: RunnableHighLevelAgent) {
+        super({
+            name: delegate.name,
+            description: delegate.instructions,
+        });
+    }
+
+    async run(input: AgentInput, _ctx: AgentContext): Promise<AgentOutput> {
+        const ctx = input.context ?? {};
+        const result = await this.delegate.run(input.prompt, {
+            sessionId: ctx.sessionId as string | undefined,
+            userId: ctx.userId as string | undefined,
+        });
+        const state =
+            result.finishReason === 'stop'
+                ? AgentState.COMPLETED
+                : result.finishReason === 'error' || result.finishReason === 'timeout'
+                  ? AgentState.FAILED
+                  : AgentState.COMPLETED;
+        return {
+            result: result.text,
+            state,
+            metadata: {
+                startTime: new Date(),
+                durationMs: 0,
+                iterations: result.steps,
+                tokensUsed: result.usage?.totalTokens,
+            },
+        };
+    }
+}

package/src/guardrails/allowlist.ts

@@ -0,0 +1,155 @@
+/**
+ * Allowlist implementation for guardrails
+ */
+
+import { AllowlistConfig, GuardrailRule, GuardrailResult, GuardrailContext } from './types.js';
+
+/**
+ * Create an allowlist-based guardrail rule
+ */
+export function createAllowlistRule(config: AllowlistConfig): GuardrailRule {
+    return {
+        name: 'allowlist',
+        description: 'Enforces allowlist restrictions on tools, hosts, paths, and outputs',
+        severity: 'error',
+        check(context: GuardrailContext): GuardrailResult {
+            // Check tool allowlist
+            if (config.allowedTools && context.toolName) {
+                if (!config.allowedTools.includes(context.toolName)) {
+                    return {
+                        passed: false,
+                        rule: 'allowlist',
+                        message: `Tool '${context.toolName}' is not in the allowed tools list`,
+                    };
+                }
+            }
+
+            // Check host allowlist for HTTP tools
+            if (config.allowedHosts && context.toolArgs?.url) {
+                const url = String(context.toolArgs.url);
+                const allowed = config.allowedHosts.some(host => url.includes(host));
+                if (!allowed) {
+                    return {
+                        passed: false,
+                        rule: 'allowlist',
+                        message: `Host in URL '${url}' is not in the allowed hosts list`,
+                    };
+                }
+            }
+
+            // Check blocked patterns
+            if (config.blockedPatterns) {
+                const raw = context.output;
+                const content =
+                    typeof raw === 'string' ? raw : raw === undefined || raw === null ? '' : JSON.stringify(raw);
+
+                for (const pattern of config.blockedPatterns) {
+                    if (pattern.test(content)) {
+                        return {
+                            passed: false,
+                            rule: 'allowlist',
+                            message: `Content matches blocked pattern: ${pattern}`,
+                        };
+                    }
+                }
+            }
+
+            return { passed: true, rule: 'allowlist' };
+        },
+    };
+}
+
+/**
+ * Default sensitive data patterns to block
+ */
+export const SENSITIVE_DATA_PATTERNS: RegExp[] = [
+    // Credit card numbers
+    /\b(?:\d[ -]*?){13,16}\b/,
+    // Social Security Numbers (SSN)
+    /\b\d{3}[ -]?\d{2}[ -]?\d{4}\b/,
+    // API keys (common patterns)
+    // eslint-disable-next-line no-useless-escape
+    /['"\s](?:api[_-]?key|apikey|token|secret)[\s]*[:=][\s]*['"][a-zA-Z0-9_\-]{16,}['"\s]/i,
+    // Private keys
+    /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/,
+    // Passwords in URLs
+    /[?&](?:password|passwd|pwd)=[^&\s]+/i,
+];
+
+/**
+ * Create a rule to block sensitive data
+ */
+export function createSensitiveDataRule(): GuardrailRule {
+    return {
+        name: 'sensitive_data',
+        description: 'Blocks common sensitive data patterns like credit cards, SSNs, API keys',
+        severity: 'error',
+        check(context: GuardrailContext): GuardrailResult {
+            const raw = context.output;
+            const content =
+                typeof raw === 'string' ? raw : raw === undefined || raw === null ? '' : JSON.stringify(raw);
+
+            for (const pattern of SENSITIVE_DATA_PATTERNS) {
+                if (pattern.test(content)) {
+                    return {
+                        passed: false,
+                        rule: 'sensitive_data',
+                        message: `Output may contain sensitive data matching pattern: ${pattern}`,
+                    };
+                }
+            }
+
+            return { passed: true, rule: 'sensitive_data' };
+        },
+    };
+}
+
+/**
+ * Create a URL validation rule
+ */
+export function createUrlValidationRule(
+    allowedProtocols: string[] = ['https:'],
+    allowedHosts?: string[]
+): GuardrailRule {
+    return {
+        name: 'url_validation',
+        description: `Validates URLs use allowed protocols (${allowedProtocols.join(', ')})`,
+        severity: 'error',
+        check(context: GuardrailContext): GuardrailResult {
+            const url = context.toolArgs?.url;
+            if (!url || typeof url !== 'string') {
+                return { passed: true, rule: 'url_validation' };
+            }
+
+            try {
+                const parsed = new URL(url);
+
+                // Check protocol
+                if (!allowedProtocols.includes(parsed.protocol)) {
+                    return {
+                        passed: false,
+                        rule: 'url_validation',
+                        message: `Protocol '${parsed.protocol}' is not allowed. Allowed: ${allowedProtocols.join(', ')}`,
+                    };
+                }
+
+                // Check host if allowlist provided
+                if (allowedHosts && !allowedHosts.includes(parsed.hostname)) {
+                    return {
+                        passed: false,
+                        rule: 'url_validation',
+                        message: `Host '${parsed.hostname}' is not in the allowed hosts list`,
+                    };
+                }
+
+                return { passed: true, rule: 'url_validation' };
+            } catch {
+                return {
+                    passed: false,
+                    rule: 'url_validation',
+                    message: `Invalid URL: ${url}`,
+                };
+            }
+        },
+    };
+}

package/src/guardrails/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Guardrails module for output validation and safety controls
+ */
+
+export * from './types';
+export {
+    GuardrailValidator,
+    createContentRule,
+    createToolAllowlistRule,
+    createMaxLengthRule,
+} from './validator';
+export {
+    createAllowlistRule,
+    createSensitiveDataRule,
+    createUrlValidationRule,
+    SENSITIVE_DATA_PATTERNS,
+} from './allowlist';