cognitive-core 0.0.2 → 0.1.2

package/src/runtime/manager.ts

@@ -0,0 +1,685 @@
+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,
+  AgentDelegate,
+} from './types.js';
+import type { ComputeProvider, ComputeSource } from './compute-provider.js';
+import { DefaultComputeProvider } from './compute-provider.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 computeProvider: ComputeProvider;
+  private memory: MemorySystem;
+  private injector: KnowledgeInjector;
+  private extractor: TrajectoryExtractor;
+  private observers: AgentObserverCallbacks[] = [];
+  private activeSessions: Map<string, AgentSession> = new Map();
+  private delegate?: AgentDelegate;
+
+  constructor(
+    memory: MemorySystem,
+    options?: {
+      injector?: KnowledgeInjector;
+      extractor?: TrajectoryExtractor;
+      computeProvider?: ComputeProvider;
+      delegate?: AgentDelegate;
+    }
+  ) {
+    this.memory = memory;
+    this.injector = options?.injector ?? new DefaultKnowledgeInjector();
+    this.extractor = options?.extractor ?? new DefaultTrajectoryExtractor();
+    this.computeProvider = options?.computeProvider ?? new DefaultComputeProvider();
+    this.delegate = options?.delegate;
+  }
+
+  /**
+   * Register an agent backend.
+   * Also registers it as a compute source with the ComputeProvider.
+   */
+  registerBackend(backend: AgentBackend, sourceOptions?: {
+    costTier?: ComputeSource['costTier'];
+    location?: ComputeSource['location'];
+    priority?: number;
+  }): void {
+    this.backends.set(backend.name, backend);
+    this.computeProvider.register({
+      name: backend.name,
+      backend,
+      costTier: sourceOptions?.costTier ?? 'low',
+      location: sourceOptions?.location ?? 'local',
+      priority: sourceOptions?.priority ?? 10,
+    });
+  }
+
+  /**
+   * 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());
+  }
+
+  /**
+   * Get the compute provider for advanced configuration
+   */
+  getComputeProvider(): ComputeProvider {
+    return this.computeProvider;
+  }
+
+  /**
+   * 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);
+    }
+  }
+
+  /**
+   * Set a delegate for caller-provided agent execution.
+   * When set, all spawn() calls bypass backend resolution and use the delegate.
+   */
+  setDelegate(delegate: AgentDelegate): void {
+    this.delegate = delegate;
+  }
+
+  /**
+   * Clear the delegate, reverting to normal backend resolution.
+   */
+  clearDelegate(): void {
+    this.delegate = undefined;
+  }
+
+  /**
+   * Get the current delegate, if any.
+   */
+  getDelegate(): AgentDelegate | undefined {
+    return this.delegate;
+  }
+
+  /**
+   * Spawn an agent to execute a task
+   * This is the main entry point for running agents
+   */
+  async spawn(config: AgentSpawnConfig): Promise<AgentResult> {
+    // Use delegate if available (bypasses backend resolution)
+    if (this.delegate) {
+      return this.spawnViaDelegate(config);
+    }
+
+    // Resolve compute target via provider
+    const target = await this.computeProvider.resolve(
+      config.agentType,
+      config.computeRequirements,
+    );
+    const backend = target.backend;
+
+    // Merge any overrides from compute resolution
+    if (target.overrides) {
+      config = { ...config, ...target.overrides };
+    }
+
+    // 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 via caller-provided delegate.
+   * Handles knowledge injection, builds trajectory, notifies observers.
+   */
+  private async spawnViaDelegate(config: AgentSpawnConfig): Promise<AgentResult> {
+    const startTime = new Date();
+
+    // 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, 'delegate');
+
+    // Build system context from prompt additions + formatted knowledge
+    const systemContext = [
+      config.systemPromptAdditions,
+      formattedKnowledge
+        ? `\n## Atlas Knowledge\n${formattedKnowledge}`
+        : undefined,
+    ]
+      .filter(Boolean)
+      .join('\n\n') || undefined;
+
+    // Call the delegate
+    const result = await this.delegate!.execute(config.task.description, {
+      cwd: config.cwd ?? process.cwd(),
+      systemContext,
+      timeoutMs: config.timeout,
+    });
+
+    const endTime = new Date();
+
+    // Build trajectory — use delegate's if provided, otherwise build minimal
+    const trajectory = result.trajectory ?? createTrajectory({
+      task: config.task,
+      steps: [
+        createStep({
+          action: 'delegate_execution',
+          observation: result.output,
+        }),
+      ],
+      outcome: result.success
+        ? successOutcome(result.structured ?? result.output)
+        : failureOutcome(result.output),
+      agentId: 'delegate',
+      wallTimeSeconds: (endTime.getTime() - startTime.getTime()) / 1000,
+    });
+
+    // Build session for observer compatibility
+    const session: AgentSession = {
+      id: crypto.randomUUID(),
+      agentType: 'delegate',
+      task: config.task,
+      state: result.success ? 'completed' : 'failed',
+      messages: [
+        {
+          role: 'assistant',
+          content: result.output,
+          timestamp: endTime,
+        },
+      ],
+      toolCalls: [],
+      startTime,
+      endTime,
+      result: result.structured ?? result.output,
+      error: result.success ? undefined : result.output,
+      metadata: {},
+    };
+
+    // Notify observers
+    this.notifySessionStart(session);
+    this.notifySessionEnd(session, trajectory);
+
+    return {
+      session,
+      trajectory,
+      success: result.success,
+      metrics: {
+        totalTime: endTime.getTime() - startTime.getTime(),
+        toolCallCount: 0,
+        messageCount: 1,
+      },
+    };
+  }
+
+  /**
+   * 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;
+
+    // Resolve backend for this agent type (best-effort, ignore errors)
+    try {
+      const target = await this.computeProvider.resolve(session.agentType);
+      if (target.backend.terminate) {
+        await target.backend.terminate(sessionId);
+      }
+    } catch {
+      // Backend may no longer be registered; still clean up session
+    }
+
+    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 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;
+    computeProvider?: ComputeProvider;
+    delegate?: AgentDelegate;
+  }
+): AgentManager {
+  return new AgentManager(memory, options);
+}