cognitive-core 0.0.2 → 0.1.2

package/src/runtime/backends/mock.ts

@@ -0,0 +1,218 @@
+import type {
+  AgentBackend,
+  AgentSpawnConfig,
+  AgentSession,
+  AgentMessage,
+  ToolCall,
+} from '../types.js';
+
+/**
+ * Mock agent behavior definition
+ */
+export interface MockAgentBehavior {
+  /** Simulated tool calls */
+  toolCalls?: Array<{
+    name: string;
+    input: unknown;
+    output: unknown;
+    delayMs?: number;
+  }>;
+  /** Messages to emit */
+  messages?: Array<{
+    role: 'assistant' | 'user';
+    content: string;
+    delayMs?: number;
+  }>;
+  /** Final result */
+  result?: unknown;
+  /** Should the agent succeed? */
+  success?: boolean;
+  /** Error message if failing */
+  error?: string;
+  /** Total duration in ms */
+  durationMs?: number;
+}
+
+/**
+ * Mock backend for testing
+ */
+export class MockBackend implements AgentBackend {
+  readonly name = 'mock';
+  readonly supportedTypes = ['mock', 'test'];
+
+  private sessions: Map<string, AgentSession> = new Map();
+  private behaviors: Map<string, MockAgentBehavior> = new Map();
+  private defaultBehavior: MockAgentBehavior;
+
+  constructor(defaultBehavior?: MockAgentBehavior) {
+    this.defaultBehavior = defaultBehavior ?? {
+      success: true,
+      result: 'Mock result',
+      durationMs: 100,
+    };
+  }
+
+  /**
+   * Set behavior for a specific task description
+   */
+  setBehavior(taskDescription: string, behavior: MockAgentBehavior): void {
+    this.behaviors.set(taskDescription, behavior);
+  }
+
+  /**
+   * Set default behavior for all tasks
+   */
+  setDefaultBehavior(behavior: MockAgentBehavior): void {
+    this.defaultBehavior = behavior;
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return true;
+  }
+
+  async spawn(config: AgentSpawnConfig): Promise<AgentSession> {
+    const sessionId = crypto.randomUUID();
+    const behavior =
+      this.behaviors.get(config.task.description) ?? this.defaultBehavior;
+
+    const session: AgentSession = {
+      id: sessionId,
+      agentType: config.agentType,
+      task: config.task,
+      state: 'running',
+      messages: [],
+      toolCalls: [],
+      startTime: new Date(),
+      metadata: {
+        injectedKnowledge: !!config.injectedKnowledge,
+        hasSystemPromptAdditions: !!config.systemPromptAdditions,
+      },
+    };
+
+    this.sessions.set(sessionId, session);
+
+    // Simulate execution asynchronously
+    this.simulateExecution(session, behavior, config).catch((error) => {
+      session.state = 'failed';
+      session.error = error.message;
+      session.endTime = new Date();
+    });
+
+    return session;
+  }
+
+  private async simulateExecution(
+    session: AgentSession,
+    behavior: MockAgentBehavior,
+    config: AgentSpawnConfig
+  ): Promise<void> {
+    const startTime = Date.now();
+
+    // Emit messages
+    if (behavior.messages) {
+      for (const msg of behavior.messages) {
+        if (msg.delayMs) {
+          await this.delay(msg.delayMs);
+        }
+
+        const message: AgentMessage = {
+          role: msg.role,
+          content: msg.content,
+          timestamp: new Date(),
+        };
+        session.messages.push(message);
+        config.onMessage?.(message);
+      }
+    }
+
+    // Emit tool calls
+    if (behavior.toolCalls) {
+      for (const tc of behavior.toolCalls) {
+        if (tc.delayMs) {
+          await this.delay(tc.delayMs);
+        }
+
+        const toolCall: ToolCall = {
+          id: crypto.randomUUID(),
+          name: tc.name,
+          input: tc.input,
+          output: tc.output,
+          startTime: new Date(),
+          endTime: new Date(),
+        };
+        session.toolCalls.push(toolCall);
+        config.onToolCall?.(toolCall);
+      }
+    }
+
+    // Wait for remaining duration
+    const elapsed = Date.now() - startTime;
+    const remaining = (behavior.durationMs ?? 100) - elapsed;
+    if (remaining > 0) {
+      await this.delay(remaining);
+    }
+
+    // Complete
+    session.endTime = new Date();
+    if (behavior.success ?? true) {
+      session.state = 'completed';
+      session.result = behavior.result;
+    } else {
+      session.state = 'failed';
+      session.error = behavior.error ?? 'Mock failure';
+    }
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  async getSession(sessionId: string): Promise<AgentSession | undefined> {
+    return this.sessions.get(sessionId);
+  }
+
+  async sendMessage(sessionId: string, _message: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error('Session not found');
+    }
+    // Mock doesn't process additional messages
+  }
+
+  async terminate(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+
+    session.state = 'failed';
+    session.error = 'Terminated';
+    session.endTime = new Date();
+  }
+
+  async listSessions(): Promise<AgentSession[]> {
+    return Array.from(this.sessions.values());
+  }
+
+  /**
+   * Get all sessions (for testing assertions)
+   */
+  getAllSessions(): AgentSession[] {
+    return Array.from(this.sessions.values());
+  }
+
+  /**
+   * Clear all sessions
+   */
+  clear(): void {
+    this.sessions.clear();
+    this.behaviors.clear();
+  }
+}
+
+/**
+ * Create a mock backend
+ */
+export function createMockBackend(
+  defaultBehavior?: MockAgentBehavior
+): MockBackend {
+  return new MockBackend(defaultBehavior);
+}

package/src/runtime/backends/subprocess.ts

@@ -0,0 +1,356 @@
+import { spawn, type ChildProcess } from 'child_process';
+import { EventEmitter } from 'events';
+import type {
+  AgentBackend,
+  AgentSpawnConfig,
+  AgentSession,
+  AgentMessage,
+  ToolCall,
+} from '../types.js';
+
+/**
+ * Configuration for subprocess-based agents
+ */
+export interface SubprocessAgentConfig {
+  /** Command to run the agent */
+  command: string;
+  /** Arguments for the command */
+  args?: string[];
+  /** How to pass the task to the agent */
+  taskPassingMode: 'stdin' | 'arg' | 'env' | 'file';
+  /** Environment variable name for task (if taskPassingMode is 'env') */
+  taskEnvVar?: string;
+  /** How to pass knowledge injection */
+  knowledgePassingMode: 'stdin' | 'env' | 'file' | 'system-prompt';
+  /** Environment variable name for knowledge (if knowledgePassingMode is 'env') */
+  knowledgeEnvVar?: string;
+  /** Parser for agent output to extract tool calls */
+  outputParser?: (output: string) => {
+    messages: AgentMessage[];
+    toolCalls: ToolCall[];
+    result?: unknown;
+    isComplete: boolean;
+  };
+}
+
+/**
+ * Running subprocess session
+ */
+interface SubprocessSession {
+  session: AgentSession;
+  process: ChildProcess;
+  outputBuffer: string;
+  emitter: EventEmitter;
+}
+
+/**
+ * Subprocess-based agent backend
+ * Spawns agents as child processes (e.g., Claude Code CLI, custom scripts)
+ */
+export class SubprocessBackend implements AgentBackend {
+  readonly name = 'subprocess';
+  readonly supportedTypes: string[];
+
+  private configs: Map<string, SubprocessAgentConfig> = new Map();
+  private sessions: Map<string, SubprocessSession> = new Map();
+
+  constructor(configs: Record<string, SubprocessAgentConfig>) {
+    this.supportedTypes = Object.keys(configs);
+    for (const [type, config] of Object.entries(configs)) {
+      this.configs.set(type, config);
+    }
+  }
+
+  async isAvailable(): Promise<boolean> {
+    // Check if at least one configured command exists
+    // For now, just return true
+    return true;
+  }
+
+  async spawn(config: AgentSpawnConfig): Promise<AgentSession> {
+    const agentConfig = this.configs.get(config.agentType);
+    if (!agentConfig) {
+      const error = new Error(`Unknown agent type: ${config.agentType}`);
+      console.error('[SubprocessBackend] Spawn failed:', error.message);
+      throw error;
+    }
+
+    const sessionId = crypto.randomUUID();
+    const session: AgentSession = {
+      id: sessionId,
+      agentType: config.agentType,
+      task: config.task,
+      state: 'running',
+      messages: [],
+      toolCalls: [],
+      startTime: new Date(),
+      metadata: {},
+    };
+
+    // Build environment (filter out undefined values from process.env)
+    const env: Record<string, string> = Object.fromEntries(
+      Object.entries({ ...process.env, ...config.env }).filter(
+        (entry): entry is [string, string] => entry[1] !== undefined
+      )
+    );
+
+    // Pass task via env if configured
+    if (agentConfig.taskPassingMode === 'env' && agentConfig.taskEnvVar) {
+      env[agentConfig.taskEnvVar] = config.task.description;
+    }
+
+    // Pass knowledge via env if configured
+    if (
+      agentConfig.knowledgePassingMode === 'env' &&
+      agentConfig.knowledgeEnvVar &&
+      config.systemPromptAdditions
+    ) {
+      env[agentConfig.knowledgeEnvVar] = config.systemPromptAdditions;
+    }
+
+    // Build arguments
+    const args = [...(agentConfig.args ?? [])];
+    if (agentConfig.taskPassingMode === 'arg') {
+      args.push(config.task.description);
+    }
+
+    // Spawn the process
+    const childProcess = spawn(agentConfig.command, args, {
+      cwd: config.cwd,
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    const emitter = new EventEmitter();
+    const subSession: SubprocessSession = {
+      session,
+      process: childProcess,
+      outputBuffer: '',
+      emitter,
+    };
+
+    this.sessions.set(sessionId, subSession);
+
+    // Pass task via stdin if configured
+    if (agentConfig.taskPassingMode === 'stdin') {
+      let input = config.task.description;
+      if (config.systemPromptAdditions) {
+        input = `${config.systemPromptAdditions}\n\n${input}`;
+      }
+      childProcess.stdin?.write(input);
+      childProcess.stdin?.end();
+    }
+
+    // Handle output
+    const parser = agentConfig.outputParser ?? this.defaultParser;
+
+    childProcess.stdout?.on('data', (data: Buffer) => {
+      const output = data.toString();
+      subSession.outputBuffer += output;
+
+      // Parse and emit events
+      const parsed = parser(subSession.outputBuffer);
+
+      // Add new messages
+      for (const msg of parsed.messages) {
+        if (!session.messages.some((m) => m.timestamp === msg.timestamp)) {
+          session.messages.push(msg);
+          config.onMessage?.(msg);
+        }
+      }
+
+      // Add new tool calls
+      for (const tc of parsed.toolCalls) {
+        if (!session.toolCalls.some((t) => t.id === tc.id)) {
+          session.toolCalls.push(tc);
+          config.onToolCall?.(tc);
+        }
+      }
+
+      if (parsed.isComplete) {
+        session.result = parsed.result;
+      }
+    });
+
+    childProcess.stderr?.on('data', (data: Buffer) => {
+      const error = data.toString();
+      session.messages.push({
+        role: 'system',
+        content: `[stderr] ${error}`,
+        timestamp: new Date(),
+      });
+    });
+
+    // Handle exit
+    childProcess.on('close', (code) => {
+      session.endTime = new Date();
+      session.state = code === 0 ? 'completed' : 'failed';
+      if (code !== 0) {
+        session.error = `Process exited with code ${code}`;
+        console.error(
+          `[SubprocessBackend] Session ${sessionId} failed: exit code ${code}`
+        );
+      }
+      emitter.emit('complete', session);
+    });
+
+    childProcess.on('error', (error) => {
+      session.endTime = new Date();
+      session.state = 'failed';
+      session.error = error.message;
+      console.error(
+        `[SubprocessBackend] Session ${sessionId} process error:`,
+        error.message
+      );
+      emitter.emit('complete', session);
+    });
+
+    // Set up timeout
+    if (config.timeout) {
+      setTimeout(() => {
+        if (session.state === 'running') {
+          console.error(
+            `[SubprocessBackend] Session ${sessionId} timed out after ${config.timeout}ms`
+          );
+          childProcess.kill('SIGTERM');
+          session.state = 'failed';
+          session.error = 'Timeout';
+          session.endTime = new Date();
+        }
+      }, config.timeout);
+    }
+
+    return session;
+  }
+
+  async getSession(sessionId: string): Promise<AgentSession | undefined> {
+    return this.sessions.get(sessionId)?.session;
+  }
+
+  async sendMessage(sessionId: string, message: string): Promise<void> {
+    const subSession = this.sessions.get(sessionId);
+    if (!subSession || subSession.session.state !== 'running') {
+      throw new Error('Session not found or not running');
+    }
+
+    subSession.process.stdin?.write(message + '\n');
+  }
+
+  async terminate(sessionId: string): Promise<void> {
+    const subSession = this.sessions.get(sessionId);
+    if (!subSession) return;
+
+    subSession.process.kill('SIGTERM');
+    subSession.session.state = 'failed';
+    subSession.session.error = 'Terminated';
+    subSession.session.endTime = new Date();
+  }
+
+  async listSessions(): Promise<AgentSession[]> {
+    return Array.from(this.sessions.values()).map((s) => s.session);
+  }
+
+  /**
+   * Default parser for agent output
+   * Override with custom parser for specific agent formats
+   */
+  private defaultParser(output: string): {
+    messages: AgentMessage[];
+    toolCalls: ToolCall[];
+    result?: unknown;
+    isComplete: boolean;
+  } {
+    const messages: AgentMessage[] = [];
+    const toolCalls: ToolCall[] = [];
+    let result: unknown;
+    let isComplete = false;
+
+    // Simple line-based parsing
+    const lines = output.split('\n');
+    for (const line of lines) {
+      if (line.trim()) {
+        messages.push({
+          role: 'assistant',
+          content: line,
+          timestamp: new Date(),
+        });
+      }
+
+      // Look for completion markers
+      if (line.includes('DONE:') || line.includes('COMPLETE:')) {
+        isComplete = true;
+        result = line.split(':').slice(1).join(':').trim();
+      }
+    }
+
+    return { messages, toolCalls, result, isComplete };
+  }
+}
+
+/**
+ * Create a subprocess backend with common agent configurations
+ */
+export function createSubprocessBackend(
+  configs: Record<string, SubprocessAgentConfig>
+): SubprocessBackend {
+  return new SubprocessBackend(configs);
+}
+
+/**
+ * Pre-configured Claude Code agent
+ */
+export const claudeCodeConfig: SubprocessAgentConfig = {
+  command: 'claude',
+  args: ['--print', '--output-format', 'json'],
+  taskPassingMode: 'arg',
+  knowledgePassingMode: 'system-prompt',
+  outputParser: (output: string) => {
+    const messages: AgentMessage[] = [];
+    const toolCalls: ToolCall[] = [];
+    let result: unknown;
+    let isComplete = false;
+
+    // Try to parse JSON lines (Claude Code output format)
+    const lines = output.split('\n');
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      try {
+        const parsed = JSON.parse(line);
+
+        if (parsed.type === 'assistant') {
+          messages.push({
+            role: 'assistant',
+            content: parsed.content ?? '',
+            timestamp: new Date(parsed.timestamp ?? Date.now()),
+          });
+        } else if (parsed.type === 'tool_use') {
+          toolCalls.push({
+            id: parsed.id ?? crypto.randomUUID(),
+            name: parsed.name,
+            input: parsed.input,
+            startTime: new Date(parsed.timestamp ?? Date.now()),
+          });
+        } else if (parsed.type === 'tool_result') {
+          const tc = toolCalls.find((t) => t.id === parsed.tool_use_id);
+          if (tc) {
+            tc.output = parsed.content;
+            tc.endTime = new Date(parsed.timestamp ?? Date.now());
+          }
+        } else if (parsed.type === 'result') {
+          isComplete = true;
+          result = parsed.result;
+        }
+      } catch {
+        // Not JSON, treat as plain text
+        messages.push({
+          role: 'assistant',
+          content: line,
+          timestamp: new Date(),
+        });
+      }
+    }
+
+    return { messages, toolCalls, result, isComplete };
+  },
+};