cognitive-core 0.2.4 → 0.3.1

package/src/atlas.ts

@@ -1,1198 +0,0 @@
-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, type TeamExperience } from './memory/index.js';
-import {
-  loadCuratedPlaybooks as loadCuratedPlaybooksFn,
-  BUNDLED_SEED_PACK_DIR,
-} from './memory/curated-loader.js';
-import {
-  resolvePlaybookSource,
-  sourceStateKey,
-  type SourceState,
-} from './memory/source-resolver.js';
-import {
-  UnifiedLearningPipeline,
-  createUnifiedPipeline,
-  type ImmediateResult,
-  type UnifiedBatchResult,
-} from './learning/unified-pipeline.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 type { MetaLearner } from './learning/meta-learner.js';
-import type { LearningEffectivenessTracker } from './learning/effectiveness.js';
-import { TaskRouter, createRouter, type RoutingDecision } from './search/router.js';
-import { DirectSolver, createSolver } from './search/solver.js';
-import {
-  RefinementLoop,
-  createRefinementLoop,
-} from './search/refinement-loop.js';
-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, 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 { SqlitePersistence, createSqlitePersistence } from './persistence/index.js';
-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
- */
-export interface AtlasStats {
-  memory: {
-    experienceCount: number;
-    playbookCount: number;
-    metaObservationCount: number;
-  };
-  teamMemory?: {
-    teamExperienceCount: number;
-    teamPlaybookCount: number;
-    rolePlaybookCount: number;
-    teamMetaObservationCount: number;
-  };
-  learning: {
-    trajectoriesProcessed: number;
-    pendingTrajectories: number;
-    teamTrajectoriesProcessed: number;
-  };
-  execution?: {
-    agentManagerEnabled: boolean;
-    refinementEnabled: boolean;
-    backends: string[];
-  };
-  skillLibrary?: {
-    coreSkillCount: number;
-    domainSkillCounts: Record<string, number>;
-    mcpServerEnabled: boolean;
-  };
-}
-
-/**
- * Playbook usage tracking
- */
-export interface PlaybookUsage {
-  playbookId: string;
-  playbookName: string;
-  wasUsed: boolean;
-  usageConfidence: number;
-  wasSuccessful: boolean;
-}
-
-/**
- * Extended solve result with refinement info
- */
-export interface SolveResult {
-  /** The execution trajectory */
-  trajectory: Trajectory;
-  /** Whether memory was used */
-  usedMemory?: boolean;
-  /** Strategy used (from legacy solver) */
-  strategy?: string;
-  /** Routing decision (when using AgentManager) */
-  routing?: RoutingDecision;
-  /** Whether the result came from agent execution (vs direct solver) */
-  usedAgentManager: boolean;
-  /** Refinement result if refinement was performed */
-  refinement?: RefinementResult;
-  /** Playbooks that were injected for this task */
-  injectedPlaybooks?: Playbook[];
-  /** Playbook usage inference results */
-  playbookUsage?: PlaybookUsage[];
-  /** Knowledge notes that were surfaced for this task */
-  surfacedKnowledge?: KnowledgeMatch[];
-}
-
-/**
- * Atlas - Adaptive Trajectory Learning and Abstraction System
- *
- * Main orchestrator that combines:
- * - Memory systems (experiences, playbooks, meta-observations)
- * - Learning engine (trajectory analysis, playbook extraction)
- * - Task routing (deciding how to solve tasks)
- * - Skill surfacing (providing playbooks to agents)
- */
-export class Atlas {
-  private memory: MemorySystem;
-  private unifiedPipeline: UnifiedLearningPipeline;
-  private router: TaskRouter;
-  private solver: DirectSolver | null = null;
-  private agentManager: AgentManager | null = null;
-  private refinementLoop: RefinementLoop | null = null;
-  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;
-
-  // 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;
-
-  // Unified SQLite persistence
-  private persistence: SqlitePersistence;
-
-  constructor(config?: Partial<AtlasConfig>) {
-    this.config = createDefaultConfig(config);
-
-    // Create unified SQLite persistence
-    this.persistence = createSqlitePersistence({
-      baseDir: this.config.storage.baseDir,
-      dbName: this.config.storage.dbName,
-    });
-
-    // Initialize memory system (with optional knowledge bank)
-    this.memory = createMemorySystem(
-      this.persistence,
-      this.config.storage.baseDir,
-      this.config.memory,
-      this.config.knowledgeBank.enabled
-        ? { ...this.config.knowledgeBank, coherenceChecking: this.config.features.coherenceChecking }
-        : undefined
-    );
-
-    // Initialize unified learning pipeline (replaces LearningPipeline + InstantLoop + LoopCoordinator)
-    this.unifiedPipeline = createUnifiedPipeline(this.memory, {
-      instant: {
-        enableReflexion: this.config.features.reflexion,
-        enableCausalExtraction: this.config.features.causalExtraction,
-      },
-      batch: {
-        learning: this.config.learning,
-        energy: {
-          countThreshold: this.config.learning.minTrajectories ?? 10,
-        },
-      },
-      features: {
-        temporalCompression: this.config.features.temporalCompression,
-        reasoningBank: this.config.features.reasoningBank,
-        reflexion: this.config.features.reflexion,
-        causalExtraction: this.config.features.causalExtraction,
-      },
-    }, this.persistence);
-
-    // Initialize router (with persistence for MoEGate)
-    this.router = createRouter(this.memory, this.config.router, undefined, this.persistence);
-
-    // 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
-      );
-    }
-  }
-
-  /**
-   * Initialize Atlas (load persisted data)
-   */
-  async init(): Promise<void> {
-    await this.persistence.init();
-
-    // Load persisted state for components created before persistence.init()
-    this.router.loadPersistedState();
-    this.unifiedPipeline.loadPersistedState();
-
-    await this.memory.init();
-
-    // Initialize unified pipeline async components (meta-learner, effectiveness tracker, energy seed)
-    await this.unifiedPipeline.init();
-
-    // Connect meta-learner to router
-    const metaLearner = this.unifiedPipeline.getMetaLearner();
-    if (metaLearner) {
-      this.router.setMetaLearner(metaLearner);
-    }
-
-    // Initialize playbook-based components if playbooks are available
-    if (this.memory.playbooks) {
-      // Load curated playbooks (bundled seed pack + additional dirs)
-      await this.loadCuratedPlaybooks();
-
-      this.skillLibrary = createSkillLibrary(
-        this.memory.playbooks,
-        this.config.skillLibrary
-      );
-      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();
-    }
-  }
-
-  /**
-   * Load curated playbooks from bundled seed pack, additional directories,
-   * and resolved sources (local paths or git repos).
-   * Called during init() when curatedPlaybooks config is enabled.
-   */
-  private async loadCuratedPlaybooks(): Promise<void> {
-    const cfg = this.config.curatedPlaybooks;
-    const recreate = cfg.recreateOnInit;
-
-    // Load bundled seed pack (shipped with cognitive-core)
-    if (cfg.loadBundledSeedPack) {
-      const loadOpts = recreate
-        ? { recreate: true, sourceId: 'bundled' }
-        : { sourceId: 'bundled' };
-      await loadCuratedPlaybooksFn(
-        BUNDLED_SEED_PACK_DIR,
-        this.memory.playbooks,
-        loadOpts,
-      );
-    }
-
-    // Load from additional directories (backward compat)
-    for (const dir of cfg.additionalDirs) {
-      const loadOpts = recreate
-        ? { recreate: true, sourceId: dir }
-        : { sourceId: dir };
-      await loadCuratedPlaybooksFn(dir, this.memory.playbooks, loadOpts);
-    }
-
-    // Resolve and load from sources (local paths + git repos)
-    if (cfg.sources.length > 0) {
-      const cacheDir = join(this.config.storage.baseDir, cfg.cache.dir);
-      for (const source of cfg.sources) {
-        await this.loadFromSource(source, cacheDir, recreate);
-      }
-    }
-  }
-
-  /**
-   * Resolve a single source (local or git) and load its playbooks.
-   */
-  private async loadFromSource(
-    source: string,
-    cacheDir: string,
-    recreate: boolean,
-  ): Promise<void> {
-    const cfg = this.config.curatedPlaybooks;
-
-    const resolved = await resolvePlaybookSource(source, {
-      cacheDir,
-      maxAgeMs: cfg.cache.maxAgeMs,
-      forceUpdate: recreate,
-      getSourceState: (s) =>
-        this.persistence.getSystemState<SourceState>(sourceStateKey(s)),
-      setSourceState: (s, state) =>
-        this.persistence.setSystemState(sourceStateKey(s), state),
-    });
-
-    if (!resolved) return;
-
-    // For git sources: skip loading if SHA hasn't changed and we're not recreating
-    // (playbooks are already in the library from a previous init).
-    // For local paths: always load (the loader handles dedup via getByName).
-    if (resolved.isGit && !resolved.updated && !recreate) return;
-
-    const loadOpts = recreate
-      ? { recreate: true, sourceId: resolved.sourceId }
-      : { sourceId: resolved.sourceId };
-
-    const result = await loadCuratedPlaybooksFn(
-      resolved.playbookDir,
-      this.memory.playbooks,
-      loadOpts,
-    );
-
-    // Update source state with playbook count
-    const stateKey = sourceStateKey(source);
-    const prevState = this.persistence.getSystemState<SourceState>(stateKey);
-    if (prevState) {
-      prevState.playbookCount = result.loaded;
-      this.persistence.setSystemState(stateKey, prevState);
-    }
-  }
-
-  /**
-   * Set the LLM provider for solving (deprecated)
-   * @deprecated Use setAgentManager() with backends for real execution
-   */
-  setProvider(provider: LLMProvider): void {
-    this.provider = provider;
-    this.solver = createSolver(this.memory, provider);
-  }
-
-  /**
-   * Set up the AgentManager with backends for real action execution
-   * This is the recommended way to configure Atlas for execution
-   */
-  setAgentManager(
-    backends: AgentBackend[],
-    options?: { delegate?: AgentDelegate }
-  ): void {
-    // Create AgentManager with memory system
-    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.unifiedPipeline,
-      this.config.agenticTasks
-    );
-
-    // Connect task runner to unified pipeline for workspace-based analysis
-    this.unifiedPipeline.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,
-      this.memory,
-      {
-        maxIterations: this.config.refinement.maxIterations,
-        minAcceptableScore: this.config.refinement.acceptableScore,
-        evaluatorConfig: {
-          evaluatorAgentType: this.config.refinement.evaluatorAgentType,
-        },
-        triggerOnStrategies: this.config.refinement.triggerOnStrategies,
-        confidenceThreshold: this.config.refinement.confidenceThreshold,
-      }
-    );
-
-    // Connect task runner to refinement loop for workspace-based evaluation and analysis
-    this.refinementLoop.setTaskRunner(this.taskRunner);
-  }
-
-  /**
-   * Get the AgentManager for direct access
-   */
-  getAgentManager(): AgentManager | null {
-    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
-   */
-  getRefinementLoop(): RefinementLoop | null {
-    return this.refinementLoop;
-  }
-
-  /**
-   * Get the AgenticTaskRunner for running analysis tasks
-   */
-  getTaskRunner(): AgenticTaskRunner | null {
-    return this.taskRunner;
-  }
-
-  /**
-   * Check if agent execution is available
-   */
-  hasAgentExecution(): boolean {
-    return this.agentManager !== null;
-  }
-
-  /**
-   * Solve a task using the best available method
-   * Prefers AgentManager with refinement when available
-   */
-  async solve(task: Task): Promise<SolveResult> {
-    // Route the task first
-    const routing = await this.router.route(task);
-
-    // Get skills for the agent if skill library is available
-    let injectedPlaybooks: Playbook[] = [];
-    let skillContext = '';
-    if (this.skillLibrary) {
-      const skills = await this.skillLibrary.getSkillsForAgent(task);
-      injectedPlaybooks = [...skills.core, ...skills.domain, ...skills.contextual];
-      skillContext = this.skillLibrary.formatForSystemPrompt(skills);
-    }
-
-    // Merge playbooks from router's memory context (deduplicating by ID)
-    // This ensures we track ALL playbooks that will be injected into the agent
-    const injectedIds = new Set(injectedPlaybooks.map(p => p.id));
-    for (const { playbook } of routing.memoryContext.playbooks) {
-      if (!injectedIds.has(playbook.id)) {
-        injectedPlaybooks.push(playbook);
-        injectedIds.add(playbook.id);
-      }
-    }
-
-    // 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, combinedContext || undefined);
-    } else if (this.solver && this.provider) {
-      // Fall back to DirectSolver (deprecated)
-      const solverResult = await this.solver.solve(task, routing);
-      result = {
-        trajectory: solverResult.trajectory,
-        usedMemory: solverResult.usedMemory,
-        strategy: solverResult.strategy,
-        usedAgentManager: false,
-      };
-    } else {
-      throw new Error(
-        'No execution method available. Call setAgentManager() or setProvider().'
-      );
-    }
-
-    // Add injected playbooks to result
-    result.injectedPlaybooks = injectedPlaybooks;
-    result.surfacedKnowledge = surfacedKnowledge;
-
-    // Infer playbook usage from trajectory
-    if (this.skillLibrary && injectedPlaybooks.length > 0) {
-      const usageResults = await this.inferPlaybookUsage(
-        result.trajectory,
-        injectedPlaybooks,
-      );
-
-      // Convert to PlaybookUsage format and record outcomes
-      result.playbookUsage = [];
-      for (const usage of usageResults) {
-        result.playbookUsage.push({
-          playbookId: usage.playbookId,
-          playbookName: usage.playbookName,
-          wasUsed: usage.wasUsed,
-          usageConfidence: usage.usageConfidence,
-          wasSuccessful: usage.wasSuccessful,
-        });
-
-        // Record outcome for tier management
-        if (usage.wasUsed) {
-          await this.skillLibrary.recordOutcome(
-            usage.playbookId,
-            result.trajectory.id,
-            usage.wasSuccessful,
-            usage.context
-          );
-        }
-      }
-    }
-
-    // Generate meta-reflection (records observation + periodically generates strategies)
-    const metaLearner = this.unifiedPipeline.getMetaLearner();
-    if (metaLearner) {
-      await this.reflectOnExecution(result.trajectory, routing);
-    }
-
-    // Annotate trajectory for effectiveness tracking
-    const effectivenessTracker = this.unifiedPipeline.getEffectivenessTracker();
-    if (effectivenessTracker) {
-      const appliedPlaybookIds = (result.playbookUsage ?? [])
-        .filter(u => u.wasUsed)
-        .map(u => u.playbookId);
-
-      const surfacedExperienceIds = routing.memoryContext.experiences.map(
-        e => e.experience.id
-      );
-
-      await effectivenessTracker.annotate(
-        result.trajectory,
-        routing.memoryContext.playbooks,
-        surfacedExperienceIds,
-        appliedPlaybookIds,
-      );
-    }
-
-    // Process the trajectory through unified pipeline (immediate + batch if energy triggers)
-    await this.unifiedPipeline.processTrajectory(result.trajectory);
-    this.trajectoriesProcessed++;
-
-    return result;
-  }
-
-  /**
-   * Solve using AgentManager with optional refinement
-   */
-  private async solveWithAgent(
-    task: Task,
-    routing: RoutingDecision,
-    skillContext?: string
-  ): Promise<SolveResult> {
-    if (!this.agentManager) {
-      throw new Error('AgentManager not available');
-    }
-
-    // Build spawn configuration
-    const spawnConfig: AgentSpawnConfig = {
-      agentType: this.config.execution.defaultAgentType,
-      task,
-      timeout: this.config.execution.maxExecutionTime * 1000,
-      captureToolCalls: this.config.execution.captureToolCalls,
-      // Inject skill context if available
-      systemPromptAdditions: skillContext || undefined,
-      // Pass router's memory context to avoid duplicate memory queries
-      injectedKnowledge: routing.memoryContext,
-    };
-
-    // Run initial execution
-    const agentResult = await this.agentManager.spawn(spawnConfig);
-
-    // Check if refinement should be triggered
-    const shouldRefine =
-      this.refinementLoop &&
-      this.config.refinement.useAgentEvaluation &&
-      this.refinementLoop.shouldTriggerRefinement(
-        routing.strategy,
-        routing.confidence
-      );
-
-    let refinementResult: RefinementResult | undefined;
-
-    if (shouldRefine && !agentResult.success) {
-      // Run refinement loop on failed trajectory
-      refinementResult = await this.refinementLoop!.refine(
-        agentResult.trajectory,
-        spawnConfig
-      );
-
-      return {
-        trajectory: refinementResult.trajectory,
-        routing,
-        usedAgentManager: true,
-        refinement: refinementResult,
-      };
-    }
-
-    return {
-      trajectory: agentResult.trajectory,
-      routing,
-      usedAgentManager: true,
-    };
-  }
-
-  /**
-   * Solve multiple tasks
-   */
-  async solveBatch(tasks: Task[]): Promise<SolveResult[]> {
-    const results: SolveResult[] = [];
-    for (const task of tasks) {
-      const result = await this.solve(task);
-      results.push(result);
-    }
-    return results;
-  }
-
-  /**
-   * Process an external trajectory (from another agent).
-   * Runs the instant loop first (hot path), then feeds into the batch pipeline.
-   */
-  async processTrajectory(trajectory: Trajectory): Promise<ImmediateResult> {
-    // Unified pipeline handles immediate + batch (if energy triggers)
-    const result = await this.unifiedPipeline.processTrajectory(trajectory);
-    this.trajectoriesProcessed++;
-    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
-   */
-  async runBatchLearning(): Promise<UnifiedBatchResult> {
-    return this.unifiedPipeline.runBatch();
-  }
-
-  /**
-   * Query memory for relevant context
-   */
-  async queryMemory(
-    query: string,
-    options?: {
-      domains?: string[];
-      includeExperiences?: boolean;
-      includePlaybooks?: boolean;
-    }
-  ) {
-    return this.memory.queryV2(query, options);
-  }
-
-  /**
-   * Get Atlas statistics
-   */
-  async getStats(): Promise<AtlasStats> {
-    const memoryStats = await this.memory.getStats();
-    const stats: AtlasStats = {
-      memory: memoryStats,
-      learning: {
-        trajectoriesProcessed: this.trajectoriesProcessed,
-        pendingTrajectories: this.unifiedPipeline.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 = {
-        agentManagerEnabled: true,
-        refinementEnabled: this.refinementLoop !== null,
-        backends: this.agentManager.listBackends(),
-      };
-    }
-
-    // Add skill library stats if available
-    if (this.skillLibrary) {
-      const libStats = this.skillLibrary.getStats();
-      stats.skillLibrary = {
-        coreSkillCount: libStats.coreSkillCount,
-        domainSkillCounts: libStats.domainSkillCounts,
-        mcpServerEnabled: this.mcpServer !== null,
-      };
-    }
-
-    return stats;
-  }
-
-  /**
-   * Get the memory system for direct access
-   */
-  getMemory(): MemorySystem {
-    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
-   */
-  getLearning(): UnifiedLearningPipeline {
-    return this.unifiedPipeline;
-  }
-
-  /**
-   * Get the skill library for direct access
-   */
-  getSkillLibrary(): SkillLibrary | null {
-    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
-   */
-  getMCPServer(): PlaybookMCPServer | null {
-    return this.mcpServer;
-  }
-
-  /**
-   * Start the MCP server for playbook access
-   */
-  async startMCPServer(): Promise<void> {
-    if (!this.memory.playbooks) {
-      throw new Error('Playbook library not available. Initialize Atlas first.');
-    }
-
-    if (this.mcpServer) {
-      return; // Already started
-    }
-
-    this.mcpServer = createPlaybookMCPServer(
-      this.memory.playbooks,
-      this.skillLibrary ?? undefined,
-      this.config.mcp
-    );
-  }
-
-  /**
-   * Stop the MCP server
-   */
-  async stopMCPServer(): Promise<void> {
-    if (this.mcpServer) {
-      this.mcpServer = null;
-    }
-  }
-
-  /**
-   * Update configuration
-   */
-  updateConfig(config: Partial<AtlasConfig>): void {
-    if (config.learning) {
-      this.unifiedPipeline.updateConfig(config.learning);
-    }
-    if (config.router) {
-      this.router.updateConfig(config.router);
-    }
-    this.config = { ...this.config, ...config };
-  }
-
-  /**
-   * 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> {
-    const metaLearnerRef = this.unifiedPipeline.getMetaLearner();
-    if (!metaLearnerRef) 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 metaLearnerRef.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 metaLearnerRef.generateReflection(
-      trajectory,
-      routingInfo,
-      playbookMatches,
-    );
-  }
-
-  /**
-   * Get the meta learner for direct access
-   */
-  getMetaLearner(): MetaLearner | null {
-    return this.unifiedPipeline.getMetaLearner();
-  }
-
-  /**
-   * Get the effectiveness tracker for direct access
-   */
-  getEffectivenessTracker(): LearningEffectivenessTracker | null {
-    return this.unifiedPipeline.getEffectivenessTracker();
-  }
-
-  async close(): Promise<void> {
-    // Stop MCP server if running
-    await this.stopMCPServer();
-
-    // Flush unified pipeline
-    if (this.unifiedPipeline.getAccumulatedCount() > 0) {
-      await this.unifiedPipeline.runBatch();
-    }
-
-    // Flush team learning pipeline
-    if (this.teamLearning && this.teamLearning.getAccumulatedCount() > 0) {
-      await this.teamLearning.runBatchLearning();
-    }
-
-    // Flush MoE gate state before closing persistence
-    this.router.persistGateState();
-
-    // Close effectiveness tracker
-    const tracker = this.unifiedPipeline.getEffectivenessTracker();
-    if (tracker) {
-      await tracker.close();
-    }
-
-    // Close skill-tree storage
-    if (this.skillTreeStorage) {
-      this.skillTreeStorage.close();
-    }
-
-    // Close memory system
-    await this.memory.close();
-
-    // Close SQLite persistence
-    this.persistence.close();
-  }
-}
-
-/**
- * Create an Atlas instance
- */
-export function createAtlas(config?: Partial<AtlasConfig>): Atlas {
-  return new Atlas(config);
-}
-
-/**
- * Create an Atlas instance with an LLM provider
- * @deprecated Use createAtlasWithAgents() for real action execution
- */
-export function createAtlasWithProvider(
-  provider: LLMProvider,
-  config?: Partial<AtlasConfig>
-): Atlas {
-  const atlas = new Atlas(config);
-  atlas.setProvider(provider);
-  return atlas;
-}
-
-/**
- * Create an Atlas instance with AgentManager backends
- * This is the recommended way to create Atlas for production use
- */
-export function createAtlasWithAgents(
-  backends: AgentBackend[],
-  config?: Partial<AtlasConfig>,
-  options?: { delegate?: AgentDelegate }
-): Atlas {
-  const atlas = new Atlas(config);
-  atlas.setAgentManager(backends, options);
-  return atlas;
-}