family-ai-agent 1.0.0

package/src/core/agents/agent-factory.ts

@@ -0,0 +1,192 @@
+import type { StructuredTool } from '@langchain/core/tools';
+import { nanoid } from 'nanoid';
+
+import { BaseAgent } from './base-agent.js';
+import { ChatAgent, createChatAgent } from './personalities/chat.js';
+import { ResearchAgent, createResearchAgent } from './personalities/research.js';
+import { CodingAgent, createCodingAgent } from './personalities/coding.js';
+import { AutomationAgent, createAutomationAgent } from './personalities/automation.js';
+import type { AgentRole, AgentIdentity } from './types.js';
+import { createLogger } from '../../utils/logger.js';
+
+const logger = createLogger('AgentFactory');
+
+export interface AgentPoolConfig {
+  maxAgentsPerRole: number;
+  defaultTools: StructuredTool[];
+}
+
+const DEFAULT_POOL_CONFIG: AgentPoolConfig = {
+  maxAgentsPerRole: 3,
+  defaultTools: [],
+};
+
+export class AgentFactory {
+  private config: AgentPoolConfig;
+  private agentPool: Map<AgentRole, BaseAgent[]> = new Map();
+  private allAgents: Map<string, BaseAgent> = new Map();
+
+  constructor(config: Partial<AgentPoolConfig> = {}) {
+    this.config = { ...DEFAULT_POOL_CONFIG, ...config };
+    this.initializePools();
+  }
+
+  private initializePools(): void {
+    const roles: AgentRole[] = ['chat', 'research', 'coding', 'automation'];
+    for (const role of roles) {
+      this.agentPool.set(role, []);
+    }
+  }
+
+  // Create a new agent of specific type
+  createAgent(role: AgentRole, tools?: StructuredTool[]): BaseAgent {
+    const agentTools = tools ?? this.config.defaultTools;
+
+    let agent: BaseAgent;
+
+    switch (role) {
+      case 'chat':
+        agent = createChatAgent(agentTools);
+        break;
+      case 'research':
+        agent = createResearchAgent(agentTools);
+        break;
+      case 'coding':
+        agent = createCodingAgent(agentTools);
+        break;
+      case 'automation':
+        agent = createAutomationAgent(agentTools);
+        break;
+      default:
+        throw new Error(`Unknown agent role: ${role}`);
+    }
+
+    // Register agent
+    this.allAgents.set(agent.id, agent);
+
+    // Add to pool
+    const pool = this.agentPool.get(role) ?? [];
+    pool.push(agent);
+    this.agentPool.set(role, pool);
+
+    logger.info('Agent created', { agentId: agent.id, role });
+
+    return agent;
+  }
+
+  // Get or create an available agent
+  getAgent(role: AgentRole): BaseAgent {
+    const pool = this.agentPool.get(role) ?? [];
+
+    // Find an idle agent
+    const idleAgent = pool.find((a) => a.getStatus() === 'idle');
+    if (idleAgent) {
+      return idleAgent;
+    }
+
+    // Create new agent if under limit
+    if (pool.length < this.config.maxAgentsPerRole) {
+      return this.createAgent(role);
+    }
+
+    // Return least busy agent (waiting status preferred over executing)
+    const waitingAgent = pool.find((a) => a.getStatus() === 'waiting');
+    if (waitingAgent) {
+      return waitingAgent;
+    }
+
+    // Return first agent as fallback
+    logger.warn('All agents busy, returning first agent', { role });
+    return pool[0]!;
+  }
+
+  // Get agent by ID
+  getAgentById(id: string): BaseAgent | undefined {
+    return this.allAgents.get(id);
+  }
+
+  // Get all agents of a role
+  getAgentsByRole(role: AgentRole): BaseAgent[] {
+    return this.agentPool.get(role) ?? [];
+  }
+
+  // Get all active agent identities
+  getActiveAgentIdentities(): AgentIdentity[] {
+    return Array.from(this.allAgents.values()).map((a) => a.getInfo());
+  }
+
+  // Release/reset an agent
+  releaseAgent(agentId: string): void {
+    const agent = this.allAgents.get(agentId);
+    if (agent) {
+      agent.reset();
+      logger.debug('Agent released', { agentId });
+    }
+  }
+
+  // Remove agent from pool
+  removeAgent(agentId: string): boolean {
+    const agent = this.allAgents.get(agentId);
+    if (!agent) return false;
+
+    // Remove from role pool
+    const role = agent.role as AgentRole;
+    const pool = this.agentPool.get(role) ?? [];
+    const index = pool.findIndex((a) => a.id === agentId);
+    if (index > -1) {
+      pool.splice(index, 1);
+      this.agentPool.set(role, pool);
+    }
+
+    // Remove from all agents
+    this.allAgents.delete(agentId);
+
+    logger.info('Agent removed', { agentId, role });
+    return true;
+  }
+
+  // Get pool statistics
+  getPoolStats(): Record<AgentRole, { total: number; idle: number; busy: number }> {
+    const stats: Record<string, { total: number; idle: number; busy: number }> = {};
+
+    for (const [role, agents] of this.agentPool) {
+      const idle = agents.filter((a) => a.getStatus() === 'idle').length;
+      stats[role] = {
+        total: agents.length,
+        idle,
+        busy: agents.length - idle,
+      };
+    }
+
+    return stats as Record<AgentRole, { total: number; idle: number; busy: number }>;
+  }
+
+  // Clear all agents
+  clear(): void {
+    for (const agent of this.allAgents.values()) {
+      agent.reset();
+    }
+    this.allAgents.clear();
+    this.initializePools();
+    logger.info('Agent pool cleared');
+  }
+}
+
+// Singleton factory instance
+let factoryInstance: AgentFactory | null = null;
+
+export function getAgentFactory(config?: Partial<AgentPoolConfig>): AgentFactory {
+  if (!factoryInstance) {
+    factoryInstance = new AgentFactory(config);
+  }
+  return factoryInstance;
+}
+
+export function resetAgentFactory(): void {
+  if (factoryInstance) {
+    factoryInstance.clear();
+    factoryInstance = null;
+  }
+}
+
+export default AgentFactory;

package/src/core/agents/base-agent.ts

@@ -0,0 +1,333 @@
+import { ChatOpenAI } from '@langchain/openai';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import { SystemMessage, HumanMessage, AIMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { StructuredTool } from '@langchain/core/tools';
+import { nanoid } from 'nanoid';
+
+import { getOpenRouterClient } from '../../llm/openrouter-client.js';
+import { createLogger, logAgentAction } from '../../utils/logger.js';
+import { AgentError } from '../../utils/errors.js';
+import type {
+  AgentConfig,
+  AgentIdentity,
+  AgentState,
+  AgentStatus,
+  AgentEvent,
+  TaskDefinition,
+  TaskResult,
+  RetrievedMemory,
+  HandoffDecision,
+} from './types.js';
+
+const logger = createLogger('BaseAgent');
+
+export abstract class BaseAgent {
+  protected readonly identity: AgentIdentity;
+  protected readonly model: ChatOpenAI;
+  protected readonly systemPrompt: string;
+  protected readonly tools: StructuredTool[];
+  protected readonly maxIterations: number;
+  protected readonly timeout: number;
+
+  protected status: AgentStatus = 'idle';
+  protected currentTask: TaskDefinition | null = null;
+  protected iterationCount = 0;
+
+  private eventListeners: ((event: AgentEvent) => void)[] = [];
+
+  constructor(config: AgentConfig) {
+    this.identity = config.identity;
+    this.systemPrompt = config.systemPrompt;
+    this.tools = config.tools;
+    this.maxIterations = config.maxIterations ?? 10;
+    this.timeout = config.timeout ?? 120000; // 2 minutes default
+
+    // Get model from OpenRouter
+    const client = getOpenRouterClient();
+    this.model = client.getChatModelForAgent({
+      model: config.model,
+      temperature: config.temperature ?? 0.7,
+      maxTokens: config.maxTokens,
+    });
+  }
+
+  // Identity getters
+  get id(): string {
+    return this.identity.id;
+  }
+
+  get name(): string {
+    return this.identity.name;
+  }
+
+  get role(): string {
+    return this.identity.role;
+  }
+
+  get capabilities(): string[] {
+    return this.identity.capabilities;
+  }
+
+  getStatus(): AgentStatus {
+    return this.status;
+  }
+
+  // Abstract methods that subclasses must implement
+  protected abstract buildSystemPrompt(
+    context: Record<string, unknown>,
+    memories: RetrievedMemory[]
+  ): string;
+
+  protected abstract shouldHandoff(
+    state: AgentState,
+    result: TaskResult
+  ): Promise<HandoffDecision>;
+
+  // Create the LangGraph agent
+  protected createAgent() {
+    return createReactAgent({
+      llm: this.model,
+      tools: this.tools,
+    });
+  }
+
+  // Main execution method
+  async execute(
+    input: string,
+    context: Record<string, unknown> = {},
+    memories: RetrievedMemory[] = []
+  ): Promise<TaskResult> {
+    const taskId = nanoid();
+    const startTime = Date.now();
+
+    this.status = 'thinking';
+    this.iterationCount = 0;
+
+    this.emitEvent('started', { taskId, input });
+
+    try {
+      // Build the full system prompt with context and memories
+      const fullSystemPrompt = this.buildSystemPrompt(context, memories);
+
+      // Create messages
+      const messages: BaseMessage[] = [
+        new SystemMessage(fullSystemPrompt),
+        new HumanMessage(input),
+      ];
+
+      // Create and invoke the agent
+      const agent = this.createAgent();
+
+      this.status = 'executing';
+      this.emitEvent('thinking', { taskId });
+
+      const result = await this.invokeWithTimeout(agent, messages);
+
+      const executionTime = Date.now() - startTime;
+      this.status = 'completed';
+
+      const taskResult: TaskResult = {
+        taskId,
+        agentId: this.id,
+        status: 'success',
+        output: this.extractOutput(result),
+        executionTimeMs: executionTime,
+        metadata: {
+          iterations: this.iterationCount,
+          model: this.model.modelName,
+        },
+      };
+
+      this.emitEvent('completed', { taskId, result: taskResult });
+      logAgentAction(this.id, 'execute', {
+        taskId,
+        success: true,
+        duration: executionTime,
+      });
+
+      return taskResult;
+    } catch (error) {
+      const executionTime = Date.now() - startTime;
+      this.status = 'error';
+
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+
+      const taskResult: TaskResult = {
+        taskId,
+        agentId: this.id,
+        status: 'failed',
+        output: null,
+        error: errorMessage,
+        executionTimeMs: executionTime,
+      };
+
+      this.emitEvent('error', { taskId, error: errorMessage });
+      logAgentAction(this.id, 'execute', {
+        taskId,
+        success: false,
+        error: errorMessage,
+        duration: executionTime,
+      });
+
+      throw new AgentError(
+        `Agent execution failed: ${errorMessage}`,
+        this.id,
+        { taskId, originalError: errorMessage }
+      );
+    } finally {
+      this.currentTask = null;
+      this.iterationCount = 0;
+    }
+  }
+
+  // Execute with timeout
+  private async invokeWithTimeout(
+    agent: ReturnType<typeof createReactAgent>,
+    messages: BaseMessage[]
+  ): Promise<unknown> {
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new AgentError('Agent execution timed out', this.id));
+      }, this.timeout);
+    });
+
+    const executionPromise = agent.invoke({
+      messages,
+    });
+
+    return Promise.race([executionPromise, timeoutPromise]);
+  }
+
+  // Extract output from agent result
+  protected extractOutput(result: unknown): string {
+    if (!result || typeof result !== 'object') {
+      return String(result);
+    }
+
+    const agentResult = result as Record<string, unknown>;
+
+    if (Array.isArray(agentResult.messages)) {
+      const lastMessage = agentResult.messages[agentResult.messages.length - 1];
+      if (lastMessage && typeof lastMessage === 'object' && 'content' in lastMessage) {
+        const content = (lastMessage as AIMessage).content;
+        return typeof content === 'string' ? content : JSON.stringify(content);
+      }
+    }
+
+    return JSON.stringify(result);
+  }
+
+  // Event handling
+  onEvent(listener: (event: AgentEvent) => void): () => void {
+    this.eventListeners.push(listener);
+    return () => {
+      const index = this.eventListeners.indexOf(listener);
+      if (index > -1) {
+        this.eventListeners.splice(index, 1);
+      }
+    };
+  }
+
+  protected emitEvent(type: AgentEvent['type'], data: Record<string, unknown>): void {
+    const event: AgentEvent = {
+      type,
+      agentId: this.id,
+      timestamp: new Date(),
+      data,
+    };
+
+    for (const listener of this.eventListeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        logger.error('Event listener error', { error });
+      }
+    }
+  }
+
+  // Stream execution for real-time output
+  async *stream(
+    input: string,
+    context: Record<string, unknown> = {},
+    memories: RetrievedMemory[] = []
+  ): AsyncGenerator<string, TaskResult, unknown> {
+    const taskId = nanoid();
+    const startTime = Date.now();
+
+    this.status = 'thinking';
+    this.emitEvent('started', { taskId, input });
+
+    try {
+      const fullSystemPrompt = this.buildSystemPrompt(context, memories);
+      const messages: BaseMessage[] = [
+        new SystemMessage(fullSystemPrompt),
+        new HumanMessage(input),
+      ];
+
+      const agent = this.createAgent();
+      this.status = 'executing';
+
+      let fullOutput = '';
+
+      const stream = await agent.stream({
+        messages,
+      });
+
+      for await (const chunk of stream) {
+        if (chunk && typeof chunk === 'object') {
+          const chunkData = chunk as Record<string, unknown>;
+          if (Array.isArray(chunkData.messages)) {
+            const lastMsg = chunkData.messages[chunkData.messages.length - 1];
+            if (lastMsg && typeof lastMsg === 'object' && 'content' in lastMsg) {
+              const content = (lastMsg as AIMessage).content;
+              if (typeof content === 'string') {
+                fullOutput = content;
+                yield content;
+              }
+            }
+          }
+        }
+      }
+
+      const executionTime = Date.now() - startTime;
+      this.status = 'completed';
+
+      const taskResult: TaskResult = {
+        taskId,
+        agentId: this.id,
+        status: 'success',
+        output: fullOutput,
+        executionTimeMs: executionTime,
+      };
+
+      this.emitEvent('completed', { taskId, result: taskResult });
+      return taskResult;
+    } catch (error) {
+      this.status = 'error';
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.emitEvent('error', { taskId, error: errorMessage });
+      throw new AgentError(`Stream execution failed: ${errorMessage}`, this.id);
+    }
+  }
+
+  // Check if agent can handle a task
+  canHandle(task: TaskDefinition): boolean {
+    const requiredCaps = task.requiredCapabilities || [];
+    return requiredCaps.every((cap) => this.capabilities.includes(cap));
+  }
+
+  // Reset agent state
+  reset(): void {
+    this.status = 'idle';
+    this.currentTask = null;
+    this.iterationCount = 0;
+  }
+
+  // Get agent info for display
+  getInfo(): AgentIdentity {
+    return { ...this.identity };
+  }
+}
+
+export default BaseAgent;

package/src/core/agents/index.ts

@@ -0,0 +1,27 @@
+// Agent exports
+export { BaseAgent } from './base-agent.js';
+export { AgentFactory, getAgentFactory, resetAgentFactory } from './agent-factory.js';
+
+// Personalities
+export { ChatAgent, createChatAgent } from './personalities/chat.js';
+export { ResearchAgent, createResearchAgent } from './personalities/research.js';
+export { CodingAgent, createCodingAgent } from './personalities/coding.js';
+export { AutomationAgent, createAutomationAgent } from './personalities/automation.js';
+
+// Types
+export type {
+  AgentRole,
+  AgentStatus,
+  AgentIdentity,
+  AgentConfig,
+  AgentState,
+  TaskDefinition,
+  TaskResult,
+  RetrievedMemory,
+  AgentMessage,
+  HandoffDecision,
+  RoutingDecision,
+  ToolResult,
+  AgentEventType,
+  AgentEvent,
+} from './types.js';