cognitive-core 0.0.2 → 0.1.2

package/src/surfacing/skill-library.ts

@@ -0,0 +1,625 @@
+/**
+ * Skill Library
+ * Tiered surfacing of playbooks for agent consumption
+ *
+ * Tiers:
+ * 1. Core Skills - Always in system prompt (highest confidence)
+ * 2. Domain Skills - Loaded when domain matches
+ * 3. Contextual - Injected based on task query
+ * 4. On-Demand - Available via MCP tool
+ */
+
+import type { StorageAdapter } from 'skill-tree';
+import type {
+  Task,
+  Playbook,
+  SkillLibraryConfig,
+} from '../types/index.js';
+import type { PlaybookLibrary } from '../memory/playbook.js';
+import { getPlaybookSuccessRate } from '../types/playbook.js';
+import { SkillPublisher } from './skill-publisher.js';
+
+/**
+ * Skills organized for agent context
+ */
+export interface AgentSkills {
+  /** Core skills - always included */
+  core: Playbook[];
+  /** Domain-specific skills */
+  domain: Playbook[];
+  /** Task-specific contextual playbooks */
+  contextual: Playbook[];
+  /** Estimated token count */
+  totalTokenEstimate: number;
+}
+
+/**
+ * Result of refreshing skill tiers
+ */
+export interface TierRefreshResult {
+  /** Playbook IDs promoted to core */
+  promoted: string[];
+  /** Playbook IDs demoted from core */
+  demoted: string[];
+  /** Current core skill count */
+  coreCount: number;
+  /** Domain skill counts */
+  domainCounts: Record<string, number>;
+}
+
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG: SkillLibraryConfig = {
+  promotion: {
+    minConfidence: 0.85,
+    minSuccessCount: 5,
+    minSuccessRate: 0.8,
+  },
+  limits: {
+    maxCoreSkills: 10,
+    maxDomainSkills: 5,
+    maxContextualPlaybooks: 3,
+  },
+  context: {
+    maxTokensForSkills: 2000,
+    includeRefinements: true,
+    includeExamples: false,
+    cacheRefreshInterval: 5 * 60 * 1000, // 5 minutes
+  },
+  demotion: {
+    failureThreshold: 3,
+    minConfidenceToRetain: 0.6,
+  },
+};
+
+/**
+ * Skill Library
+ * Manages tiered access to playbooks for agent consumption
+ */
+export class SkillLibrary {
+  private playbooks: PlaybookLibrary;
+  private config: SkillLibraryConfig;
+
+  // Cached promoted skills (refreshed periodically)
+  private coreSkills: Playbook[] = [];
+  private domainSkills: Map<string, Playbook[]> = new Map();
+  private lastRefresh: Date | null = null;
+  private consecutiveFailures: Map<string, number> = new Map();
+  private skillPublisher: SkillPublisher | null = null;
+
+  constructor(
+    playbooks: PlaybookLibrary,
+    config?: Partial<SkillLibraryConfig>
+  ) {
+    this.playbooks = playbooks;
+    this.config = this.mergeConfig(DEFAULT_CONFIG, config);
+  }
+
+  /**
+   * Merge configuration with defaults
+   */
+  private mergeConfig(
+    defaults: SkillLibraryConfig,
+    overrides?: Partial<SkillLibraryConfig>
+  ): SkillLibraryConfig {
+    if (!overrides) return defaults;
+
+    return {
+      promotion: { ...defaults.promotion, ...overrides.promotion },
+      limits: { ...defaults.limits, ...overrides.limits },
+      context: { ...defaults.context, ...overrides.context },
+      demotion: { ...defaults.demotion, ...overrides.demotion },
+    };
+  }
+
+  /**
+   * Set a skill-tree StorageAdapter for publishing graduated playbooks.
+   * When set, promoted playbooks are automatically saved as skills.
+   */
+  setPublisher(storage: StorageAdapter): void {
+    this.skillPublisher = new SkillPublisher(storage);
+  }
+
+  /**
+   * Get the skill publisher (if configured)
+   */
+  getPublisher(): SkillPublisher | null {
+    return this.skillPublisher;
+  }
+
+  // === TIER MANAGEMENT ===
+
+  /**
+   * Refresh skill tiers based on current playbook state
+   * Called periodically or after significant learning
+   */
+  async refreshTiers(): Promise<TierRefreshResult> {
+    const allPlaybooks = await this.playbooks.getAll();
+    const previousCoreIds = new Set(this.coreSkills.map((p) => p.id));
+
+    // Find playbooks that meet promotion criteria
+    const promotionCandidates = allPlaybooks
+      .filter((p) => this.meetsPromotionCriteria(p))
+      .sort((a, b) => {
+        // Sort by confidence * success rate
+        const scoreA = a.confidence * getPlaybookSuccessRate(a);
+        const scoreB = b.confidence * getPlaybookSuccessRate(b);
+        return scoreB - scoreA;
+      });
+
+    // Check for demotions
+    const demotions: string[] = [];
+    for (const playbook of this.coreSkills) {
+      if (this.meetsDemotionCriteria(playbook)) {
+        demotions.push(playbook.id);
+      }
+    }
+
+    // Update core skills (respecting max limit)
+    this.coreSkills = promotionCandidates
+      .filter((p) => !demotions.includes(p.id))
+      .slice(0, this.config.limits.maxCoreSkills);
+
+    const newCoreIds = new Set(this.coreSkills.map((p) => p.id));
+
+    // Calculate promotions and demotions
+    const promoted = [...newCoreIds].filter((id) => !previousCoreIds.has(id));
+    const demoted = [...previousCoreIds].filter((id) => !newCoreIds.has(id));
+
+    // Update domain skills
+    this.domainSkills.clear();
+    for (const playbook of allPlaybooks) {
+      if (newCoreIds.has(playbook.id)) continue; // Skip core skills
+
+      for (const domain of playbook.applicability.domains) {
+        const domainList = this.domainSkills.get(domain) ?? [];
+
+        if (domainList.length < this.config.limits.maxDomainSkills) {
+          domainList.push(playbook);
+          this.domainSkills.set(domain, domainList);
+        }
+      }
+    }
+
+    // Sort domain skills by confidence
+    for (const [domain, skills] of this.domainSkills) {
+      this.domainSkills.set(
+        domain,
+        skills.sort((a, b) => b.confidence - a.confidence)
+      );
+    }
+
+    this.lastRefresh = new Date();
+
+    // Publish newly promoted playbooks to external registry
+    if (this.skillPublisher && promoted.length > 0) {
+      const promotedPlaybooks = this.coreSkills.filter(p => promoted.includes(p.id));
+      await this.skillPublisher.publishPlaybooks(promotedPlaybooks);
+    }
+
+    // Deprecate demoted playbooks in external registry
+    if (this.skillPublisher && demoted.length > 0) {
+      for (const id of demoted) {
+        await this.skillPublisher.deprecateSkill(id, 'Demoted from core tier due to low performance');
+      }
+    }
+
+    // Build domain counts
+    const domainCounts: Record<string, number> = {};
+    for (const [domain, skills] of this.domainSkills) {
+      domainCounts[domain] = skills.length;
+    }
+
+    return {
+      promoted,
+      demoted,
+      coreCount: this.coreSkills.length,
+      domainCounts,
+    };
+  }
+
+  /**
+   * Check if a playbook qualifies for core skill status
+   */
+  private meetsPromotionCriteria(playbook: Playbook): boolean {
+    const { minConfidence, minSuccessCount, minSuccessRate } =
+      this.config.promotion;
+    const { successCount, failureCount } = playbook.evolution;
+    const totalUses = successCount + failureCount;
+    const actualSuccessRate = totalUses > 0 ? successCount / totalUses : 0;
+
+    return (
+      playbook.confidence >= minConfidence &&
+      successCount >= minSuccessCount &&
+      actualSuccessRate >= minSuccessRate
+    );
+  }
+
+  /**
+   * Check if a core skill should be demoted
+   */
+  private meetsDemotionCriteria(playbook: Playbook): boolean {
+    const { failureThreshold, minConfidenceToRetain } = this.config.demotion;
+    const recentFailures = this.consecutiveFailures.get(playbook.id) ?? 0;
+
+    return (
+      recentFailures >= failureThreshold ||
+      playbook.confidence < minConfidenceToRetain
+    );
+  }
+
+  // === RETRIEVAL FOR AGENT CONTEXT ===
+
+  /**
+   * Get skills for agent system prompt
+   * Returns tiered skills based on task context
+   */
+  async getSkillsForAgent(
+    task: Task,
+    options?: {
+      includeCore?: boolean;
+      includeDomain?: boolean;
+      includeContextual?: boolean;
+    }
+  ): Promise<AgentSkills> {
+    const includeCore = options?.includeCore ?? true;
+    const includeDomain = options?.includeDomain ?? true;
+    const includeContextual = options?.includeContextual ?? true;
+
+    // Ensure tiers are fresh (refresh if older than cache interval)
+    if (
+      !this.lastRefresh ||
+      Date.now() - this.lastRefresh.getTime() > this.config.context.cacheRefreshInterval
+    ) {
+      await this.refreshTiers();
+    }
+
+    const result: AgentSkills = {
+      core: [],
+      domain: [],
+      contextual: [],
+      totalTokenEstimate: 0,
+    };
+
+    // Add core skills
+    if (includeCore) {
+      result.core = [...this.coreSkills];
+      result.totalTokenEstimate += this.estimateTokens(result.core);
+    }
+
+    // Add domain skills
+    if (includeDomain && task.domain) {
+      const domainSkills = this.domainSkills.get(task.domain) ?? [];
+      result.domain = domainSkills.filter(
+        (p) => !result.core.some((c) => c.id === p.id)
+      );
+      result.totalTokenEstimate += this.estimateTokens(result.domain);
+    }
+
+    // Add contextual playbooks (from query)
+    if (includeContextual) {
+      const matches = await this.playbooks.findMatching(task.description, {
+        k: this.config.limits.maxContextualPlaybooks,
+        domains: task.domain ? [task.domain] : undefined,
+        excludeAntiPatterns: true,
+      });
+
+      result.contextual = matches
+        .map((m) => m.playbook)
+        .filter(
+          (p) =>
+            !result.core.some((c) => c.id === p.id) &&
+            !result.domain.some((d) => d.id === p.id)
+        );
+      result.totalTokenEstimate += this.estimateTokens(result.contextual);
+    }
+
+    // Trim if over token budget
+    while (
+      result.totalTokenEstimate > this.config.context.maxTokensForSkills &&
+      result.contextual.length > 0
+    ) {
+      result.contextual.pop();
+      result.totalTokenEstimate = this.estimateTokens([
+        ...result.core,
+        ...result.domain,
+        ...result.contextual,
+      ]);
+    }
+
+    return result;
+  }
+
+  /**
+   * Estimate token count for playbooks
+   */
+  private estimateTokens(playbooks: Playbook[]): number {
+    let tokens = 0;
+
+    for (const playbook of playbooks) {
+      // Rough estimate: 4 characters per token
+      tokens += playbook.name.length / 4;
+      tokens += playbook.guidance.strategy.length / 4;
+      tokens += playbook.guidance.tactics.join(' ').length / 4;
+
+      if (this.config.context.includeRefinements) {
+        tokens +=
+          playbook.evolution.refinements
+            .map((r) => `${r.context}: ${r.addition}`)
+            .join(' ').length / 4;
+      }
+
+      if (playbook.guidance.steps) {
+        tokens += playbook.guidance.steps.join(' ').length / 4;
+      }
+    }
+
+    return Math.ceil(tokens);
+  }
+
+  /**
+   * Format skills for system prompt injection
+   */
+  formatForSystemPrompt(skills: AgentSkills): string {
+    const sections: string[] = [];
+
+    // Format core skills
+    if (skills.core.length > 0) {
+      sections.push('## Core Skills\n');
+      sections.push('These are proven approaches you should follow:\n');
+      for (const playbook of skills.core) {
+        sections.push(this.formatPlaybookForPrompt(playbook, 'core'));
+      }
+    }
+
+    // Format domain skills
+    if (skills.domain.length > 0) {
+      sections.push('## Domain Skills\n');
+      for (const playbook of skills.domain) {
+        sections.push(this.formatPlaybookForPrompt(playbook, 'domain'));
+      }
+    }
+
+    // Format contextual playbooks
+    if (skills.contextual.length > 0) {
+      sections.push('## Relevant Playbooks\n');
+      for (const playbook of skills.contextual) {
+        sections.push(this.formatPlaybookForPrompt(playbook, 'contextual'));
+      }
+    }
+
+    return sections.join('\n');
+  }
+
+  /**
+   * Format a single playbook for prompt
+   */
+  private formatPlaybookForPrompt(
+    playbook: Playbook,
+    _tier: 'core' | 'domain' | 'contextual'
+  ): string {
+    const lines: string[] = [];
+    const confidencePercent = Math.round(playbook.confidence * 100);
+
+    lines.push(`### ${playbook.name} (${confidencePercent}% confidence)`);
+    lines.push(`**When**: ${playbook.applicability.situations[0] ?? 'General use'}`);
+    lines.push(`**Strategy**: ${playbook.guidance.strategy}`);
+
+    if (playbook.guidance.tactics.length > 0) {
+      lines.push('**Tactics**:');
+      for (const tactic of playbook.guidance.tactics.slice(0, 5)) {
+        lines.push(`  - ${tactic}`);
+      }
+    }
+
+    if (
+      this.config.context.includeRefinements &&
+      playbook.evolution.refinements.length > 0
+    ) {
+      lines.push('**Notes**:');
+      for (const ref of playbook.evolution.refinements.slice(0, 2)) {
+        lines.push(`  - In ${ref.context}: ${ref.addition}`);
+      }
+    }
+
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  // === LIFECYCLE INTEGRATION ===
+
+  /**
+   * Record playbook usage outcome (inferred from trajectory)
+   * Called by learning pipeline after trajectory analysis
+   */
+  async recordOutcome(
+    playbookId: string,
+    trajectoryId: string,
+    success: boolean,
+    context?: string
+  ): Promise<void> {
+    if (success) {
+      // Reset consecutive failures
+      this.consecutiveFailures.set(playbookId, 0);
+      await this.playbooks.recordSuccess(playbookId, trajectoryId);
+    } else {
+      // Increment consecutive failures
+      const currentFailures = this.consecutiveFailures.get(playbookId) ?? 0;
+      this.consecutiveFailures.set(playbookId, currentFailures + 1);
+      await this.playbooks.recordFailure(
+        playbookId,
+        trajectoryId,
+        context ?? 'Unknown',
+        'Task failed'
+      );
+    }
+  }
+
+  /**
+   * Get promotion candidates
+   */
+  async getPromotionCandidates(): Promise<Playbook[]> {
+    const allPlaybooks = await this.playbooks.getAll();
+    const coreIds = new Set(this.coreSkills.map((p) => p.id));
+
+    return allPlaybooks.filter(
+      (p) => !coreIds.has(p.id) && this.meetsPromotionCriteria(p)
+    );
+  }
+
+  /**
+   * Get demotion candidates
+   */
+  async getDemotionCandidates(): Promise<Playbook[]> {
+    return this.coreSkills.filter((p) => this.meetsDemotionCriteria(p));
+  }
+
+  /**
+   * Get current core skills
+   */
+  getCoreSkills(): Playbook[] {
+    return [...this.coreSkills];
+  }
+
+  /**
+   * Get domain skills
+   */
+  getDomainSkills(domain: string): Playbook[] {
+    return [...(this.domainSkills.get(domain) ?? [])];
+  }
+
+  /**
+   * Get all domains with skills
+   */
+  getDomains(): string[] {
+    return Array.from(this.domainSkills.keys());
+  }
+
+  /**
+   * Get statistics
+   */
+  getStats(): {
+    coreSkillCount: number;
+    domainSkillCounts: Record<string, number>;
+    lastRefresh: Date | null;
+    consecutiveFailures: Record<string, number>;
+  } {
+    const domainSkillCounts: Record<string, number> = {};
+    for (const [domain, skills] of this.domainSkills) {
+      domainSkillCounts[domain] = skills.length;
+    }
+
+    // Convert consecutive failures map to record
+    const failureRecord: Record<string, number> = {};
+    for (const [id, count] of this.consecutiveFailures) {
+      if (count > 0) {
+        failureRecord[id] = count;
+      }
+    }
+
+    return {
+      coreSkillCount: this.coreSkills.length,
+      domainSkillCounts,
+      lastRefresh: this.lastRefresh,
+      consecutiveFailures: failureRecord,
+    };
+  }
+
+  /**
+   * Get consecutive failure count for a playbook
+   */
+  getConsecutiveFailures(playbookId: string): number {
+    return this.consecutiveFailures.get(playbookId) ?? 0;
+  }
+
+  /**
+   * Reset consecutive failures for a playbook
+   */
+  resetConsecutiveFailures(playbookId: string): void {
+    this.consecutiveFailures.delete(playbookId);
+  }
+
+  /**
+   * Get all playbooks at risk of demotion
+   */
+  getAtRiskPlaybooks(): Array<{
+    playbook: Playbook;
+    consecutiveFailures: number;
+    failuresUntilDemotion: number;
+  }> {
+    const atRisk: Array<{
+      playbook: Playbook;
+      consecutiveFailures: number;
+      failuresUntilDemotion: number;
+    }> = [];
+
+    for (const playbook of this.coreSkills) {
+      const failures = this.consecutiveFailures.get(playbook.id) ?? 0;
+      const threshold = this.config.demotion.failureThreshold;
+
+      if (failures > 0) {
+        atRisk.push({
+          playbook,
+          consecutiveFailures: failures,
+          failuresUntilDemotion: Math.max(0, threshold - failures),
+        });
+      }
+    }
+
+    return atRisk.sort(
+      (a, b) => a.failuresUntilDemotion - b.failuresUntilDemotion
+    );
+  }
+
+  /**
+   * Apply time-based decay to consecutive failures
+   * Reduces failure counts for playbooks that haven't been used recently
+   * @param decayAmount Amount to reduce failure count by (default: 1)
+   */
+  applyFailureDecay(decayAmount = 1): void {
+    for (const [playbookId, count] of this.consecutiveFailures) {
+      const newCount = Math.max(0, count - decayAmount);
+      if (newCount === 0) {
+        this.consecutiveFailures.delete(playbookId);
+      } else {
+        this.consecutiveFailures.set(playbookId, newCount);
+      }
+    }
+  }
+
+  /**
+   * Export consecutive failure state for persistence
+   */
+  exportFailureState(): Record<string, number> {
+    const state: Record<string, number> = {};
+    for (const [id, count] of this.consecutiveFailures) {
+      if (count > 0) {
+        state[id] = count;
+      }
+    }
+    return state;
+  }
+
+  /**
+   * Import consecutive failure state from persistence
+   */
+  importFailureState(state: Record<string, number>): void {
+    this.consecutiveFailures.clear();
+    for (const [id, count] of Object.entries(state)) {
+      if (count > 0) {
+        this.consecutiveFailures.set(id, count);
+      }
+    }
+  }
+}
+
+/**
+ * Create a skill library
+ */
+export function createSkillLibrary(
+  playbooks: PlaybookLibrary,
+  config?: Partial<SkillLibraryConfig>
+): SkillLibrary {
+  return new SkillLibrary(playbooks, config);
+}