attocode 0.2.3 → 0.2.5

package/dist/src/integrations/quality/self-improvement.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Self-Improvement Protocol
+ *
+ * Diagnoses tool call failures, proposes description improvements,
+ * and connects to the existing FailureTracker and LearningStore
+ * for cross-session persistence.
+ *
+ * Key features:
+ * - Tool failure diagnosis (why did this fail?)
+ * - Improved arguments suggestion (how to fix the call)
+ * - Tool description improvements (better docs for the LLM)
+ * - Success pattern tracking
+ */
+import type { LearningStore } from './learning-store.js';
+export interface ToolCallDiagnosis {
+    /** Tool that was called */
+    toolName: string;
+    /** Original arguments that failed */
+    originalArgs: Record<string, unknown>;
+    /** The error message */
+    error: string;
+    /** Why it failed */
+    diagnosis: string;
+    /** How to fix the call */
+    suggestedFix: string;
+    /** Fixed arguments (if determinable) */
+    improvedArgs?: Record<string, unknown>;
+    /** Better tool description (if applicable) */
+    descriptionImprovement?: string;
+    /** Error category */
+    category: FailureCategory;
+}
+export type FailureCategory = 'wrong_args' | 'missing_args' | 'file_not_found' | 'permission' | 'timeout' | 'syntax_error' | 'state_error' | 'unknown';
+export interface SelfImprovementConfig {
+    /** Enable tool call diagnosis (default: true) */
+    enableDiagnosis: boolean;
+    /** Enable description improvement proposals (default: false) */
+    enableDescriptionImprovement: boolean;
+    /** Maximum diagnoses to cache (default: 50) */
+    maxDiagnosisCache: number;
+}
+export interface SuccessPattern {
+    toolName: string;
+    argPattern: Record<string, string>;
+    context: string;
+    count: number;
+}
+export declare class SelfImprovementProtocol {
+    private config;
+    private learningStore;
+    private diagnosisCache;
+    private successPatterns;
+    private failureCounts;
+    constructor(config?: Partial<SelfImprovementConfig>, learningStore?: LearningStore | null);
+    /**
+     * Diagnose why a tool call failed.
+     * Uses error pattern matching for fast diagnosis.
+     */
+    diagnoseToolFailure(toolName: string, args: Record<string, unknown>, error: string, _toolDescription?: string): ToolCallDiagnosis;
+    /**
+     * Record a successful tool call pattern.
+     */
+    recordSuccess(toolName: string, args: Record<string, unknown>, context: string): void;
+    /**
+     * Get failure count for a tool.
+     */
+    getFailureCount(toolName: string): number;
+    /**
+     * Check if a tool has been failing repeatedly (3+ times).
+     */
+    isRepeatedlyFailing(toolName: string): boolean;
+    /**
+     * Get a diagnosis-enhanced error message for the LLM.
+     * Includes the diagnosis and suggested fix alongside the error.
+     */
+    enhanceErrorMessage(toolName: string, error: string, args: Record<string, unknown>): string;
+    /**
+     * Get success patterns for a tool (useful for prompt context).
+     */
+    getSuccessPatterns(toolName: string): SuccessPattern[];
+    /**
+     * Persist a failure learning to the learning store.
+     */
+    private persistFailureLearning;
+}
+/**
+ * Create a self-improvement protocol.
+ */
+export declare function createSelfImprovementProtocol(config?: Partial<SelfImprovementConfig>, learningStore?: LearningStore | null): SelfImprovementProtocol;
+//# sourceMappingURL=self-improvement.d.ts.map

package/dist/src/integrations/quality/self-improvement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-improvement.d.ts","sourceRoot":"","sources":["../../../../src/integrations/quality/self-improvement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOzD,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,8CAA8C;IAC9C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB;IACrB,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,cAAc,GACd,gBAAgB,GAChB,YAAY,GACZ,SAAS,GACT,cAAc,GACd,aAAa,GACb,SAAS,CAAC;AAEd,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,gEAAgE;IAChE,4BAA4B,EAAE,OAAO,CAAC;IACtC,+CAA+C;IAC/C,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAiFD,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,aAAa,CAAkC;gBAGrD,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,EACvC,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI;IAMtC;;;OAGG;IACH,mBAAmB,CACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,EACb,gBAAgB,CAAC,EAAE,MAAM,GACxB,iBAAiB;IA2DpB;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAqBrF;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIzC;;OAEG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI9C;;;OAGG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAkB3F;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE;IAItD;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAiB/B;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,EACvC,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,GACnC,uBAAuB,CAEzB"}

package/dist/src/integrations/quality/self-improvement.js

@@ -0,0 +1,229 @@
+/**
+ * Self-Improvement Protocol
+ *
+ * Diagnoses tool call failures, proposes description improvements,
+ * and connects to the existing FailureTracker and LearningStore
+ * for cross-session persistence.
+ *
+ * Key features:
+ * - Tool failure diagnosis (why did this fail?)
+ * - Improved arguments suggestion (how to fix the call)
+ * - Tool description improvements (better docs for the LLM)
+ * - Success pattern tracking
+ */
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const DEFAULT_CONFIG = {
+    enableDiagnosis: true,
+    enableDescriptionImprovement: false,
+    maxDiagnosisCache: 50,
+};
+/**
+ * Common error patterns and their diagnoses.
+ */
+const ERROR_PATTERNS = [
+    {
+        pattern: /ENOENT|no such file|file not found|does not exist/i,
+        category: 'file_not_found',
+        diagnosis: 'The target file or directory does not exist',
+        fix: 'Use glob or list_files to verify the path before accessing it',
+    },
+    {
+        pattern: /EACCES|permission denied|not permitted/i,
+        category: 'permission',
+        diagnosis: 'Insufficient permissions to perform this operation',
+        fix: 'Check file permissions or try a different approach',
+    },
+    {
+        pattern: /timeout|timed out|ETIMEDOUT/i,
+        category: 'timeout',
+        diagnosis: 'The operation timed out',
+        fix: 'Try with a shorter command or increase timeout',
+    },
+    {
+        pattern: /syntax error|unexpected token|parse error/i,
+        category: 'syntax_error',
+        diagnosis: 'The command or arguments contain a syntax error',
+        fix: 'Check command syntax and argument formatting',
+    },
+    {
+        pattern: /required|missing|undefined is not/i,
+        category: 'missing_args',
+        diagnosis: 'One or more required arguments were not provided',
+        fix: 'Review the tool schema and provide all required arguments',
+    },
+    {
+        pattern: /invalid|not a valid|type error|expected.*got/i,
+        category: 'wrong_args',
+        diagnosis: 'The arguments were of the wrong type or format',
+        fix: 'Check the argument types against the tool schema',
+    },
+    {
+        pattern: /not found in file|no match|unique match/i,
+        category: 'state_error',
+        diagnosis: 'The expected content was not found (file may have changed)',
+        fix: 'Re-read the file to get current content before editing',
+    },
+    {
+        pattern: /not in.*allowlist|Command.*blocked/i,
+        category: 'permission',
+        diagnosis: 'The command is not in the sandbox allowlist',
+        fix: 'Use built-in tools instead: read_file, write_file, edit_file, glob, grep. These bypass the sandbox allowlist.',
+    },
+    {
+        pattern: /Expected string, received (array|object)/i,
+        category: 'wrong_args',
+        diagnosis: 'The content argument must be a single string, not an array or object',
+        fix: 'content must be a single string. Join lines with newlines (\\n), not an array of strings.',
+    },
+];
+// =============================================================================
+// PROTOCOL
+// =============================================================================
+export class SelfImprovementProtocol {
+    config;
+    learningStore;
+    diagnosisCache = new Map();
+    successPatterns = new Map();
+    failureCounts = new Map();
+    constructor(config, learningStore) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.learningStore = learningStore ?? null;
+    }
+    /**
+     * Diagnose why a tool call failed.
+     * Uses error pattern matching for fast diagnosis.
+     */
+    diagnoseToolFailure(toolName, args, error, _toolDescription) {
+        // Track failure count
+        const failKey = toolName;
+        const count = (this.failureCounts.get(failKey) ?? 0) + 1;
+        this.failureCounts.set(failKey, count);
+        // Match against known patterns
+        let category = 'unknown';
+        let diagnosis = 'Unable to determine the exact cause of failure';
+        let suggestedFix = 'Try a different approach or tool';
+        for (const pattern of ERROR_PATTERNS) {
+            if (pattern.pattern.test(error)) {
+                category = pattern.category;
+                diagnosis = pattern.diagnosis;
+                suggestedFix = pattern.fix;
+                break;
+            }
+        }
+        // Build improved args for specific categories
+        let improvedArgs;
+        if (category === 'file_not_found' && args.path) {
+            // Suggest using glob to find the file
+            suggestedFix = `File "${args.path}" not found. Use glob to search for similar files.`;
+        }
+        if (category === 'state_error' && toolName === 'edit_file') {
+            suggestedFix = 'Re-read the file to get current content, then retry the edit.';
+        }
+        const result = {
+            toolName,
+            originalArgs: args,
+            error,
+            diagnosis,
+            suggestedFix,
+            improvedArgs,
+            category,
+        };
+        // Cache the diagnosis
+        const cacheKey = `${toolName}:${error.slice(0, 100)}`;
+        this.diagnosisCache.set(cacheKey, result);
+        if (this.diagnosisCache.size > this.config.maxDiagnosisCache) {
+            // Remove oldest entries
+            const keys = [...this.diagnosisCache.keys()];
+            for (let i = 0; i < 10; i++) {
+                this.diagnosisCache.delete(keys[i]);
+            }
+        }
+        // Persist to learning store for cross-session learning
+        if (this.learningStore && count >= 3) {
+            this.persistFailureLearning(toolName, diagnosis, suggestedFix);
+        }
+        return result;
+    }
+    /**
+     * Record a successful tool call pattern.
+     */
+    recordSuccess(toolName, args, context) {
+        const key = `${toolName}:${Object.keys(args).sort().join(',')}`;
+        const existing = this.successPatterns.get(key);
+        if (existing) {
+            existing.count++;
+        }
+        else {
+            this.successPatterns.set(key, {
+                toolName,
+                argPattern: Object.fromEntries(Object.entries(args).map(([k, v]) => [k, typeof v])),
+                context,
+                count: 1,
+            });
+        }
+        // Reset failure count on success
+        this.failureCounts.set(toolName, 0);
+    }
+    /**
+     * Get failure count for a tool.
+     */
+    getFailureCount(toolName) {
+        return this.failureCounts.get(toolName) ?? 0;
+    }
+    /**
+     * Check if a tool has been failing repeatedly (3+ times).
+     */
+    isRepeatedlyFailing(toolName) {
+        return (this.failureCounts.get(toolName) ?? 0) >= 3;
+    }
+    /**
+     * Get a diagnosis-enhanced error message for the LLM.
+     * Includes the diagnosis and suggested fix alongside the error.
+     */
+    enhanceErrorMessage(toolName, error, args) {
+        if (!this.config.enableDiagnosis)
+            return error;
+        const diagnosis = this.diagnoseToolFailure(toolName, args, error);
+        const parts = [error];
+        if (diagnosis.diagnosis !== 'Unable to determine the exact cause of failure') {
+            parts.push(`\n[Diagnosis: ${diagnosis.diagnosis}]`);
+            parts.push(`[Suggested fix: ${diagnosis.suggestedFix}]`);
+        }
+        if (this.isRepeatedlyFailing(toolName)) {
+            parts.push(`\n[Warning: "${toolName}" has failed ${this.getFailureCount(toolName)} times. Consider using a different tool or approach.]`);
+        }
+        return parts.join('');
+    }
+    /**
+     * Get success patterns for a tool (useful for prompt context).
+     */
+    getSuccessPatterns(toolName) {
+        return [...this.successPatterns.values()].filter(p => p.toolName === toolName);
+    }
+    /**
+     * Persist a failure learning to the learning store.
+     */
+    persistFailureLearning(toolName, diagnosis, fix) {
+        try {
+            this.learningStore?.proposeLearning({
+                type: 'best_practice',
+                description: `Tool "${toolName}" failure pattern: ${diagnosis}`,
+                details: `Fix: ${fix}`,
+                categories: ['runtime'],
+                actions: [toolName],
+            });
+        }
+        catch {
+            // Learning store errors are not critical
+        }
+    }
+}
+/**
+ * Create a self-improvement protocol.
+ */
+export function createSelfImprovementProtocol(config, learningStore) {
+    return new SelfImprovementProtocol(config, learningStore);
+}
+//# sourceMappingURL=self-improvement.js.map

package/dist/src/integrations/quality/self-improvement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-improvement.js","sourceRoot":"","sources":["../../../../src/integrations/quality/self-improvement.ts"],"names":[],"mappings":"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"}

package/dist/src/integrations/quality/tool-recommendation.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool Recommendation Engine
+ *
+ * Heuristic-based tool recommendation for subagents and swarm workers.
+ * Maps task types to tool categories and analyzes task descriptions
+ * for tool-relevant keywords.
+ *
+ * Key features:
+ * - Static task-type → tool-category mappings (no LLM call needed)
+ * - Keyword analysis for MCP tool preloading
+ * - Tool filtering for subagent specialization
+ * - Custom task types fall back to a known type's tools based on capability
+ */
+import type { WorkerCapability } from '../swarm/types.js';
+export interface ToolRecommendation {
+    toolName: string;
+    relevanceScore: number;
+    reason: string;
+    source: 'builtin' | 'mcp';
+}
+export interface ToolRecommendationConfig {
+    /** Maximum tools to recommend per agent (default: 15) */
+    maxToolsPerAgent?: number;
+    /** Enable MCP tool preloading for known patterns (default: true) */
+    enablePreloading?: boolean;
+    /** Task-type to tool mapping overrides */
+    taskToolOverrides?: Record<string, string[]>;
+}
+export interface ToolCategory {
+    name: string;
+    tools: string[];
+    relevance: number;
+}
+export declare class ToolRecommendationEngine {
+    private config;
+    constructor(config?: ToolRecommendationConfig);
+    /**
+     * Recommend tools for a task based on type and description.
+     * Custom task types not in TASK_TYPE_TOOL_MAP fall back to a known type
+     * based on the custom type's capability (via TaskTypeConfig).
+     */
+    recommendTools(taskDescription: string, taskType: string, availableToolNames: string[], capability?: WorkerCapability): ToolRecommendation[];
+    /**
+     * Get MCP tool prefixes that should be preloaded for a task type.
+     */
+    getMCPPreloadPrefixes(taskDescription: string): string[];
+    /**
+     * Filter tools for an agent based on task type.
+     * Returns tool names that should be available to the agent.
+     */
+    getToolFilterForTaskType(taskType: string, availableToolNames: string[]): string[];
+    /**
+     * Infer a SubtaskType from an agent name.
+     */
+    static inferTaskType(agentName: string): string;
+}
+/**
+ * Create a tool recommendation engine with optional config.
+ */
+export declare function createToolRecommendationEngine(config?: ToolRecommendationConfig): ToolRecommendationEngine;
+//# sourceMappingURL=tool-recommendation.d.ts.map

package/dist/src/integrations/quality/tool-recommendation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-recommendation.d.ts","sourceRoot":"","sources":["../../../../src/integrations/quality/tool-recommendation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAM1D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,KAAK,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AA0HD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,MAAM,CAAqC;gBAEvC,MAAM,CAAC,EAAE,wBAAwB;IAQ7C;;;;OAIG;IACH,cAAc,CACZ,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,MAAM,EAAE,EAC5B,UAAU,CAAC,EAAE,gBAAgB,GAC5B,kBAAkB,EAAE;IAoEvB;;OAEG;IACH,qBAAqB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,EAAE;IAgBxD;;;OAGG;IACH,wBAAwB,CACtB,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,MAAM,EAAE,GAC3B,MAAM,EAAE;IAKX;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAmChD;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,CAAC,EAAE,wBAAwB,GAChC,wBAAwB,CAE1B"}

package/dist/src/integrations/quality/tool-recommendation.js

@@ -0,0 +1,268 @@
+/**
+ * Tool Recommendation Engine
+ *
+ * Heuristic-based tool recommendation for subagents and swarm workers.
+ * Maps task types to tool categories and analyzes task descriptions
+ * for tool-relevant keywords.
+ *
+ * Key features:
+ * - Static task-type → tool-category mappings (no LLM call needed)
+ * - Keyword analysis for MCP tool preloading
+ * - Tool filtering for subagent specialization
+ * - Custom task types fall back to a known type's tools based on capability
+ */
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/**
+ * Static mapping from subtask types to tool categories.
+ * Core heuristic: task type determines which tools are most useful.
+ */
+const TASK_TYPE_TOOL_MAP = {
+    research: [
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep', 'list_files', 'search_files', 'search_code', 'get_file_info'], relevance: 1.0 },
+        { name: 'web', tools: ['web_search'], relevance: 0.8 },
+        { name: 'file_writing', tools: ['write_file', 'edit_file'], relevance: 0.6 },
+        { name: 'bash_readonly', tools: ['bash'], relevance: 0.5 },
+        { name: 'task_coordination', tools: ['task_get', 'task_list'], relevance: 0.3 },
+    ],
+    analysis: [
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep', 'list_files', 'search_files', 'search_code'], relevance: 1.0 },
+        { name: 'bash_readonly', tools: ['bash'], relevance: 0.6 },
+        { name: 'web', tools: ['web_search'], relevance: 0.5 },
+    ],
+    design: [
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep', 'list_files'], relevance: 0.9 },
+        { name: 'file_writing', tools: ['write_file'], relevance: 0.4 },
+    ],
+    implement: [
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep', 'list_files'], relevance: 0.8 },
+        { name: 'file_writing', tools: ['write_file', 'edit_file'], relevance: 1.0 },
+        { name: 'execution', tools: ['bash'], relevance: 0.7 },
+        { name: 'task_coordination', tools: ['task_create', 'task_update', 'task_get', 'task_list'], relevance: 0.3 },
+    ],
+    test: [
+        { name: 'execution', tools: ['bash'], relevance: 1.0 },
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep'], relevance: 0.7 },
+        { name: 'file_writing', tools: ['write_file', 'edit_file'], relevance: 0.5 },
+    ],
+    refactor: [
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep', 'list_files', 'search_code'], relevance: 0.9 },
+        { name: 'file_writing', tools: ['write_file', 'edit_file'], relevance: 1.0 },
+        { name: 'execution', tools: ['bash'], relevance: 0.5 },
+    ],
+    review: [
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep', 'list_files', 'search_files'], relevance: 1.0 },
+        { name: 'file_writing', tools: ['write_file', 'edit_file'], relevance: 0.4 },
+        { name: 'bash_readonly', tools: ['bash'], relevance: 0.3 },
+    ],
+    document: [
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep'], relevance: 0.8 },
+        { name: 'file_writing', tools: ['write_file', 'edit_file'], relevance: 1.0 },
+    ],
+    integrate: [
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep'], relevance: 0.8 },
+        { name: 'file_writing', tools: ['write_file', 'edit_file'], relevance: 0.9 },
+        { name: 'execution', tools: ['bash'], relevance: 0.8 },
+    ],
+    deploy: [
+        { name: 'execution', tools: ['bash'], relevance: 1.0 },
+        { name: 'file_reading', tools: ['read_file', 'glob'], relevance: 0.5 },
+        { name: 'file_writing', tools: ['write_file', 'edit_file'], relevance: 0.4 },
+    ],
+    merge: [
+        { name: 'file_reading', tools: ['read_file', 'glob', 'grep'], relevance: 0.9 },
+        { name: 'file_writing', tools: ['write_file', 'edit_file'], relevance: 1.0 },
+        { name: 'execution', tools: ['bash'], relevance: 0.5 },
+        { name: 'task_coordination', tools: ['task_get', 'task_list'], relevance: 0.3 },
+    ],
+};
+/**
+ * Map a WorkerCapability to the closest built-in task type for tool recommendations.
+ * Used as a fallback when a custom task type isn't in TASK_TYPE_TOOL_MAP.
+ */
+const CAPABILITY_TO_TOOL_MAP_KEY = {
+    code: 'implement',
+    research: 'research',
+    review: 'review',
+    test: 'test',
+    document: 'document',
+    write: 'merge',
+};
+/**
+ * Keyword patterns that suggest specific MCP tools.
+ */
+const MCP_KEYWORD_PATTERNS = [
+    {
+        keywords: ['browser', 'screenshot', 'click', 'navigate', 'page', 'web page', 'UI test'],
+        mcpPrefix: 'mcp_playwright',
+        description: 'Playwright browser automation',
+    },
+    {
+        keywords: ['database', 'sql', 'query', 'table', 'schema'],
+        mcpPrefix: 'mcp_sqlite',
+        description: 'SQLite database operations',
+    },
+    {
+        keywords: ['documentation', 'library docs', 'api docs', 'npm package'],
+        mcpPrefix: 'mcp_context7',
+        description: 'Context7 documentation lookup',
+    },
+    {
+        keywords: ['web search', 'google', 'search online', 'look up'],
+        mcpPrefix: 'mcp_serper',
+        description: 'Web search via Serper',
+    },
+    {
+        keywords: ['github', 'pull request', 'issue', 'repository'],
+        mcpPrefix: 'mcp_github',
+        description: 'GitHub API operations',
+    },
+];
+// =============================================================================
+// ENGINE
+// =============================================================================
+export class ToolRecommendationEngine {
+    config;
+    constructor(config) {
+        this.config = {
+            maxToolsPerAgent: config?.maxToolsPerAgent ?? 15,
+            enablePreloading: config?.enablePreloading ?? true,
+            taskToolOverrides: config?.taskToolOverrides ?? {},
+        };
+    }
+    /**
+     * Recommend tools for a task based on type and description.
+     * Custom task types not in TASK_TYPE_TOOL_MAP fall back to a known type
+     * based on the custom type's capability (via TaskTypeConfig).
+     */
+    recommendTools(taskDescription, taskType, availableToolNames, capability) {
+        const recommendations = new Map();
+        const availableSet = new Set(availableToolNames);
+        // Phase 1: Task-type based recommendations
+        // For custom types not in the map, fall back to a known type via capability
+        let categories;
+        if (this.config.taskToolOverrides[taskType]) {
+            categories = [{ name: 'override', tools: this.config.taskToolOverrides[taskType], relevance: 1.0 }];
+        }
+        else if (TASK_TYPE_TOOL_MAP[taskType]) {
+            categories = TASK_TYPE_TOOL_MAP[taskType];
+        }
+        else {
+            // Custom type fallback: use capability to find closest built-in tool map
+            const fallbackType = capability
+                ? CAPABILITY_TO_TOOL_MAP_KEY[capability] ?? 'implement'
+                : 'implement';
+            categories = TASK_TYPE_TOOL_MAP[fallbackType] ?? [];
+        }
+        for (const category of categories) {
+            for (const toolName of category.tools) {
+                if (availableSet.has(toolName) && !recommendations.has(toolName)) {
+                    recommendations.set(toolName, {
+                        toolName,
+                        relevanceScore: category.relevance,
+                        reason: `${category.name} tool for ${taskType} tasks`,
+                        source: 'builtin',
+                    });
+                }
+            }
+        }
+        // Phase 2: Keyword-based MCP tool recommendations
+        const taskLower = taskDescription.toLowerCase();
+        for (const pattern of MCP_KEYWORD_PATTERNS) {
+            const matchCount = pattern.keywords.filter(kw => taskLower.includes(kw)).length;
+            if (matchCount > 0) {
+                // Find available MCP tools matching the prefix
+                for (const toolName of availableToolNames) {
+                    if (toolName.startsWith(pattern.mcpPrefix) && !recommendations.has(toolName)) {
+                        const relevance = Math.min(0.5 + matchCount * 0.15, 1.0);
+                        recommendations.set(toolName, {
+                            toolName,
+                            relevanceScore: relevance,
+                            reason: `${pattern.description} (matched: ${matchCount} keywords)`,
+                            source: 'mcp',
+                        });
+                    }
+                }
+            }
+        }
+        // Phase 3: Always include spawn_agent for complex tasks
+        if (availableSet.has('spawn_agent') && !recommendations.has('spawn_agent')) {
+            recommendations.set('spawn_agent', {
+                toolName: 'spawn_agent',
+                relevanceScore: 0.3,
+                reason: 'Available for delegation',
+                source: 'builtin',
+            });
+        }
+        // Sort by relevance and limit
+        return [...recommendations.values()]
+            .sort((a, b) => b.relevanceScore - a.relevanceScore)
+            .slice(0, this.config.maxToolsPerAgent);
+    }
+    /**
+     * Get MCP tool prefixes that should be preloaded for a task type.
+     */
+    getMCPPreloadPrefixes(taskDescription) {
+        if (!this.config.enablePreloading)
+            return [];
+        const taskLower = taskDescription.toLowerCase();
+        const prefixes = [];
+        for (const pattern of MCP_KEYWORD_PATTERNS) {
+            const matches = pattern.keywords.filter(kw => taskLower.includes(kw));
+            if (matches.length > 0) {
+                prefixes.push(pattern.mcpPrefix);
+            }
+        }
+        return prefixes;
+    }
+    /**
+     * Filter tools for an agent based on task type.
+     * Returns tool names that should be available to the agent.
+     */
+    getToolFilterForTaskType(taskType, availableToolNames) {
+        const recommendations = this.recommendTools('', taskType, availableToolNames);
+        return recommendations.map(r => r.toolName);
+    }
+    /**
+     * Infer a SubtaskType from an agent name.
+     */
+    static inferTaskType(agentName) {
+        const nameToType = {
+            researcher: 'research',
+            coder: 'implement',
+            reviewer: 'review',
+            architect: 'design',
+            debugger: 'analysis',
+            tester: 'test',
+            documenter: 'document',
+            synthesizer: 'merge',
+            writer: 'document',
+            merger: 'merge',
+        };
+        const lower = agentName.toLowerCase();
+        if (nameToType[lower]) {
+            return nameToType[lower];
+        }
+        // Dynamic swarm names like "swarm-coder-task-1" should resolve by role token.
+        const tokens = lower.split(/[^a-z0-9]+/).filter(Boolean);
+        for (const token of tokens) {
+            if (nameToType[token]) {
+                return nameToType[token];
+            }
+        }
+        // For swarm workers, default to implementation rather than research so
+        // write-capable profiles are selected unless explicitly constrained.
+        if (lower.startsWith('swarm-')) {
+            return 'implement';
+        }
+        return 'research';
+    }
+}
+/**
+ * Create a tool recommendation engine with optional config.
+ */
+export function createToolRecommendationEngine(config) {
+    return new ToolRecommendationEngine(config);
+}
+//# sourceMappingURL=tool-recommendation.js.map