cognitive-core 0.1.0 → 0.2.0

package/src/runtime/backends/acp-protocol.ts

@@ -0,0 +1,231 @@
+/**
+ * ACP Protocol Handler (Base Class)
+ *
+ * Extracts the ACP wire protocol handling (processUpdate, runPrompt,
+ * session state management) from the monolithic ACPBackend into a
+ * reusable base class.
+ *
+ * Backend implementations (local, remote) extend this and provide
+ * their own spawn() / terminate() for their compute environment.
+ */
+import type {
+  Session,
+  ExtendedSessionUpdate,
+} from 'acp-factory';
+import type {
+  AgentSpawnConfig,
+  AgentSession,
+  AgentMessage,
+  ToolCall,
+} from '../types.js';
+
+// ============================================================
+// Session State Types
+// ============================================================
+
+/**
+ * Base session state shared by all ACP backends.
+ * Subclasses can extend this with backend-specific fields.
+ */
+export interface ACPSessionBase {
+  atlasSession: AgentSession;
+  acpSession: Session;
+}
+
+// ============================================================
+// Protocol Handler Base Class
+// ============================================================
+
+/**
+ * Abstract base class that handles ACP wire protocol concerns:
+ * - processUpdate(): Parses ExtendedSessionUpdate into AgentSession messages/tool calls
+ * - runPrompt(): Streams updates from an ACP session prompt
+ * - Common session accessors (getSession, sendMessage, listSessions)
+ *
+ * Subclasses provide their own lifecycle management (spawn, terminate).
+ */
+export abstract class ACPProtocolHandler<
+  TState extends ACPSessionBase = ACPSessionBase,
+> {
+  protected sessions: Map<string, TState> = new Map();
+
+  // ----------------------------------------------------------
+  // Protocol: process a single ACP session update
+  // ----------------------------------------------------------
+
+  /**
+   * Process a session update from the agent.
+   * Uses defensive typing since ACP types can vary.
+   */
+  protected 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;
+    }
+  }
+
+  // ----------------------------------------------------------
+  // Protocol: run a prompt and collect streaming updates
+  // ----------------------------------------------------------
+
+  /**
+   * Run a prompt on an ACP session and collect all streaming updates
+   * into the Atlas session.
+   */
+  protected async runPrompt(
+    state: TState,
+    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(
+        `[ACPProtocol] Session ${atlasSession.id} prompt execution failed:`,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
+  // ----------------------------------------------------------
+  // Common session accessors
+  // ----------------------------------------------------------
+
+  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 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;
+  }
+}

package/src/runtime/backends/acp.ts

@@ -1,24 +1,26 @@
 /**
- * ACP Backend using acp-factory
+ * Local 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.
+ * Extends ACPProtocolHandler with local process spawning via AgentFactory.
+ * The protocol handling (processUpdate, runPrompt, session management) is
+ * inherited from the base class so it can be reused by future remote backends.
  */
 import {
   AgentFactory,
   AgentHandle,
-  Session,
   type AgentConfig,
   type SpawnOptions,
-  type ExtendedSessionUpdate,
 } from 'acp-factory';
 import type {
   AgentBackend,
   AgentSpawnConfig,
   AgentSession,
-  AgentMessage,
-  ToolCall,
 } from '../types.js';
+import { ACPProtocolHandler, type ACPSessionBase } from './acp-protocol.js';
+
+// ============================================================
+// Configuration Types
+// ============================================================
 
 /**
  * ACP agent configuration
@@ -28,27 +30,39 @@ export interface ACPAgentConfig extends AgentConfig {
   displayName?: string;
 }
 
+// ============================================================
+// Local Session State
+// ============================================================
+
 /**
- * Active ACP session state
+ * Session state for locally-spawned ACP agents.
+ * Extends the base with an AgentHandle for process lifecycle.
  */
-interface ACPSessionState {
-  atlasSession: AgentSession;
+interface LocalACPSessionState extends ACPSessionBase {
   agentHandle: AgentHandle;
-  acpSession: Session;
 }
 
+// ============================================================
+// LocalACPBackend
+// ============================================================
+
 /**
- * ACP Backend
- * Uses acp-factory to spawn and manage ACP-compatible agents
+ * Local ACP Backend
+ *
+ * Spawns ACP-compatible agents as local processes via AgentFactory.
+ * Protocol handling is inherited from ACPProtocolHandler.
  */
-export class ACPBackend implements AgentBackend {
+export class LocalACPBackend
+  extends ACPProtocolHandler<LocalACPSessionState>
+  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>) {
+    super();
     this.supportedTypes = Object.keys(configs);
 
     // Register all agent configs with AgentFactory
@@ -83,7 +97,7 @@ export class ACPBackend implements AgentBackend {
     };
 
     try {
-      // Spawn the agent
+      // Spawn the agent locally via AgentFactory
       const spawnOptions: SpawnOptions = {
         permissionMode: 'auto-approve', // Auto-approve for automated learning
         env: config.env,
@@ -100,7 +114,7 @@ export class ACPBackend implements AgentBackend {
       const acpSession = await agentHandle.createSession(cwd);
 
       // Store session state
-      const state: ACPSessionState = {
+      const state: LocalACPSessionState = {
         atlasSession,
         agentHandle,
         acpSession,
@@ -116,7 +130,7 @@ export class ACPBackend implements AgentBackend {
         promptContent += `\n\n## Additional Context\n\`\`\`json\n${JSON.stringify(config.task.context, null, 2)}\n\`\`\``;
       }
 
-      // Send prompt and collect updates
+      // Send prompt and collect updates (inherited protocol handler)
       await this.runPrompt(state, promptContent, config);
 
       return atlasSession;
@@ -125,169 +139,13 @@ export class ACPBackend implements AgentBackend {
       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)
+        `[LocalACPBackend] 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;
@@ -298,19 +156,19 @@ export class ACPBackend implements AgentBackend {
     } catch (error) {
       // Log cancellation errors but don't throw
       console.error(
-        `[ACPBackend] Session ${sessionId} cancel error:`,
-        error instanceof Error ? error.message : String(error)
+        `[LocalACPBackend] Session ${sessionId} cancel error:`,
+        error instanceof Error ? error.message : String(error),
       );
     }
 
     try {
-      // Close the agent handle
+      // Close the local 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)
+        `[LocalACPBackend] Session ${sessionId} close error:`,
+        error instanceof Error ? error.message : String(error),
       );
     }
 
@@ -322,32 +180,35 @@ export class ACPBackend implements AgentBackend {
     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
+   * Get a raw agent handle for advanced usage (local-specific)
    */
   getAgentHandle(sessionId: string): AgentHandle | undefined {
     return this.sessions.get(sessionId)?.agentHandle;
   }
 }
 
+// ============================================================
+// Backward-compatible alias
+// ============================================================
+
+/**
+ * @deprecated Use LocalACPBackend directly. ACPBackend is a backward-compatible alias.
+ */
+export const ACPBackend = LocalACPBackend;
+export type ACPBackend = LocalACPBackend;
+
+// ============================================================
+// Factory helpers
+// ============================================================
+
 /**
  * Create an ACP backend with agent configurations
  */
 export function createACPBackend(
-  configs: Record<string, ACPAgentConfig>
-): ACPBackend {
-  return new ACPBackend(configs);
+  configs: Record<string, ACPAgentConfig>,
+): LocalACPBackend {
+  return new LocalACPBackend(configs);
 }
 
 /**

package/src/runtime/backends/index.ts

@@ -12,6 +12,7 @@ export {
 } from './mock.js';
 
 export {
+  LocalACPBackend,
   ACPBackend,
   createACPBackend,
   claudeCodeACPConfig,
@@ -20,5 +21,18 @@ export {
   type ACPAgentConfig,
 } from './acp.js';
 
+export {
+  ACPProtocolHandler,
+  type ACPSessionBase,
+} from './acp-protocol.js';
+
+export {
+  MacroAgentBackendAdapter,
+  adaptMacroBackend,
+  createMacroAgentSource,
+  type MacroAgentBackendLike,
+  type MacroSessionLike,
+} from './macro-agent.js';
+
 // Re-export useful types from acp-factory
 export { AgentFactory } from 'acp-factory';