ak-claude 0.0.2 → 0.0.5

package/GUIDE.md

@@ -430,6 +430,22 @@ const agent = new ToolAgent({
 });
 ```
 
+### Parallel Tool Execution
+
+Control whether tool calls within a round execute in parallel or sequentially:
+
+```javascript
+const agent = new ToolAgent({
+  tools: [...],
+  toolExecutor: myExecutor,
+  parallelToolCalls: true,   // default: unlimited parallel execution
+  // parallelToolCalls: false, // sequential execution
+  // parallelToolCalls: 3,    // max 3 concurrent tool executions
+});
+```
+
+When the model returns multiple tool calls in a single response, parallel execution runs them concurrently — significantly faster for I/O-bound tools (HTTP requests, database queries, etc.).
+
 ### Streaming
 
 Stream the agent's output in real-time --- useful for showing progress in a UI:

package/README.md

@@ -561,6 +561,7 @@ All classes (except AgentQuery) accept `BaseClaudeOptions`:
 | `onBeforeExecution` | function | — | `async (toolName, args) => boolean` — gate execution |
 | `toolChoice` | object | — | Tool choice config (`auto`, `any`, `tool`, `none`) |
 | `disableParallelToolUse` | boolean | `false` | Force sequential tool calls |
+| `parallelToolCalls` | boolean \| number | `true` | Parallel tool execution: `false` = sequential, `true` = unlimited, number = concurrency limit |
 
 ### CodeAgent-Specific
 

package/index.cjs

@@ -1280,7 +1280,7 @@ No markdown code blocks, no preamble text.`;
     };
     if (this._isStructured) {
       try {
-        if (this._responseSchema) {
+        if (this._responseSchema && !this.vertexai) {
           result.data = JSON.parse(text);
         } else {
           result.data = extractJSON(text);
@@ -1309,6 +1309,24 @@ No markdown code blocks, no preamble text.`;
 var message_default = Message;
 
 // tool-agent.js
+async function runWithConcurrency(tasks, concurrency) {
+  if (concurrency === Infinity) return Promise.all(tasks.map((t) => t()));
+  if (concurrency === 1) {
+    const results2 = [];
+    for (const t of tasks) results2.push(await t());
+    return results2;
+  }
+  const results = new Array(tasks.length);
+  let next = 0;
+  async function worker() {
+    while (next < tasks.length) {
+      const i = next++;
+      results[i] = await tasks[i]();
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, tasks.length) }, () => worker()));
+  return results;
+}
 var ToolAgent = class extends base_default {
   /**
    * @param {ToolAgentOptions} [options={}]
@@ -1332,6 +1350,8 @@ var ToolAgent = class extends base_default {
     }
     this.toolChoice = options.toolChoice ?? void 0;
     this.disableParallelToolUse = options.disableParallelToolUse ?? false;
+    this.parallelToolCalls = options.parallelToolCalls ?? true;
+    this._concurrency = this.parallelToolCalls === true ? Infinity : this.parallelToolCalls === false ? 1 : this.parallelToolCalls;
     this.maxToolRounds = options.maxToolRounds || 10;
     this.onToolCall = options.onToolCall || null;
     this.onBeforeExecution = options.onBeforeExecution || null;
@@ -1373,8 +1393,7 @@ var ToolAgent = class extends base_default {
       if (response.stop_reason !== "tool_use") break;
       const toolUseBlocks = response.content.filter((b) => b.type === "tool_use");
       if (toolUseBlocks.length === 0) break;
-      const toolResults = [];
-      for (const block of toolUseBlocks) {
+      const tasks = toolUseBlocks.map((block) => async () => {
         if (this.onToolCall) {
           try {
             this.onToolCall(block.name, block.input);
@@ -1387,13 +1406,7 @@ var ToolAgent = class extends base_default {
             const allowed = await this.onBeforeExecution(block.name, block.input);
             if (allowed === false) {
               const result2 = { error: "Execution denied by onBeforeExecution callback" };
-              allToolCalls.push({ name: block.name, args: block.input, result: result2 });
-              toolResults.push({
-                type: "tool_result",
-                tool_use_id: block.id,
-                content: JSON.stringify(result2)
-              });
-              continue;
+              return { toolCall: { name: block.name, args: block.input, result: result2 }, toolResult: { type: "tool_result", tool_use_id: block.id, content: JSON.stringify(result2) } };
             }
           } catch (e) {
             logger_default.warn(`onBeforeExecution callback error: ${e.message}`);
@@ -1406,13 +1419,14 @@ var ToolAgent = class extends base_default {
           logger_default.warn(`Tool ${block.name} failed: ${err.message}`);
           result = { error: err.message };
         }
-        allToolCalls.push({ name: block.name, args: block.input, result });
-        toolResults.push({
-          type: "tool_result",
-          tool_use_id: block.id,
-          content: typeof result === "string" ? result : JSON.stringify(result)
-        });
-      }
+        return {
+          toolCall: { name: block.name, args: block.input, result },
+          toolResult: { type: "tool_result", tool_use_id: block.id, content: typeof result === "string" ? result : JSON.stringify(result) }
+        };
+      });
+      const results = await runWithConcurrency(tasks, this._concurrency);
+      const toolResults = results.map((r) => r.toolResult);
+      for (const r of results) allToolCalls.push(r.toolCall);
       response = await this._sendMessage(toolResults, { tools: this.tools, ...toolChoice && { tool_choice: toolChoice } });
     }
     this._cumulativeUsage = {
@@ -1472,43 +1486,88 @@ var ToolAgent = class extends base_default {
         return;
       }
       const toolResults = [];
-      for (const block of toolUseBlocks) {
-        if (this._stopped) break;
-        yield { type: "tool_call", toolName: block.name, args: block.input };
-        if (this.onToolCall) {
-          try {
-            this.onToolCall(block.name, block.input);
-          } catch (e) {
-            logger_default.warn(`onToolCall callback error: ${e.message}`);
+      if (this._concurrency === 1) {
+        for (const block of toolUseBlocks) {
+          if (this._stopped) break;
+          yield { type: "tool_call", toolName: block.name, args: block.input };
+          if (this.onToolCall) {
+            try {
+              this.onToolCall(block.name, block.input);
+            } catch (e) {
+              logger_default.warn(`onToolCall callback error: ${e.message}`);
+            }
           }
-        }
-        let denied = false;
-        if (this.onBeforeExecution) {
-          try {
-            const allowed = await this.onBeforeExecution(block.name, block.input);
-            if (allowed === false) denied = true;
-          } catch (e) {
-            logger_default.warn(`onBeforeExecution callback error: ${e.message}`);
+          let denied = false;
+          if (this.onBeforeExecution) {
+            try {
+              const allowed = await this.onBeforeExecution(block.name, block.input);
+              if (allowed === false) denied = true;
+            } catch (e) {
+              logger_default.warn(`onBeforeExecution callback error: ${e.message}`);
+            }
           }
-        }
-        let result;
-        if (denied) {
-          result = { error: "Execution denied by onBeforeExecution callback" };
-        } else {
-          try {
-            result = await this.toolExecutor(block.name, block.input);
-          } catch (err) {
-            logger_default.warn(`Tool ${block.name} failed: ${err.message}`);
-            result = { error: err.message };
+          let result;
+          if (denied) {
+            result = { error: "Execution denied by onBeforeExecution callback" };
+          } else {
+            try {
+              result = await this.toolExecutor(block.name, block.input);
+            } catch (err) {
+              logger_default.warn(`Tool ${block.name} failed: ${err.message}`);
+              result = { error: err.message };
+            }
           }
+          allToolCalls.push({ name: block.name, args: block.input, result });
+          yield { type: "tool_result", toolName: block.name, result };
+          toolResults.push({
+            type: "tool_result",
+            tool_use_id: block.id,
+            content: typeof result === "string" ? result : JSON.stringify(result)
+          });
         }
-        allToolCalls.push({ name: block.name, args: block.input, result });
-        yield { type: "tool_result", toolName: block.name, result };
-        toolResults.push({
-          type: "tool_result",
-          tool_use_id: block.id,
-          content: typeof result === "string" ? result : JSON.stringify(result)
+      } else {
+        for (const block of toolUseBlocks) {
+          yield { type: "tool_call", toolName: block.name, args: block.input };
+        }
+        const tasks = toolUseBlocks.map((block) => async () => {
+          if (this.onToolCall) {
+            try {
+              this.onToolCall(block.name, block.input);
+            } catch (e) {
+              logger_default.warn(`onToolCall callback error: ${e.message}`);
+            }
+          }
+          let denied = false;
+          if (this.onBeforeExecution) {
+            try {
+              const allowed = await this.onBeforeExecution(block.name, block.input);
+              if (allowed === false) denied = true;
+            } catch (e) {
+              logger_default.warn(`onBeforeExecution callback error: ${e.message}`);
+            }
+          }
+          let result;
+          if (denied) {
+            result = { error: "Execution denied by onBeforeExecution callback" };
+          } else {
+            try {
+              result = await this.toolExecutor(block.name, block.input);
+            } catch (err) {
+              logger_default.warn(`Tool ${block.name} failed: ${err.message}`);
+              result = { error: err.message };
+            }
+          }
+          return {
+            toolCall: { name: block.name, args: block.input, result },
+            toolResult: { type: "tool_result", tool_use_id: block.id, content: typeof result === "string" ? result : JSON.stringify(result) }
+          };
         });
+        const results = await runWithConcurrency(tasks, this._concurrency);
+        for (const r of results) {
+          allToolCalls.push(r.toolCall);
+          yield { type: "tool_result", toolName: r.toolCall.name, result: r.toolCall.result };
+          toolResults.push(r.toolResult);
+        }
       }
       stream = await this._streamMessage(toolResults, { tools: this.tools, ...toolChoice && { tool_choice: toolChoice } });
     }

package/message.js

@@ -183,7 +183,7 @@ class Message extends BaseClaude {
 		// Parse structured data if configured
 		if (this._isStructured) {
 			try {
-				if (this._responseSchema) {
+				if (this._responseSchema && !this.vertexai) {
 					// Native structured output — guaranteed valid JSON
 					result.data = JSON.parse(text);
 				} else {

package/package.json

@@ -2,7 +2,7 @@
 	"name": "ak-claude",
 	"author": "ak@mixpanel.com",
 	"description": "AK's Claude AI Helper for doing... everything",
-	"version": "0.0.2",
+	"version": "0.0.5",
 	"main": "index.js",
 	"files": [
 		"index.js",

package/tool-agent.js

@@ -19,6 +19,31 @@ import log from './logger.js';
  * @typedef {import('./types').AgentStreamEvent} AgentStreamEvent
  */
 
+/**
+ * Execute async task factories with a concurrency limit.
+ * @param {Array<() => Promise<any>>} tasks
+ * @param {number} concurrency - Infinity for unlimited, 1 for sequential
+ * @returns {Promise<any[]>} Results in same order as tasks
+ */
+async function runWithConcurrency(tasks, concurrency) {
+	if (concurrency === Infinity) return Promise.all(tasks.map(t => t()));
+	if (concurrency === 1) {
+		const results = [];
+		for (const t of tasks) results.push(await t());
+		return results;
+	}
+	const results = new Array(tasks.length);
+	let next = 0;
+	async function worker() {
+		while (next < tasks.length) {
+			const i = next++;
+			results[i] = await tasks[i]();
+		}
+	}
+	await Promise.all(Array.from({ length: Math.min(concurrency, tasks.length) }, () => worker()));
+	return results;
+}
+
 /**
  * AI agent that uses user-provided tools to accomplish tasks.
  * Automatically manages the tool-use loop: when Claude decides to call
@@ -90,6 +115,13 @@ class ToolAgent extends BaseClaude {
 		this.toolChoice = options.toolChoice ?? undefined;
 		this.disableParallelToolUse = options.disableParallelToolUse ?? false;
 
+		// ── Parallel execution ──
+		this.parallelToolCalls = options.parallelToolCalls ?? true;
+		/** @private */
+		this._concurrency = this.parallelToolCalls === true ? Infinity
+			: this.parallelToolCalls === false ? 1
+			: this.parallelToolCalls;
+
 		// ── Tool loop config ──
 		this.maxToolRounds = options.maxToolRounds || 10;
 		this.onToolCall = options.onToolCall || null;
@@ -147,9 +179,8 @@ class ToolAgent extends BaseClaude {
 			const toolUseBlocks = response.content.filter(b => b.type === 'tool_use');
 			if (toolUseBlocks.length === 0) break;
 
-			// Execute tools and build tool_result content blocks
-			const toolResults = [];
-			for (const block of toolUseBlocks) {
+			// Execute tools (parallel or sequential based on _concurrency)
+			const tasks = toolUseBlocks.map(block => async () => {
 				// Fire onToolCall callback
 				if (this.onToolCall) {
 					try { this.onToolCall(block.name, block.input); }
@@ -162,13 +193,7 @@ class ToolAgent extends BaseClaude {
 						const allowed = await this.onBeforeExecution(block.name, block.input);
 						if (allowed === false) {
 							const result = { error: 'Execution denied by onBeforeExecution callback' };
-							allToolCalls.push({ name: block.name, args: block.input, result });
-							toolResults.push({
-								type: 'tool_result',
-								tool_use_id: block.id,
-								content: JSON.stringify(result)
-							});
-							continue;
+							return { toolCall: { name: block.name, args: block.input, result }, toolResult: { type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(result) } };
 						}
 					} catch (e) {
 						log.warn(`onBeforeExecution callback error: ${e.message}`);
@@ -183,14 +208,15 @@ class ToolAgent extends BaseClaude {
 					result = { error: err.message };
 				}
 
-				allToolCalls.push({ name: block.name, args: block.input, result });
+				return {
+					toolCall: { name: block.name, args: block.input, result },
+					toolResult: { type: 'tool_result', tool_use_id: block.id, content: typeof result === 'string' ? result : JSON.stringify(result) }
+				};
+			});
 
-				toolResults.push({
-					type: 'tool_result',
-					tool_use_id: block.id,
-					content: typeof result === 'string' ? result : JSON.stringify(result)
-				});
-			}
+			const results = await runWithConcurrency(tasks, this._concurrency);
+			const toolResults = results.map(r => r.toolResult);
+			for (const r of results) allToolCalls.push(r.toolCall);
 
 			// Send tool results back to Claude as user message
 			response = await this._sendMessage(toolResults, { tools: this.tools, ...(toolChoice && { tool_choice: toolChoice }) });
@@ -270,50 +296,97 @@ class ToolAgent extends BaseClaude {
 				return;
 			}
 
-			// Execute tools sequentially so we can yield events
+			// Execute tools and yield events
 			const toolResults = [];
-			for (const block of toolUseBlocks) {
-				if (this._stopped) break;
+			if (this._concurrency === 1) {
+				// Sequential: yield tool_call, execute, yield tool_result for each
+				for (const block of toolUseBlocks) {
+					if (this._stopped) break;
 
-				yield { type: 'tool_call', toolName: block.name, args: block.input };
+					yield { type: 'tool_call', toolName: block.name, args: block.input };
 
-				// Fire onToolCall callback
-				if (this.onToolCall) {
-					try { this.onToolCall(block.name, block.input); }
-					catch (e) { log.warn(`onToolCall callback error: ${e.message}`); }
-				}
+					if (this.onToolCall) {
+						try { this.onToolCall(block.name, block.input); }
+						catch (e) { log.warn(`onToolCall callback error: ${e.message}`); }
+					}
 
-				// Check onBeforeExecution gate
-				let denied = false;
-				if (this.onBeforeExecution) {
-					try {
-						const allowed = await this.onBeforeExecution(block.name, block.input);
-						if (allowed === false) denied = true;
-					} catch (e) {
-						log.warn(`onBeforeExecution callback error: ${e.message}`);
+					let denied = false;
+					if (this.onBeforeExecution) {
+						try {
+							const allowed = await this.onBeforeExecution(block.name, block.input);
+							if (allowed === false) denied = true;
+						} catch (e) {
+							log.warn(`onBeforeExecution callback error: ${e.message}`);
+						}
 					}
-				}
 
-				let result;
-				if (denied) {
-					result = { error: 'Execution denied by onBeforeExecution callback' };
-				} else {
-					try {
-						result = await this.toolExecutor(block.name, block.input);
-					} catch (err) {
-						log.warn(`Tool ${block.name} failed: ${err.message}`);
-						result = { error: err.message };
+					let result;
+					if (denied) {
+						result = { error: 'Execution denied by onBeforeExecution callback' };
+					} else {
+						try {
+							result = await this.toolExecutor(block.name, block.input);
+						} catch (err) {
+							log.warn(`Tool ${block.name} failed: ${err.message}`);
+							result = { error: err.message };
+						}
 					}
+
+					allToolCalls.push({ name: block.name, args: block.input, result });
+					yield { type: 'tool_result', toolName: block.name, result };
+
+					toolResults.push({
+						type: 'tool_result',
+						tool_use_id: block.id,
+						content: typeof result === 'string' ? result : JSON.stringify(result)
+					});
 				}
+			} else {
+				// Parallel: yield all tool_call events, execute all, yield all tool_result events
+				for (const block of toolUseBlocks) {
+					yield { type: 'tool_call', toolName: block.name, args: block.input };
+				}
+
+				const tasks = toolUseBlocks.map(block => async () => {
+					if (this.onToolCall) {
+						try { this.onToolCall(block.name, block.input); }
+						catch (e) { log.warn(`onToolCall callback error: ${e.message}`); }
+					}
+
+					let denied = false;
+					if (this.onBeforeExecution) {
+						try {
+							const allowed = await this.onBeforeExecution(block.name, block.input);
+							if (allowed === false) denied = true;
+						} catch (e) {
+							log.warn(`onBeforeExecution callback error: ${e.message}`);
+						}
+					}
 
-				allToolCalls.push({ name: block.name, args: block.input, result });
-				yield { type: 'tool_result', toolName: block.name, result };
+					let result;
+					if (denied) {
+						result = { error: 'Execution denied by onBeforeExecution callback' };
+					} else {
+						try {
+							result = await this.toolExecutor(block.name, block.input);
+						} catch (err) {
+							log.warn(`Tool ${block.name} failed: ${err.message}`);
+							result = { error: err.message };
+						}
+					}
 
-				toolResults.push({
-					type: 'tool_result',
-					tool_use_id: block.id,
-					content: typeof result === 'string' ? result : JSON.stringify(result)
+					return {
+						toolCall: { name: block.name, args: block.input, result },
+						toolResult: { type: 'tool_result', tool_use_id: block.id, content: typeof result === 'string' ? result : JSON.stringify(result) }
+					};
 				});
+
+				const results = await runWithConcurrency(tasks, this._concurrency);
+				for (const r of results) {
+					allToolCalls.push(r.toolCall);
+					yield { type: 'tool_result', toolName: r.toolCall.name, result: r.toolCall.result };
+					toolResults.push(r.toolResult);
+				}
 			}
 
 			// Send tool results back and get next stream

package/types.d.ts

@@ -203,6 +203,8 @@ export interface ToolAgentOptions extends BaseClaudeOptions {
   toolChoice?: ToolChoice;
   /** Disable parallel tool use — forces sequential tool calls (default: false) */
   disableParallelToolUse?: boolean;
+  /** Parallel tool execution: false = sequential, true = unlimited parallel, number = concurrency limit (default: true) */
+  parallelToolCalls?: boolean | number;
 }
 
 export interface LocalDataEntry {
@@ -483,6 +485,7 @@ export declare class ToolAgent extends BaseClaude {
   onBeforeExecution: ((toolName: string, args: Record<string, any>) => Promise<boolean>) | null;
   toolChoice: ToolChoice | undefined;
   disableParallelToolUse: boolean;
+  parallelToolCalls: boolean | number;
 
   chat(message: string, opts?: Record<string, any>): Promise<AgentResponse>;
   stream(message: string, opts?: Record<string, any>): AsyncGenerator<AgentStreamEvent, void, unknown>;