cognitive-core 0.1.0 → 0.2.0

package/src/learning/maintenance-scheduler.ts

@@ -0,0 +1,271 @@
+/**
+ * MaintenanceScheduler — Circadian-style duty-gated maintenance scheduling.
+ *
+ * Inspired by ruvector's CircadianController (ruvector-nervous-system/routing/circadian.rs).
+ * Gates background maintenance work using configurable triggers:
+ *
+ *   - 'manual': Only runs when explicitly requested
+ *   - 'afterNBatches': Runs after N batch cycles complete
+ *   - 'periodic': Runs on a time interval
+ *
+ * Maintenance tasks are deferred during active batch processing to avoid
+ * contention. A duty-factor model ensures maintenance doesn't starve
+ * the primary learning pipeline.
+ */
+
+/**
+ * Maintenance trigger mode.
+ */
+export type MaintenanceMode = 'manual' | 'afterNBatches' | 'periodic';
+
+/**
+ * Configuration for the MaintenanceScheduler.
+ */
+export interface MaintenanceSchedulerConfig {
+  /** Trigger mode (default: 'afterNBatches') */
+  mode: MaintenanceMode;
+  /** For 'afterNBatches' mode: batches between maintenance runs (default: 5) */
+  batchInterval: number;
+  /** For 'periodic' mode: milliseconds between runs (default: 3600000 = 1h) */
+  intervalMs: number;
+  /** Skip maintenance if a batch is currently running (default: true) */
+  deferDuringBatch: boolean;
+  /** Maximum queued maintenance tasks before dropping oldest (default: 10) */
+  maxQueueSize: number;
+}
+
+const DEFAULT_CONFIG: MaintenanceSchedulerConfig = {
+  mode: 'afterNBatches',
+  batchInterval: 5,
+  intervalMs: 3_600_000,
+  deferDuringBatch: true,
+  maxQueueSize: 10,
+};
+
+/**
+ * A maintenance task that can be scheduled.
+ */
+export interface MaintenanceTask {
+  /** Unique name for this task (e.g., 'knowledge-defrag', 'temporal-compression') */
+  name: string;
+  /** Priority (higher = run first) */
+  priority: number;
+  /** The async work to perform */
+  execute: () => Promise<MaintenanceTaskResult>;
+}
+
+/**
+ * Result of a maintenance task execution.
+ */
+export interface MaintenanceTaskResult {
+  taskName: string;
+  success: boolean;
+  durationMs: number;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Result of a full maintenance cycle.
+ */
+export interface MaintenanceCycleResult {
+  /** Whether the cycle actually ran (false if deferred or not due) */
+  ran: boolean;
+  /** Reason the cycle was skipped, if applicable */
+  skipReason?: 'not_due' | 'batch_in_progress' | 'manual_mode' | 'queue_empty';
+  /** Results from each task that ran */
+  taskResults: MaintenanceTaskResult[];
+  /** Total duration of the cycle in ms */
+  totalDurationMs: number;
+  /** Timestamp of this cycle */
+  timestamp: Date;
+}
+
+/**
+ * MaintenanceScheduler — duty-gated background maintenance scheduling.
+ */
+export class MaintenanceScheduler {
+  private config: MaintenanceSchedulerConfig;
+  private registeredTasks: MaintenanceTask[] = [];
+  private batchesSinceLastMaintenance = 0;
+  private lastMaintenanceTime = 0;
+  private isBatchRunning = false;
+  private cycleHistory: MaintenanceCycleResult[] = [];
+
+  constructor(config?: Partial<MaintenanceSchedulerConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Register a maintenance task.
+   * Tasks are sorted by priority (descending) before execution.
+   */
+  registerTask(task: MaintenanceTask): void {
+    // Replace existing task with same name
+    this.registeredTasks = this.registeredTasks.filter(t => t.name !== task.name);
+    this.registeredTasks.push(task);
+    this.registeredTasks.sort((a, b) => b.priority - a.priority);
+  }
+
+  /**
+   * Unregister a maintenance task by name.
+   */
+  unregisterTask(name: string): void {
+    this.registeredTasks = this.registeredTasks.filter(t => t.name !== name);
+  }
+
+  /**
+   * Signal that a batch cycle has completed.
+   * For 'afterNBatches' mode, this increments the counter.
+   */
+  onBatchComplete(): void {
+    this.batchesSinceLastMaintenance++;
+  }
+
+  /**
+   * Signal that a batch is starting (for deferral logic).
+   */
+  onBatchStart(): void {
+    this.isBatchRunning = true;
+  }
+
+  /**
+   * Signal that a batch has finished running.
+   */
+  onBatchEnd(): void {
+    this.isBatchRunning = false;
+  }
+
+  /**
+   * Check whether maintenance should run now.
+   */
+  shouldRunMaintenance(): boolean {
+    if (this.config.mode === 'manual') return false;
+    if (this.config.deferDuringBatch && this.isBatchRunning) return false;
+    if (this.registeredTasks.length === 0) return false;
+
+    if (this.config.mode === 'afterNBatches') {
+      return this.batchesSinceLastMaintenance >= this.config.batchInterval;
+    }
+
+    if (this.config.mode === 'periodic') {
+      const now = Date.now();
+      return (now - this.lastMaintenanceTime) >= this.config.intervalMs;
+    }
+
+    return false;
+  }
+
+  /**
+   * Run a maintenance cycle.
+   * Executes all registered tasks in priority order.
+   *
+   * Can be called manually regardless of mode — bypasses trigger checks.
+   */
+  async runMaintenance(options?: { force?: boolean }): Promise<MaintenanceCycleResult> {
+    const start = Date.now();
+
+    // Check if we should run (unless forced)
+    if (!options?.force) {
+      if (this.config.deferDuringBatch && this.isBatchRunning) {
+        return this.skipResult('batch_in_progress', start);
+      }
+      if (this.registeredTasks.length === 0) {
+        return this.skipResult('queue_empty', start);
+      }
+    }
+
+    // Execute tasks in priority order
+    const taskResults: MaintenanceTaskResult[] = [];
+    for (const task of this.registeredTasks) {
+      const taskStart = Date.now();
+      try {
+        const result = await task.execute();
+        taskResults.push(result);
+      } catch (error) {
+        taskResults.push({
+          taskName: task.name,
+          success: false,
+          durationMs: Date.now() - taskStart,
+          details: {
+            error: error instanceof Error ? error.message : String(error),
+          },
+        });
+      }
+    }
+
+    // Reset counters
+    this.batchesSinceLastMaintenance = 0;
+    this.lastMaintenanceTime = Date.now();
+
+    const result: MaintenanceCycleResult = {
+      ran: true,
+      taskResults,
+      totalDurationMs: Date.now() - start,
+      timestamp: new Date(),
+    };
+
+    this.cycleHistory.push(result);
+    if (this.cycleHistory.length > this.config.maxQueueSize) {
+      this.cycleHistory.shift();
+    }
+
+    return result;
+  }
+
+  /**
+   * Get the list of registered tasks.
+   */
+  getRegisteredTasks(): readonly MaintenanceTask[] {
+    return this.registeredTasks;
+  }
+
+  /**
+   * Get maintenance cycle history.
+   */
+  getCycleHistory(): readonly MaintenanceCycleResult[] {
+    return this.cycleHistory;
+  }
+
+  /**
+   * Get the number of batches since last maintenance.
+   */
+  getBatchesSinceLastMaintenance(): number {
+    return this.batchesSinceLastMaintenance;
+  }
+
+  /**
+   * Get current configuration.
+   */
+  getConfig(): Readonly<MaintenanceSchedulerConfig> {
+    return this.config;
+  }
+
+  /**
+   * Update configuration.
+   */
+  updateConfig(config: Partial<MaintenanceSchedulerConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  private skipResult(
+    reason: MaintenanceCycleResult['skipReason'],
+    start: number,
+  ): MaintenanceCycleResult {
+    return {
+      ran: false,
+      skipReason: reason,
+      taskResults: [],
+      totalDurationMs: Date.now() - start,
+      timestamp: new Date(),
+    };
+  }
+}
+
+/**
+ * Create a MaintenanceScheduler.
+ */
+export function createMaintenanceScheduler(
+  config?: Partial<MaintenanceSchedulerConfig>,
+): MaintenanceScheduler {
+  return new MaintenanceScheduler(config);
+}

package/src/learning/meta-learner.ts

@@ -16,6 +16,8 @@ import type {
 import { createMetaObservation, createMetaStrategy } from '../types/index.js';
 import type { MetaMemory } from '../memory/meta.js';
 import type { PlaybookMatch } from '../memory/playbook.js';
+import type { MetaReflectionOutput } from '../workspace/templates/meta-reflection.js';
+import { detectRepeatedActions, extractToolNames } from '../utils/trajectory-helpers.js';
 
 /**
  * Routing decision from the router
@@ -129,6 +131,59 @@ export class MetaLearner {
     return observation;
   }
 
+  /**
+   * Record a meta-observation from workspace-based reflection output.
+   * Bridges MetaReflectionOutput (from the meta-reflection template)
+   * into the MetaObservation storage format.
+   */
+  async recordFromReflection(
+    reflection: MetaReflectionOutput,
+    trajectoryId: string,
+    routing: RoutingDecision,
+    playbookIds: string[],
+    actualEffort: number,
+  ): Promise<MetaObservation> {
+    const observation = createMetaObservation({
+      trajectoryId,
+      routing: {
+        decision: routing.strategy,
+        confidence: routing.confidence,
+        reasoning: routing.reasoning,
+      },
+      memoryUsage: {
+        experiencesRetrieved: 0,
+        playbooksApplied: playbookIds,
+        retrievalQuality: reflection.retrievalQuality,
+      },
+      execution: {
+        decompositionUsed: reflection.decompositionUsed,
+        refinementIterations: reflection.refinementIterations,
+        backtrackingOccurred: reflection.backtrackingOccurred,
+        toolsUsed: [],
+      },
+      outcome: {
+        success: reflection.outcomeQuality !== 'poor',
+        quality: reflection.outcomeQuality,
+        effortActual: actualEffort,
+        effortEstimate: routing.estimatedBudget,
+      },
+      lessons: {
+        whatWorked: reflection.whatWorked,
+        whatFailed: reflection.whatFailed,
+        suggestions: reflection.suggestions,
+      },
+    });
+
+    await this.meta.recordObservation(observation);
+    this.observationCount++;
+
+    if (this.observationCount % this.config.strategyGenerationInterval === 0) {
+      await this.learn();
+    }
+
+    return observation;
+  }
+
   /**
    * Analyze accumulated observations and generate meta-strategies
    */
@@ -321,31 +376,12 @@ export class MetaLearner {
     toolsUsed: string[];
   } {
     const steps = trajectory.steps;
-    const toolsUsed = new Set<string>();
-    let backtrackingOccurred = false;
-
-    // Collect tools used (extract from action)
-    for (const step of steps) {
-      // Try to extract tool name from action (e.g., "tool_use: Bash" or just "Bash")
-      const toolMatch = step.action.match(/^(?:tool_use:\s*)?(\w+)/);
-      if (toolMatch) {
-        toolsUsed.add(toolMatch[1]);
-      }
-    }
 
-    // Check for backtracking (similar actions repeated)
-    const actionCounts = new Map<string, number>();
-    for (const step of steps) {
-      const normalized = step.action.toLowerCase().slice(0, 50);
-      actionCounts.set(normalized, (actionCounts.get(normalized) ?? 0) + 1);
-    }
+    // Collect tools used
+    const toolsUsed = extractToolNames(steps);
 
-    for (const count of actionCounts.values()) {
-      if (count > 2) {
-        backtrackingOccurred = true;
-        break;
-      }
-    }
+    // Check for backtracking (similar actions repeated)
+    const backtrackingOccurred = detectRepeatedActions(steps, 3).length > 0;
 
     // Check for decomposition (multiple sub-tasks)
     const decompositionUsed =

package/src/learning/reflexion-generator.ts

@@ -0,0 +1,273 @@
+/**
+ * ReflexionGenerator — Generates structured self-reflection from completed trajectories.
+ *
+ * Two modes:
+ * - **heuristic** (default, no LLM): Extracts patterns, tool names, file paths,
+ *   error messages, and strategy assessments from trajectory data.
+ * - **agentic** (optional): Uses LLM via ComputeProvider for deeper analysis.
+ *   Falls back to heuristic if LLM is unavailable.
+ */
+
+import type { Trajectory, ReflexionEpisode } from '../types/index.js';
+import type { PlaybookMatch } from '../memory/playbook.js';
+import { classifyErrorType } from '../utils/error-classifier.js';
+import { detectRepeatedActions, extractToolNames } from '../utils/trajectory-helpers.js';
+
+/**
+ * Configuration for ReflexionGenerator
+ */
+export interface ReflexionGeneratorConfig {
+  /** Generation mode: 'heuristic' (default) or 'agentic' */
+  mode?: 'heuristic' | 'agentic';
+  /** Max length for taskSummary (default: 200) */
+  maxSummaryLength?: number;
+  /** Max number of key insights to extract (default: 5) */
+  maxInsights?: number;
+}
+
+/**
+ * ReflexionGenerator — creates ReflexionEpisode from trajectory + matched playbooks
+ */
+export class ReflexionGenerator {
+  private config: Required<ReflexionGeneratorConfig>;
+
+  constructor(config?: ReflexionGeneratorConfig) {
+    this.config = {
+      mode: config?.mode ?? 'heuristic',
+      maxSummaryLength: config?.maxSummaryLength ?? 200,
+      maxInsights: config?.maxInsights ?? 5,
+    };
+  }
+
+  /**
+   * Generate a reflexion episode from a completed trajectory.
+   */
+  async generate(
+    trajectory: Trajectory,
+    matchedPlaybooks?: PlaybookMatch[]
+  ): Promise<ReflexionEpisode> {
+    // Currently only heuristic mode is implemented
+    return this.generateHeuristic(trajectory, matchedPlaybooks ?? []);
+  }
+
+  /**
+   * Heuristic mode — no LLM calls, pure pattern extraction.
+   */
+  private generateHeuristic(
+    trajectory: Trajectory,
+    matchedPlaybooks: PlaybookMatch[]
+  ): ReflexionEpisode {
+    const outcome = this.mapOutcome(trajectory);
+    const taskSummary = trajectory.task.description.slice(0, this.config.maxSummaryLength);
+    const selfCritique = this.extractSelfCritique(trajectory);
+    const keyInsights = this.extractKeyInsights(trajectory);
+    const strategyAssessment = this.assessStrategy(trajectory, matchedPlaybooks);
+    const suggestedPlaybookUpdates = this.suggestPlaybookUpdates(
+      trajectory,
+      matchedPlaybooks
+    );
+
+    return {
+      id: crypto.randomUUID(),
+      trajectoryId: trajectory.id,
+      taskSummary,
+      outcome,
+      selfCritique,
+      keyInsights,
+      strategyAssessment,
+      suggestedPlaybookUpdates,
+      domain: trajectory.task.domain ?? 'general',
+      createdAt: new Date(),
+    };
+  }
+
+  /**
+   * Map trajectory outcome to reflexion outcome label.
+   */
+  private mapOutcome(trajectory: Trajectory): 'success' | 'partial' | 'failure' {
+    if (trajectory.outcome.success) return 'success';
+    if (
+      trajectory.outcome.partialScore !== undefined &&
+      trajectory.outcome.partialScore > 0
+    ) {
+      return 'partial';
+    }
+    return 'failure';
+  }
+
+  /**
+   * Extract self-critique from the trajectory.
+   * Looks at failed steps, error messages, and wasted actions.
+   */
+  private extractSelfCritique(trajectory: Trajectory): string {
+    const parts: string[] = [];
+
+    if (!trajectory.outcome.success) {
+      // Summarize what went wrong
+      if (trajectory.outcome.errorInfo) {
+        parts.push(`Failed with: ${trajectory.outcome.errorInfo.slice(0, 150)}`);
+      }
+
+      // Count steps with low attribution scores (wasted effort)
+      const lowAttributionSteps = trajectory.steps.filter(
+        (s) => s.attributionScore !== undefined && s.attributionScore < 0.2
+      );
+      if (lowAttributionSteps.length > 0) {
+        parts.push(
+          `${lowAttributionSteps.length} of ${trajectory.steps.length} steps had low attribution (wasted effort)`
+        );
+      }
+    } else {
+      // Successful — note efficiency
+      const stepCount = trajectory.steps.length;
+      if (stepCount > 10) {
+        parts.push(`Succeeded but took ${stepCount} steps — may be overcomplicating`);
+      } else {
+        parts.push(`Completed efficiently in ${stepCount} steps`);
+      }
+    }
+
+    // Look for repeated actions (potential thrashing)
+    const repeated = detectRepeatedActions(trajectory.steps, 3);
+    if (repeated.length > 0) {
+      parts.push(
+        `Repeated actions detected: ${repeated.map(({ action, count }) => `"${action.slice(0, 30)}..." (${count}x)`).join(', ')}`
+      );
+    }
+
+    return parts.join('. ') || 'No specific critique identified';
+  }
+
+  /**
+   * Extract key insights from the trajectory.
+   * Pulls tool names, file paths, and notable observations.
+   */
+  private extractKeyInsights(trajectory: Trajectory): string[] {
+    const insights: string[] = [];
+
+    // Extract tool names from steps
+    const toolNames = extractToolNames(trajectory.steps);
+    if (toolNames.size > 0) {
+      insights.push(`Tools used: ${[...toolNames].join(', ')}`);
+    }
+
+    // Extract file paths from observations
+    const filePaths = new Set<string>();
+    for (const step of trajectory.steps) {
+      const pathMatches = step.observation?.match(
+        /(?:\/[\w.-]+)+(?:\.[\w]+)/g
+      );
+      if (pathMatches) {
+        for (const p of pathMatches.slice(0, 5)) {
+          filePaths.add(p);
+        }
+      }
+    }
+    if (filePaths.size > 0) {
+      insights.push(`Key files: ${[...filePaths].slice(0, 5).join(', ')}`);
+    }
+
+    // Note error patterns for failed trajectories
+    if (!trajectory.outcome.success && trajectory.outcome.errorInfo) {
+      const errorType = classifyErrorType(trajectory.outcome.errorInfo);
+      if (errorType) {
+        insights.push(`Error pattern: ${errorType}`);
+      }
+    }
+
+    // Note step count and efficiency
+    const highAttributionSteps = trajectory.steps.filter(
+      (s) => s.attributionScore !== undefined && s.attributionScore > 0.7
+    );
+    if (highAttributionSteps.length > 0) {
+      insights.push(
+        `${highAttributionSteps.length} high-impact steps identified`
+      );
+    }
+
+    return insights.slice(0, this.config.maxInsights);
+  }
+
+
+  /**
+   * Assess the strategy by comparing matched playbooks against the outcome.
+   */
+  private assessStrategy(
+    trajectory: Trajectory,
+    matchedPlaybooks: PlaybookMatch[]
+  ): string {
+    if (matchedPlaybooks.length === 0) {
+      if (trajectory.outcome.success) {
+        return 'Succeeded without playbook guidance — potential new playbook candidate';
+      }
+      return 'Failed without playbook guidance — no applicable playbooks found';
+    }
+
+    const topMatch = matchedPlaybooks[0];
+    const matchScore = Math.round(topMatch.score * 100);
+
+    if (trajectory.outcome.success) {
+      return `Succeeded with playbook "${topMatch.playbook.name}" (${matchScore}% match). Strategy confirmed.`;
+    }
+
+    // Failure with a matched playbook
+    return `Failed despite playbook "${topMatch.playbook.name}" (${matchScore}% match). Playbook may need refinement for this context.`;
+  }
+
+  /**
+   * Suggest playbook updates based on the trajectory outcome.
+   */
+  private suggestPlaybookUpdates(
+    trajectory: Trajectory,
+    matchedPlaybooks: PlaybookMatch[]
+  ): string[] {
+    const suggestions: string[] = [];
+
+    if (trajectory.outcome.success && matchedPlaybooks.length === 0) {
+      // Successful without playbooks — suggest creating one
+      suggestions.push(
+        `Create new playbook for: ${trajectory.task.description.slice(0, 100)}`
+      );
+    }
+
+    if (!trajectory.outcome.success) {
+      // Failed — suggest updates to matched playbooks
+      for (const match of matchedPlaybooks) {
+        if (trajectory.outcome.errorInfo) {
+          suggestions.push(
+            `Add anti-pattern to "${match.playbook.name}": ${trajectory.outcome.errorInfo.slice(0, 80)}`
+          );
+        }
+
+        // Suggest refinement based on error context
+        const domain = trajectory.task.domain;
+        if (domain) {
+          suggestions.push(
+            `Add refinement to "${match.playbook.name}" for domain "${domain}"`
+          );
+        }
+      }
+
+      // If no playbooks matched a failure, suggest broader coverage
+      if (matchedPlaybooks.length === 0 && trajectory.outcome.errorInfo) {
+        const errorType = classifyErrorType(trajectory.outcome.errorInfo);
+        if (errorType) {
+          suggestions.push(
+            `Create error-handling playbook for pattern: ${errorType}`
+          );
+        }
+      }
+    }
+
+    return suggestions;
+  }
+}
+
+/**
+ * Create a ReflexionGenerator instance
+ */
+export function createReflexionGenerator(
+  config?: ReflexionGeneratorConfig
+): ReflexionGenerator {
+  return new ReflexionGenerator(config);
+}