cognitive-core 0.0.1 → 0.1.0

package/src/runtime/backends/acp.ts

@@ -0,0 +1,378 @@
+/**
+ * ACP Backend using acp-factory
+ *
+ * This backend uses the acp-factory package to spawn and manage ACP-compatible
+ * agents like Claude Code, providing a clean interface for Atlas integration.
+ */
+import {
+  AgentFactory,
+  AgentHandle,
+  Session,
+  type AgentConfig,
+  type SpawnOptions,
+  type ExtendedSessionUpdate,
+} from 'acp-factory';
+import type {
+  AgentBackend,
+  AgentSpawnConfig,
+  AgentSession,
+  AgentMessage,
+  ToolCall,
+} from '../types.js';
+
+/**
+ * ACP agent configuration
+ */
+export interface ACPAgentConfig extends AgentConfig {
+  /** Display name for the agent */
+  displayName?: string;
+}
+
+/**
+ * Active ACP session state
+ */
+interface ACPSessionState {
+  atlasSession: AgentSession;
+  agentHandle: AgentHandle;
+  acpSession: Session;
+}
+
+/**
+ * ACP Backend
+ * Uses acp-factory to spawn and manage ACP-compatible agents
+ */
+export class ACPBackend implements AgentBackend {
+  readonly name = 'acp';
+  readonly supportedTypes: string[];
+
+  private sessions: Map<string, ACPSessionState> = new Map();
+  private handles: Map<string, AgentHandle> = new Map();
+
+  constructor(configs: Record<string, ACPAgentConfig>) {
+    this.supportedTypes = Object.keys(configs);
+
+    // Register all agent configs with AgentFactory
+    for (const [name, config] of Object.entries(configs)) {
+      AgentFactory.register(name, {
+        command: config.command,
+        args: config.args,
+        env: config.env,
+      });
+    }
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return this.supportedTypes.length > 0;
+  }
+
+  async spawn(config: AgentSpawnConfig): Promise<AgentSession> {
+    const atlasSessionId = crypto.randomUUID();
+
+    // Create Atlas session tracking
+    const atlasSession: AgentSession = {
+      id: atlasSessionId,
+      agentType: config.agentType,
+      task: config.task,
+      state: 'running',
+      messages: [],
+      toolCalls: [],
+      startTime: new Date(),
+      metadata: {
+        injectedKnowledge: !!config.injectedKnowledge,
+      },
+    };
+
+    try {
+      // Spawn the agent
+      const spawnOptions: SpawnOptions = {
+        permissionMode: 'auto-approve', // Auto-approve for automated learning
+        env: config.env,
+      };
+
+      const agentHandle = await AgentFactory.spawn(config.agentType, spawnOptions);
+      this.handles.set(atlasSessionId, agentHandle);
+
+      // Store capabilities
+      atlasSession.metadata.capabilities = agentHandle.capabilities;
+
+      // Create a session with the agent
+      const cwd = config.cwd ?? process.cwd();
+      const acpSession = await agentHandle.createSession(cwd);
+
+      // Store session state
+      const state: ACPSessionState = {
+        atlasSession,
+        agentHandle,
+        acpSession,
+      };
+      this.sessions.set(atlasSessionId, state);
+
+      // Build prompt content with knowledge injection
+      let promptContent = config.task.description;
+      if (config.systemPromptAdditions) {
+        promptContent = `## Context from Atlas Memory\n\n${config.systemPromptAdditions}\n\n---\n\n${promptContent}`;
+      }
+      if (Object.keys(config.task.context).length > 0) {
+        promptContent += `\n\n## Additional Context\n\`\`\`json\n${JSON.stringify(config.task.context, null, 2)}\n\`\`\``;
+      }
+
+      // Send prompt and collect updates
+      await this.runPrompt(state, promptContent, config);
+
+      return atlasSession;
+    } catch (error) {
+      atlasSession.state = 'failed';
+      atlasSession.error = error instanceof Error ? error.message : 'Unknown error';
+      atlasSession.endTime = new Date();
+      console.error(
+        `[ACPBackend] Session ${atlasSessionId} spawn failed:`,
+        error instanceof Error ? error.message : String(error)
+      );
+      return atlasSession;
+    }
+  }
+
+  /**
+   * Run a prompt and collect all updates
+   */
+  private async runPrompt(
+    state: ACPSessionState,
+    promptContent: string,
+    config: AgentSpawnConfig
+  ): Promise<void> {
+    const { atlasSession, acpSession } = state;
+
+    try {
+      // Stream updates from the agent
+      for await (const update of acpSession.prompt(promptContent)) {
+        this.processUpdate(atlasSession, update, config);
+      }
+
+      // Mark as completed
+      atlasSession.state = 'completed';
+      atlasSession.endTime = new Date();
+    } catch (error) {
+      atlasSession.state = 'failed';
+      atlasSession.error = error instanceof Error ? error.message : 'Unknown error';
+      atlasSession.endTime = new Date();
+      console.error(
+        `[ACPBackend] Session ${atlasSession.id} prompt execution failed:`,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+
+  /**
+   * Process a session update from the agent
+   * Uses defensive typing since ACP types can vary
+   */
+  private processUpdate(
+    session: AgentSession,
+    update: ExtendedSessionUpdate,
+    config: AgentSpawnConfig
+  ): void {
+    // Cast to any for flexible property access since ACP types are complex unions
+    const u = update as Record<string, unknown>;
+    const updateType = u.sessionUpdate as string;
+
+    switch (updateType) {
+      case 'agent_message_chunk':
+      case 'user_message_chunk':
+      case 'agent_thought_chunk': {
+        // ContentChunk has a single 'content' field (ContentBlock)
+        const content = u.content as Record<string, unknown> | undefined;
+        if (content && content.type === 'text' && typeof content.text === 'string') {
+          const message: AgentMessage = {
+            role: updateType === 'user_message_chunk' ? 'user' : 'assistant',
+            content: content.text,
+            timestamp: new Date(),
+          };
+          session.messages.push(message);
+          config.onMessage?.(message);
+        }
+        break;
+      }
+
+      case 'tool_call': {
+        // ToolCall has toolCallId, title, rawInput, status, content, etc.
+        const toolCallId = (u.toolCallId as string) ?? crypto.randomUUID();
+        const title = (u.title as string) ?? 'unknown';
+        const rawInput = u.rawInput;
+
+        const toolCall: ToolCall = {
+          id: toolCallId,
+          name: title,
+          input: rawInput,
+          startTime: new Date(),
+        };
+        session.toolCalls.push(toolCall);
+        config.onToolCall?.(toolCall);
+        break;
+      }
+
+      case 'tool_call_update': {
+        // ToolCallUpdate has toolCallId, status, content, etc.
+        const toolCallId = u.toolCallId as string;
+        const status = u.status as string | undefined;
+        const content = u.content as Array<Record<string, unknown>> | undefined;
+
+        const existingTc = session.toolCalls.find((t) => t.id === toolCallId);
+        if (existingTc) {
+          if (status === 'completed' || status === 'failed') {
+            existingTc.endTime = new Date();
+          }
+          if (content && Array.isArray(content)) {
+            // Extract text from content blocks
+            const outputs: string[] = [];
+            for (const block of content) {
+              if (block.type === 'text' && typeof block.text === 'string') {
+                outputs.push(block.text);
+              } else if (block.type === 'diff' && typeof block.diff === 'string') {
+                outputs.push(block.diff);
+              }
+            }
+            if (outputs.length > 0) {
+              existingTc.output = outputs.join('\n');
+            }
+          }
+          if (status === 'failed') {
+            existingTc.error = 'Tool call failed';
+          }
+        }
+        break;
+      }
+
+      case 'permission_request': {
+        // In auto-approve mode, this shouldn't happen, but log it
+        session.messages.push({
+          role: 'system',
+          content: `Permission requested: ${JSON.stringify(update)}`,
+          timestamp: new Date(),
+        });
+        break;
+      }
+
+      case 'plan': {
+        // Agent shared its plan
+        const plan = u.plan;
+        session.messages.push({
+          role: 'assistant',
+          content: `[Plan] ${JSON.stringify(plan)}`,
+          timestamp: new Date(),
+        });
+        break;
+      }
+
+      default:
+        // Log other updates for debugging
+        session.metadata.lastUpdate = update;
+    }
+  }
+
+  async getSession(sessionId: string): Promise<AgentSession | undefined> {
+    return this.sessions.get(sessionId)?.atlasSession;
+  }
+
+  async sendMessage(sessionId: string, message: string): Promise<void> {
+    const state = this.sessions.get(sessionId);
+    if (!state) {
+      throw new Error('Session not found');
+    }
+
+    // Send additional prompt
+    for await (const update of state.acpSession.prompt(message)) {
+      this.processUpdate(state.atlasSession, update, {
+        agentType: state.atlasSession.agentType,
+        task: state.atlasSession.task,
+      });
+    }
+  }
+
+  async terminate(sessionId: string): Promise<void> {
+    const state = this.sessions.get(sessionId);
+    if (!state) return;
+
+    try {
+      // Cancel any running prompt
+      await state.acpSession.cancel();
+    } catch (error) {
+      // Log cancellation errors but don't throw
+      console.error(
+        `[ACPBackend] Session ${sessionId} cancel error:`,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+
+    try {
+      // Close the agent handle
+      await state.agentHandle.close();
+    } catch (error) {
+      // Log close errors but don't throw
+      console.error(
+        `[ACPBackend] Session ${sessionId} close error:`,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+
+    state.atlasSession.state = 'failed';
+    state.atlasSession.error = 'Terminated';
+    state.atlasSession.endTime = new Date();
+
+    this.sessions.delete(sessionId);
+    this.handles.delete(sessionId);
+  }
+
+  async listSessions(): Promise<AgentSession[]> {
+    return Array.from(this.sessions.values()).map((s) => s.atlasSession);
+  }
+
+  /**
+   * Get a raw ACP session for advanced usage
+   */
+  getACPSession(sessionId: string): Session | undefined {
+    return this.sessions.get(sessionId)?.acpSession;
+  }
+
+  /**
+   * Get a raw agent handle for advanced usage
+   */
+  getAgentHandle(sessionId: string): AgentHandle | undefined {
+    return this.sessions.get(sessionId)?.agentHandle;
+  }
+}
+
+/**
+ * Create an ACP backend with agent configurations
+ */
+export function createACPBackend(
+  configs: Record<string, ACPAgentConfig>
+): ACPBackend {
+  return new ACPBackend(configs);
+}
+
+/**
+ * Pre-configured Claude Code agent via claude-code-acp
+ */
+export const claudeCodeACPConfig: ACPAgentConfig = {
+  command: 'npx',
+  args: ['claude-code-acp'],
+  displayName: 'Claude Code (ACP)',
+};
+
+/**
+ * Pre-configured Claude direct (requires --print mode)
+ * Note: This may not support full ACP protocol
+ */
+export const claudeCodeDirectConfig: ACPAgentConfig = {
+  command: 'claude',
+  args: ['--print'],
+  displayName: 'Claude (Direct)',
+};
+
+/**
+ * Helper to register common agents
+ */
+export function registerCommonAgents(): void {
+  AgentFactory.register('claude-code', claudeCodeACPConfig);
+  AgentFactory.register('claude-code-acp', claudeCodeACPConfig);
+}

package/src/runtime/backends/index.ts

@@ -0,0 +1,24 @@
+export {
+  SubprocessBackend,
+  createSubprocessBackend,
+  claudeCodeConfig,
+  type SubprocessAgentConfig,
+} from './subprocess.js';
+
+export {
+  MockBackend,
+  createMockBackend,
+  type MockAgentBehavior,
+} from './mock.js';
+
+export {
+  ACPBackend,
+  createACPBackend,
+  claudeCodeACPConfig,
+  claudeCodeDirectConfig,
+  registerCommonAgents,
+  type ACPAgentConfig,
+} from './acp.js';
+
+// Re-export useful types from acp-factory
+export { AgentFactory } from 'acp-factory';

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