cognitive-core 0.1.0 → 0.1.2

package/src/atlas.ts

@@ -1,21 +1,53 @@
 import type {
   Task,
   Trajectory,
+  TeamTrajectory,
+  TeamPlaybook,
   AtlasConfig,
   Playbook,
 } from './types/index.js';
+import type { KnowledgeMatch } from './types/knowledge.js';
 import { createDefaultConfig } from './types/index.js';
-import { MemorySystem, createMemorySystem } from './memory/index.js';
+import { MemorySystem, createMemorySystem, type TeamExperience } from './memory/index.js';
 import {
   LearningPipeline,
   createLearningPipeline,
   type ProcessResult,
   type BatchResult,
 } from './learning/index.js';
+import {
+  TeamLearningPipeline,
+  createTeamLearningPipeline,
+  type TeamBatchResult,
+  type TeamProcessResult,
+} from './learning/team-pipeline.js';
+import {
+  TeamMetaLearner,
+  createTeamMetaLearner,
+} from './learning/team-meta-learner.js';
+import {
+  TeamRouter,
+  createTeamRouter,
+  type TeamRecommendation,
+  type TeamRecommendationInput,
+} from './search/team-router.js';
+import {
+  TeamSkillLibrary,
+  createTeamSkillLibrary,
+  type TeamOutcomeFeedback,
+} from './surfacing/team-skill-library.js';
 import {
   PlaybookUsageInference,
   createUsageInference,
 } from './learning/usage-inference.js';
+import {
+  MetaLearner,
+  createMetaLearner,
+} from './learning/meta-learner.js';
+import {
+  LearningEffectivenessTracker,
+  createEffectivenessTracker,
+} from './learning/effectiveness.js';
 import { TaskRouter, createRouter, type RoutingDecision } from './search/router.js';
 import { DirectSolver, createSolver } from './search/solver.js';
 import {
@@ -25,15 +57,30 @@ import {
 import type { RefinementResult } from './search/refinement-types.js';
 import type { LLMProvider } from './agents/types.js';
 import { AgentManager, createAgentManager } from './runtime/manager.js';
-import type { AgentBackend, AgentSpawnConfig } from './runtime/types.js';
+import type { AgentBackend, AgentSpawnConfig, AgentDelegate } from './runtime/types.js';
 import {
   SkillLibrary,
   createSkillLibrary,
 } from './surfacing/skill-library.js';
+import { SqliteStorageAdapter } from './surfacing/sqlite-storage-adapter.js';
+import { join } from 'node:path';
 import {
   PlaybookMCPServer,
   createPlaybookMCPServer,
 } from './mcp/playbook-server.js';
+import {
+  AgenticTaskRunner,
+  createAgenticTaskRunner,
+} from './workspace/runner.js';
+import { usageInferenceTemplate } from './workspace/templates/usage-inference.js';
+import { metaReflectionTemplate } from './workspace/templates/meta-reflection.js';
+import { WorkspaceManager } from 'agent-workspace';
+
+/**
+ * Result from processing a team trajectory.
+ * Re-exports the pipeline's TeamProcessResult type.
+ */
+export type { TeamProcessResult } from './learning/team-pipeline.js';
 
 /**
  * Atlas statistics
@@ -44,9 +91,16 @@ export interface AtlasStats {
     playbookCount: number;
     metaObservationCount: number;
   };
+  teamMemory?: {
+    teamExperienceCount: number;
+    teamPlaybookCount: number;
+    rolePlaybookCount: number;
+    teamMetaObservationCount: number;
+  };
   learning: {
     trajectoriesProcessed: number;
     pendingTrajectories: number;
+    teamTrajectoriesProcessed: number;
   };
   execution?: {
     agentManagerEnabled: boolean;
@@ -91,6 +145,8 @@ export interface SolveResult {
   injectedPlaybooks?: Playbook[];
   /** Playbook usage inference results */
   playbookUsage?: PlaybookUsage[];
+  /** Knowledge notes that were surfaced for this task */
+  surfacedKnowledge?: KnowledgeMatch[];
 }
 
 /**
@@ -112,19 +168,36 @@ export class Atlas {
   private config: AtlasConfig;
   private provider: LLMProvider | null = null;
   private trajectoriesProcessed = 0;
+  private teamTrajectoriesProcessed = 0;
 
   // Playbook-based components
   private skillLibrary: SkillLibrary | null = null;
+  private skillTreeStorage: SqliteStorageAdapter | null = null;
   private usageInference: PlaybookUsageInference | null = null;
   private mcpServer: PlaybookMCPServer | null = null;
 
+  // Meta-learning and effectiveness
+  private metaLearner: MetaLearner | null = null;
+  private effectivenessTracker: LearningEffectivenessTracker | null = null;
+
+  // Agentic workspace components
+  private taskRunner: AgenticTaskRunner | null = null;
+  private workspaceManager: WorkspaceManager | null = null;
+
+  // Team-aware learning, recommendation, and surfacing
+  private teamLearning: TeamLearningPipeline | null = null;
+  private teamRouter: TeamRouter | null = null;
+  private teamMetaLearner: TeamMetaLearner | null = null;
+  private teamSkillLibrary: TeamSkillLibrary | null = null;
+
   constructor(config?: Partial<AtlasConfig>) {
     this.config = createDefaultConfig(config);
 
-    // Initialize memory system
+    // Initialize memory system (with optional knowledge bank)
     this.memory = createMemorySystem(
       this.config.storage.baseDir,
-      this.config.memory
+      this.config.memory,
+      this.config.knowledgeBank.enabled ? this.config.knowledgeBank : undefined
     );
 
     // Initialize learning pipeline
@@ -132,6 +205,27 @@ export class Atlas {
 
     // Initialize router
     this.router = createRouter(this.memory, this.config.router);
+
+    // Initialize team learning pipeline and router if enabled
+    if (this.config.teamLearning.enabled) {
+      this.teamLearning = createTeamLearningPipeline(
+        this.memory.teamExperiences,
+        this.config.teamLearning
+      );
+
+      // Initialize team meta-learner and team router
+      this.teamMetaLearner = createTeamMetaLearner(
+        this.memory.teamExperiences
+      );
+      this.teamRouter = createTeamRouter(
+        this.memory.teamExperiences,
+        undefined,
+        this.teamMetaLearner
+      );
+      this.teamSkillLibrary = createTeamSkillLibrary(
+        this.memory.teamExperiences
+      );
+    }
   }
 
   /**
@@ -148,9 +242,29 @@ export class Atlas {
       );
       this.usageInference = createUsageInference();
 
+      // Wire skill-tree publisher if enabled (default: true)
+      if (this.config.skillTree.enabled) {
+        const dbPath = join(this.config.storage.baseDir, this.config.skillTree.dbPath);
+        this.skillTreeStorage = new SqliteStorageAdapter(dbPath);
+        await this.skillTreeStorage.initialize();
+        this.skillLibrary.setPublisher(this.skillTreeStorage);
+      }
+
       // Refresh skill tiers on init
       await this.skillLibrary.refreshTiers();
     }
+
+    // Initialize meta-learner and connect to router
+    if (this.memory.meta) {
+      this.metaLearner = createMetaLearner(this.memory.meta);
+      this.router.setMetaLearner(this.metaLearner);
+    }
+
+    // Initialize effectiveness tracker
+    this.effectivenessTracker = createEffectivenessTracker(
+      this.config.storage.baseDir
+    );
+    await this.effectivenessTracker.init();
   }
 
   /**
@@ -166,15 +280,41 @@ export class Atlas {
    * Set up the AgentManager with backends for real action execution
    * This is the recommended way to configure Atlas for execution
    */
-  setAgentManager(backends: AgentBackend[]): void {
+  setAgentManager(
+    backends: AgentBackend[],
+    options?: { delegate?: AgentDelegate }
+  ): void {
     // Create AgentManager with memory system
-    this.agentManager = createAgentManager(this.memory);
+    this.agentManager = createAgentManager(this.memory, {
+      delegate: options?.delegate,
+    });
 
     // Register all backends
     for (const backend of backends) {
       this.agentManager.registerBackend(backend);
     }
 
+    // Create workspace infrastructure (using agent-workspace package)
+    this.workspaceManager = new WorkspaceManager({
+      baseDir: this.config.agenticTasks.workspaceBaseDir,
+      prefix: 'atlas-workspaces',
+    });
+    this.taskRunner = createAgenticTaskRunner(
+      this.workspaceManager,
+      this.agentManager,
+      this.memory,
+      this.learning,
+      this.config.agenticTasks
+    );
+
+    // Connect task runner to learning pipeline for workspace-based analysis
+    this.learning.setTaskRunner(this.taskRunner);
+
+    // Connect task runner to team learning pipeline
+    if (this.teamLearning) {
+      this.teamLearning.setTaskRunner(this.taskRunner);
+    }
+
     // Create refinement loop with config
     this.refinementLoop = createRefinementLoop(
       this.agentManager,
@@ -189,6 +329,9 @@ export class Atlas {
         confidenceThreshold: this.config.refinement.confidenceThreshold,
       }
     );
+
+    // Connect task runner to refinement loop for workspace-based evaluation and analysis
+    this.refinementLoop.setTaskRunner(this.taskRunner);
   }
 
   /**
@@ -198,6 +341,24 @@ export class Atlas {
     return this.agentManager;
   }
 
+  /**
+   * Set a delegate for caller-provided agent execution.
+   * Requires AgentManager to be initialized first (via setAgentManager).
+   */
+  setDelegate(delegate: AgentDelegate): void {
+    if (!this.agentManager) {
+      throw new Error('AgentManager not initialized. Call setAgentManager() first.');
+    }
+    this.agentManager.setDelegate(delegate);
+  }
+
+  /**
+   * Get the current delegate, if any.
+   */
+  getDelegate(): AgentDelegate | undefined {
+    return this.agentManager?.getDelegate();
+  }
+
   /**
    * Get the RefinementLoop for registering domain verifiers
    */
@@ -205,6 +366,13 @@ export class Atlas {
     return this.refinementLoop;
   }
 
+  /**
+   * Get the AgenticTaskRunner for running analysis tasks
+   */
+  getTaskRunner(): AgenticTaskRunner | null {
+    return this.taskRunner;
+  }
+
   /**
    * Check if agent execution is available
    */
@@ -239,11 +407,30 @@ export class Atlas {
       }
     }
 
+    // Surface knowledge from knowledge bank (independent from skill surfacing)
+    let knowledgeContext = '';
+    let surfacedKnowledge: KnowledgeMatch[] | undefined;
+    if (this.memory.knowledgeBank) {
+      surfacedKnowledge = await this.memory.knowledgeBank.getRelevantKnowledge(
+        { description: task.description, domain: task.domain },
+      );
+      if (surfacedKnowledge.length > 0) {
+        knowledgeContext = this.memory.knowledgeBank.formatKnowledgeForPrompt(
+          surfacedKnowledge,
+        );
+      }
+    }
+
+    // Combine skill context + knowledge context
+    const combinedContext = [skillContext, knowledgeContext]
+      .filter(Boolean)
+      .join('\n\n');
+
     let result: SolveResult;
 
     // Prefer AgentManager if available
     if (this.agentManager) {
-      result = await this.solveWithAgent(task, routing, skillContext);
+      result = await this.solveWithAgent(task, routing, combinedContext || undefined);
     } else if (this.solver && this.provider) {
       // Fall back to DirectSolver (deprecated)
       const solverResult = await this.solver.solve(task, routing);
@@ -261,12 +448,13 @@ export class Atlas {
 
     // Add injected playbooks to result
     result.injectedPlaybooks = injectedPlaybooks;
+    result.surfacedKnowledge = surfacedKnowledge;
 
     // Infer playbook usage from trajectory
-    if (this.usageInference && this.skillLibrary && injectedPlaybooks.length > 0) {
-      const usageResults = await this.usageInference.inferUsage(
+    if (this.skillLibrary && injectedPlaybooks.length > 0) {
+      const usageResults = await this.inferPlaybookUsage(
         result.trajectory,
-        injectedPlaybooks
+        injectedPlaybooks,
       );
 
       // Convert to PlaybookUsage format and record outcomes
@@ -292,6 +480,29 @@ export class Atlas {
       }
     }
 
+    // Generate meta-reflection (records observation + periodically generates strategies)
+    if (this.metaLearner) {
+      await this.reflectOnExecution(result.trajectory, routing);
+    }
+
+    // Annotate trajectory for effectiveness tracking
+    if (this.effectivenessTracker) {
+      const appliedPlaybookIds = (result.playbookUsage ?? [])
+        .filter(u => u.wasUsed)
+        .map(u => u.playbookId);
+
+      const surfacedExperienceIds = routing.memoryContext.experiences.map(
+        e => e.experience.id
+      );
+
+      await this.effectivenessTracker.annotate(
+        result.trajectory,
+        routing.memoryContext.playbooks,
+        surfacedExperienceIds,
+        appliedPlaybookIds,
+      );
+    }
+
     // Process the trajectory for learning
     await this.learning.processTrajectory(result.trajectory);
     this.trajectoriesProcessed++;
@@ -385,6 +596,170 @@ export class Atlas {
     return result;
   }
 
+  /**
+   * Process a team trajectory through the full team learning pipeline.
+   * Ingests, analyzes (heuristic or agentic), stores, and accumulates
+   * for batch team playbook extraction.
+   */
+  async processTeamTrajectory(
+    trajectory: TeamTrajectory
+  ): Promise<TeamProcessResult> {
+    if (!this.config.teamLearning.enabled || !this.teamLearning) {
+      return { teamTrajectoryId: trajectory.id, stored: false, analyzed: false };
+    }
+
+    const result = await this.teamLearning.processTeamTrajectory(trajectory);
+    this.teamTrajectoriesProcessed++;
+
+    // Generate team meta-reflection for the meta-learner
+    if (this.teamMetaLearner) {
+      try {
+        await this.teamMetaLearner.generateReflection(trajectory);
+      } catch (error) {
+        console.error(
+          '[Atlas] Team meta-reflection failed:',
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+
+    // Run batch team learning if ready
+    if (this.teamLearning.shouldRunBatch()) {
+      await this.runTeamBatchLearning();
+    }
+
+    return result;
+  }
+
+  /**
+   * Run batch team playbook extraction explicitly.
+   */
+  async runTeamBatchLearning(): Promise<TeamBatchResult | null> {
+    if (!this.teamLearning) return null;
+    return this.teamLearning.runBatchLearning();
+  }
+
+  /**
+   * Get the team learning pipeline for direct access.
+   */
+  getTeamLearning(): TeamLearningPipeline | null {
+    return this.teamLearning;
+  }
+
+  /**
+   * Recommend a team composition for a given task.
+   * Uses team playbooks and meta-strategies to produce a recommendation
+   * with optional OpenTeams YAML export.
+   */
+  async recommendTeam(input: TeamRecommendationInput): Promise<TeamRecommendation> {
+    if (!this.teamRouter) {
+      throw new Error(
+        'Team learning is not enabled. Set teamLearning.enabled = true in config.'
+      );
+    }
+    return this.teamRouter.recommend(input);
+  }
+
+  /**
+   * Get the team router for direct access.
+   */
+  getTeamRouter(): TeamRouter | null {
+    return this.teamRouter;
+  }
+
+  /**
+   * Get the team meta-learner for direct access.
+   */
+  getTeamMetaLearner(): TeamMetaLearner | null {
+    return this.teamMetaLearner;
+  }
+
+  /**
+   * Get the team skill library for direct access.
+   */
+  getTeamSkillLibrary(): TeamSkillLibrary | null {
+    return this.teamSkillLibrary;
+  }
+
+  /**
+   * Record team outcome feedback to update playbook evolution.
+   * Updates success/failure counts, recalculates confidence, and
+   * accumulates average metrics for the team playbook.
+   */
+  async recordTeamOutcome(feedback: TeamOutcomeFeedback): Promise<void> {
+    if (!this.teamSkillLibrary) {
+      throw new Error(
+        'Team learning is not enabled. Set teamLearning.enabled = true in config.'
+      );
+    }
+    await this.teamSkillLibrary.recordTeamOutcome(feedback);
+  }
+
+  /**
+   * Format role guidance for injection into an agent's system prompt.
+   * Returns markdown-formatted role playbook content for the given role.
+   */
+  async formatRoleGuidance(
+    role: string,
+    context?: { topology?: string; domain?: string; taskType?: string }
+  ): Promise<string> {
+    if (!this.teamSkillLibrary) return '';
+
+    const ranked = await this.teamSkillLibrary.findRolePlaybooks(role, {
+      topology: context?.topology,
+      domain: context?.domain,
+      taskType: context?.taskType,
+    });
+
+    return this.teamSkillLibrary.formatRoleGuidance(
+      role,
+      ranked.map((r) => r.playbook)
+    );
+  }
+
+  /**
+   * Query team memory for coordination patterns.
+   */
+  async queryTeamMemory(
+    query: string,
+    options?: {
+      domain?: string;
+      topology?: string;
+      includeExperiences?: boolean;
+      includePlaybooks?: boolean;
+    }
+  ) {
+    const results: {
+      experiences: Array<{ experience: TeamExperience; score: number }>;
+      playbooks: Array<{ playbook: TeamPlaybook; score: number }>;
+    } = {
+      experiences: [],
+      playbooks: [],
+    };
+
+    const shouldIncludeAll = !options || (
+      options.includeExperiences === undefined &&
+      options.includePlaybooks === undefined
+    );
+
+    if (shouldIncludeAll || options?.includeExperiences) {
+      results.experiences = await this.memory.teamExperiences.findSimilarTeamExperiences(
+        query,
+        { domain: options?.domain, topology: options?.topology }
+      );
+    }
+
+    if (shouldIncludeAll || options?.includePlaybooks) {
+      results.playbooks = await this.memory.teamExperiences.findMatchingTeamPlaybooks({
+        taskType: query,
+        domain: options?.domain,
+        topology: options?.topology,
+      });
+    }
+
+    return results;
+  }
+
   /**
    * Run batch learning explicitly
    */
@@ -416,9 +791,21 @@ export class Atlas {
       learning: {
         trajectoriesProcessed: this.trajectoriesProcessed,
         pendingTrajectories: this.learning.getAccumulatedCount(),
+        teamTrajectoriesProcessed: this.teamTrajectoriesProcessed,
       },
     };
 
+    // Add team memory stats if team learning is enabled
+    if (this.config.teamLearning.enabled) {
+      const teamStats = await this.memory.teamExperiences.getStats();
+      stats.teamMemory = {
+        teamExperienceCount: teamStats.teamExperienceCount,
+        teamPlaybookCount: teamStats.teamPlaybookCount,
+        rolePlaybookCount: teamStats.rolePlaybookCount,
+        teamMetaObservationCount: teamStats.metaObservationCount,
+      };
+    }
+
     // Add execution stats if AgentManager is available
     if (this.agentManager) {
       stats.execution = {
@@ -448,6 +835,13 @@ export class Atlas {
     return this.memory;
   }
 
+  /**
+   * Get the knowledge bank for direct access (null if not enabled)
+   */
+  getKnowledgeBank(): import('./memory/knowledge-bank.js').KnowledgeBank | null {
+    return this.memory.knowledgeBank;
+  }
+
   /**
    * Get the learning pipeline for direct access
    */
@@ -462,6 +856,13 @@ export class Atlas {
     return this.skillLibrary;
   }
 
+  /**
+   * Get the skill-tree storage adapter (null if not enabled)
+   */
+  getSkillTreeStorage(): SqliteStorageAdapter | null {
+    return this.skillTreeStorage;
+  }
+
   /**
    * Get the MCP server for direct access
    */
@@ -511,8 +912,102 @@ export class Atlas {
   }
 
   /**
-   * Close Atlas (flush data to disk)
+   * Infer playbook usage via workspace template when taskRunner available,
+   * otherwise fall back to heuristic.
+   */
+  private async inferPlaybookUsage(
+    trajectory: Trajectory,
+    injectedPlaybooks: Playbook[],
+  ): Promise<import('./learning/usage-inference.js').PlaybookUsageResult[]> {
+    if (this.taskRunner && injectedPlaybooks.length > 0) {
+      try {
+        const result = await this.taskRunner.run(usageInferenceTemplate, {
+          trajectory,
+          injectedPlaybooks,
+        });
+        return result.output;
+      } catch (error) {
+        console.error(
+          'Workspace-based usage inference failed, falling back to heuristic:',
+          error instanceof Error ? error.message : error
+        );
+      }
+    }
+
+    // Heuristic fallback
+    if (this.usageInference) {
+      return this.usageInference.inferUsage(trajectory, injectedPlaybooks);
+    }
+    return [];
+  }
+
+  /**
+   * Reflect on execution via workspace template when taskRunner available,
+   * otherwise fall back to MetaLearner's built-in heuristic reflection.
+   */
+  private async reflectOnExecution(
+    trajectory: Trajectory,
+    routing: RoutingDecision,
+  ): Promise<void> {
+    if (!this.metaLearner) return;
+
+    const routingInfo = {
+      strategy: routing.strategy,
+      confidence: routing.confidence,
+      estimatedBudget: routing.estimatedBudget,
+      reasoning: routing.reasoning,
+    };
+    const playbookMatches = routing.memoryContext.playbooks;
+
+    if (this.taskRunner) {
+      try {
+        const result = await this.taskRunner.run(metaReflectionTemplate, {
+          trajectory,
+          routingDecision: routingInfo,
+          playbooksUsed: playbookMatches,
+        });
+
+        // Bridge template output into MetaLearner storage
+        const playbookIds = playbookMatches.map(p => p.playbook.id);
+        const actualEffort = trajectory.llmCalls ?? trajectory.steps.length;
+        await this.metaLearner.recordFromReflection(
+          result.output,
+          trajectory.id,
+          routingInfo,
+          playbookIds,
+          actualEffort,
+        );
+        return;
+      } catch (error) {
+        console.error(
+          'Workspace-based meta-reflection failed, falling back to heuristic:',
+          error instanceof Error ? error.message : error
+        );
+      }
+    }
+
+    // Heuristic fallback
+    await this.metaLearner.generateReflection(
+      trajectory,
+      routingInfo,
+      playbookMatches,
+    );
+  }
+
+  /**
+   * Get the meta learner for direct access
    */
+  getMetaLearner(): MetaLearner | null {
+    return this.metaLearner;
+  }
+
+  /**
+   * Get the effectiveness tracker for direct access
+   */
+  getEffectivenessTracker(): LearningEffectivenessTracker | null {
+    return this.effectivenessTracker;
+  }
+
   async close(): Promise<void> {
     // Stop MCP server if running
     await this.stopMCPServer();
@@ -521,6 +1016,22 @@ export class Atlas {
     if (this.learning.getAccumulatedCount() > 0) {
       await this.learning.runBatchLearning();
     }
+
+    // Flush team learning pipeline
+    if (this.teamLearning && this.teamLearning.getAccumulatedCount() > 0) {
+      await this.teamLearning.runBatchLearning();
+    }
+
+    // Close effectiveness tracker
+    if (this.effectivenessTracker) {
+      await this.effectivenessTracker.close();
+    }
+
+    // Close skill-tree storage
+    if (this.skillTreeStorage) {
+      this.skillTreeStorage.close();
+    }
+
     // Close memory system
     await this.memory.close();
   }
@@ -552,9 +1063,10 @@ export function createAtlasWithProvider(
  */
 export function createAtlasWithAgents(
   backends: AgentBackend[],
-  config?: Partial<AtlasConfig>
+  config?: Partial<AtlasConfig>,
+  options?: { delegate?: AgentDelegate }
 ): Atlas {
   const atlas = new Atlas(config);
-  atlas.setAgentManager(backends);
+  atlas.setAgentManager(backends, options);
   return atlas;
 }