cognitive-core 0.0.2 → 0.1.2

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

@@ -0,0 +1,239 @@
+/**
+ * Local ACP Backend using acp-factory
+ *
+ * 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,
+  type AgentConfig,
+  type SpawnOptions,
+} from 'acp-factory';
+import type {
+  AgentBackend,
+  AgentSpawnConfig,
+  AgentSession,
+} from '../types.js';
+import { ACPProtocolHandler, type ACPSessionBase } from './acp-protocol.js';
+
+// ============================================================
+// Configuration Types
+// ============================================================
+
+/**
+ * ACP agent configuration
+ */
+export interface ACPAgentConfig extends AgentConfig {
+  /** Display name for the agent */
+  displayName?: string;
+}
+
+// ============================================================
+// Local Session State
+// ============================================================
+
+/**
+ * Session state for locally-spawned ACP agents.
+ * Extends the base with an AgentHandle for process lifecycle.
+ */
+interface LocalACPSessionState extends ACPSessionBase {
+  agentHandle: AgentHandle;
+}
+
+// ============================================================
+// LocalACPBackend
+// ============================================================
+
+/**
+ * Local ACP Backend
+ *
+ * Spawns ACP-compatible agents as local processes via AgentFactory.
+ * Protocol handling is inherited from ACPProtocolHandler.
+ */
+export class LocalACPBackend
+  extends ACPProtocolHandler<LocalACPSessionState>
+  implements AgentBackend
+{
+  readonly name = 'acp';
+  readonly supportedTypes: string[];
+
+  private handles: Map<string, AgentHandle> = new Map();
+
+  constructor(configs: Record<string, ACPAgentConfig>) {
+    super();
+    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 locally via AgentFactory
+      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: LocalACPSessionState = {
+        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 (inherited protocol handler)
+      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(
+        `[LocalACPBackend] Session ${atlasSessionId} spawn failed:`,
+        error instanceof Error ? error.message : String(error),
+      );
+      return atlasSession;
+    }
+  }
+
+  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(
+        `[LocalACPBackend] Session ${sessionId} cancel error:`,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+
+    try {
+      // Close the local agent handle
+      await state.agentHandle.close();
+    } catch (error) {
+      // Log close errors but don't throw
+      console.error(
+        `[LocalACPBackend] 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);
+  }
+
+  /**
+   * 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>,
+): LocalACPBackend {
+  return new LocalACPBackend(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,38 @@
+export {
+  SubprocessBackend,
+  createSubprocessBackend,
+  claudeCodeConfig,
+  type SubprocessAgentConfig,
+} from './subprocess.js';
+
+export {
+  MockBackend,
+  createMockBackend,
+  type MockAgentBehavior,
+} from './mock.js';
+
+export {
+  LocalACPBackend,
+  ACPBackend,
+  createACPBackend,
+  claudeCodeACPConfig,
+  claudeCodeDirectConfig,
+  registerCommonAgents,
+  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';

package/src/runtime/backends/macro-agent.ts

@@ -0,0 +1,177 @@
+/**
+ * macro-agent backend adapter.
+ *
+ * Wraps macro-agent's MacroAgentBackend as a cognitive-core AgentBackend
+ * using structural typing — cognitive-core does not import macro-agent.
+ *
+ * Usage:
+ * ```typescript
+ * import { MacroAgentBackend } from 'macro-agent';
+ * import { adaptMacroBackend, createMacroAgentSource } from 'cognitive-core';
+ *
+ * const macroBackend = new MacroAgentBackend(agentManager);
+ * const backend = adaptMacroBackend(macroBackend);
+ * atlas.setAgentManager([backend]);
+ *
+ * // Or register as a ComputeSource:
+ * const source = createMacroAgentSource(macroBackend, { costTier: 'medium' });
+ * computeProvider.register(source);
+ * ```
+ */
+
+import type {
+  AgentBackend,
+  AgentSpawnConfig,
+  AgentSession,
+  AgentMessage,
+  ToolCall,
+} from '../types.js';
+import type { ComputeSource, CostTier } from '../compute-provider.js';
+import type { Task } from '../../types/index.js';
+
+// ── Structural interface ──────────────────────────────────────
+
+/**
+ * Structural contract for macro-agent's MacroAgentBackend.
+ *
+ * Any object matching this shape can be adapted — no import from
+ * macro-agent is needed. macro-agent's bridge types (CognitiveAgentSession,
+ * CognitiveAgentMessage, CognitiveToolCall) are structurally identical
+ * to cognitive-core's canonical types.
+ */
+export interface MacroAgentBackendLike {
+  readonly name: string;
+  readonly supportedTypes: readonly string[];
+  isAvailable(): Promise<boolean>;
+  spawn(config: {
+    agentType: string;
+    task: { description: string };
+  }): Promise<MacroSessionLike>;
+  getSession(sessionId: string): Promise<MacroSessionLike | undefined>;
+  terminate(sessionId: string): Promise<void>;
+  listSessions(): Promise<MacroSessionLike[]>;
+}
+
+/**
+ * Structural contract for macro-agent's CognitiveAgentSession.
+ */
+export interface MacroSessionLike {
+  id: string;
+  agentType: string;
+  task: { description: string };
+  state: string;
+  messages: AgentMessage[];
+  toolCalls: ToolCall[];
+  startTime: Date;
+  endTime?: Date;
+  result?: unknown;
+  error?: string;
+  metadata: Record<string, unknown>;
+}
+
+// ── Adapter ───────────────────────────────────────────────────
+
+/**
+ * Adapter that wraps a macro-agent-compatible backend as a cognitive-core
+ * AgentBackend.
+ *
+ * Handles the type gap between macro-agent's CognitiveTask (description-only
+ * subset) and cognitive-core's Task (full schema with id, domain, etc.).
+ * Since cognitive-core always passes full Task objects through spawn(),
+ * the adapter caches them and re-attaches on session retrieval.
+ */
+export class MacroAgentBackendAdapter implements AgentBackend {
+  readonly name: string;
+  readonly supportedTypes: string[];
+
+  private readonly inner: MacroAgentBackendLike;
+  private readonly taskCache = new Map<string, Task>();
+
+  constructor(backend: MacroAgentBackendLike) {
+    this.inner = backend;
+    this.name = backend.name;
+    this.supportedTypes = [...backend.supportedTypes];
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return this.inner.isAvailable();
+  }
+
+  async spawn(config: AgentSpawnConfig): Promise<AgentSession> {
+    const session = await this.inner.spawn(config);
+    this.taskCache.set(session.id, config.task);
+    return this.toAgentSession(session);
+  }
+
+  async getSession(sessionId: string): Promise<AgentSession | undefined> {
+    const session = await this.inner.getSession(sessionId);
+    if (!session) return undefined;
+    return this.toAgentSession(session);
+  }
+
+  async terminate(sessionId: string): Promise<void> {
+    return this.inner.terminate(sessionId);
+  }
+
+  async listSessions(): Promise<AgentSession[]> {
+    const sessions = await this.inner.listSessions();
+    return sessions.map(s => this.toAgentSession(s));
+  }
+
+  private toAgentSession(session: MacroSessionLike): AgentSession {
+    const task = this.taskCache.get(session.id);
+    return {
+      id: session.id,
+      agentType: session.agentType,
+      // Prefer the cached full Task; fall back to runtime object (which IS
+      // a full Task when cognitive-core is the caller, just typed narrowly).
+      task: task ?? (session.task as Task),
+      state: session.state as AgentSession['state'],
+      messages: session.messages,
+      toolCalls: session.toolCalls,
+      startTime: session.startTime,
+      endTime: session.endTime,
+      result: session.result,
+      error: session.error,
+      metadata: session.metadata,
+    };
+  }
+}
+
+// ── Factory helpers ───────────────────────────────────────────
+
+/**
+ * Adapt a macro-agent MacroAgentBackend for use with cognitive-core.
+ *
+ * @param backend - Any object matching the MacroAgentBackendLike shape
+ * @returns An AgentBackend usable with Atlas.setAgentManager()
+ */
+export function adaptMacroBackend(
+  backend: MacroAgentBackendLike,
+): AgentBackend {
+  return new MacroAgentBackendAdapter(backend);
+}
+
+/**
+ * Create a ComputeSource for macro-agent backend registration
+ * with DefaultComputeProvider.
+ *
+ * @param backend - Any object matching the MacroAgentBackendLike shape
+ * @param options - Cost tier, location, and priority for compute resolution
+ */
+export function createMacroAgentSource(
+  backend: MacroAgentBackendLike,
+  options?: {
+    costTier?: CostTier;
+    location?: 'local' | 'remote';
+    priority?: number;
+  },
+): ComputeSource {
+  return {
+    name: backend.name,
+    backend: adaptMacroBackend(backend),
+    costTier: options?.costTier ?? 'medium',
+    location: options?.location ?? 'local',
+    priority: options?.priority ?? 50,
+  };
+}