cognitive-core 0.2.5 → 0.3.1

package/src/mcp/playbook-server.ts

@@ -1,565 +0,0 @@
-/**
- * MCP Playbook Server
- * Exposes playbook retrieval via Model Context Protocol
- *
- * @deprecated This module is deprecated in favor of the CLI interface and SKILL.md approach.
- * See /SKILL.md for instructions on how agents should interact with cognitive-core.
- * Use the CLI at bin/cognitive-core instead of this MCP server.
- *
- * This server provides on-demand access to the full playbook library,
- * allowing agents to search for specific guidance beyond what's in their
- * system prompt.
- */
-
-import type { Playbook } from '../types/index.js';
-import type { PlaybookLibrary, PlaybookMatch } from '../memory/playbook.js';
-import type { SkillLibrary } from '../surfacing/skill-library.js';
-import type { MCPServerConfig } from '../types/config.js';
-import {
-  validateMCPArgs,
-  MCPSearchPlaybooksSchema,
-  MCPGetPlaybookDetailsSchema,
-  MCPGetPlaybooksByDomainSchema,
-} from '../utils/validation.js';
-
-/**
- * MCP Tool definition
- */
-export interface MCPTool {
-  name: string;
-  description: string;
-  inputSchema: {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-}
-
-/**
- * MCP Tool call request
- */
-export interface MCPToolCall {
-  name: string;
-  arguments: Record<string, unknown>;
-}
-
-/**
- * MCP Tool call result
- */
-export interface MCPToolResult {
-  content: Array<{
-    type: 'text';
-    text: string;
-  }>;
-  isError?: boolean;
-}
-
-/**
- * Search result for MCP
- */
-export interface PlaybookSearchResult {
-  id: string;
-  name: string;
-  confidence: number;
-  matchScore: number;
-  matchType: string;
-  strategy: string;
-  tactics: string[];
-  successRate: number;
-  domains: string[];
-}
-
-/**
- * Default configuration
- */
-const DEFAULT_CONFIG: MCPServerConfig = {
-  enabled: true,
-  exposeResources: true,
-  exposeTools: true,
-  maxResults: 5,
-  minConfidence: 0.3,
-  includeRefinements: true,
-  enableDomainFiltering: true,
-};
-
-/**
- * MCP Playbook Server
- * Provides playbook search tools for agents
- */
-export class PlaybookMCPServer {
-  private playbooks: PlaybookLibrary;
-  private config: MCPServerConfig;
-
-  constructor(
-    playbooks: PlaybookLibrary,
-    _skillLibrary?: SkillLibrary,
-    config?: Partial<MCPServerConfig>
-  ) {
-    this.playbooks = playbooks;
-    this.config = { ...DEFAULT_CONFIG, ...config };
-  }
-
-  /**
-   * Get available MCP tools
-   */
-  getTools(): MCPTool[] {
-    return [
-      {
-        name: 'search_playbooks',
-        description:
-          'Search for playbooks that provide guidance for solving a problem. ' +
-          'Returns strategies, tactics, and success indicators for matching playbooks.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            query: {
-              type: 'string',
-              description: 'Description of the problem or task to find playbooks for',
-            },
-            domain: {
-              type: 'string',
-              description: 'Optional domain to filter results (e.g., "code", "testing", "refactoring")',
-            },
-            maxResults: {
-              type: 'number',
-              description: 'Maximum number of playbooks to return (default: 5)',
-            },
-          },
-          required: ['query'],
-        },
-      },
-      {
-        name: 'get_playbook_details',
-        description:
-          'Get detailed information about a specific playbook by ID, ' +
-          'including full tactics, steps, refinements, and usage statistics.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            playbookId: {
-              type: 'string',
-              description: 'The ID of the playbook to retrieve',
-            },
-          },
-          required: ['playbookId'],
-        },
-      },
-      {
-        name: 'list_domains',
-        description: 'List all domains that have playbooks available.',
-        inputSchema: {
-          type: 'object',
-          properties: {},
-        },
-      },
-      {
-        name: 'get_playbooks_by_domain',
-        description: 'Get all playbooks for a specific domain.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            domain: {
-              type: 'string',
-              description: 'The domain to get playbooks for',
-            },
-            maxResults: {
-              type: 'number',
-              description: 'Maximum number of playbooks to return (default: 10)',
-            },
-          },
-          required: ['domain'],
-        },
-      },
-    ];
-  }
-
-  /**
-   * Handle an MCP tool call
-   */
-  async handleToolCall(call: MCPToolCall): Promise<MCPToolResult> {
-    try {
-      switch (call.name) {
-        case 'search_playbooks':
-          return await this.handleSearchPlaybooks(call.arguments);
-        case 'get_playbook_details':
-          return await this.handleGetPlaybookDetails(call.arguments);
-        case 'list_domains':
-          return await this.handleListDomains();
-        case 'get_playbooks_by_domain':
-          return await this.handleGetPlaybooksByDomain(call.arguments);
-        default:
-          return {
-            content: [{ type: 'text', text: `Unknown tool: ${call.name}` }],
-            isError: true,
-          };
-      }
-    } catch (error) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
-          },
-        ],
-        isError: true,
-      };
-    }
-  }
-
-  /**
-   * Handle search_playbooks tool call
-   */
-  private async handleSearchPlaybooks(
-    args: Record<string, unknown>
-  ): Promise<MCPToolResult> {
-    // Validate arguments
-    const validated = validateMCPArgs(
-      MCPSearchPlaybooksSchema,
-      args,
-      'search_playbooks'
-    );
-    const { query, domain } = validated;
-    const maxResults = validated.maxResults ?? this.config.maxResults;
-
-    const matches = await this.playbooks.findMatching(query, {
-      k: maxResults,
-      domains: domain ? [domain] : undefined,
-      minConfidence: this.config.minConfidence,
-      excludeAntiPatterns: true,
-    });
-
-    if (matches.length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: 'No playbooks found matching your query. Try a different description or broader search terms.',
-          },
-        ],
-      };
-    }
-
-    const results: PlaybookSearchResult[] = matches.map((m) =>
-      this.formatPlaybookForSearch(m)
-    );
-
-    const formattedResults = results
-      .map((r) => this.formatSearchResultAsText(r))
-      .join('\n\n---\n\n');
-
-    return {
-      content: [{ type: 'text', text: formattedResults }],
-    };
-  }
-
-  /**
-   * Handle get_playbook_details tool call
-   */
-  private async handleGetPlaybookDetails(
-    args: Record<string, unknown>
-  ): Promise<MCPToolResult> {
-    // Validate arguments
-    const validated = validateMCPArgs(
-      MCPGetPlaybookDetailsSchema,
-      args,
-      'get_playbook_details'
-    );
-    const playbook = await this.playbooks.get(validated.playbookId);
-
-    if (!playbook) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Playbook not found: ${validated.playbookId}`,
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const details = this.formatPlaybookDetails(playbook);
-    return {
-      content: [{ type: 'text', text: details }],
-    };
-  }
-
-  /**
-   * Handle list_domains tool call
-   */
-  private async handleListDomains(): Promise<MCPToolResult> {
-    const allPlaybooks = await this.playbooks.getAll();
-    const domains = new Set<string>();
-
-    for (const playbook of allPlaybooks) {
-      for (const domain of playbook.applicability.domains) {
-        domains.add(domain);
-      }
-    }
-
-    const domainList = Array.from(domains).sort();
-
-    if (domainList.length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: 'No domains found. Playbooks may not have domain assignments yet.',
-          },
-        ],
-      };
-    }
-
-    const text = `Available domains:\n${domainList.map((d) => `  - ${d}`).join('\n')}`;
-    return {
-      content: [{ type: 'text', text }],
-    };
-  }
-
-  /**
-   * Handle get_playbooks_by_domain tool call
-   */
-  private async handleGetPlaybooksByDomain(
-    args: Record<string, unknown>
-  ): Promise<MCPToolResult> {
-    // Validate arguments
-    const validated = validateMCPArgs(
-      MCPGetPlaybooksByDomainSchema,
-      args,
-      'get_playbooks_by_domain'
-    );
-    const { domain } = validated;
-    const maxResults = validated.maxResults ?? 10;
-
-    const allPlaybooks = await this.playbooks.getAll();
-    const domainPlaybooks = allPlaybooks
-      .filter((p) => p.applicability.domains.includes(domain))
-      .sort((a, b) => b.confidence - a.confidence)
-      .slice(0, maxResults);
-
-    if (domainPlaybooks.length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `No playbooks found for domain: ${domain}`,
-          },
-        ],
-      };
-    }
-
-    const formatted = domainPlaybooks
-      .map((p) => this.formatPlaybookSummary(p))
-      .join('\n\n');
-
-    return {
-      content: [{ type: 'text', text: formatted }],
-    };
-  }
-
-  /**
-   * Format playbook match for search results
-   */
-  private formatPlaybookForSearch(match: PlaybookMatch): PlaybookSearchResult {
-    const { playbook, score, matchType } = match;
-    const { successCount, failureCount } = playbook.evolution;
-    const totalUses = successCount + failureCount;
-
-    return {
-      id: playbook.id,
-      name: playbook.name,
-      confidence: playbook.confidence,
-      matchScore: score,
-      matchType,
-      strategy: playbook.guidance.strategy,
-      tactics: playbook.guidance.tactics,
-      successRate: totalUses > 0 ? successCount / totalUses : 0,
-      domains: playbook.applicability.domains,
-    };
-  }
-
-  /**
-   * Format search result as text
-   */
-  private formatSearchResultAsText(result: PlaybookSearchResult): string {
-    const lines: string[] = [];
-
-    lines.push(`## ${result.name}`);
-    lines.push(`ID: ${result.id}`);
-    lines.push(`Match: ${Math.round(result.matchScore * 100)}% (${result.matchType})`);
-    lines.push(`Confidence: ${Math.round(result.confidence * 100)}%`);
-    lines.push(`Success Rate: ${Math.round(result.successRate * 100)}%`);
-
-    if (result.domains.length > 0) {
-      lines.push(`Domains: ${result.domains.join(', ')}`);
-    }
-
-    lines.push('');
-    lines.push(`**Strategy**: ${result.strategy}`);
-
-    if (result.tactics.length > 0) {
-      lines.push('**Tactics**:');
-      for (const tactic of result.tactics.slice(0, 5)) {
-        lines.push(`  - ${tactic}`);
-      }
-      if (result.tactics.length > 5) {
-        lines.push(`  ... and ${result.tactics.length - 5} more`);
-      }
-    }
-
-    return lines.join('\n');
-  }
-
-  /**
-   * Format playbook summary
-   */
-  private formatPlaybookSummary(playbook: Playbook): string {
-    const lines: string[] = [];
-    const { successCount, failureCount } = playbook.evolution;
-    const totalUses = successCount + failureCount;
-    const successRate = totalUses > 0 ? successCount / totalUses : 0;
-
-    lines.push(`## ${playbook.name}`);
-    lines.push(`ID: ${playbook.id}`);
-    lines.push(`Confidence: ${Math.round(playbook.confidence * 100)}%`);
-    lines.push(`Uses: ${totalUses} (${Math.round(successRate * 100)}% success)`);
-    lines.push('');
-    lines.push(`**Strategy**: ${playbook.guidance.strategy}`);
-
-    return lines.join('\n');
-  }
-
-  /**
-   * Format full playbook details
-   */
-  private formatPlaybookDetails(playbook: Playbook): string {
-    const lines: string[] = [];
-    const { successCount, failureCount } = playbook.evolution;
-    const totalUses = successCount + failureCount;
-    const successRate = totalUses > 0 ? successCount / totalUses : 0;
-
-    lines.push(`# ${playbook.name}`);
-    lines.push(`ID: ${playbook.id}`);
-    lines.push(`Version: ${playbook.evolution.version}`);
-    lines.push(`Confidence: ${Math.round(playbook.confidence * 100)}%`);
-    lines.push(`Complexity: ${playbook.complexity}`);
-    lines.push(`Estimated Effort: ${playbook.estimatedEffort} steps`);
-    lines.push('');
-
-    // Applicability
-    lines.push('## Applicability');
-    if (playbook.applicability.situations.length > 0) {
-      lines.push('**When to use**:');
-      for (const sit of playbook.applicability.situations) {
-        lines.push(`  - ${sit}`);
-      }
-    }
-    if (playbook.applicability.triggers.length > 0) {
-      lines.push('**Triggers**:');
-      for (const trigger of playbook.applicability.triggers) {
-        lines.push(`  - ${trigger}`);
-      }
-    }
-    if (playbook.applicability.antiPatterns.length > 0) {
-      lines.push('**Avoid when**:');
-      for (const anti of playbook.applicability.antiPatterns) {
-        lines.push(`  - ${anti}`);
-      }
-    }
-    if (playbook.applicability.domains.length > 0) {
-      lines.push(`**Domains**: ${playbook.applicability.domains.join(', ')}`);
-    }
-    lines.push('');
-
-    // Guidance
-    lines.push('## Guidance');
-    lines.push(`**Strategy**: ${playbook.guidance.strategy}`);
-    if (playbook.guidance.tactics.length > 0) {
-      lines.push('**Tactics**:');
-      for (const tactic of playbook.guidance.tactics) {
-        lines.push(`  - ${tactic}`);
-      }
-    }
-    if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
-      lines.push('**Steps**:');
-      for (let i = 0; i < playbook.guidance.steps.length; i++) {
-        lines.push(`  ${i + 1}. ${playbook.guidance.steps[i]}`);
-      }
-    }
-    lines.push('');
-
-    // Verification
-    lines.push('## Verification');
-    if (playbook.verification.successIndicators.length > 0) {
-      lines.push('**Success indicators**:');
-      for (const ind of playbook.verification.successIndicators) {
-        lines.push(`  - ${ind}`);
-      }
-    }
-    if (playbook.verification.failureIndicators.length > 0) {
-      lines.push('**Failure indicators**:');
-      for (const ind of playbook.verification.failureIndicators) {
-        lines.push(`  - ${ind}`);
-      }
-    }
-    lines.push('');
-
-    // Statistics
-    lines.push('## Statistics');
-    lines.push(`- Total uses: ${totalUses}`);
-    lines.push(`- Success rate: ${Math.round(successRate * 100)}%`);
-    lines.push(`- Successes: ${successCount}`);
-    lines.push(`- Failures: ${failureCount}`);
-    lines.push('');
-
-    // Refinements (if enabled)
-    if (
-      this.config.includeRefinements &&
-      playbook.evolution.refinements.length > 0
-    ) {
-      lines.push('## Context-Specific Refinements');
-      for (const ref of playbook.evolution.refinements) {
-        lines.push(`- **${ref.context}**: ${ref.addition}`);
-      }
-      lines.push('');
-    }
-
-    // Failure modes
-    if (playbook.evolution.failures.length > 0) {
-      lines.push('## Known Failure Modes');
-      for (const failure of playbook.evolution.failures.slice(0, 5)) {
-        lines.push(`- ${failure.context}: ${failure.failureMode}`);
-      }
-      lines.push('');
-    }
-
-    return lines.join('\n');
-  }
-
-  /**
-   * Get server info for MCP protocol
-   */
-  getServerInfo(): {
-    name: string;
-    version: string;
-    description: string;
-  } {
-    return {
-      name: 'atlas-playbook-server',
-      version: '1.0.0',
-      description:
-        'MCP server providing access to the Atlas playbook library for on-demand guidance retrieval',
-    };
-  }
-}
-
-/**
- * Create an MCP playbook server
- */
-export function createPlaybookMCPServer(
-  playbooks: PlaybookLibrary,
-  skillLibrary?: SkillLibrary,
-  config?: Partial<MCPServerConfig>
-): PlaybookMCPServer {
-  return new PlaybookMCPServer(playbooks, skillLibrary, config);
-}

package/src/memory/candidate-retrieval.ts

@@ -1,72 +0,0 @@
-/**
- * Shared candidate retrieval helper for memory stores.
- *
- * Consolidates the "inverted index narrow → fallback to full scan" pattern
- * used by ExperienceMemory, PlaybookLibrary, and CausalStore.
- */
-
-import type { InvertedIndex } from '../embeddings/inverted-index.js';
-
-/**
- * A store-like interface that can resolve items by ID or return all values.
- */
-export interface ItemResolver<T> {
-  get(id: string): T | undefined;
-  values(): T[];
-}
-
-/**
- * Options for candidate retrieval.
- */
-export interface CandidateRetrievalOptions {
-  /** How many final results are desired */
-  k: number;
-  /** Multiplier for how many candidates to pull from the index (default: 10) */
-  candidateMultiplier?: number;
-  /** Minimum candidate pool from index (default: 50) */
-  minCandidates?: number;
-}
-
-/**
- * Retrieve candidates using an inverted index with fallback to full scan.
- *
- * This pattern is shared across multiple memory stores:
- * 1. Use the inverted index to narrow to a candidate set.
- * 2. If enough candidates are found, resolve them by ID.
- * 3. Otherwise, fall back to the provided fallback set (or full store scan).
- *
- * @param query - The text query to search with.
- * @param index - The inverted index for candidate narrowing.
- * @param resolver - Store that can resolve items by ID or return all values.
- * @param options - Retrieval options.
- * @param fallbackItems - Optional pre-filtered fallback items. If not provided,
- *   `resolver.values()` is used.
- * @returns The candidate items to score.
- */
-export function getCandidates<T>(
-  query: string,
-  index: InvertedIndex,
-  resolver: ItemResolver<T>,
-  options: CandidateRetrievalOptions,
-  fallbackItems?: T[],
-): T[] {
-  const multiplier = options.candidateMultiplier ?? 10;
-  const minCandidates = options.minCandidates ?? 50;
-  const maxCandidates = Math.max(options.k * multiplier, minCandidates);
-
-  const candidateIds = index.getCandidates(query, maxCandidates);
-
-  if (candidateIds.length >= options.k) {
-    // Enough candidates from index — resolve them
-    const items: T[] = [];
-    for (const id of candidateIds) {
-      const item = resolver.get(id);
-      if (item) items.push(item);
-    }
-    // If all IDs were stale/unresolvable, fall back to full scan
-    if (items.length > 0) return items;
-  }
-
-  // Too few candidates — fall back
-  return fallbackItems ?? resolver.values();
-}