confused-ai-core 0.1.0

package/src/orchestration/mcp-types.ts

@@ -0,0 +1,59 @@
+/**
+ * MCP (Model Context Protocol) and A2A (Agent-to-Agent) support.
+ * First-class integration for external tools and cross-agent communication.
+ */
+
+import type { Tool } from '../tools/types.js';
+
+/** MCP tool descriptor (from MCP server) */
+export interface MCPToolDescriptor {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema?: Record<string, unknown>;
+}
+
+/** MCP client: connect to an MCP server and expose tools to the agent */
+export interface MCPClient {
+    /** List tools offered by the MCP server */
+    listTools(): Promise<MCPToolDescriptor[]>;
+
+    /** Call a tool by name with arguments */
+    callTool(name: string, args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text?: string }> }>;
+
+    /** Optional: get framework Tool adapters for registry */
+    getTools?(): Promise<Tool[]>;
+
+    /** Disconnect / cleanup */
+    disconnect?(): Promise<void>;
+}
+
+/** MCP server adapter: expose framework tools via MCP (for external clients) */
+export interface MCPServerAdapter {
+    /** Start serving (e.g. stdio or HTTP) */
+    start(): Promise<void>;
+
+    /** Stop serving */
+    stop(): Promise<void>;
+
+    /** Register a tool to expose */
+    registerTool(tool: Tool): void;
+}
+
+/** A2A (Agent-to-Agent) message for cross-agent communication */
+export interface A2AMessage {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string | string[];
+    readonly type: 'request' | 'response' | 'event';
+    readonly payload: unknown;
+    readonly timestamp: Date;
+    readonly correlationId?: string;
+}
+
+/** A2A client: send/receive messages to other agents */
+export interface A2AClient {
+    send(message: Omit<A2AMessage, 'id' | 'timestamp'>): Promise<A2AMessage>;
+
+    /** Subscribe to incoming messages (e.g. for this agent id) */
+    subscribe(agentId: string, handler: (msg: A2AMessage) => void | Promise<void>): () => void;
+}

package/src/orchestration/message-bus.ts

@@ -0,0 +1,192 @@
+/**
+ * Message Bus Implementation
+ *
+ * Handles inter-agent communication with pub/sub pattern
+ */
+
+import {
+    MessageBus,
+    AgentMessage,
+    MessageType,
+    MessageFilter,
+    MessageHandler,
+    Subscription,
+    MessagePriority,
+} from './types.js';
+import type { EntityId } from '../core/types.js';
+
+/**
+ * Message bus implementation
+ */
+export class MessageBusImpl implements MessageBus {
+    private messages: AgentMessage[] = [];
+    private subscriptions: Map<EntityId, Set<SubscriptionImpl>> = new Map();
+    private pendingRequests: Map<string, { resolve: (value: unknown) => void; reject: (error: Error) => void; timeout: ReturnType<typeof setTimeout> }> = new Map();
+    private messageCounter = 0;
+
+    async send(message: Omit<AgentMessage, 'id' | 'timestamp'>): Promise<AgentMessage> {
+        const fullMessage: AgentMessage = {
+            ...message,
+            id: this.generateId(),
+            timestamp: new Date(),
+        };
+
+        this.messages.push(fullMessage);
+
+        // Deliver to subscribers
+        await this.deliverMessage(fullMessage);
+
+        return fullMessage;
+    }
+
+    subscribe(
+        subscriberId: EntityId,
+        filter: MessageFilter,
+        handler: MessageHandler
+    ): Subscription {
+        const subscription: SubscriptionImpl = {
+            id: this.generateId(),
+            subscriberId,
+            filter,
+            handler,
+            unsubscribe: () => {
+                const subs = this.subscriptions.get(subscriberId);
+                if (subs) {
+                    subs.delete(subscription);
+                }
+            },
+        };
+
+        if (!this.subscriptions.has(subscriberId)) {
+            this.subscriptions.set(subscriberId, new Set());
+        }
+
+        this.subscriptions.get(subscriberId)!.add(subscription);
+
+        return subscription;
+    }
+
+    unsubscribe(subscription: Subscription): void {
+        subscription.unsubscribe();
+    }
+
+    async request<T>(to: EntityId, payload: unknown, timeoutMs = 30000): Promise<T> {
+        const correlationId = this.generateId();
+
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(correlationId);
+                reject(new Error(`Request timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+
+            this.pendingRequests.set(correlationId, {
+                resolve: resolve as (value: unknown) => void,
+                reject,
+                timeout,
+            });
+
+            // Send request message
+            this.send({
+                from: 'orchestrator',
+                to,
+                type: MessageType.QUERY,
+                payload,
+                priority: MessagePriority.HIGH,
+                correlationId,
+            }).catch(reject);
+        });
+    }
+
+    /**
+     * Respond to a request
+     */
+    async respond(correlationId: string, payload: unknown): Promise<void> {
+        const pending = this.pendingRequests.get(correlationId);
+        if (pending) {
+            clearTimeout(pending.timeout);
+            this.pendingRequests.delete(correlationId);
+            pending.resolve(payload);
+        }
+    }
+
+    /**
+     * Get message history
+     */
+    getMessages(filter?: MessageFilter): AgentMessage[] {
+        if (!filter) {
+            return [...this.messages];
+        }
+
+        return this.messages.filter(msg => this.matchesFilter(msg, filter));
+    }
+
+    private async deliverMessage(message: AgentMessage): Promise<void> {
+        const targetId = message.to;
+
+        if (targetId === 'broadcast') {
+            // Deliver to all subscribers
+            for (const [_, subs] of this.subscriptions) {
+                for (const sub of subs) {
+                    if (this.matchesFilter(message, sub.filter)) {
+                        try {
+                            await sub.handler(message);
+                        } catch (error) {
+                            console.error('Error handling message:', error);
+                        }
+                    }
+                }
+            }
+        } else {
+            // Deliver to specific subscriber
+            const subs = this.subscriptions.get(targetId);
+            if (subs) {
+                for (const sub of subs) {
+                    if (this.matchesFilter(message, sub.filter)) {
+                        try {
+                            await sub.handler(message);
+                        } catch (error) {
+                            console.error('Error handling message:', error);
+                        }
+                    }
+                }
+            }
+        }
+
+        // Handle response messages
+        if (message.correlationId && message.type === MessageType.TASK_RESPONSE) {
+            await this.respond(message.correlationId, message.payload);
+        }
+    }
+
+    private matchesFilter(message: AgentMessage, filter: MessageFilter): boolean {
+        if (filter.from && message.from !== filter.from) {
+            return false;
+        }
+
+        if (filter.types && !filter.types.includes(message.type)) {
+            return false;
+        }
+
+        if (filter.correlationId && message.correlationId !== filter.correlationId) {
+            return false;
+        }
+
+        if (filter.minPriority !== undefined && message.priority > filter.minPriority) {
+            return false;
+        }
+
+        return true;
+    }
+
+    private generateId(): string {
+        return `msg-${Date.now()}-${++this.messageCounter}`;
+    }
+}
+
+/**
+ * Subscription implementation
+ */
+interface SubscriptionImpl extends Subscription {
+    filter: MessageFilter;
+    handler: MessageHandler;
+}

package/src/orchestration/orchestrator.ts

@@ -0,0 +1,349 @@
+/**
+ * Multi-Agent Orchestrator Implementation
+ *
+ * Coordinates multiple agents with message passing and load balancing
+ */
+
+import {
+    Orchestrator,
+    AgentRegistration,
+    AgentRole,
+    MessageType,
+    MessagePriority,
+    DelegationTask,
+    DelegationResult,
+    DelegationStatus,
+    DelegationPriority,
+    CoordinationTask,
+    CoordinationResult,
+    CoordinationType,
+    CoordinationStatus,
+} from './types.js';
+import type { MessageBus, Subscription } from './types.js';
+import { MessageBusImpl } from './message-bus';
+import { RoundRobinLoadBalancer } from './load-balancer';
+import type { Agent, AgentInput, AgentContext } from '../core/types.js';
+import type { AgentOutput } from '../core/types.js';
+import { AgentState } from '../core/types.js';
+import type { EntityId } from '../core/types.js';
+import type { LoadBalancer } from './types.js';
+import { AgentContextBuilder } from '../core/context-builder.js';
+import { InMemoryStore } from '../memory/in-memory-store.js';
+import { ToolRegistryImpl } from '../tools/registry.js';
+import { ClassicalPlanner } from '../planner/classical-planner.js';
+import { PlanningAlgorithm } from '../planner/types.js';
+
+const ORCHESTRATOR_ID = 'orchestrator' as EntityId;
+
+/**
+ * Orchestrator implementation
+ */
+export class OrchestratorImpl implements Orchestrator {
+    private agents: Map<EntityId, AgentRegistration> = new Map();
+    private subscriptions: Map<EntityId, Subscription> = new Map();
+    private messageBus: MessageBus;
+    private loadBalancer: LoadBalancer;
+    private _isRunning = false;
+
+    constructor(
+        messageBus?: MessageBus,
+        loadBalancer?: LoadBalancer
+    ) {
+        this.messageBus = messageBus ?? new MessageBusImpl();
+        this.loadBalancer = loadBalancer ?? new RoundRobinLoadBalancer();
+    }
+
+    async registerAgent(agent: Agent, role: AgentRole): Promise<void> {
+        const registration: AgentRegistration = {
+            agent,
+            role,
+            capabilities: role.responsibilities,
+            metadata: {
+                registeredAt: new Date(),
+                totalTasksCompleted: 0,
+                totalTasksFailed: 0,
+                averageExecutionTimeMs: 0,
+                currentLoad: 0,
+                maxConcurrentTasks: role.permissions.canExecuteTools ? 5 : 1,
+            },
+        };
+
+        this.agents.set(agent.id, registration);
+
+        const subscription = this.messageBus.subscribe(
+            agent.id,
+            { types: [MessageType.QUERY] },
+            async (msg) => {
+                const payload = msg.payload as { type?: string; task?: AgentInput };
+                const taskInput = (payload?.task ?? payload) as AgentInput;
+                const ctx = createMinimalContext(agent);
+                try {
+                    const output = await agent.run(taskInput, ctx);
+                    await this.messageBus.send({
+                        from: agent.id,
+                        to: ORCHESTRATOR_ID,
+                        type: MessageType.TASK_RESPONSE,
+                        payload: output,
+                        correlationId: msg.correlationId,
+                        priority: MessagePriority.NORMAL,
+                    });
+                } catch (err) {
+                    const errorOutput: AgentOutput = {
+                        result: err instanceof Error ? err.message : String(err),
+                        state: AgentState.FAILED,
+                        metadata: { startTime: new Date(), iterations: 0 },
+                    };
+                    await this.messageBus.send({
+                        from: agent.id,
+                        to: ORCHESTRATOR_ID,
+                        type: MessageType.TASK_RESPONSE,
+                        payload: errorOutput,
+                        correlationId: msg.correlationId,
+                        priority: MessagePriority.NORMAL,
+                    });
+                }
+            }
+        );
+        this.subscriptions.set(agent.id, subscription);
+
+        // Notify other agents
+        await this.broadcast({
+            type: 'agent_registered',
+            agentId: agent.id,
+            role: role.name,
+        }, MessageType.EVENT);
+    }
+
+    async unregisterAgent(agentId: EntityId): Promise<void> {
+        const registration = this.agents.get(agentId);
+        if (!registration) {
+            throw new Error(`Agent ${agentId} not found`);
+        }
+
+        const subscription = this.subscriptions.get(agentId);
+        if (subscription) {
+            this.messageBus.unsubscribe(subscription);
+            this.subscriptions.delete(agentId);
+        }
+        this.agents.delete(agentId);
+
+        await this.broadcast({
+            type: 'agent_unregistered',
+            agentId,
+        }, MessageType.EVENT);
+    }
+
+    getAgent(agentId: EntityId): AgentRegistration | undefined {
+        return this.agents.get(agentId);
+    }
+
+    listAgents(): AgentRegistration[] {
+        return Array.from(this.agents.values());
+    }
+
+    findAgentsByRole(roleName: string): AgentRegistration[] {
+        return Array.from(this.agents.values()).filter(
+            reg => reg.role.name === roleName
+        );
+    }
+
+    findAgentsByCapability(capability: string): AgentRegistration[] {
+        return Array.from(this.agents.values()).filter(
+            reg => reg.capabilities.includes(capability)
+        );
+    }
+
+    async delegateTask(task: DelegationTask, options?: { timeoutMs?: number; retryCount?: number }): Promise<DelegationResult> {
+        const startTime = Date.now();
+
+        // Find candidates with required capabilities
+        const candidates = this.findAgentsByCapabilities(task.requiredCapabilities);
+
+        if (candidates.length === 0) {
+            return {
+                taskId: task.id,
+                assignedAgentId: '',
+                status: DelegationStatus.FAILED,
+                error: 'No agents found with required capabilities',
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+
+        // Select best agent using load balancer
+        const selected = this.loadBalancer.selectAgent(candidates, task);
+
+        if (!selected) {
+            return {
+                taskId: task.id,
+                assignedAgentId: '',
+                status: DelegationStatus.REJECTED,
+                error: 'No agent available to handle task',
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+
+        try {
+            // Send task to selected agent
+            const response = await this.messageBus.request(
+                selected.agent.id,
+                {
+                    type: 'task',
+                    task: task.input,
+                },
+                options?.timeoutMs ?? 30000
+            );
+
+            // Update metrics
+            this.loadBalancer.updateMetrics(
+                selected.agent.id,
+                Date.now() - startTime,
+                true
+            );
+
+            return {
+                taskId: task.id,
+                assignedAgentId: selected.agent.id,
+                status: DelegationStatus.COMPLETED,
+                output: response as AgentOutput,
+                executionTimeMs: Date.now() - startTime,
+            };
+        } catch (error) {
+            // Update metrics
+            this.loadBalancer.updateMetrics(
+                selected.agent.id,
+                Date.now() - startTime,
+                false
+            );
+
+            return {
+                taskId: task.id,
+                assignedAgentId: selected.agent.id,
+                status: DelegationStatus.FAILED,
+                error: error instanceof Error ? error.message : String(error),
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+    }
+
+    async broadcast(payload: unknown, type: MessageType = MessageType.NOTIFICATION): Promise<void> {
+        for (const [agentId] of this.agents) {
+            await this.messageBus.send({
+                from: ORCHESTRATOR_ID,
+                to: agentId,
+                type,
+                payload,
+                priority: MessagePriority.NORMAL,
+            });
+        }
+    }
+
+    getMessageBus(): MessageBus {
+        return this.messageBus;
+    }
+
+    async start(): Promise<void> {
+        this._isRunning = true;
+    }
+
+    async stop(): Promise<void> {
+        this._isRunning = false;
+    }
+
+    /**
+     * Check if orchestrator is running
+     */
+    isRunning(): boolean {
+        return this._isRunning;
+    }
+
+    /**
+     * Coordinate multiple agents for a complex task
+     */
+    async coordinate(agents: AgentRegistration[], task: CoordinationTask): Promise<CoordinationResult> {
+        const startTime = Date.now();
+        const results = new Map<EntityId, AgentOutput>();
+
+        switch (task.coordinationType) {
+            case CoordinationType.SEQUENTIAL:
+                for (const agentReg of agents) {
+                    const result = await this.delegateTask({
+                        id: `${task.id}-${agentReg.agent.id}`,
+                        description: task.description,
+                        requiredCapabilities: agentReg.capabilities,
+                        input: { prompt: task.description },
+                        priority: DelegationPriority.NORMAL,
+                    });
+
+                    if (result.output) {
+                        results.set(agentReg.agent.id, result.output);
+                    }
+                }
+                break;
+
+            case CoordinationType.PARALLEL:
+                const promises = agents.map(agentReg =>
+                    this.delegateTask({
+                        id: `${task.id}-${agentReg.agent.id}`,
+                        description: task.description,
+                        requiredCapabilities: agentReg.capabilities,
+                        input: { prompt: task.description },
+                        priority: DelegationPriority.NORMAL,
+                    })
+                );
+
+                const parallelResults = await Promise.all(promises);
+                for (let i = 0; i < agents.length; i++) {
+                    const output = parallelResults[i].output;
+                    if (output) {
+                        results.set(agents[i].agent.id, output);
+                    }
+                }
+                break;
+
+            default:
+                // Default to sequential
+                for (const agentReg of agents) {
+                    const result = await this.delegateTask({
+                        id: `${task.id}-${agentReg.agent.id}`,
+                        description: task.description,
+                        requiredCapabilities: agentReg.capabilities,
+                        input: { prompt: task.description },
+                        priority: DelegationPriority.NORMAL,
+                    });
+
+                    if (result.output) {
+                        results.set(agentReg.agent.id, result.output);
+                    }
+                }
+        }
+
+        return {
+            taskId: task.id,
+            status: results.size === agents.length
+                ? CoordinationStatus.SUCCESS
+                : results.size > 0
+                    ? CoordinationStatus.PARTIAL
+                    : CoordinationStatus.FAILED,
+            results,
+            executionTimeMs: Date.now() - startTime,
+        };
+    }
+
+    private findAgentsByCapabilities(requiredCapabilities: string[]): AgentRegistration[] {
+        return Array.from(this.agents.values()).filter(reg =>
+            requiredCapabilities.every(cap => reg.capabilities.includes(cap))
+        );
+    }
+}
+
+/**
+ * Create a minimal AgentContext for in-process agent execution
+ */
+function createMinimalContext(agent: Agent): AgentContext {
+    return new AgentContextBuilder()
+        .withAgentId(agent.id)
+        .withMemory(new InMemoryStore())
+        .withTools(new ToolRegistryImpl())
+        .withPlanner(new ClassicalPlanner({ algorithm: PlanningAlgorithm.HIERARCHICAL }))
+        .build();
+}

package/src/orchestration/pipeline.ts

@@ -0,0 +1,66 @@
+/**
+ * Pipeline pattern: run agents in sequence, passing output of one as input to the next.
+ *
+ * Inspired by VoltAgent's pipeline pattern:
+ * https://github.com/VoltAgent/voltagent/blob/main/website/blog/2025-07-16-ai-agent-orchestration/index.md
+ */
+
+import type { Agent, AgentInput, AgentOutput, AgentContext } from '../core/types.js';
+import { AgentState } from '../core/types.js';
+import { createRunnableAgent } from './agent-adapter.js';
+import { AgentContextBuilder } from '../core/context-builder.js';
+import { InMemoryStore } from '../memory/in-memory-store.js';
+import { ToolRegistryImpl } from '../tools/registry.js';
+import { ClassicalPlanner } from '../planner/classical-planner.js';
+import { PlanningAlgorithm } from '../planner/index.js';
+
+export interface PipelineConfig {
+    readonly name: string;
+    readonly description?: string;
+    /** Agents in execution order; output of step N is passed as input to step N+1 */
+    readonly agents: Agent[];
+}
+
+/**
+ * Creates a pipeline agent that runs the given agents in sequence.
+ * Each agent receives the previous agent's output as its input (as JSON in the prompt).
+ */
+export function createPipeline(config: PipelineConfig): Agent {
+    const run = async (input: AgentInput, _ctx: AgentContext): Promise<AgentOutput> => {
+        const results: unknown[] = [];
+        let currentPrompt = input.prompt;
+        const sharedContext = new AgentContextBuilder()
+            .withAgentId(`pipeline-${config.name}`)
+            .withMemory(new InMemoryStore())
+            .withTools(new ToolRegistryImpl())
+            .withPlanner(new ClassicalPlanner({ algorithm: PlanningAlgorithm.HIERARCHICAL }))
+            .build();
+
+        for (const agent of config.agents) {
+            const agentInput: AgentInput = {
+                prompt: currentPrompt,
+                context: input.context,
+            };
+            const output = await agent.run(agentInput, sharedContext);
+            const result = output.result;
+            results.push(result);
+            currentPrompt = typeof result === 'string' ? result : JSON.stringify(result);
+        }
+
+        return {
+            result: results.length === 1 ? results[0] : { steps: results, final: results[results.length - 1] },
+            state: AgentState.COMPLETED,
+            metadata: {
+                startTime: new Date(),
+                durationMs: 0,
+                iterations: config.agents.length,
+            },
+        };
+    };
+
+    return createRunnableAgent({
+        name: config.name,
+        description: config.description ?? `Pipeline of ${config.agents.length} agents`,
+        run,
+    });
+}