@compilr-dev/agents 0.2.1 → 0.3.1

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

@@ -143,6 +143,10 @@ export interface SubAgentEventInfo {
      * Type of the sub-agent
      */
     agentType: string;
+    /**
+     * Tool use ID for correlation with parent tool call
+     */
+    toolUseId?: string;
     /**
      * The original event from the sub-agent
      */
@@ -174,13 +178,19 @@ export interface TaskToolOptions {
      */
     defaultTimeout?: number;
     /**
-     * Called when a sub-agent is spawned
+     * Called when a sub-agent is spawned.
+     * @param agentType - The type of agent being spawned
+     * @param description - Description of the task
+     * @param toolUseId - Tool use ID for correlation (enables parallel tracking)
      */
-    onSpawn?: (agentType: string, description: string) => void;
+    onSpawn?: (agentType: string, description: string, toolUseId?: string) => void;
     /**
-     * Called when a sub-agent completes
+     * Called when a sub-agent completes.
+     * @param agentType - The type of agent that completed
+     * @param result - The task result
+     * @param toolUseId - Tool use ID for correlation (enables parallel tracking)
      */
-    onComplete?: (agentType: string, result: TaskResult) => void;
+    onComplete?: (agentType: string, result: TaskResult, toolUseId?: string) => void;
     /**
      * Called when a sub-agent emits an event (for real-time streaming)
      * Only called if enableEventStreaming is true

package/dist/tools/builtin/task.js

@@ -114,7 +114,8 @@ export function createTaskTool(options) {
             },
             required: ['description', 'prompt', 'subagent_type'],
         },
-        execute: async (input) => {
+        execute: async (input, context) => {
+            const toolUseId = context?.toolUseId;
             const { description, prompt, subagent_type, model, context_mode, thoroughness = 'medium', } = input;
             // Validate agent type exists
             if (!Object.hasOwn(agentTypes, subagent_type)) {
@@ -124,16 +125,14 @@ export function createTaskTool(options) {
             const agentConfig = agentTypes[subagent_type];
             // Check concurrent limit
             if (activeCount >= maxConcurrent) {
-                console.error(`[task-tool] BLOCKED: activeCount=${String(activeCount)}, maxConcurrent=${String(maxConcurrent)}`);
                 return createErrorResult(`Maximum concurrent sub-agents (${String(maxConcurrent)}) reached. ` +
                     `Wait for existing tasks to complete.`);
             }
-            // Notify spawn
+            // Notify spawn (include toolUseId for parallel execution tracking)
             if (onSpawn) {
-                onSpawn(subagent_type, description);
+                onSpawn(subagent_type, description, toolUseId);
             }
             activeCount++;
-            console.error(`[task-tool] SPAWN: ${subagent_type}, activeCount=${String(activeCount)}`);
             try {
                 // Note: Sub-agents currently use the parent's provider
                 // Future enhancement: support model switching via providerFactory
@@ -178,6 +177,7 @@ export function createTaskTool(options) {
                         onSubAgentEvent({
                             agentName: subAgentName,
                             agentType: subagent_type,
+                            toolUseId,
                             event,
                         });
                     };
@@ -194,21 +194,21 @@ export function createTaskTool(options) {
                     iterations: result.iterations,
                     toolCalls: result.toolCalls.length,
                 };
-                // Notify completion
+                // Notify completion (include toolUseId for parallel execution tracking)
                 if (onComplete) {
-                    onComplete(subagent_type, taskResult);
+                    onComplete(subagent_type, taskResult, toolUseId);
                 }
                 return createSuccessResult(taskResult);
             }
             catch (error) {
-                console.error(`[task-tool] ERROR: ${subagent_type}, error=${error instanceof Error ? error.message : String(error)}`);
                 return createErrorResult(`Sub-agent failed: ${error instanceof Error ? error.message : String(error)}`);
             }
             finally {
                 activeCount--;
-                console.error(`[task-tool] DONE: ${subagent_type}, activeCount=${String(activeCount)}`);
             }
         },
+        // Task tool can run in parallel since sub-agents are independent
+        parallel: true,
     });
 }
 /**

package/dist/tools/define.d.ts

@@ -22,6 +22,13 @@ export interface DefineToolOptions<T extends object> {
      * Function that executes the tool
      */
     execute: (input: T) => Promise<ToolExecutionResult>;
+    /**
+     * If true, multiple calls to this tool can execute in parallel.
+     * When the LLM requests multiple parallel-safe tools in one response,
+     * they will be executed concurrently using Promise.all.
+     * Default: false (sequential execution)
+     */
+    parallel?: boolean;
 }
 /**
  * Define a tool with type-safe input handling

package/dist/tools/define.js

@@ -32,6 +32,7 @@ export function defineTool(options) {
     return {
         definition,
         execute: options.execute,
+        parallel: options.parallel,
     };
 }
 /**

package/dist/tools/registry.d.ts

@@ -1,7 +1,7 @@
 /**
  * ToolRegistry - Manages available tools for an agent
  */
-import type { Tool, ToolDefinition, ToolRegistry as IToolRegistry, ToolExecutionResult } from './types.js';
+import type { Tool, ToolDefinition, ToolRegistry as IToolRegistry, ToolExecutionResult, ToolExecutionContext } from './types.js';
 /**
  * Options for creating a DefaultToolRegistry
  */
@@ -61,9 +61,10 @@ export declare class DefaultToolRegistry implements IToolRegistry {
      *
      * @param name - Tool name
      * @param input - Tool input parameters
+     * @param contextOrTimeout - Optional execution context or timeout override
      * @param timeoutMs - Optional timeout override (uses default if not provided)
      */
-    execute(name: string, input: Record<string, unknown>, timeoutMs?: number): Promise<ToolExecutionResult>;
+    execute(name: string, input: Record<string, unknown>, contextOrTimeout?: ToolExecutionContext | number, timeoutMs?: number): Promise<ToolExecutionResult>;
     /**
      * Execute a tool with a timeout
      */

package/dist/tools/registry.js

@@ -75,9 +75,10 @@ export class DefaultToolRegistry {
      *
      * @param name - Tool name
      * @param input - Tool input parameters
+     * @param contextOrTimeout - Optional execution context or timeout override
      * @param timeoutMs - Optional timeout override (uses default if not provided)
      */
-    async execute(name, input, timeoutMs) {
+    async execute(name, input, contextOrTimeout, timeoutMs) {
         const tool = this.tools.get(name);
         if (!tool) {
             return {
@@ -85,15 +86,27 @@ export class DefaultToolRegistry {
                 error: `Tool not found: ${name}`,
             };
         }
+        // Handle backwards compatibility: contextOrTimeout can be number (old API) or context (new API)
+        let context;
+        let explicitTimeout;
+        if (typeof contextOrTimeout === 'number') {
+            // Old API: execute(name, input, timeoutMs)
+            explicitTimeout = contextOrTimeout;
+        }
+        else {
+            // New API: execute(name, input, context?, timeoutMs?)
+            context = contextOrTimeout;
+            explicitTimeout = timeoutMs;
+        }
         // Determine timeout: explicit param > per-tool config > default
         const perToolTimeout = Object.hasOwn(this.toolTimeouts, name)
             ? this.toolTimeouts[name]
             : undefined;
-        const timeout = timeoutMs ?? perToolTimeout ?? this.defaultTimeoutMs;
+        const timeout = explicitTimeout ?? perToolTimeout ?? this.defaultTimeoutMs;
         // If timeout is 0 or negative, execute without timeout
         if (timeout <= 0) {
             try {
-                return await tool.execute(input);
+                return await tool.execute(input, context);
             }
             catch (error) {
                 return {
@@ -104,7 +117,7 @@ export class DefaultToolRegistry {
         }
         // Execute with timeout
         try {
-            return await this.executeWithTimeout(tool, name, input, timeout);
+            return await this.executeWithTimeout(tool, name, input, timeout, context);
         }
         catch (error) {
             if (error instanceof ToolTimeoutError) {
@@ -122,7 +135,7 @@ export class DefaultToolRegistry {
     /**
      * Execute a tool with a timeout
      */
-    async executeWithTimeout(tool, name, input, timeoutMs) {
+    async executeWithTimeout(tool, name, input, timeoutMs, context) {
         // Create a promise that rejects after the timeout
         const timeoutPromise = new Promise((_, reject) => {
             setTimeout(() => {
@@ -130,7 +143,7 @@ export class DefaultToolRegistry {
             }, timeoutMs);
         });
         // Race the tool execution against the timeout
-        return Promise.race([tool.execute(input), timeoutPromise]);
+        return Promise.race([tool.execute(input, context), timeoutPromise]);
     }
     /**
      * Clear all registered tools

package/dist/tools/types.d.ts

@@ -25,16 +25,40 @@ export interface ToolExecutionResult {
     result?: unknown;
     error?: string;
 }
+/**
+ * Context passed to tool execution for streaming output
+ */
+export interface ToolExecutionContext {
+    /**
+     * Callback for streaming output (e.g., bash stdout/stderr)
+     * @param output - The output text
+     * @param stream - Which stream the output came from
+     */
+    onOutput?: (output: string, stream?: 'stdout' | 'stderr') => void;
+    /**
+     * Tool use ID for correlation with events
+     */
+    toolUseId?: string;
+}
 /**
  * Tool handler function type
+ * @param input - The tool input parameters
+ * @param context - Optional execution context for streaming
  */
-export type ToolHandler<T = object> = (input: T) => Promise<ToolExecutionResult>;
+export type ToolHandler<T = object> = (input: T, context?: ToolExecutionContext) => Promise<ToolExecutionResult>;
 /**
  * Tool implementation - combines definition with handler
  */
 export interface Tool<T = object> {
     definition: ToolDefinition;
     execute: ToolHandler<T>;
+    /**
+     * If true, multiple calls to this tool can execute in parallel.
+     * When the LLM requests multiple parallel-safe tools in one response,
+     * they will be executed concurrently using Promise.all.
+     * Default: false (sequential execution)
+     */
+    parallel?: boolean;
 }
 /**
  * Tool registry for managing available tools
@@ -54,6 +78,9 @@ export interface ToolRegistry {
     getDefinitions(): ToolDefinition[];
     /**
      * Execute a tool by name with given input
+     * @param name - Tool name
+     * @param input - Tool input parameters
+     * @param context - Optional execution context for streaming
      */
-    execute(name: string, input: Record<string, unknown>): Promise<ToolExecutionResult>;
+    execute(name: string, input: Record<string, unknown>, context?: ToolExecutionContext): Promise<ToolExecutionResult>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",