@compilr-dev/agents 0.0.1

package/dist/tools/builtin/task.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Task Tool - LLM-controlled sub-agent spawning
+ *
+ * This tool allows the agent to spawn specialized sub-agents for complex tasks.
+ * It implements the "Hybrid" approach where both programmatic and LLM-controlled
+ * sub-agent spawning are supported.
+ *
+ * Enhanced features:
+ * - Context inheritance modes (isolated, inherit, inherit-summary)
+ * - Thoroughness levels for exploration agents
+ * - Tool inheritance & filtering
+ * - Event streaming from sub-agents
+ * - Extended built-in agent types
+ */
+import type { Tool } from '../types.js';
+import type { Agent, AgentEvent } from '../../agent.js';
+import type { LLMProvider } from '../../providers/types.js';
+/**
+ * Context inheritance mode for sub-agents
+ */
+export type ContextMode = 'isolated' | 'inherit' | 'inherit-summary';
+/**
+ * Thoroughness level for exploration agents
+ */
+export type ThoroughnessLevel = 'quick' | 'medium' | 'thorough';
+/**
+ * Input parameters for task tool
+ */
+export interface TaskInput {
+    /**
+     * A short (3-5 word) description of the task
+     */
+    description: string;
+    /**
+     * Detailed task prompt for the sub-agent to perform
+     */
+    prompt: string;
+    /**
+     * The type of specialized agent to use (e.g., 'explore', 'code-review', 'general')
+     */
+    subagent_type: string;
+    /**
+     * Optional model to use for this agent (e.g., 'sonnet', 'opus', 'haiku')
+     */
+    model?: string;
+    /**
+     * Context inheritance mode (default: from agent type config)
+     * - 'isolated': Fresh context, no parent history
+     * - 'inherit': Receives parent's full message history
+     * - 'inherit-summary': Receives summarized parent context
+     */
+    context_mode?: ContextMode;
+    /**
+     * Thoroughness level for exploration agents (default: 'medium')
+     * - 'quick': Fast searches, basic analysis
+     * - 'medium': Balanced depth and speed
+     * - 'thorough': Comprehensive analysis, multiple passes
+     */
+    thoroughness?: ThoroughnessLevel;
+}
+/**
+ * Result of task tool execution
+ */
+export interface TaskResult {
+    /**
+     * The sub-agent's response
+     */
+    response: string;
+    /**
+     * The agent type that was used
+     */
+    agentType: string;
+    /**
+     * Number of iterations the sub-agent took
+     */
+    iterations: number;
+    /**
+     * Tool calls made by the sub-agent
+     */
+    toolCalls: number;
+}
+/**
+ * Configuration for a pre-defined agent type
+ */
+export interface AgentTypeConfig {
+    /**
+     * Description of what this agent type does
+     */
+    description: string;
+    /**
+     * System prompt for this agent type
+     */
+    systemPrompt?: string;
+    /**
+     * Tools available to this agent type (tool names or Tool instances)
+     */
+    tools?: (string | Tool)[];
+    /**
+     * Skills available to this agent type
+     */
+    skills?: string[];
+    /**
+     * Maximum iterations for this agent type
+     */
+    maxIterations?: number;
+    /**
+     * Default model for this agent type
+     */
+    defaultModel?: string;
+    /**
+     * Default context inheritance mode
+     */
+    contextMode?: ContextMode;
+    /**
+     * Whether this agent type supports thoroughness levels
+     */
+    supportsThoroughness?: boolean;
+    /**
+     * Tool inheritance mode:
+     * - 'none': Only use tools specified in this config
+     * - 'all': Inherit all parent tools plus config tools
+     * - 'filter': Inherit parent tools filtered by allowedTools/deniedTools
+     */
+    toolInheritance?: 'none' | 'all' | 'filter';
+    /**
+     * Tool names to allow (whitelist) when toolInheritance is 'filter'
+     */
+    allowedTools?: string[];
+    /**
+     * Tool names to deny (blacklist) when toolInheritance is 'filter'
+     */
+    deniedTools?: string[];
+}
+/**
+ * Sub-agent event with source information
+ */
+export interface SubAgentEventInfo {
+    /**
+     * Name of the sub-agent that emitted this event
+     */
+    agentName: string;
+    /**
+     * Type of the sub-agent
+     */
+    agentType: string;
+    /**
+     * The original event from the sub-agent
+     */
+    event: AgentEvent;
+}
+/**
+ * Options for creating a task tool
+ */
+export interface TaskToolOptions {
+    /**
+     * The parent agent that will spawn sub-agents
+     */
+    parentAgent: Agent;
+    /**
+     * Available agent types and their configurations
+     */
+    agentTypes: Record<string, AgentTypeConfig>;
+    /**
+     * Provider factory for creating sub-agent providers
+     * Called with model name, returns LLM provider
+     */
+    providerFactory?: (model: string) => LLMProvider;
+    /**
+     * Maximum concurrent sub-agents (default: 3)
+     */
+    maxConcurrent?: number;
+    /**
+     * Default timeout for sub-agent execution in ms (default: 300000 = 5 min)
+     */
+    defaultTimeout?: number;
+    /**
+     * Called when a sub-agent is spawned
+     */
+    onSpawn?: (agentType: string, description: string) => void;
+    /**
+     * Called when a sub-agent completes
+     */
+    onComplete?: (agentType: string, result: TaskResult) => void;
+    /**
+     * Called when a sub-agent emits an event (for real-time streaming)
+     * Only called if enableEventStreaming is true
+     */
+    onSubAgentEvent?: (eventInfo: SubAgentEventInfo) => void;
+    /**
+     * Enable event streaming from sub-agents (default: false)
+     * When enabled, sub-agent events are forwarded to onSubAgentEvent
+     */
+    enableEventStreaming?: boolean;
+}
+/**
+ * Create a task tool for LLM-controlled sub-agent spawning
+ */
+export declare function createTaskTool(options: TaskToolOptions): Tool<TaskInput>;
+/**
+ * Default agent type configurations
+ */
+export declare const defaultAgentTypes: Record<string, AgentTypeConfig>;

package/dist/tools/builtin/task.js

@@ -0,0 +1,350 @@
+/**
+ * Task Tool - LLM-controlled sub-agent spawning
+ *
+ * This tool allows the agent to spawn specialized sub-agents for complex tasks.
+ * It implements the "Hybrid" approach where both programmatic and LLM-controlled
+ * sub-agent spawning are supported.
+ *
+ * Enhanced features:
+ * - Context inheritance modes (isolated, inherit, inherit-summary)
+ * - Thoroughness levels for exploration agents
+ * - Tool inheritance & filtering
+ * - Event streaming from sub-agents
+ * - Extended built-in agent types
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+/**
+ * Map our context mode to agent's context mode
+ */
+function mapContextMode(mode) {
+    switch (mode) {
+        case 'isolated':
+            return 'isolated';
+        case 'inherit':
+            return 'shared';
+        case 'inherit-summary':
+            return 'inherited';
+        default:
+            return 'isolated';
+    }
+}
+/**
+ * Get thoroughness-adjusted max iterations and system prompt suffix
+ */
+function getThoroughnessConfig(level, baseIterations) {
+    switch (level) {
+        case 'quick':
+            return {
+                maxIterations: Math.min(baseIterations, 5),
+                promptSuffix: '\n\nBe efficient - do quick searches and return findings promptly. ' +
+                    'Avoid deep dives unless absolutely necessary.',
+            };
+        case 'medium':
+            return {
+                maxIterations: baseIterations,
+                promptSuffix: '',
+            };
+        case 'thorough':
+            return {
+                maxIterations: Math.max(baseIterations, 25),
+                promptSuffix: '\n\nBe thorough - check multiple locations, consider different naming conventions, ' +
+                    'and verify findings from multiple angles. Take your time to be comprehensive.',
+            };
+        default:
+            return { maxIterations: baseIterations, promptSuffix: '' };
+    }
+}
+/**
+ * Create a task tool for LLM-controlled sub-agent spawning
+ */
+export function createTaskTool(options) {
+    const { parentAgent, agentTypes, providerFactory, maxConcurrent = 3, defaultTimeout = 300000, onSpawn, onComplete, onSubAgentEvent, enableEventStreaming = false, } = options;
+    // Track active sub-agents
+    let activeCount = 0;
+    // Build description of available agent types
+    const agentTypeDescriptions = Object.entries(agentTypes)
+        .map(([name, config]) => {
+        let desc = `- ${name}: ${config.description}`;
+        if (config.supportsThoroughness) {
+            desc += ' (supports thoroughness: quick/medium/thorough)';
+        }
+        return desc;
+    })
+        .join('\n');
+    return defineTool({
+        name: 'task',
+        description: 'Launch a specialized sub-agent to handle complex, multi-step tasks autonomously. ' +
+            'Use this when a task requires focused work that would benefit from delegation.\n\n' +
+            'Available agent types:\n' +
+            agentTypeDescriptions,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                description: {
+                    type: 'string',
+                    description: 'A short (3-5 word) description of the task',
+                },
+                prompt: {
+                    type: 'string',
+                    description: 'Detailed task prompt for the sub-agent. Include all context needed ' +
+                        'and specify exactly what information should be returned.',
+                },
+                subagent_type: {
+                    type: 'string',
+                    description: `The type of agent to use. Available: ${Object.keys(agentTypes).join(', ')}`,
+                },
+                model: {
+                    type: 'string',
+                    description: 'Optional model override. Use "haiku" for quick tasks, ' +
+                        '"sonnet" for standard tasks, "opus" for complex tasks.',
+                },
+                context_mode: {
+                    type: 'string',
+                    enum: ['isolated', 'inherit', 'inherit-summary'],
+                    description: 'Context inheritance: "isolated" (fresh), "inherit" (full parent history), ' +
+                        '"inherit-summary" (summarized parent context)',
+                },
+                thoroughness: {
+                    type: 'string',
+                    enum: ['quick', 'medium', 'thorough'],
+                    description: 'Thoroughness level for exploration agents: "quick" (fast), ' +
+                        '"medium" (balanced), "thorough" (comprehensive)',
+                },
+            },
+            required: ['description', 'prompt', 'subagent_type'],
+        },
+        execute: async (input) => {
+            const { description, prompt, subagent_type, model, context_mode, thoroughness = 'medium', } = input;
+            // Validate agent type exists
+            if (!Object.hasOwn(agentTypes, subagent_type)) {
+                return createErrorResult(`Unknown agent type: '${subagent_type}'. ` +
+                    `Available types: ${Object.keys(agentTypes).join(', ')}`);
+            }
+            const agentConfig = agentTypes[subagent_type];
+            // Check concurrent limit
+            if (activeCount >= maxConcurrent) {
+                return createErrorResult(`Maximum concurrent sub-agents (${String(maxConcurrent)}) reached. ` +
+                    `Wait for existing tasks to complete.`);
+            }
+            // Notify spawn
+            if (onSpawn) {
+                onSpawn(subagent_type, description);
+            }
+            activeCount++;
+            try {
+                // Note: Sub-agents currently use the parent's provider
+                // Future enhancement: support model switching via providerFactory
+                void model; // Model parameter reserved for future use
+                void providerFactory; // Provider factory reserved for future use
+                // Create sub-agent using parent's method
+                const subAgentName = `task-${subagent_type}-${String(Date.now())}`;
+                // Determine context mode (input overrides config default)
+                const effectiveContextMode = context_mode ?? agentConfig.contextMode ?? 'isolated';
+                // Get thoroughness adjustments if supported
+                const baseIterations = agentConfig.maxIterations ?? 10;
+                const { maxIterations, promptSuffix } = agentConfig.supportsThoroughness
+                    ? getThoroughnessConfig(thoroughness, baseIterations)
+                    : { maxIterations: baseIterations, promptSuffix: '' };
+                // Build system prompt with thoroughness suffix
+                const systemPrompt = agentConfig.systemPrompt
+                    ? agentConfig.systemPrompt + promptSuffix
+                    : promptSuffix.trim() || undefined;
+                // Use parent's sub-agent system
+                parentAgent.createSubAgent({
+                    name: subAgentName,
+                    description: description,
+                    systemPrompt: systemPrompt,
+                    maxIterations: maxIterations,
+                    contextMode: mapContextMode(effectiveContextMode),
+                    // Tools would be configured based on agentConfig.tools and toolInheritance
+                });
+                // Run the sub-agent with timeout
+                const timeoutPromise = new Promise((_, reject) => {
+                    const timer = setTimeout(() => {
+                        reject(new Error(`Sub-agent timed out after ${String(defaultTimeout)}ms`));
+                    }, defaultTimeout);
+                    // Ensure timer doesn't prevent process exit
+                    if (typeof timer.unref === 'function') {
+                        timer.unref();
+                    }
+                });
+                // Set up event handler for streaming if enabled
+                let eventHandler;
+                if (enableEventStreaming && onSubAgentEvent) {
+                    eventHandler = (event) => {
+                        onSubAgentEvent({
+                            agentName: subAgentName,
+                            agentType: subagent_type,
+                            event,
+                        });
+                    };
+                }
+                const resultPromise = parentAgent.runSubAgent(subAgentName, prompt, {
+                    onEvent: eventHandler,
+                });
+                const result = await Promise.race([resultPromise, timeoutPromise]);
+                // Cleanup
+                parentAgent.disposeSubAgent(subAgentName);
+                const taskResult = {
+                    response: result.response,
+                    agentType: subagent_type,
+                    iterations: result.iterations,
+                    toolCalls: result.toolCalls.length,
+                };
+                // Notify completion
+                if (onComplete) {
+                    onComplete(subagent_type, taskResult);
+                }
+                return createSuccessResult(taskResult);
+            }
+            catch (error) {
+                return createErrorResult(`Sub-agent failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            finally {
+                activeCount--;
+            }
+        },
+    });
+}
+/**
+ * Default agent type configurations
+ */
+export const defaultAgentTypes = {
+    explore: {
+        description: 'Fast agent for exploring codebases. Use for finding files, ' +
+            'searching code, or answering questions about code structure.',
+        systemPrompt: 'You are a codebase exploration agent. Your task is to efficiently ' +
+            'search and analyze code to answer questions. Use glob and grep tools ' +
+            'to find relevant files, then read them to understand the code. ' +
+            'Be thorough but efficient. Return a clear, concise summary of your findings.',
+        maxIterations: 15,
+        defaultModel: 'haiku',
+        contextMode: 'inherit-summary',
+        supportsThoroughness: true,
+        toolInheritance: 'filter',
+        allowedTools: ['glob', 'grep', 'read'],
+    },
+    'code-review': {
+        description: 'Agent specialized for reviewing code changes. Use after writing ' +
+            'significant code to check for issues.',
+        systemPrompt: 'You are a code review agent. Analyze the provided code for:\n' +
+            '1. Bugs and potential issues\n' +
+            '2. Security vulnerabilities\n' +
+            '3. Performance concerns\n' +
+            '4. Code style and best practices\n' +
+            'Provide specific, actionable feedback with file and line references.',
+        maxIterations: 10,
+        defaultModel: 'sonnet',
+        contextMode: 'inherit-summary',
+        supportsThoroughness: false,
+        toolInheritance: 'filter',
+        allowedTools: ['glob', 'grep', 'read'],
+    },
+    general: {
+        description: 'General-purpose agent for complex multi-step tasks. Use when ' +
+            'other specialized types do not fit.',
+        systemPrompt: 'You are a general-purpose agent. Complete the task thoroughly and ' +
+            'report back with a clear summary of what you accomplished.',
+        maxIterations: 20,
+        defaultModel: 'sonnet',
+        contextMode: 'isolated',
+        supportsThoroughness: false,
+        toolInheritance: 'all',
+    },
+    plan: {
+        description: 'Planning agent for breaking down complex tasks. Use to create ' +
+            'implementation plans before coding.',
+        systemPrompt: 'You are a planning agent. Analyze the task and create a detailed ' +
+            'implementation plan with specific steps. Consider edge cases, ' +
+            'dependencies, and potential issues. Output a structured plan.',
+        maxIterations: 10,
+        defaultModel: 'sonnet',
+        contextMode: 'inherit-summary',
+        supportsThoroughness: false,
+        toolInheritance: 'filter',
+        allowedTools: ['glob', 'grep', 'read'],
+    },
+    'test-runner': {
+        description: 'Agent for running and analyzing tests. Use to run test suites, ' +
+            'analyze failures, and suggest fixes.',
+        systemPrompt: 'You are a test runner agent. Your tasks include:\n' +
+            '1. Running test suites and capturing output\n' +
+            '2. Analyzing test failures and identifying root causes\n' +
+            '3. Suggesting fixes for failing tests\n' +
+            '4. Verifying fixes by re-running tests\n' +
+            'Report test results clearly and provide actionable suggestions.',
+        maxIterations: 15,
+        defaultModel: 'sonnet',
+        contextMode: 'inherit-summary',
+        supportsThoroughness: true,
+        toolInheritance: 'filter',
+        allowedTools: ['bash', 'glob', 'grep', 'read'],
+    },
+    'doc-lookup': {
+        description: 'Agent for searching documentation and APIs. Use to find ' +
+            'documentation, understand APIs, or research technical topics.',
+        systemPrompt: 'You are a documentation lookup agent. Your tasks include:\n' +
+            '1. Searching for relevant documentation\n' +
+            '2. Finding API references and usage examples\n' +
+            '3. Explaining complex concepts clearly\n' +
+            '4. Providing code examples when helpful\n' +
+            'Return well-organized, easy-to-understand information.',
+        maxIterations: 10,
+        defaultModel: 'haiku',
+        contextMode: 'isolated',
+        supportsThoroughness: true,
+        toolInheritance: 'filter',
+        allowedTools: ['webFetch', 'glob', 'grep', 'read'],
+    },
+    refactor: {
+        description: 'Agent for refactoring code safely. Use for renaming, extracting, ' +
+            'or restructuring code while maintaining behavior.',
+        systemPrompt: 'You are a refactoring agent. Your tasks include:\n' +
+            '1. Identifying code that needs refactoring\n' +
+            '2. Planning safe refactoring steps\n' +
+            '3. Implementing changes incrementally\n' +
+            '4. Verifying behavior is preserved\n' +
+            'Always prefer small, incremental changes. Report what was changed.',
+        maxIterations: 20,
+        defaultModel: 'sonnet',
+        contextMode: 'inherit-summary',
+        supportsThoroughness: false,
+        toolInheritance: 'filter',
+        allowedTools: ['glob', 'grep', 'read', 'edit', 'write'],
+        deniedTools: ['bash'],
+    },
+    'security-audit': {
+        description: 'Agent for security auditing code. Use to scan for vulnerabilities, ' +
+            'check dependencies, and identify security issues.',
+        systemPrompt: 'You are a security audit agent. Analyze code for:\n' +
+            '1. OWASP Top 10 vulnerabilities\n' +
+            '2. Injection attacks (SQL, XSS, command injection)\n' +
+            '3. Authentication and authorization issues\n' +
+            '4. Sensitive data exposure\n' +
+            '5. Insecure dependencies\n' +
+            '6. Configuration issues\n' +
+            'Provide severity ratings and remediation steps for each finding.',
+        maxIterations: 15,
+        defaultModel: 'sonnet',
+        contextMode: 'isolated',
+        supportsThoroughness: true,
+        toolInheritance: 'filter',
+        allowedTools: ['glob', 'grep', 'read', 'bash'],
+    },
+    debug: {
+        description: 'Agent for debugging issues. Use to investigate bugs, analyze ' +
+            'error logs, and find root causes.',
+        systemPrompt: 'You are a debugging agent. Your approach:\n' +
+            '1. Gather information about the issue\n' +
+            '2. Form hypotheses about root causes\n' +
+            '3. Test hypotheses systematically\n' +
+            '4. Identify the root cause\n' +
+            '5. Suggest or implement fixes\n' +
+            'Document your reasoning and findings clearly.',
+        maxIterations: 20,
+        defaultModel: 'sonnet',
+        contextMode: 'inherit',
+        supportsThoroughness: true,
+        toolInheritance: 'all',
+    },
+};