lynkr 9.9.1 → 9.10.0

package/src/agents/decomposition/telemetry.js

@@ -1,55 +0,0 @@
-/**
- * Decomposition telemetry + shadow mode (Phase 6).
- *
- * Appends one JSON line per decomposition decision to
- * data/decomposition-decisions.jsonl so the net token effect can be audited.
- * Because the research is clear that decomposition can COST more than it saves,
- * a shadow mode (TASK_DECOMPOSITION_SHADOW=true) runs the gate + records what it
- * WOULD have done without actually decomposing — so savings can be validated on
- * real traffic before enabling for real.
- */
-
-const fs = require("fs");
-const path = require("path");
-const logger = require("../../logger");
-
-const LOG_PATH = path.join(__dirname, "../../../data/decomposition-decisions.jsonl");
-
-function estimateTokens(text) {
-  if (typeof text !== "string") return 0;
-  return Math.ceil(text.length / 4);
-}
-
-/**
- * Rough net-savings estimate.
- * monolithic ≈ what one big context would have cost (estimated input tokens).
- * decomposed ≈ planning + Σ(subagent in+out) + synthesis.
- * Positive `savedTokens` = decomposition was cheaper.
- */
-function estimateSavings({ monolithicTokens, planUsage, dispatchStats, synthUsage }) {
-  const decomposed =
-    (planUsage?.inputTokens || 0) +
-    (planUsage?.outputTokens || 0) +
-    (dispatchStats?.inputTokens || 0) +
-    (dispatchStats?.outputTokens || 0) +
-    (synthUsage?.inputTokens || 0) +
-    (synthUsage?.outputTokens || 0);
-  return {
-    monolithicTokens: monolithicTokens || 0,
-    decomposedTokens: decomposed,
-    savedTokens: (monolithicTokens || 0) - decomposed,
-  };
-}
-
-function record(entry) {
-  const line = { timestamp: Date.now(), ...entry };
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, JSON.stringify(line) + "\n");
-  } catch (err) {
-    logger.debug({ err: err.message }, "[Decomposition] Telemetry append failed");
-  }
-  return line;
-}
-
-module.exports = { record, estimateSavings, estimateTokens, LOG_PATH };

package/src/agents/definitions/loader.js

@@ -1,653 +0,0 @@
-const fs = require("fs");
-const path = require("path");
-const yaml = require("js-yaml");
-const logger = require("../../logger");
-const Skillbook = require("../skillbook");
-
-// How often to prune low-quality learned skills. 6 hours is frequent enough to
-// keep skillbooks tidy on a long-running process but rare enough to be
-// negligible overhead. Hardcoded on purpose — not worth a config knob.
-const SKILL_PRUNE_INTERVAL_MS = 6 * 60 * 60 * 1000;
-
-class AgentDefinitionLoader {
-  constructor() {
-    this.agents = new Map();
-    this.skillbooks = new Map(); // agentType → Skillbook
-    this.initialized = false;
-    this.pruneTimer = null;
-
-    // Initialize synchronously for compatibility
-    this.loadBuiltInAgentsSync();
-    this.loadFilesystemAgents();
-
-    // Load skillbooks asynchronously (non-blocking)
-    this._loadSkillbooksAsync();
-  }
-
-  /**
-   * Async initialization of skillbooks (doesn't block constructor)
-   */
-  async _loadSkillbooksAsync() {
-    try {
-      // Load skillbooks for all built-in agents
-      const agentTypes = Array.from(this.agents.keys());
-
-      await Promise.all(
-        agentTypes.map(async (agentType) => {
-          const skillbook = await Skillbook.load(agentType);
-          this.skillbooks.set(agentType, skillbook);
-
-          // Update agent system prompt with learned skills
-          this._injectSkillsIntoPrompt(agentType);
-        })
-      );
-
-      this.initialized = true;
-
-      logger.info({
-        agentCount: this.agents.size,
-        skillbooksLoaded: this.skillbooks.size,
-        totalSkills: Array.from(this.skillbooks.values())
-          .reduce((sum, sb) => sum + sb.skills.size, 0)
-      }, "Skillbooks loaded and injected into agents");
-
-    } catch (error) {
-      logger.error({
-        error: error.message
-      }, "Failed to load skillbooks");
-    }
-  }
-
-  /**
-   * Inject learned skills into agent system prompt
-   */
-  _injectSkillsIntoPrompt(agentType) {
-    const agent = this.agents.get(agentType);
-    const skillbook = this.skillbooks.get(agentType);
-
-    if (!agent || !skillbook) return;
-
-    // Store original prompt if not already stored
-    if (!agent.originalSystemPrompt) {
-      agent.originalSystemPrompt = agent.systemPrompt;
-    }
-
-    // Get learned skills
-    const skillsSection = skillbook.formatForPrompt();
-
-    // Inject skills into prompt (prepend to agent prompt)
-    if (skillsSection) {
-      agent.systemPrompt = agent.originalSystemPrompt + "\n" + skillsSection;
-    }
-  }
-
-  /**
-   * Get skillbook for agent type
-   */
-  getSkillbook(agentType) {
-    return this.skillbooks.get(agentType);
-  }
-
-  /**
-   * Replace an agent's skillbook with a freshly-learned instance and re-inject
-   * its skills into the (in-memory) system prompt. Called by the executor after
-   * a run persists new skills, so learning takes effect within the running
-   * process instead of only after a restart. Injection rebuilds from
-   * originalSystemPrompt, so repeated calls do not duplicate the skills block.
-   */
-  setSkillbook(agentType, skillbook) {
-    if (!agentType || !skillbook) return;
-    // Match the case-insensitive key an agent is actually stored under.
-    const key = this.agents.has(agentType)
-      ? agentType
-      : Array.from(this.agents.keys()).find(
-          k => k.toLowerCase() === String(agentType).toLowerCase()
-        );
-    if (!key) return;
-
-    this.skillbooks.set(key, skillbook);
-    this._injectSkillsIntoPrompt(key);
-  }
-
-  /**
-   * Reload skillbooks and update prompts (call after learning)
-   */
-  async reloadSkillbooks() {
-    await this._loadSkillbooksAsync();
-  }
-
-  /**
-   * Prune low-quality skills from every loaded skillbook. Skillbook.prune()
-   * only drops skills that have been tried enough times to prove they don't
-   * help (default: useCount >= 3 && confidence < 0.2), so fresh skills are
-   * never removed. Persists and re-injects only the skillbooks that changed.
-   * @returns {Promise<number>} total skills pruned across all agents
-   */
-  async pruneSkillbooks() {
-    let totalPruned = 0;
-
-    for (const [agentType, skillbook] of this.skillbooks.entries()) {
-      try {
-        const pruned = skillbook.prune();
-        if (pruned > 0) {
-          await skillbook.save();
-          this._injectSkillsIntoPrompt(agentType);
-          totalPruned += pruned;
-        }
-      } catch (error) {
-        logger.warn(
-          { agentType, error: error.message },
-          "Failed to prune skillbook"
-        );
-      }
-    }
-
-    if (totalPruned > 0) {
-      logger.info({ totalPruned }, "Pruned low-quality agent skills");
-    }
-    return totalPruned;
-  }
-
-  /**
-   * Start periodic skillbook pruning. Idempotent; a non-positive interval
-   * disables pruning. The timer is unref'd so it never keeps the process alive.
-   */
-  startSkillPruning(intervalMs = SKILL_PRUNE_INTERVAL_MS) {
-    if (this.pruneTimer) return; // already running
-    if (!Number.isInteger(intervalMs) || intervalMs <= 0) {
-      logger.debug({ intervalMs }, "Skillbook pruning disabled");
-      return;
-    }
-
-    this.pruneTimer = setInterval(() => {
-      this.pruneSkillbooks().catch((error) => {
-        logger.warn({ error: error.message }, "Skillbook pruning failed");
-      });
-    }, intervalMs);
-    this.pruneTimer.unref();
-
-    logger.info({ intervalMs }, "Skillbook pruning started");
-  }
-
-  /**
-   * Stop periodic skillbook pruning (for shutdown / tests).
-   */
-  stopSkillPruning() {
-    if (this.pruneTimer) {
-      clearInterval(this.pruneTimer);
-      this.pruneTimer = null;
-    }
-  }
-
-  /**
-   * Load built-in agents (Explore, Plan, General)
-   */
-  loadBuiltInAgentsSync() {
-    // Explore Agent
-    this.agents.set("Explore", {
-      name: "Explore",
-      description: "Fast codebase exploration for finding files, searching code, and understanding architecture. MUST BE USED when user asks 'where is', 'find all', 'how does X work', or needs to search codebase.",
-      systemPrompt: `You are a fast codebase exploration agent.
-
-Your role:
-- Search codebases efficiently using Glob, Grep, Read
-- Find files, functions, patterns
-- Answer questions about code location and structure
-- Provide concise, actionable findings
-
-Tools available: Glob, Grep, Read, workspace_search, workspace_symbol_search
-
-IMPORTANT RULES:
-1. You CANNOT spawn subagents (no Task tool)
-2. Return ONLY a summary of findings (not all intermediate steps)
-3. Be efficient - aim for 5-8 tool calls maximum
-4. Include specific file paths and line numbers in your final answer
-5. When done, provide clear summary starting with "EXPLORATION COMPLETE:"
-
-Work autonomously. Do not ask questions.`,
-      allowedTools: [
-        "Glob",
-        "Grep",
-        "Read"
-      ],
-      model: "haiku", // Fast, cheap
-      maxSteps: 25, // Increased for thorough exploration
-      builtIn: true
-    });
-
-    // Plan Agent
-    this.agents.set("Plan", {
-      name: "Plan",
-      description: "Design implementation plans for features. MUST BE USED when user asks 'how should I implement', 'plan for adding', 'design approach for', or needs architectural guidance.",
-      systemPrompt: `You are an implementation planning agent.
-
-Your role:
-- Understand existing codebase architecture
-- Design step-by-step implementation plans
-- Identify files to modify
-- Consider edge cases and testing
-
-Tools available: All exploration tools
-
-IMPORTANT RULES:
-1. You CANNOT spawn subagents (no Task tool)
-2. Explore codebase first to understand patterns
-3. Create detailed, numbered implementation steps
-4. Return ONLY the final plan (not exploration details)
-5. When done, provide plan starting with "IMPLEMENTATION PLAN:"
-
-Maximum 10 exploration steps, then generate plan.
-Work autonomously. Make reasonable assumptions.`,
-      allowedTools: [
-        "Glob",
-        "Grep",
-        "Read"
-      ],
-      model: "sonnet", // Needs reasoning
-      maxSteps: 15,
-      builtIn: true
-    });
-
-    // General-Purpose Agent
-    this.agents.set("general-purpose", {
-      name: "general-purpose",
-      description: "Complex multi-step tasks requiring file modifications, refactoring, or implementing features. MUST BE USED for 'refactor', 'implement', 'add feature', 'update all', or complex changes.",
-      systemPrompt: `You are a general-purpose agent for complex tasks.
-
-Your role:
-- Execute multi-step implementations
-- Modify files, refactor code, add features
-- Use all available tools to complete tasks
-- Handle errors and adapt
-
-Tools available: ALL TOOLS (Read, Write, Edit, Bash, Glob, Grep, etc.)
-
-IMPORTANT RULES:
-1. You CANNOT spawn subagents (no Task tool)
-2. Break complex tasks into steps
-3. Execute autonomously
-4. Return ONLY summary of changes (not all tool output)
-5. When done, provide summary starting with "TASK COMPLETE:"
-
-Maximum 20 steps.
-Work autonomously. Complete the task.`,
-      allowedTools: [], // Empty = all tools allowed
-      model: "sonnet",
-      maxSteps: 20,
-      builtIn: true
-    });
-
-    // Test Agent
-    this.agents.set("Test", {
-      name: "Test",
-      description: "Write tests, fix test failures, improve test coverage. MUST BE USED for 'write tests for', 'fix failing tests', 'improve coverage', or test-related tasks.",
-      systemPrompt: `You are a test writing and fixing agent.
-
-Your role:
-- Write comprehensive unit tests
-- Fix failing tests
-- Improve test coverage
-- Use appropriate testing frameworks and patterns
-
-Tools available: Read, Write, Edit, Bash, Glob, Grep
-
-IMPORTANT RULES:
-1. You CANNOT spawn subagents (no Task tool)
-2. Explore existing tests to match style and framework
-3. Write tests that cover edge cases
-4. Run tests with Bash to verify they pass
-5. When done, provide summary starting with "TESTS COMPLETE:"
-
-Best practices:
-- Follow existing test patterns in codebase
-- Use descriptive test names
-- Test edge cases and error conditions
-- Mock external dependencies
-- Aim for clear, maintainable tests
-
-Maximum 20 steps.
-Work autonomously.`,
-      allowedTools: [
-        "Read",
-        "Write",
-        "Edit",
-        "Bash",
-        "Glob",
-        "Grep"
-      ],
-      model: "sonnet",
-      maxSteps: 20,
-      builtIn: true
-    });
-
-    // Debug Agent
-    this.agents.set("Debug", {
-      name: "Debug",
-      description: "Investigate bugs, analyze logs, find root causes. MUST BE USED for 'debug', 'why is X failing', 'investigate error', or troubleshooting tasks.",
-      systemPrompt: `You are a debugging agent specialized in finding root causes.
-
-Your role:
-- Investigate bugs systematically
-- Analyze error messages and logs
-- Trace code execution paths
-- Identify root causes
-- Suggest fixes
-
-Tools available: Read, Grep, Bash, Glob
-
-IMPORTANT RULES:
-1. You CANNOT spawn subagents (no Task tool)
-2. Form hypotheses and test them systematically
-3. Read relevant code and logs
-4. Use Grep to search for error patterns
-5. When done, provide analysis starting with "DEBUG COMPLETE:"
-
-Debugging approach:
-- Understand the error message/symptom
-- Locate relevant code
-- Trace execution path
-- Identify root cause
-- Explain findings clearly
-- Suggest specific fixes
-
-Maximum 15 steps.
-Work autonomously.`,
-      allowedTools: [
-        "Read",
-        "Grep",
-        "Bash",
-        "Glob"
-      ],
-      model: "sonnet",
-      maxSteps: 15,
-      builtIn: true
-    });
-
-    // Fix Agent
-    this.agents.set("Fix", {
-      name: "Fix",
-      description: "Fix specific bugs with minimal code changes. MUST BE USED for 'fix bug', 'fix error', 'patch', or targeted bug fixes.",
-      systemPrompt: `You are a bug fixing agent focused on surgical fixes.
-
-Your role:
-- Fix specific bugs with minimal changes
-- Preserve existing behavior
-- Make targeted, safe edits
-- Verify fixes work
-
-Tools available: Read, Edit, Bash
-
-IMPORTANT RULES:
-1. You CANNOT spawn subagents (no Task tool)
-2. Read the buggy code carefully
-3. Make minimal, surgical changes
-4. Verify fix doesn't break other code
-5. When done, provide summary starting with "FIX COMPLETE:"
-
-Fixing principles:
-- Change only what's necessary
-- Preserve surrounding code
-- Don't refactor while fixing
-- Test the fix if possible
-- Explain what you changed and why
-
-Maximum 10 steps.
-Work autonomously.`,
-      allowedTools: [
-        "Read",
-        "Edit",
-        "Bash"
-      ],
-      model: "sonnet",
-      maxSteps: 10,
-      builtIn: true
-    });
-
-    // Refactor Agent
-    this.agents.set("Refactor", {
-      name: "Refactor",
-      description: "Code refactoring, improving structure, eliminating duplication. MUST BE USED for 'refactor', 'clean up code', 'remove duplication', 'improve structure', or code quality improvements.",
-      systemPrompt: `You are a code refactoring agent focused on improving code quality.
-
-Your role:
-- Refactor code to improve structure and readability
-- Eliminate code duplication (DRY principle)
-- Improve naming and organization
-- Preserve existing behavior exactly
-- Make targeted, safe improvements
-
-Tools available: Read, Edit, Grep, Glob
-
-IMPORTANT RULES:
-1. You CANNOT spawn subagents (no Task tool)
-2. Read code carefully before refactoring
-3. PRESERVE existing behavior - no functional changes
-4. Make incremental, safe changes
-5. When done, provide summary starting with "REFACTOR COMPLETE:"
-
-Refactoring principles:
-- Keep changes minimal and focused
-- Maintain test compatibility
-- Improve readability without over-engineering
-- Extract duplicated code into functions
-- Rename variables for clarity
-- Organize code logically
-
-Maximum 15 steps.
-Work autonomously.`,
-      allowedTools: [
-        "Read",
-        "Edit",
-        "Grep",
-        "Glob"
-      ],
-      model: "sonnet",
-      maxSteps: 15,
-      builtIn: true
-    });
-
-    // Documentation Agent
-    this.agents.set("Documentation", {
-      name: "Documentation",
-      description: "Writing and updating documentation, README files, API docs. MUST BE USED for 'write docs', 'update README', 'document API', 'add comments', or documentation tasks.",
-      systemPrompt: `You are a documentation writing agent.
-
-Your role:
-- Write clear, comprehensive documentation
-- Update README files with usage examples
-- Document APIs, functions, and modules
-- Add helpful code comments where needed
-- Create user-friendly guides
-
-Tools available: Read, Write, Edit, Glob, Grep
-
-IMPORTANT RULES:
-1. You CANNOT spawn subagents (no Task tool)
-2. Read existing code to understand functionality
-3. Write clear, concise documentation
-4. Include practical examples
-5. When done, provide summary starting with "DOCUMENTATION COMPLETE:"
-
-Documentation best practices:
-- Start with purpose and overview
-- Provide clear examples
-- Document parameters and return values
-- Explain edge cases and limitations
-- Use consistent formatting
-- Keep language simple and direct
-
-Maximum 10 steps.
-Work autonomously.`,
-      allowedTools: [
-        "Read",
-        "Write",
-        "Edit",
-        "Glob",
-        "Grep"
-      ],
-      model: "haiku", // Documentation doesn't need deep reasoning
-      maxSteps: 10,
-      builtIn: true
-    });
-
-    logger.info({ count: this.agents.size }, "Loaded built-in agents");
-  }
-
-  /**
-   * Load agents from .claude/agents/*.md files
-   */
-  loadFilesystemAgents() {
-    const agentsDir = path.join(process.cwd(), ".claude", "agents");
-
-    if (!fs.existsSync(agentsDir)) {
-      logger.debug("No .claude/agents directory found, skipping filesystem agents");
-      return;
-    }
-
-    const files = fs.readdirSync(agentsDir).filter(f => f.endsWith(".md"));
-
-    for (const file of files) {
-      try {
-        const content = fs.readFileSync(path.join(agentsDir, file), "utf8");
-        const agent = this.parseAgentFile(content, file);
-
-        if (agent) {
-          // Programmatic agents take precedence over filesystem
-          if (!this.agents.has(agent.name) || !this.agents.get(agent.name).builtIn) {
-            this.agents.set(agent.name, agent);
-            logger.info({ name: agent.name, file }, "Loaded filesystem agent");
-          }
-        }
-      } catch (error) {
-        logger.warn({ file, error: error.message }, "Failed to load agent file");
-      }
-    }
-  }
-
-  /**
-   * Parse agent markdown file with YAML frontmatter
-   */
-  parseAgentFile(content, filename) {
-    const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-
-    if (!match) {
-      logger.warn({ filename }, "Agent file missing YAML frontmatter");
-      return null;
-    }
-
-    const [, frontmatter, body] = match;
-    const config = yaml.load(frontmatter);
-
-    return {
-      name: config.name || path.basename(filename, ".md"),
-      description: config.description || "",
-      systemPrompt: body.trim(),
-      allowedTools: config.tools || [],
-      model: config.model || "sonnet",
-      maxSteps: config.maxSteps || 15,
-      builtIn: false,
-      source: "filesystem"
-    };
-  }
-
-  /**
-   * Register agent programmatically (takes precedence over filesystem)
-   */
-  registerAgent(name, definition) {
-    this.agents.set(name, {
-      ...definition,
-      name,
-      builtIn: false,
-      source: "programmatic"
-    });
-    logger.info({ name }, "Registered programmatic agent");
-  }
-
-  /**
-   * Get agent definition by name
-   */
-  getAgent(name) {
-    // Case-insensitive lookup
-    const normalized = name.toLowerCase();
-    for (const [key, value] of this.agents.entries()) {
-      if (key.toLowerCase() === normalized) {
-        return value;
-      }
-    }
-    return null;
-  }
-
-  /**
-   * Get all agent definitions
-   */
-  getAllAgents() {
-    return Array.from(this.agents.values());
-  }
-
-  /**
-   * Find agent by task description (automatic delegation)
-   */
-  findAgentForTask(taskDescription) {
-    const desc = taskDescription.toLowerCase();
-
-    // Score each agent based on description match
-    let bestMatch = null;
-    let bestScore = 0;
-
-    for (const agent of this.agents.values()) {
-      const agentDesc = agent.description.toLowerCase();
-
-      // Extract keywords from agent description
-      const keywords = this.extractKeywords(agentDesc);
-
-      // Count matches
-      let score = 0;
-      for (const keyword of keywords) {
-        if (desc.includes(keyword)) {
-          score += keyword.length; // Longer keywords = higher weight
-        }
-      }
-
-      if (score > bestScore) {
-        bestScore = score;
-        bestMatch = agent;
-      }
-    }
-
-    // Require minimum score to avoid false positives
-    if (bestScore >= 5) {
-      logger.info({
-        agent: bestMatch.name,
-        score: bestScore,
-        task: taskDescription.slice(0, 50)
-      }, "Auto-selected agent for task");
-      return bestMatch;
-    }
-
-    return null;
-  }
-
-  /**
-   * Extract keywords from agent description
-   */
-  extractKeywords(description) {
-    // Extract words in quotes and common phrases
-    const keywords = [];
-
-    // Words in quotes
-    const quoted = description.match(/'([^']+)'/g) || [];
-    keywords.push(...quoted.map(q => q.replace(/'/g, "")));
-
-    // Common action words
-    const actions = ["find", "search", "implement", "plan", "refactor", "explore"];
-    for (const action of actions) {
-      if (description.includes(action)) {
-        keywords.push(action);
-      }
-    }
-
-    return keywords;
-  }
-}
-
-module.exports = AgentDefinitionLoader;