cognitive-core 0.2.4 → 0.3.1

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

@@ -1,231 +0,0 @@
-/**
- * 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,239 +0,0 @@
-/**
- * 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

@@ -1,38 +0,0 @@
-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

@@ -1,177 +0,0 @@
-/**
- * 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,
-  };
-}