lynkr 1.0.0 → 2.0.0

package/src/agents/reflector.js

@@ -0,0 +1,321 @@
+const logger = require("../logger");
+
+/**
+ * Reflector - Analyzes agent executions and extracts sophisticated patterns
+ * Inspired by ACE framework's Reflector role
+ */
+class Reflector {
+  /**
+   * Reflect on execution and generate skill recommendations
+   * @param {Object} context - Execution context
+   * @param {boolean} successful - Whether execution succeeded
+   * @returns {Array} - Array of skill objects
+   */
+  static reflect(context, successful) {
+    const skills = [];
+
+    // Skip trivial executions
+    if (context.steps < 2) {
+      return skills;
+    }
+
+    // Analyze tool usage patterns
+    const toolPatterns = this._analyzeToolUsage(context);
+    skills.push(...toolPatterns);
+
+    // Analyze execution efficiency
+    const efficiencyPatterns = this._analyzeEfficiency(context, successful);
+    skills.push(...efficiencyPatterns);
+
+    // Analyze error handling
+    const errorPatterns = this._analyzeErrors(context, successful);
+    skills.push(...errorPatterns);
+
+    // Analyze task-specific patterns
+    const taskPatterns = this._analyzeTaskPatterns(context, successful);
+    skills.push(...taskPatterns);
+
+    logger.debug({
+      agentType: context.agentName,
+      skillsExtracted: skills.length,
+      successful
+    }, "Reflection complete");
+
+    return skills;
+  }
+
+  /**
+   * Analyze tool usage patterns
+   */
+  static _analyzeToolUsage(context) {
+    const patterns = [];
+    const transcript = context.transcript || [];
+
+    // Extract tool sequence
+    const toolSequence = transcript
+      .filter(entry => entry.type === "tool_call" && !entry.error)
+      .map(entry => entry.toolName);
+
+    if (toolSequence.length === 0) {
+      return patterns;
+    }
+
+    // Pattern 1: Common tool combinations
+    if (toolSequence.length >= 2) {
+      const uniqueTools = [...new Set(toolSequence)];
+      const taskType = this._inferTaskType(context.taskPrompt);
+
+      if (taskType) {
+        patterns.push({
+          pattern: `${taskType} requires ${uniqueTools.length} tools`,
+          action: `Use: ${uniqueTools.join(" → ")}`,
+          reasoning: `Observed successful sequence for ${taskType.toLowerCase()}`,
+          tools: uniqueTools,
+          confidence: 0.6
+        });
+      }
+    }
+
+    // Pattern 2: Tool repetition (indicates iteration/refinement)
+    const toolCounts = {};
+    toolSequence.forEach(tool => {
+      toolCounts[tool] = (toolCounts[tool] || 0) + 1;
+    });
+
+    const repeatedTools = Object.entries(toolCounts)
+      .filter(([_, count]) => count > 1)
+      .map(([tool, _]) => tool);
+
+    if (repeatedTools.length > 0) {
+      patterns.push({
+        pattern: "Iterative refinement needed",
+        action: `Multiple calls to: ${repeatedTools.join(", ")}`,
+        reasoning: "Task required iterative approach",
+        tools: repeatedTools,
+        confidence: 0.5
+      });
+    }
+
+    // Pattern 3: First tool used (often indicates primary approach)
+    if (toolSequence.length > 0) {
+      const firstTool = toolSequence[0];
+      const taskType = this._inferTaskType(context.taskPrompt);
+
+      if (taskType) {
+        patterns.push({
+          pattern: `Start ${taskType} with exploration`,
+          action: `Begin with ${firstTool}`,
+          reasoning: `${firstTool} is effective starting point`,
+          tools: [firstTool],
+          confidence: 0.55
+        });
+      }
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Analyze execution efficiency
+   */
+  static _analyzeEfficiency(context, successful) {
+    const patterns = [];
+
+    if (!successful) {
+      return patterns; // Only analyze successful executions for efficiency
+    }
+
+    const efficiency = context.steps / context.maxSteps;
+
+    // Pattern 1: Highly efficient (< 50% of max steps)
+    if (efficiency < 0.5) {
+      const toolsUsed = this._extractUniqueTools(context);
+
+      patterns.push({
+        pattern: "Efficient execution pattern",
+        action: `Quick resolution in ${context.steps} steps using ${toolsUsed.join(", ")}`,
+        reasoning: `Completed efficiently (${Math.round(efficiency * 100)}% of max steps)`,
+        tools: toolsUsed,
+        confidence: 0.75
+      });
+    }
+
+    // Pattern 2: Near max steps (> 80% of max)
+    if (efficiency > 0.8) {
+      patterns.push({
+        pattern: "Complex task requiring many steps",
+        action: "Consider breaking down or optimizing approach",
+        reasoning: `Used ${context.steps}/${context.maxSteps} steps - may need optimization`,
+        tools: this._extractUniqueTools(context),
+        confidence: 0.4
+      });
+    }
+
+    // Pattern 3: Token usage efficiency
+    const tokensPerStep = (context.inputTokens + context.outputTokens) / context.steps;
+    if (tokensPerStep < 1000) {
+      patterns.push({
+        pattern: "Token-efficient approach",
+        action: "Concise tool usage and responses",
+        reasoning: `Low token usage per step (~${Math.round(tokensPerStep)} tokens)`,
+        tools: [],
+        confidence: 0.6
+      });
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Analyze error handling patterns
+   */
+  static _analyzeErrors(context, successful) {
+    const patterns = [];
+    const transcript = context.transcript || [];
+
+    const errorEntries = transcript.filter(entry =>
+      entry.type === "tool_call" && entry.error
+    );
+
+    if (errorEntries.length === 0) {
+      return patterns;
+    }
+
+    // Pattern 1: Recovered from errors
+    if (successful) {
+      const failedTools = errorEntries.map(e => e.toolName);
+      const recoveryTools = transcript
+        .slice(errorEntries[errorEntries.length - 1].timestamp)
+        .filter(e => e.type === "tool_call" && !e.error)
+        .map(e => e.toolName);
+
+      patterns.push({
+        pattern: "Error recovery strategy",
+        action: `After ${failedTools[0]} fails, try ${recoveryTools[0] || "alternative approach"}`,
+        reasoning: `Successfully recovered from ${errorEntries.length} error(s)`,
+        tools: [...new Set([...failedTools, ...recoveryTools])],
+        confidence: 0.65
+      });
+    }
+
+    // Pattern 2: Failed due to errors
+    if (!successful) {
+      const failedTools = [...new Set(errorEntries.map(e => e.toolName))];
+
+      patterns.push({
+        pattern: `Avoid ${failedTools.join(", ")} for this task type`,
+        action: "Use alternative tools",
+        reasoning: `These tools failed for ${this._inferTaskType(context.taskPrompt)}`,
+        tools: failedTools,
+        confidence: 0.3
+      });
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Analyze task-specific patterns
+   */
+  static _analyzeTaskPatterns(context, successful) {
+    const patterns = [];
+
+    if (!successful) {
+      return patterns;
+    }
+
+    const taskType = this._inferTaskType(context.taskPrompt);
+    if (!taskType) {
+      return patterns;
+    }
+
+    const tools = this._extractUniqueTools(context);
+    const steps = context.steps;
+
+    // Build comprehensive task-specific pattern
+    patterns.push({
+      pattern: `${taskType} methodology`,
+      action: `Use ${tools.length} tools in sequence: ${tools.slice(0, 3).join(" → ")}${tools.length > 3 ? "..." : ""}`,
+      reasoning: `Proven approach for ${taskType.toLowerCase()} (${steps} steps, ${successful ? "success" : "failed"})`,
+      tools: tools,
+      confidence: this._calculatePatternConfidence(context, successful)
+    });
+
+    return patterns;
+  }
+
+  /**
+   * Infer task type from prompt
+   */
+  static _inferTaskType(prompt) {
+    const lower = prompt.toLowerCase();
+
+    const taskTypes = [
+      { keywords: ["find", "search", "locate", "where"], type: "Search task" },
+      { keywords: ["list", "show", "display", "enumerate"], type: "Listing task" },
+      { keywords: ["explain", "understand", "analyze", "examine"], type: "Analysis task" },
+      { keywords: ["fix", "repair", "debug", "solve"], type: "Fix task" },
+      { keywords: ["test", "verify", "check", "validate"], type: "Testing task" },
+      { keywords: ["refactor", "improve", "clean", "optimize"], type: "Refactoring task" },
+      { keywords: ["implement", "create", "add", "build"], type: "Implementation task" },
+      { keywords: ["document", "write", "describe"], type: "Documentation task" }
+    ];
+
+    for (const { keywords, type } of taskTypes) {
+      if (keywords.some(keyword => lower.includes(keyword))) {
+        return type;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract unique tools from context
+   */
+  static _extractUniqueTools(context) {
+    const transcript = context.transcript || [];
+    const toolsUsed = transcript
+      .filter(entry => entry.type === "tool_call" && !entry.error)
+      .map(entry => entry.toolName);
+
+    return [...new Set(toolsUsed)];
+  }
+
+  /**
+   * Calculate pattern confidence based on execution quality
+   */
+  static _calculatePatternConfidence(context, successful) {
+    if (!successful) {
+      return 0.25;
+    }
+
+    let confidence = 0.5;
+
+    // Boost for efficient execution
+    const efficiency = context.steps / context.maxSteps;
+    if (efficiency < 0.5) {
+      confidence += 0.2;
+    }
+
+    // Boost for no errors
+    const errorCount = (context.transcript || [])
+      .filter(e => e.type === "tool_call" && e.error).length;
+
+    if (errorCount === 0) {
+      confidence += 0.15;
+    } else {
+      confidence -= (errorCount * 0.05);
+    }
+
+    // Boost for comprehensive tool usage (2-5 tools)
+    const toolCount = this._extractUniqueTools(context).length;
+    if (toolCount >= 2 && toolCount <= 5) {
+      confidence += 0.1;
+    }
+
+    return Math.max(0.2, Math.min(0.9, confidence));
+  }
+}
+
+module.exports = Reflector;

package/src/agents/skillbook.js

@@ -0,0 +1,331 @@
+const logger = require("../logger");
+const path = require("path");
+const fs = require("fs").promises;
+
+/**
+ * Skillbook - Persistent knowledge store for agent learning
+ * Each agent type has its own skillbook that evolves with experience
+ */
+class Skillbook {
+  constructor(agentType) {
+    this.agentType = agentType;
+    this.skills = new Map(); // pattern → skill object
+    this.loaded = false;
+  }
+
+  /**
+   * Add or update a skill
+   * Uses incremental merging - doesn't replace existing knowledge
+   */
+  addSkill(skill) {
+    if (!skill.pattern || !skill.action) {
+      logger.warn({ skill }, "Invalid skill format, skipping");
+      return false;
+    }
+
+    const key = this._normalizePattern(skill.pattern);
+    const existing = this.skills.get(key);
+
+    if (existing) {
+      // Merge with existing skill
+      existing.useCount++;
+      existing.lastUsed = Date.now();
+
+      // Update confidence (weighted average)
+      const newConfidence = skill.confidence || 0.5;
+      existing.confidence = (existing.confidence * 0.7) + (newConfidence * 0.3);
+
+      // Update action if new one has higher confidence
+      if (newConfidence > existing.confidence) {
+        existing.action = skill.action;
+        existing.reasoning = skill.reasoning || existing.reasoning;
+      }
+
+      logger.debug({
+        agentType: this.agentType,
+        pattern: skill.pattern,
+        confidence: existing.confidence
+      }, "Updated existing skill");
+    } else {
+      // Add new skill
+      this.skills.set(key, {
+        pattern: skill.pattern,
+        action: skill.action,
+        reasoning: skill.reasoning || "",
+        tools: skill.tools || [],
+        confidence: skill.confidence || 0.5,
+        useCount: 1,
+        createdAt: Date.now(),
+        lastUsed: Date.now()
+      });
+
+      logger.info({
+        agentType: this.agentType,
+        pattern: skill.pattern,
+        totalSkills: this.skills.size
+      }, "Added new skill");
+    }
+
+    return true;
+  }
+
+  /**
+   * Get top N skills for context injection
+   * Sorted by: confidence * useCount * recency
+   */
+  getTopSkills(n = 5) {
+    if (this.skills.size === 0) {
+      return [];
+    }
+
+    const now = Date.now();
+    const maxAge = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+    return Array.from(this.skills.values())
+      .map(skill => {
+        // Recency factor (skills used recently are more valuable)
+        const age = now - skill.lastUsed;
+        const recencyFactor = Math.max(0.1, 1 - (age / maxAge));
+
+        // Combined score
+        const score = skill.confidence * skill.useCount * recencyFactor;
+
+        return { ...skill, score };
+      })
+      .sort((a, b) => b.score - a.score)
+      .slice(0, n)
+      .map(skill => ({
+        pattern: skill.pattern,
+        action: skill.action,
+        reasoning: skill.reasoning,
+        confidence: skill.confidence
+      }));
+  }
+
+  /**
+   * Format skills for prompt injection
+   */
+  formatForPrompt(skills = null) {
+    const topSkills = skills || this.getTopSkills(5);
+
+    if (topSkills.length === 0) {
+      return "";
+    }
+
+    const formatted = topSkills.map((skill, i) => {
+      const confidenceBar = "█".repeat(Math.round(skill.confidence * 5));
+      return `${i + 1}. ${skill.pattern}
+   → ${skill.action}
+   ${skill.reasoning ? `   Why: ${skill.reasoning}` : ''}
+   Confidence: ${confidenceBar} ${Math.round(skill.confidence * 100)}%`;
+    }).join("\n\n");
+
+    return `
+## Previously Learned Skills
+
+You've successfully used these patterns before. Consider applying them:
+
+${formatted}
+
+Apply these learnings when relevant, but don't force them if the situation differs.
+`;
+  }
+
+  /**
+   * Record when a skill is used
+   */
+  recordUsage(pattern, successful = true) {
+    const key = this._normalizePattern(pattern);
+    const skill = this.skills.get(key);
+
+    if (skill) {
+      skill.useCount++;
+      skill.lastUsed = Date.now();
+
+      // Adjust confidence based on success
+      if (successful) {
+        skill.confidence = Math.min(1.0, skill.confidence + 0.05);
+      } else {
+        skill.confidence = Math.max(0.1, skill.confidence - 0.1);
+      }
+
+      logger.debug({
+        agentType: this.agentType,
+        pattern,
+        successful,
+        newConfidence: skill.confidence
+      }, "Recorded skill usage");
+    }
+  }
+
+  /**
+   * Prune low-quality skills
+   */
+  prune(minConfidence = 0.2, minUseCount = 3) {
+    let pruned = 0;
+
+    for (const [key, skill] of this.skills.entries()) {
+      // Remove skills that have been tried multiple times but remain low confidence
+      if (skill.useCount >= minUseCount && skill.confidence < minConfidence) {
+        this.skills.delete(key);
+        pruned++;
+      }
+    }
+
+    if (pruned > 0) {
+      logger.info({
+        agentType: this.agentType,
+        pruned,
+        remaining: this.skills.size
+      }, "Pruned low-confidence skills");
+    }
+
+    return pruned;
+  }
+
+  /**
+   * Get statistics
+   */
+  getStats() {
+    const skills = Array.from(this.skills.values());
+
+    return {
+      agentType: this.agentType,
+      totalSkills: skills.length,
+      averageConfidence: skills.reduce((sum, s) => sum + s.confidence, 0) / skills.length || 0,
+      totalUses: skills.reduce((sum, s) => sum + s.useCount, 0),
+      highConfidenceSkills: skills.filter(s => s.confidence >= 0.8).length
+    };
+  }
+
+  /**
+   * Save to disk (JSON format)
+   */
+  async save() {
+    const filepath = this._getFilePath();
+
+    try {
+      // Ensure directory exists
+      const dir = path.dirname(filepath);
+      await fs.mkdir(dir, { recursive: true });
+
+      const data = {
+        agentType: this.agentType,
+        skills: Array.from(this.skills.entries()),
+        savedAt: Date.now(),
+        version: "1.0"
+      };
+
+      await fs.writeFile(filepath, JSON.stringify(data, null, 2), 'utf8');
+
+      logger.debug({
+        agentType: this.agentType,
+        filepath,
+        skillCount: this.skills.size
+      }, "Saved skillbook");
+
+      return true;
+    } catch (error) {
+      logger.error({
+        error: error.message,
+        agentType: this.agentType,
+        filepath
+      }, "Failed to save skillbook");
+      return false;
+    }
+  }
+
+  /**
+   * Load from disk
+   */
+  async load() {
+    if (this.loaded) {
+      return true; // Already loaded
+    }
+
+    const filepath = this._getFilePath();
+
+    try {
+      const content = await fs.readFile(filepath, 'utf8');
+      const data = JSON.parse(content);
+
+      if (data.agentType !== this.agentType) {
+        throw new Error(`Agent type mismatch: expected ${this.agentType}, got ${data.agentType}`);
+      }
+
+      // Restore skills map
+      this.skills = new Map(data.skills);
+      this.loaded = true;
+
+      logger.info({
+        agentType: this.agentType,
+        skillCount: this.skills.size,
+        filepath
+      }, "Loaded skillbook");
+
+      return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        // File doesn't exist yet - this is fine for new agents
+        logger.debug({
+          agentType: this.agentType,
+          filepath
+        }, "No existing skillbook found, starting fresh");
+        this.loaded = true;
+        return true;
+      }
+
+      logger.error({
+        error: error.message,
+        agentType: this.agentType,
+        filepath
+      }, "Failed to load skillbook");
+
+      this.loaded = true; // Mark as loaded to prevent retries
+      return false;
+    }
+  }
+
+  /**
+   * Clear all skills (use with caution)
+   */
+  clear() {
+    this.skills.clear();
+    logger.warn({
+      agentType: this.agentType
+    }, "Cleared skillbook");
+  }
+
+  /**
+   * Get file path for this agent's skillbook
+   */
+  _getFilePath() {
+    const dataDir = path.join(process.cwd(), 'data', 'skillbooks');
+    return path.join(dataDir, `${this.agentType.toLowerCase()}.json`);
+  }
+
+  /**
+   * Normalize pattern for consistent matching
+   */
+  _normalizePattern(pattern) {
+    return pattern.toLowerCase().trim().replace(/\s+/g, ' ');
+  }
+
+  /**
+   * Static method: Load skillbook for agent type
+   */
+  static async load(agentType) {
+    const skillbook = new Skillbook(agentType);
+    await skillbook.load();
+    return skillbook;
+  }
+
+  /**
+   * Static method: Get or create skillbook
+   */
+  static async getOrCreate(agentType) {
+    return Skillbook.load(agentType);
+  }
+}
+
+module.exports = Skillbook;