cognitive-core 0.0.2 → 0.1.0

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 };
+  },
+};

package/src/runtime/flows/learning.ts

@@ -0,0 +1,183 @@
+import type { Task } from '../../types/index.js';
+import type { MemorySystem } from '../../memory/system.js';
+import type { LearningPipeline, ProcessResult, BatchResult } from '../../learning/index.js';
+import type { AgentManager } from '../manager.js';
+import type { AgentResult, AgentSession, AgentObserverCallbacks } from '../types.js';
+
+/**
+ * Configuration for the learning flow
+ */
+export interface LearningFlowConfig {
+  /** Agent type to use for execution */
+  agentType: string;
+  /** Minimum trajectories before running batch learning */
+  batchThreshold?: number;
+  /** Whether to auto-run batch learning when threshold is reached */
+  autoBatch?: boolean;
+  /** Observer callbacks for real-time monitoring */
+  observer?: AgentObserverCallbacks;
+}
+
+/**
+ * Result of a learning flow execution
+ */
+export interface LearningFlowResult {
+  /** The agent result */
+  agentResult: AgentResult;
+  /** Processing result from learning pipeline */
+  processResult: ProcessResult;
+  /** Batch result if batch learning was triggered */
+  batchResult?: BatchResult;
+}
+
+/**
+ * Learning Flow
+ * Orchestrates: Agent execution → Trajectory capture → Playbook extraction → Memory storage
+ *
+ * This flow is for the "observation" direction:
+ * - Watch agents solve tasks
+ * - Extract learning signals from their trajectories
+ * - Store playbooks for future guidance
+ */
+export class LearningFlow {
+  private manager: AgentManager;
+  private pipeline: LearningPipeline;
+  private config: LearningFlowConfig;
+
+  constructor(
+    manager: AgentManager,
+    pipeline: LearningPipeline,
+    _memory: MemorySystem,
+    config: LearningFlowConfig
+  ) {
+    this.manager = manager;
+    this.pipeline = pipeline;
+    this.config = {
+      batchThreshold: 10,
+      autoBatch: true,
+      ...config,
+    };
+
+    // Register observer if provided
+    if (config.observer) {
+      this.manager.addObserver(config.observer);
+    }
+  }
+
+  /**
+   * Run a single task through the learning flow
+   */
+  async run(task: Task): Promise<LearningFlowResult> {
+    // 1. Spawn agent and get result (WITHOUT knowledge injection for pure learning)
+    const agentResult = await this.manager.spawnBaseline({
+      agentType: this.config.agentType,
+      task,
+      captureToolCalls: true,
+    });
+
+    // 2. Process trajectory through learning pipeline
+    const processResult = await this.pipeline.processTrajectory(
+      agentResult.trajectory
+    );
+
+    // 3. Run batch learning if threshold reached
+    let batchResult: BatchResult | undefined;
+    if (
+      this.config.autoBatch &&
+      this.pipeline.getAccumulatedCount() >= (this.config.batchThreshold ?? 10)
+    ) {
+      batchResult = await this.pipeline.runBatchLearning();
+    }
+
+    return {
+      agentResult,
+      processResult,
+      batchResult,
+    };
+  }
+
+  /**
+   * Run multiple tasks through the learning flow
+   */
+  async runBatch(tasks: Task[]): Promise<LearningFlowResult[]> {
+    const results: LearningFlowResult[] = [];
+    for (const task of tasks) {
+      const result = await this.run(task);
+      results.push(result);
+    }
+    return results;
+  }
+
+  /**
+   * Observe an external session and learn from it
+   * Use this when another system provides the session
+   */
+  async observeExternal(
+    session: AgentSession,
+    task: Task
+  ): Promise<LearningFlowResult> {
+    // Extract trajectory from session
+    const trajectory = await this.manager.observeAndLearn(session, task);
+
+    // Process through learning pipeline
+    const processResult = await this.pipeline.processTrajectory(trajectory);
+
+    // Check for batch learning
+    let batchResult: BatchResult | undefined;
+    if (
+      this.config.autoBatch &&
+      this.pipeline.getAccumulatedCount() >= (this.config.batchThreshold ?? 10)
+    ) {
+      batchResult = await this.pipeline.runBatchLearning();
+    }
+
+    return {
+      agentResult: {
+        session,
+        trajectory,
+        success: session.state === 'completed',
+        metrics: {
+          totalTime: session.endTime
+            ? session.endTime.getTime() - session.startTime.getTime()
+            : 0,
+          toolCallCount: session.toolCalls.length,
+          messageCount: session.messages.length,
+        },
+      },
+      processResult,
+      batchResult,
+    };
+  }
+
+  /**
+   * Force batch learning
+   */
+  async runBatchLearning(): Promise<BatchResult> {
+    return this.pipeline.runBatchLearning();
+  }
+
+  /**
+   * Get learning statistics
+   */
+  getStats(): {
+    pendingTrajectories: number;
+    batchThreshold: number;
+  } {
+    return {
+      pendingTrajectories: this.pipeline.getAccumulatedCount(),
+      batchThreshold: this.config.batchThreshold ?? 10,
+    };
+  }
+}
+
+/**
+ * Create a learning flow
+ */
+export function createLearningFlow(
+  manager: AgentManager,
+  pipeline: LearningPipeline,
+  memory: MemorySystem,
+  config: LearningFlowConfig
+): LearningFlow {
+  return new LearningFlow(manager, pipeline, memory, config);
+}