cognitive-core 0.2.5 → 0.3.1

package/src/surfacing/skill-library.ts

@@ -1,625 +0,0 @@
-/**
- * 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);
-}