cognitive-core 0.0.2 → 0.1.0

package/src/runtime/manager.ts

@@ -0,0 +1,541 @@
+import type { Task, Trajectory, Step } from '../types/index.js';
+import {
+  createTrajectory,
+  createStep,
+  successOutcome,
+  failureOutcome,
+} from '../types/index.js';
+import type { MemorySystem, MemoryQueryResultV2 } from '../memory/system.js';
+import type {
+  AgentBackend,
+  AgentSpawnConfig,
+  AgentSession,
+  AgentResult,
+  AgentMessage,
+  ToolCall,
+  AgentObserverCallbacks,
+  KnowledgeInjector,
+  TrajectoryExtractor,
+} from './types.js';
+
+/**
+ * Default knowledge injector - formats memory for context injection
+ */
+export class DefaultKnowledgeInjector implements KnowledgeInjector {
+  format(
+    knowledge: MemoryQueryResultV2,
+    _agentType: string,
+    options?: { maxTokens?: number; format?: 'markdown' | 'json' | 'xml' }
+  ): string {
+    const format = options?.format ?? 'markdown';
+
+    if (format === 'json') {
+      return JSON.stringify(knowledge, null, 2);
+    }
+
+    if (format === 'xml') {
+      return this.formatXml(knowledge);
+    }
+
+    return this.formatMarkdown(knowledge);
+  }
+
+  private formatMarkdown(knowledge: MemoryQueryResultV2): string {
+    const sections: string[] = [];
+
+    if (knowledge.playbooks.length > 0) {
+      sections.push('## Applicable Playbooks\n');
+      for (const { playbook, score, matchType } of knowledge.playbooks) {
+        sections.push(`### ${playbook.name} (${(score * 100).toFixed(0)}% match via ${matchType})`);
+        sections.push(`**Strategy:** ${playbook.guidance.strategy}`);
+        if (playbook.guidance.tactics.length > 0) {
+          sections.push(`**Tactics:** ${playbook.guidance.tactics.join(', ')}`);
+        }
+        if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+          sections.push('**Steps:**');
+          playbook.guidance.steps.forEach((step, i) => {
+            sections.push(`${i + 1}. ${step}`);
+          });
+        }
+        sections.push(`*Confidence: ${(playbook.confidence * 100).toFixed(0)}%*\n`);
+      }
+    }
+
+    if (knowledge.experiences.length > 0) {
+      sections.push('## Similar Past Experiences\n');
+      for (const { experience, score } of knowledge.experiences) {
+        sections.push(`### Experience (relevance: ${(score * 100).toFixed(0)}%)`);
+        sections.push(`**Task:** ${experience.taskInput.slice(0, 200)}...`);
+        sections.push(`**Outcome:** ${experience.success ? 'Success' : 'Failed'}`);
+        sections.push(`**Approach:** ${experience.solutionOutput.slice(0, 300)}...`);
+        sections.push('');
+      }
+    }
+
+    return sections.join('\n');
+  }
+
+  private formatXml(knowledge: MemoryQueryResultV2): string {
+    const parts: string[] = ['<atlas-knowledge>'];
+
+    if (knowledge.playbooks.length > 0) {
+      parts.push('  <playbooks>');
+      for (const { playbook, score } of knowledge.playbooks) {
+        parts.push(`    <playbook name="${this.escapeXml(playbook.name)}" relevance="${score.toFixed(2)}">`);
+        parts.push(`      <strategy>${this.escapeXml(playbook.guidance.strategy)}</strategy>`);
+        if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+          parts.push('      <steps>');
+          playbook.guidance.steps.forEach((step, i) => {
+            parts.push(`        <step n="${i + 1}">${this.escapeXml(step)}</step>`);
+          });
+          parts.push('      </steps>');
+        }
+        parts.push(`      <confidence>${playbook.confidence}</confidence>`);
+        parts.push('    </playbook>');
+      }
+      parts.push('  </playbooks>');
+    }
+
+    if (knowledge.experiences.length > 0) {
+      parts.push('  <experiences>');
+      for (const { experience, score } of knowledge.experiences) {
+        parts.push(`    <experience relevance="${score.toFixed(2)}">`);
+        parts.push(`      <task>${this.escapeXml(experience.taskInput.slice(0, 200))}</task>`);
+        parts.push(`      <outcome>${experience.success ? 'success' : 'failure'}</outcome>`);
+        parts.push('    </experience>');
+      }
+      parts.push('  </experiences>');
+    }
+
+    parts.push('</atlas-knowledge>');
+    return parts.join('\n');
+  }
+
+  private escapeXml(str: string): string {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+}
+
+/**
+ * Default trajectory extractor - converts agent sessions to trajectories
+ */
+export class DefaultTrajectoryExtractor implements TrajectoryExtractor {
+  extract(session: AgentSession, task: Task): Trajectory {
+    const steps: Step[] = [];
+
+    // Convert tool calls to steps
+    for (const toolCall of session.toolCalls) {
+      steps.push(
+        createStep({
+          thought: this.extractThought(session.messages, toolCall),
+          action: `${toolCall.name}: ${this.summarizeInput(toolCall.input)}`,
+          observation: toolCall.error
+            ? `Error: ${toolCall.error}`
+            : this.summarizeOutput(toolCall.output),
+          metadata: {
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            duration: toolCall.endTime
+              ? toolCall.endTime.getTime() - toolCall.startTime.getTime()
+              : undefined,
+          },
+        })
+      );
+    }
+
+    // Determine outcome
+    const outcome =
+      session.state === 'completed'
+        ? successOutcome(session.result)
+        : failureOutcome(
+            session.error ?? 'Session did not complete successfully'
+          );
+
+    return createTrajectory({
+      task,
+      steps,
+      outcome,
+      agentId: `${session.agentType}:${session.id}`,
+      wallTimeSeconds: session.endTime
+        ? (session.endTime.getTime() - session.startTime.getTime()) / 1000
+        : 0,
+      metadata: {
+        sessionId: session.id,
+        agentType: session.agentType,
+        messageCount: session.messages.length,
+        ...session.metadata,
+      },
+    });
+  }
+
+  private extractThought(
+    messages: AgentMessage[],
+    toolCall: ToolCall
+  ): string | undefined {
+    // Find the assistant message just before this tool call
+    const toolCallTime = toolCall.startTime.getTime();
+    const precedingMessages = messages.filter(
+      (m) =>
+        m.role === 'assistant' &&
+        m.timestamp.getTime() < toolCallTime &&
+        m.timestamp.getTime() > toolCallTime - 60000 // Within 1 minute
+    );
+
+    if (precedingMessages.length > 0) {
+      const lastMessage = precedingMessages[precedingMessages.length - 1];
+      // Extract reasoning/thought from the message
+      return lastMessage.content.slice(0, 500);
+    }
+
+    return undefined;
+  }
+
+  private summarizeInput(input: unknown): string {
+    if (typeof input === 'string') {
+      return input.slice(0, 100);
+    }
+    if (typeof input === 'object' && input !== null) {
+      const str = JSON.stringify(input);
+      return str.slice(0, 100) + (str.length > 100 ? '...' : '');
+    }
+    return String(input);
+  }
+
+  private summarizeOutput(output: unknown): string {
+    if (output === undefined) return 'No output';
+    if (typeof output === 'string') {
+      return output.slice(0, 200) + (output.length > 200 ? '...' : '');
+    }
+    if (typeof output === 'object' && output !== null) {
+      const str = JSON.stringify(output);
+      return str.slice(0, 200) + (str.length > 200 ? '...' : '');
+    }
+    return String(output);
+  }
+}
+
+/**
+ * Agent Manager - orchestrates agent spawning, observation, and learning
+ */
+export class AgentManager {
+  private backends: Map<string, AgentBackend> = new Map();
+  private memory: MemorySystem;
+  private injector: KnowledgeInjector;
+  private extractor: TrajectoryExtractor;
+  private observers: AgentObserverCallbacks[] = [];
+  private activeSessions: Map<string, AgentSession> = new Map();
+
+  constructor(
+    memory: MemorySystem,
+    options?: {
+      injector?: KnowledgeInjector;
+      extractor?: TrajectoryExtractor;
+    }
+  ) {
+    this.memory = memory;
+    this.injector = options?.injector ?? new DefaultKnowledgeInjector();
+    this.extractor = options?.extractor ?? new DefaultTrajectoryExtractor();
+  }
+
+  /**
+   * Register an agent backend
+   */
+  registerBackend(backend: AgentBackend): void {
+    this.backends.set(backend.name, backend);
+  }
+
+  /**
+   * Get a registered backend
+   */
+  getBackend(name: string): AgentBackend | undefined {
+    return this.backends.get(name);
+  }
+
+  /**
+   * List available backends
+   */
+  listBackends(): string[] {
+    return Array.from(this.backends.keys());
+  }
+
+  /**
+   * Add an observer for agent events
+   */
+  addObserver(callbacks: AgentObserverCallbacks): void {
+    this.observers.push(callbacks);
+  }
+
+  /**
+   * Remove an observer
+   */
+  removeObserver(callbacks: AgentObserverCallbacks): void {
+    const index = this.observers.indexOf(callbacks);
+    if (index >= 0) {
+      this.observers.splice(index, 1);
+    }
+  }
+
+  /**
+   * Spawn an agent to execute a task
+   * This is the main entry point for running agents
+   */
+  async spawn(config: AgentSpawnConfig): Promise<AgentResult> {
+    // Find appropriate backend
+    const backend = this.findBackend(config.agentType);
+    if (!backend) {
+      throw new Error(
+        `No backend found for agent type: ${config.agentType}. ` +
+          `Available backends: ${this.listBackends().join(', ')}`
+      );
+    }
+
+    // Query memory for relevant knowledge if not provided
+    let knowledge = config.injectedKnowledge;
+    if (!knowledge) {
+      knowledge = await this.memory.queryV2(config.task.description, {
+        domains: config.task.domain ? [config.task.domain] : undefined,
+      });
+    }
+
+    // Format knowledge for injection
+    const formattedKnowledge = this.injector.format(knowledge, config.agentType);
+
+    // Use a session holder to allow callbacks to reference the session
+    // before it's assigned (closures capture the holder object, not the value)
+    const sessionHolder: { current: AgentSession | null } = { current: null };
+
+    // Build full config with knowledge injection
+    const fullConfig: AgentSpawnConfig = {
+      ...config,
+      systemPromptAdditions: [
+        config.systemPromptAdditions,
+        formattedKnowledge
+          ? `\n## Atlas Knowledge\n${formattedKnowledge}`
+          : undefined,
+      ]
+        .filter(Boolean)
+        .join('\n\n'),
+      onMessage: (message) => {
+        config.onMessage?.(message);
+        if (sessionHolder.current) {
+          this.notifyMessage(sessionHolder.current, message);
+        }
+      },
+      onToolCall: (toolCall) => {
+        config.onToolCall?.(toolCall);
+        if (sessionHolder.current) {
+          this.notifyToolCall(sessionHolder.current, toolCall);
+        }
+      },
+    };
+
+    // Spawn the agent
+    const session = await backend.spawn(fullConfig);
+    sessionHolder.current = session;
+    this.activeSessions.set(session.id, session);
+    this.notifySessionStart(session);
+
+    // Wait for completion and extract trajectory
+    const finalSession = await this.waitForCompletion(backend, session.id);
+    this.activeSessions.delete(session.id);
+
+    const trajectory = this.extractor.extract(finalSession, config.task);
+    this.notifySessionEnd(finalSession, trajectory);
+
+    return {
+      session: finalSession,
+      trajectory,
+      success: finalSession.state === 'completed',
+      metrics: {
+        totalTime: finalSession.endTime
+          ? finalSession.endTime.getTime() - finalSession.startTime.getTime()
+          : 0,
+        toolCallCount: finalSession.toolCalls.length,
+        messageCount: finalSession.messages.length,
+      },
+    };
+  }
+
+  /**
+   * Spawn an agent WITHOUT knowledge injection (for baseline/control)
+   */
+  async spawnBaseline(
+    config: Omit<AgentSpawnConfig, 'injectedKnowledge'>
+  ): Promise<AgentResult> {
+    return this.spawn({
+      ...config,
+      injectedKnowledge: {
+        experiences: [],
+        playbooks: [],
+      },
+    });
+  }
+
+  /**
+   * Run an A/B comparison: with and without knowledge injection
+   */
+  async compareWithKnowledge(
+    config: Omit<AgentSpawnConfig, 'injectedKnowledge'>
+  ): Promise<{
+    withKnowledge: AgentResult;
+    baseline: AgentResult;
+    improvement: {
+      timeDelta: number;
+      toolCallDelta: number;
+      successDelta: number;
+    };
+  }> {
+    // Run baseline first
+    const baseline = await this.spawnBaseline(config);
+
+    // Run with knowledge
+    const withKnowledge = await this.spawn(config);
+
+    return {
+      withKnowledge,
+      baseline,
+      improvement: {
+        timeDelta: baseline.metrics.totalTime - withKnowledge.metrics.totalTime,
+        toolCallDelta:
+          baseline.metrics.toolCallCount - withKnowledge.metrics.toolCallCount,
+        successDelta:
+          (withKnowledge.success ? 1 : 0) - (baseline.success ? 1 : 0),
+      },
+    };
+  }
+
+  /**
+   * Observe an external agent session and learn from it
+   * Use this when you have access to another agent's execution
+   */
+  async observeAndLearn(session: AgentSession, task: Task): Promise<Trajectory> {
+    const trajectory = this.extractor.extract(session, task);
+
+    // Store in memory for learning
+    await this.memory.storeTrajectory(trajectory);
+
+    return trajectory;
+  }
+
+  /**
+   * Get active sessions
+   */
+  getActiveSessions(): AgentSession[] {
+    return Array.from(this.activeSessions.values());
+  }
+
+  /**
+   * Terminate a session
+   */
+  async terminate(sessionId: string): Promise<void> {
+    const session = this.activeSessions.get(sessionId);
+    if (!session) return;
+
+    const backend = this.findBackend(session.agentType);
+    if (backend?.terminate) {
+      await backend.terminate(sessionId);
+    }
+
+    this.activeSessions.delete(sessionId);
+  }
+
+  /**
+   * Terminate all active sessions
+   */
+  async terminateAll(): Promise<void> {
+    const sessionIds = Array.from(this.activeSessions.keys());
+    await Promise.all(sessionIds.map((id) => this.terminate(id)));
+  }
+
+  /**
+   * Close the manager and clean up resources
+   * Terminates all active sessions and clears all state
+   */
+  async close(): Promise<void> {
+    // Terminate all active sessions
+    await this.terminateAll();
+
+    // Clear backends
+    this.backends.clear();
+
+    // Clear observers
+    this.observers = [];
+  }
+
+  // Private helpers
+
+  private findBackend(agentType: string): AgentBackend | undefined {
+    // First try exact match
+    for (const backend of this.backends.values()) {
+      if (backend.supportedTypes.includes(agentType)) {
+        return backend;
+      }
+    }
+    // Then try by backend name
+    return this.backends.get(agentType);
+  }
+
+  private async waitForCompletion(
+    backend: AgentBackend,
+    sessionId: string
+  ): Promise<AgentSession> {
+    // Poll for completion
+    while (true) {
+      const session = await backend.getSession(sessionId);
+      if (!session) {
+        throw new Error(`Session ${sessionId} not found`);
+      }
+
+      if (
+        session.state === 'completed' ||
+        session.state === 'failed'
+      ) {
+        return session;
+      }
+
+      // Wait before polling again
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  }
+
+  private notifySessionStart(session: AgentSession): void {
+    for (const observer of this.observers) {
+      observer.onSessionStart?.(session);
+    }
+  }
+
+  private notifyMessage(session: AgentSession, message: AgentMessage): void {
+    for (const observer of this.observers) {
+      observer.onMessage?.(session, message);
+    }
+  }
+
+  private notifyToolCall(session: AgentSession, toolCall: ToolCall): void {
+    for (const observer of this.observers) {
+      observer.onToolCall?.(session, toolCall);
+    }
+  }
+
+  private notifySessionEnd(session: AgentSession, trajectory: Trajectory): void {
+    for (const observer of this.observers) {
+      observer.onSessionEnd?.(session, trajectory);
+    }
+  }
+}
+
+/**
+ * Create an agent manager
+ */
+export function createAgentManager(
+  memory: MemorySystem,
+  options?: {
+    injector?: KnowledgeInjector;
+    extractor?: TrajectoryExtractor;
+  }
+): AgentManager {
+  return new AgentManager(memory, options);
+}

package/src/runtime/types.ts

@@ -0,0 +1,157 @@
+import type { Task, Trajectory } from '../types/index.js';
+import type { MemoryQueryResultV2 } from '../memory/system.js';
+
+/**
+ * Message in an agent conversation
+ */
+export interface AgentMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool_use' | 'tool_result';
+  content: string;
+  toolName?: string;
+  toolInput?: unknown;
+  toolOutput?: unknown;
+  timestamp: Date;
+}
+
+/**
+ * Tool call made by an agent
+ */
+export interface ToolCall {
+  id: string;
+  name: string;
+  input: unknown;
+  output?: unknown;
+  error?: string;
+  startTime: Date;
+  endTime?: Date;
+}
+
+/**
+ * Agent execution state
+ */
+export type AgentState = 'idle' | 'running' | 'paused' | 'completed' | 'failed';
+
+/**
+ * Agent session - represents a running or completed agent execution
+ */
+export interface AgentSession {
+  id: string;
+  agentType: string;
+  task: Task;
+  state: AgentState;
+  messages: AgentMessage[];
+  toolCalls: ToolCall[];
+  startTime: Date;
+  endTime?: Date;
+  result?: unknown;
+  error?: string;
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Configuration for spawning an agent
+ */
+export interface AgentSpawnConfig {
+  /** Type of agent to spawn (e.g., 'claude-code', 'custom', etc.) */
+  agentType: string;
+  /** Task for the agent to work on */
+  task: Task;
+  /** Optional knowledge to inject into the agent's context */
+  injectedKnowledge?: MemoryQueryResultV2;
+  /** Custom system prompt additions */
+  systemPromptAdditions?: string;
+  /** Environment variables for the agent */
+  env?: Record<string, string>;
+  /** Working directory */
+  cwd?: string;
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Whether to capture detailed tool calls */
+  captureToolCalls?: boolean;
+  /** Callback for real-time observation */
+  onMessage?: (message: AgentMessage) => void;
+  onToolCall?: (toolCall: ToolCall) => void;
+  /** Additional backend-specific options */
+  backendOptions?: Record<string, unknown>;
+}
+
+/**
+ * Result of agent execution
+ */
+export interface AgentResult {
+  session: AgentSession;
+  trajectory: Trajectory;
+  success: boolean;
+  metrics: {
+    totalTime: number;
+    toolCallCount: number;
+    messageCount: number;
+    tokenEstimate?: number;
+  };
+}
+
+/**
+ * Agent backend protocol - implement this for different agent systems
+ */
+export interface AgentBackend {
+  /** Unique name for this backend */
+  readonly name: string;
+
+  /** Supported agent types */
+  readonly supportedTypes: string[];
+
+  /** Check if backend is available/configured */
+  isAvailable(): Promise<boolean>;
+
+  /** Spawn and run an agent */
+  spawn(config: AgentSpawnConfig): Promise<AgentSession>;
+
+  /** Get status of a running session */
+  getSession(sessionId: string): Promise<AgentSession | undefined>;
+
+  /** Send a message to a running session */
+  sendMessage?(sessionId: string, message: string): Promise<void>;
+
+  /** Pause a running session */
+  pause?(sessionId: string): Promise<void>;
+
+  /** Resume a paused session */
+  resume?(sessionId: string): Promise<void>;
+
+  /** Terminate a session */
+  terminate?(sessionId: string): Promise<void>;
+
+  /** List active sessions */
+  listSessions?(): Promise<AgentSession[]>;
+}
+
+/**
+ * Knowledge injector - formats knowledge for injection into agents
+ */
+export interface KnowledgeInjector {
+  /** Format knowledge for a specific agent type */
+  format(
+    knowledge: MemoryQueryResultV2,
+    agentType: string,
+    options?: { maxTokens?: number; format?: 'markdown' | 'json' | 'xml' }
+  ): string;
+}
+
+/**
+ * Trajectory extractor - extracts trajectories from agent sessions
+ */
+export interface TrajectoryExtractor {
+  /** Extract a trajectory from an agent session */
+  extract(session: AgentSession, task: Task): Trajectory;
+}
+
+/**
+ * Agent observer callbacks
+ */
+export interface AgentObserverCallbacks {
+  onSessionStart?: (session: AgentSession) => void;
+  onMessage?: (session: AgentSession, message: AgentMessage) => void;
+  onToolCall?: (session: AgentSession, toolCall: ToolCall) => void;
+  onSessionEnd?: (session: AgentSession, trajectory: Trajectory) => void;
+  onError?: (session: AgentSession, error: Error) => void;
+}