@draht/agent-core 2026.3.14 → 2026.3.25

package/README.md

@@ -99,6 +99,15 @@ prompt("Read config.json")
 └─ agent_end
 ```
 
+Tool execution mode is configurable:
+
+- `parallel` (default): preflight tool calls sequentially, execute allowed tools concurrently, emit final `tool_execution_end` and `toolResult` messages in assistant source order
+- `sequential`: execute tool calls one by one, matching the historical behavior
+
+The `beforeToolCall` hook runs after `tool_execution_start` and validated argument parsing. It can block execution. The `afterToolCall` hook runs after tool execution finishes and before `tool_execution_end` and final tool result message events are emitted.
+
+When you use the `Agent` class, assistant `message_end` processing is treated as a barrier before tool preflight begins. That means `beforeToolCall` sees agent state that already includes the assistant message that requested the tool call.
+
 ### continue() Event Sequence
 
 `continue()` resumes from existing context without adding a new message. Use it for retries after errors.
@@ -159,6 +168,23 @@ const agent = new Agent({
   // Dynamic API key resolution (for expiring OAuth tokens)
   getApiKey: async (provider) => refreshToken(),
 
+  // Tool execution mode: "parallel" (default) or "sequential"
+  toolExecution: "parallel",
+
+  // Preflight each tool call after args are validated. Can block execution.
+  beforeToolCall: async ({ toolCall, args, context }) => {
+    if (toolCall.name === "bash") {
+      return { block: true, reason: "bash is disabled" };
+    }
+  },
+
+  // Postprocess each tool result before final tool events are emitted.
+  afterToolCall: async ({ toolCall, result, isError, context }) => {
+    if (!isError) {
+      return { details: { ...result.details, audited: true } };
+    }
+  },
+
   // Custom thinking budgets for token-based providers
   thinkingBudgets: {
     minimal: 128,
@@ -214,6 +240,9 @@ agent.setSystemPrompt("New prompt");
 agent.setModel(getModel("openai", "gpt-4o"));
 agent.setThinkingLevel("medium");
 agent.setTools([myTool]);
+agent.setToolExecution("sequential");
+agent.setBeforeToolCall(async ({ toolCall }) => undefined);
+agent.setAfterToolCall(async ({ toolCall, result }) => undefined);
 agent.replaceMessages(newMessages);
 agent.appendMessage(message);
 agent.clearMessages();
@@ -281,10 +310,10 @@ agent.clearAllQueues();
 
 Use clearSteeringQueue, clearFollowUpQueue, or clearAllQueues to drop queued messages.
 
-When steering messages are detected after a tool completes:
-1. Remaining tools are skipped with error results
+When steering messages are detected after a turn completes:
+1. All tool calls from the current assistant message have already finished
 2. Steering messages are injected
-3. LLM responds to the interruption
+3. The LLM responds on the next turn
 
 Follow-up messages are checked only when there are no more tool calls and no steering messages. If any are queued, they are injected and another turn runs.
 
@@ -393,6 +422,9 @@ const context: AgentContext = {
 const config: AgentLoopConfig = {
   model: getModel("openai", "gpt-4o"),
   convertToLlm: (msgs) => msgs.filter(m => ["user", "assistant", "toolResult"].includes(m.role)),
+  toolExecution: "parallel",
+  beforeToolCall: async ({ toolCall, args, context }) => undefined,
+  afterToolCall: async ({ toolCall, result, isError, context }) => undefined,
 };
 
 const userMessage = { role: "user", content: "Hello", timestamp: Date.now() };
@@ -407,6 +439,8 @@ for await (const event of agentLoopContinue(context, config)) {
 }
 ```
 
+These low-level streams are observational. They preserve event order, but they do not wait for your async event handling to settle before later producer phases continue. If you need message processing to act as a barrier before tool preflight, use the `Agent` class instead of raw `agentLoop()` or `agentLoopContinue()`.
+
 ## License
 
 MIT

package/dist/agent-loop.d.ts

@@ -4,6 +4,7 @@
  */
 import { EventStream } from "@draht/ai";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 /**
  * Start an agent loop with a new prompt message.
  * The prompt is added to the context and events are emitted for it.
@@ -18,4 +19,6 @@ export declare function agentLoop(prompts: AgentMessage[], context: AgentContext
  * This cannot be validated here since `convertToLlm` is only called once per turn.
  */
 export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn): Promise<AgentMessage[]>;
+export declare function runAgentLoopContinue(context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn): Promise<AgentMessage[]>;
 //# sourceMappingURL=agent-loop.d.ts.map

package/dist/agent-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGN,WAAW,EAIX,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EAGZ,QAAQ,EACR,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAqBzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAsBzC","sourcesContent":["/**\n * Agent loop that works with AgentMessage throughout.\n * Transforms to Message[] only at the LLM call boundary.\n */\n\nimport {\n\ttype AssistantMessage,\n\ttype Context,\n\tEventStream,\n\tstreamSimple,\n\ttype ToolResultMessage,\n\tvalidateToolArguments,\n} from \"@draht/ai\";\nimport type {\n\tAgentContext,\n\tAgentEvent,\n\tAgentLoopConfig,\n\tAgentMessage,\n\tAgentTool,\n\tAgentToolResult,\n\tStreamFn,\n} from \"./types.js\";\n\n/**\n * Start an agent loop with a new prompt message.\n * The prompt is added to the context and events are emitted for it.\n */\nexport function agentLoop(\n\tprompts: AgentMessage[],\n\tcontext: AgentContext,\n\tconfig: AgentLoopConfig,\n\tsignal?: AbortSignal,\n\tstreamFn?: StreamFn,\n): EventStream<AgentEvent, AgentMessage[]> {\n\tconst stream = createAgentStream();\n\n\t(async () => {\n\t\tconst newMessages: AgentMessage[] = [...prompts];\n\t\tconst currentContext: AgentContext = {\n\t\t\t...context,\n\t\t\tmessages: [...context.messages, ...prompts],\n\t\t};\n\n\t\tstream.push({ type: \"agent_start\" });\n\t\tstream.push({ type: \"turn_start\" });\n\t\tfor (const prompt of prompts) {\n\t\t\tstream.push({ type: \"message_start\", message: prompt });\n\t\t\tstream.push({ type: \"message_end\", message: prompt });\n\t\t}\n\n\t\tawait runLoop(currentContext, newMessages, config, signal, stream, streamFn);\n\t})();\n\n\treturn stream;\n}\n\n/**\n * Continue an agent loop from the current context without adding a new message.\n * Used for retries - context already has user message or tool results.\n *\n * **Important:** The last message in context must convert to a `user` or `toolResult` message\n * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.\n * This cannot be validated here since `convertToLlm` is only called once per turn.\n */\nexport function agentLoopContinue(\n\tcontext: AgentContext,\n\tconfig: AgentLoopConfig,\n\tsignal?: AbortSignal,\n\tstreamFn?: StreamFn,\n): EventStream<AgentEvent, AgentMessage[]> {\n\tif (context.messages.length === 0) {\n\t\tthrow new Error(\"Cannot continue: no messages in context\");\n\t}\n\n\tif (context.messages[context.messages.length - 1].role === \"assistant\") {\n\t\tthrow new Error(\"Cannot continue from message role: assistant\");\n\t}\n\n\tconst stream = createAgentStream();\n\n\t(async () => {\n\t\tconst newMessages: AgentMessage[] = [];\n\t\tconst currentContext: AgentContext = { ...context };\n\n\t\tstream.push({ type: \"agent_start\" });\n\t\tstream.push({ type: \"turn_start\" });\n\n\t\tawait runLoop(currentContext, newMessages, config, signal, stream, streamFn);\n\t})();\n\n\treturn stream;\n}\n\nfunction createAgentStream(): EventStream<AgentEvent, AgentMessage[]> {\n\treturn new EventStream<AgentEvent, AgentMessage[]>(\n\t\t(event: AgentEvent) => event.type === \"agent_end\",\n\t\t(event: AgentEvent) => (event.type === \"agent_end\" ? event.messages : []),\n\t);\n}\n\n/**\n * Main loop logic shared by agentLoop and agentLoopContinue.\n */\nasync function runLoop(\n\tcurrentContext: AgentContext,\n\tnewMessages: AgentMessage[],\n\tconfig: AgentLoopConfig,\n\tsignal: AbortSignal | undefined,\n\tstream: EventStream<AgentEvent, AgentMessage[]>,\n\tstreamFn?: StreamFn,\n): Promise<void> {\n\tlet firstTurn = true;\n\t// Check for steering messages at start (user may have typed while waiting)\n\tlet pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];\n\n\t// Outer loop: continues when queued follow-up messages arrive after agent would stop\n\twhile (true) {\n\t\tlet hasMoreToolCalls = true;\n\t\tlet steeringAfterTools: AgentMessage[] | null = null;\n\n\t\t// Inner loop: process tool calls and steering messages\n\t\twhile (hasMoreToolCalls || pendingMessages.length > 0) {\n\t\t\tif (!firstTurn) {\n\t\t\t\tstream.push({ type: \"turn_start\" });\n\t\t\t} else {\n\t\t\t\tfirstTurn = false;\n\t\t\t}\n\n\t\t\t// Process pending messages (inject before next assistant response)\n\t\t\tif (pendingMessages.length > 0) {\n\t\t\t\tfor (const message of pendingMessages) {\n\t\t\t\t\tstream.push({ type: \"message_start\", message });\n\t\t\t\t\tstream.push({ type: \"message_end\", message });\n\t\t\t\t\tcurrentContext.messages.push(message);\n\t\t\t\t\tnewMessages.push(message);\n\t\t\t\t}\n\t\t\t\tpendingMessages = [];\n\t\t\t}\n\n\t\t\t// Stream assistant response\n\t\t\tconst message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn);\n\t\t\tnewMessages.push(message);\n\n\t\t\tif (message.stopReason === \"error\" || message.stopReason === \"aborted\") {\n\t\t\t\tstream.push({ type: \"turn_end\", message, toolResults: [] });\n\t\t\t\tstream.push({ type: \"agent_end\", messages: newMessages });\n\t\t\t\tstream.end(newMessages);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Check for tool calls\n\t\t\tconst toolCalls = message.content.filter((c) => c.type === \"toolCall\");\n\t\t\thasMoreToolCalls = toolCalls.length > 0;\n\n\t\t\tconst toolResults: ToolResultMessage[] = [];\n\t\t\tif (hasMoreToolCalls) {\n\t\t\t\tconst toolExecution = await executeToolCalls(\n\t\t\t\t\tcurrentContext.tools,\n\t\t\t\t\tmessage,\n\t\t\t\t\tsignal,\n\t\t\t\t\tstream,\n\t\t\t\t\tconfig.getSteeringMessages,\n\t\t\t\t);\n\t\t\t\ttoolResults.push(...toolExecution.toolResults);\n\t\t\t\tsteeringAfterTools = toolExecution.steeringMessages ?? null;\n\n\t\t\t\tfor (const result of toolResults) {\n\t\t\t\t\tcurrentContext.messages.push(result);\n\t\t\t\t\tnewMessages.push(result);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tstream.push({ type: \"turn_end\", message, toolResults });\n\n\t\t\t// Get steering messages after turn completes\n\t\t\tif (steeringAfterTools && steeringAfterTools.length > 0) {\n\t\t\t\tpendingMessages = steeringAfterTools;\n\t\t\t\tsteeringAfterTools = null;\n\t\t\t} else {\n\t\t\t\tpendingMessages = (await config.getSteeringMessages?.()) || [];\n\t\t\t}\n\t\t}\n\n\t\t// Agent would stop here. Check for follow-up messages.\n\t\tconst followUpMessages = (await config.getFollowUpMessages?.()) || [];\n\t\tif (followUpMessages.length > 0) {\n\t\t\t// Set as pending so inner loop processes them\n\t\t\tpendingMessages = followUpMessages;\n\t\t\tcontinue;\n\t\t}\n\n\t\t// No more messages, exit\n\t\tbreak;\n\t}\n\n\tstream.push({ type: \"agent_end\", messages: newMessages });\n\tstream.end(newMessages);\n}\n\n/**\n * Stream an assistant response from the LLM.\n * This is where AgentMessage[] gets transformed to Message[] for the LLM.\n */\nasync function streamAssistantResponse(\n\tcontext: AgentContext,\n\tconfig: AgentLoopConfig,\n\tsignal: AbortSignal | undefined,\n\tstream: EventStream<AgentEvent, AgentMessage[]>,\n\tstreamFn?: StreamFn,\n): Promise<AssistantMessage> {\n\t// Apply context transform if configured (AgentMessage[] → AgentMessage[])\n\tlet messages = context.messages;\n\tif (config.transformContext) {\n\t\tmessages = await config.transformContext(messages, signal);\n\t}\n\n\t// Convert to LLM-compatible messages (AgentMessage[] → Message[])\n\tconst llmMessages = await config.convertToLlm(messages);\n\n\t// Build LLM context\n\tconst llmContext: Context = {\n\t\tsystemPrompt: context.systemPrompt,\n\t\tmessages: llmMessages,\n\t\ttools: context.tools,\n\t};\n\n\tconst streamFunction = streamFn || streamSimple;\n\n\t// Resolve API key (important for expiring tokens)\n\tconst resolvedApiKey =\n\t\t(config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;\n\n\tconst response = await streamFunction(config.model, llmContext, {\n\t\t...config,\n\t\tapiKey: resolvedApiKey,\n\t\tsignal,\n\t});\n\n\tlet partialMessage: AssistantMessage | null = null;\n\tlet addedPartial = false;\n\n\tfor await (const event of response) {\n\t\tswitch (event.type) {\n\t\t\tcase \"start\":\n\t\t\t\tpartialMessage = event.partial;\n\t\t\t\tcontext.messages.push(partialMessage);\n\t\t\t\taddedPartial = true;\n\t\t\t\tstream.push({ type: \"message_start\", message: { ...partialMessage } });\n\t\t\t\tbreak;\n\n\t\t\tcase \"text_start\":\n\t\t\tcase \"text_delta\":\n\t\t\tcase \"text_end\":\n\t\t\tcase \"thinking_start\":\n\t\t\tcase \"thinking_delta\":\n\t\t\tcase \"thinking_end\":\n\t\t\tcase \"toolcall_start\":\n\t\t\tcase \"toolcall_delta\":\n\t\t\tcase \"toolcall_end\":\n\t\t\t\tif (partialMessage) {\n\t\t\t\t\tpartialMessage = event.partial;\n\t\t\t\t\tcontext.messages[context.messages.length - 1] = partialMessage;\n\t\t\t\t\tstream.push({\n\t\t\t\t\t\ttype: \"message_update\",\n\t\t\t\t\t\tassistantMessageEvent: event,\n\t\t\t\t\t\tmessage: { ...partialMessage },\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tbreak;\n\n\t\t\tcase \"done\":\n\t\t\tcase \"error\": {\n\t\t\t\tconst finalMessage = await response.result();\n\t\t\t\tif (addedPartial) {\n\t\t\t\t\tcontext.messages[context.messages.length - 1] = finalMessage;\n\t\t\t\t} else {\n\t\t\t\t\tcontext.messages.push(finalMessage);\n\t\t\t\t}\n\t\t\t\tif (!addedPartial) {\n\t\t\t\t\tstream.push({ type: \"message_start\", message: { ...finalMessage } });\n\t\t\t\t}\n\t\t\t\tstream.push({ type: \"message_end\", message: finalMessage });\n\t\t\t\treturn finalMessage;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn await response.result();\n}\n\n/**\n * Execute tool calls from an assistant message.\n */\nasync function executeToolCalls(\n\ttools: AgentTool<any>[] | undefined,\n\tassistantMessage: AssistantMessage,\n\tsignal: AbortSignal | undefined,\n\tstream: EventStream<AgentEvent, AgentMessage[]>,\n\tgetSteeringMessages?: AgentLoopConfig[\"getSteeringMessages\"],\n): Promise<{ toolResults: ToolResultMessage[]; steeringMessages?: AgentMessage[] }> {\n\tconst toolCalls = assistantMessage.content.filter((c) => c.type === \"toolCall\");\n\tconst results: ToolResultMessage[] = [];\n\tlet steeringMessages: AgentMessage[] | undefined;\n\n\tfor (let index = 0; index < toolCalls.length; index++) {\n\t\tconst toolCall = toolCalls[index];\n\t\tconst tool = tools?.find((t) => t.name === toolCall.name);\n\n\t\tstream.push({\n\t\t\ttype: \"tool_execution_start\",\n\t\t\ttoolCallId: toolCall.id,\n\t\t\ttoolName: toolCall.name,\n\t\t\targs: toolCall.arguments,\n\t\t});\n\n\t\tlet result: AgentToolResult<any>;\n\t\tlet isError = false;\n\n\t\ttry {\n\t\t\tif (!tool) throw new Error(`Tool ${toolCall.name} not found`);\n\n\t\t\tconst validatedArgs = validateToolArguments(tool, toolCall);\n\n\t\t\tresult = await tool.execute(toolCall.id, validatedArgs, signal, (partialResult) => {\n\t\t\t\tstream.push({\n\t\t\t\t\ttype: \"tool_execution_update\",\n\t\t\t\t\ttoolCallId: toolCall.id,\n\t\t\t\t\ttoolName: toolCall.name,\n\t\t\t\t\targs: toolCall.arguments,\n\t\t\t\t\tpartialResult,\n\t\t\t\t});\n\t\t\t});\n\t\t} catch (e) {\n\t\t\tresult = {\n\t\t\t\tcontent: [{ type: \"text\", text: e instanceof Error ? e.message : String(e) }],\n\t\t\t\tdetails: {},\n\t\t\t};\n\t\t\tisError = true;\n\t\t}\n\n\t\tstream.push({\n\t\t\ttype: \"tool_execution_end\",\n\t\t\ttoolCallId: toolCall.id,\n\t\t\ttoolName: toolCall.name,\n\t\t\tresult,\n\t\t\tisError,\n\t\t});\n\n\t\tconst toolResultMessage: ToolResultMessage = {\n\t\t\trole: \"toolResult\",\n\t\t\ttoolCallId: toolCall.id,\n\t\t\ttoolName: toolCall.name,\n\t\t\tcontent: result.content,\n\t\t\tdetails: result.details,\n\t\t\tisError,\n\t\t\ttimestamp: Date.now(),\n\t\t};\n\n\t\tresults.push(toolResultMessage);\n\t\tstream.push({ type: \"message_start\", message: toolResultMessage });\n\t\tstream.push({ type: \"message_end\", message: toolResultMessage });\n\n\t\t// Check for steering messages - skip remaining tools if user interrupted\n\t\tif (getSteeringMessages) {\n\t\t\tconst steering = await getSteeringMessages();\n\t\t\tif (steering.length > 0) {\n\t\t\t\tsteeringMessages = steering;\n\t\t\t\tconst remainingCalls = toolCalls.slice(index + 1);\n\t\t\t\tfor (const skipped of remainingCalls) {\n\t\t\t\t\tresults.push(skipToolCall(skipped, stream));\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn { toolResults: results, steeringMessages };\n}\n\nfunction skipToolCall(\n\ttoolCall: Extract<AssistantMessage[\"content\"][number], { type: \"toolCall\" }>,\n\tstream: EventStream<AgentEvent, AgentMessage[]>,\n): ToolResultMessage {\n\tconst result: AgentToolResult<any> = {\n\t\tcontent: [{ type: \"text\", text: \"Skipped due to queued user message.\" }],\n\t\tdetails: {},\n\t};\n\n\tstream.push({\n\t\ttype: \"tool_execution_start\",\n\t\ttoolCallId: toolCall.id,\n\t\ttoolName: toolCall.name,\n\t\targs: toolCall.arguments,\n\t});\n\tstream.push({\n\t\ttype: \"tool_execution_end\",\n\t\ttoolCallId: toolCall.id,\n\t\ttoolName: toolCall.name,\n\t\tresult,\n\t\tisError: true,\n\t});\n\n\tconst toolResultMessage: ToolResultMessage = {\n\t\trole: \"toolResult\",\n\t\ttoolCallId: toolCall.id,\n\t\ttoolName: toolCall.name,\n\t\tcontent: result.content,\n\t\tdetails: {},\n\t\tisError: true,\n\t\ttimestamp: Date.now(),\n\t};\n\n\tstream.push({ type: \"message_start\", message: toolResultMessage });\n\tstream.push({ type: \"message_end\", message: toolResultMessage });\n\n\treturn toolResultMessage;\n}\n"]}
+{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGN,WAAW,EAIX,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EAIZ,QAAQ,EACR,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzE;;;GAGG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAqBzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CA4BzC;AAED,wBAAsB,YAAY,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC,CAgBzB;AAED,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC,CAiBzB","sourcesContent":["/**\n * Agent loop that works with AgentMessage throughout.\n * Transforms to Message[] only at the LLM call boundary.\n */\n\nimport {\n\ttype AssistantMessage,\n\ttype Context,\n\tEventStream,\n\tstreamSimple,\n\ttype ToolResultMessage,\n\tvalidateToolArguments,\n} from \"@draht/ai\";\nimport type {\n\tAgentContext,\n\tAgentEvent,\n\tAgentLoopConfig,\n\tAgentMessage,\n\tAgentTool,\n\tAgentToolCall,\n\tAgentToolResult,\n\tStreamFn,\n} from \"./types.js\";\n\nexport type AgentEventSink = (event: AgentEvent) => Promise<void> | void;\n\n/**\n * Start an agent loop with a new prompt message.\n * The prompt is added to the context and events are emitted for it.\n */\nexport function agentLoop(\n\tprompts: AgentMessage[],\n\tcontext: AgentContext,\n\tconfig: AgentLoopConfig,\n\tsignal?: AbortSignal,\n\tstreamFn?: StreamFn,\n): EventStream<AgentEvent, AgentMessage[]> {\n\tconst stream = createAgentStream();\n\n\tvoid runAgentLoop(\n\t\tprompts,\n\t\tcontext,\n\t\tconfig,\n\t\tasync (event) => {\n\t\t\tstream.push(event);\n\t\t},\n\t\tsignal,\n\t\tstreamFn,\n\t)\n\t\t.then((messages) => {\n\t\t\tstream.end(messages);\n\t\t})\n\t\t.catch(() => {\n\t\t\tstream.end([]);\n\t\t});\n\n\treturn stream;\n}\n\n/**\n * Continue an agent loop from the current context without adding a new message.\n * Used for retries - context already has user message or tool results.\n *\n * **Important:** The last message in context must convert to a `user` or `toolResult` message\n * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.\n * This cannot be validated here since `convertToLlm` is only called once per turn.\n */\nexport function agentLoopContinue(\n\tcontext: AgentContext,\n\tconfig: AgentLoopConfig,\n\tsignal?: AbortSignal,\n\tstreamFn?: StreamFn,\n): EventStream<AgentEvent, AgentMessage[]> {\n\tif (context.messages.length === 0) {\n\t\tthrow new Error(\"Cannot continue: no messages in context\");\n\t}\n\n\tif (context.messages[context.messages.length - 1].role === \"assistant\") {\n\t\tthrow new Error(\"Cannot continue from message role: assistant\");\n\t}\n\n\tconst stream = createAgentStream();\n\n\tvoid runAgentLoopContinue(\n\t\tcontext,\n\t\tconfig,\n\t\tasync (event) => {\n\t\t\tstream.push(event);\n\t\t},\n\t\tsignal,\n\t\tstreamFn,\n\t)\n\t\t.then((messages) => {\n\t\t\tstream.end(messages);\n\t\t})\n\t\t.catch(() => {\n\t\t\tstream.end([]);\n\t\t});\n\n\treturn stream;\n}\n\nexport async function runAgentLoop(\n\tprompts: AgentMessage[],\n\tcontext: AgentContext,\n\tconfig: AgentLoopConfig,\n\temit: AgentEventSink,\n\tsignal?: AbortSignal,\n\tstreamFn?: StreamFn,\n): Promise<AgentMessage[]> {\n\tconst newMessages: AgentMessage[] = [...prompts];\n\tconst currentContext: AgentContext = {\n\t\t...context,\n\t\tmessages: [...context.messages, ...prompts],\n\t};\n\n\tawait emit({ type: \"agent_start\" });\n\tawait emit({ type: \"turn_start\" });\n\tfor (const prompt of prompts) {\n\t\tawait emit({ type: \"message_start\", message: prompt });\n\t\tawait emit({ type: \"message_end\", message: prompt });\n\t}\n\n\tawait runLoop(currentContext, newMessages, config, signal, emit, streamFn);\n\treturn newMessages;\n}\n\nexport async function runAgentLoopContinue(\n\tcontext: AgentContext,\n\tconfig: AgentLoopConfig,\n\temit: AgentEventSink,\n\tsignal?: AbortSignal,\n\tstreamFn?: StreamFn,\n): Promise<AgentMessage[]> {\n\tif (context.messages.length === 0) {\n\t\tthrow new Error(\"Cannot continue: no messages in context\");\n\t}\n\n\tif (context.messages[context.messages.length - 1].role === \"assistant\") {\n\t\tthrow new Error(\"Cannot continue from message role: assistant\");\n\t}\n\n\tconst newMessages: AgentMessage[] = [];\n\tconst currentContext: AgentContext = { ...context };\n\n\tawait emit({ type: \"agent_start\" });\n\tawait emit({ type: \"turn_start\" });\n\n\tawait runLoop(currentContext, newMessages, config, signal, emit, streamFn);\n\treturn newMessages;\n}\n\nfunction createAgentStream(): EventStream<AgentEvent, AgentMessage[]> {\n\treturn new EventStream<AgentEvent, AgentMessage[]>(\n\t\t(event: AgentEvent) => event.type === \"agent_end\",\n\t\t(event: AgentEvent) => (event.type === \"agent_end\" ? event.messages : []),\n\t);\n}\n\n/**\n * Main loop logic shared by agentLoop and agentLoopContinue.\n */\nasync function runLoop(\n\tcurrentContext: AgentContext,\n\tnewMessages: AgentMessage[],\n\tconfig: AgentLoopConfig,\n\tsignal: AbortSignal | undefined,\n\temit: AgentEventSink,\n\tstreamFn?: StreamFn,\n): Promise<void> {\n\tlet firstTurn = true;\n\t// Check for steering messages at start (user may have typed while waiting)\n\tlet pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];\n\n\t// Outer loop: continues when queued follow-up messages arrive after agent would stop\n\twhile (true) {\n\t\tlet hasMoreToolCalls = true;\n\n\t\t// Inner loop: process tool calls and steering messages\n\t\twhile (hasMoreToolCalls || pendingMessages.length > 0) {\n\t\t\tif (!firstTurn) {\n\t\t\t\tawait emit({ type: \"turn_start\" });\n\t\t\t} else {\n\t\t\t\tfirstTurn = false;\n\t\t\t}\n\n\t\t\t// Process pending messages (inject before next assistant response)\n\t\t\tif (pendingMessages.length > 0) {\n\t\t\t\tfor (const message of pendingMessages) {\n\t\t\t\t\tawait emit({ type: \"message_start\", message });\n\t\t\t\t\tawait emit({ type: \"message_end\", message });\n\t\t\t\t\tcurrentContext.messages.push(message);\n\t\t\t\t\tnewMessages.push(message);\n\t\t\t\t}\n\t\t\t\tpendingMessages = [];\n\t\t\t}\n\n\t\t\t// Stream assistant response\n\t\t\tconst message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn);\n\t\t\tnewMessages.push(message);\n\n\t\t\tif (message.stopReason === \"error\" || message.stopReason === \"aborted\") {\n\t\t\t\tawait emit({ type: \"turn_end\", message, toolResults: [] });\n\t\t\t\tawait emit({ type: \"agent_end\", messages: newMessages });\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Check for tool calls\n\t\t\tconst toolCalls = message.content.filter((c) => c.type === \"toolCall\");\n\t\t\thasMoreToolCalls = toolCalls.length > 0;\n\n\t\t\tconst toolResults: ToolResultMessage[] = [];\n\t\t\tif (hasMoreToolCalls) {\n\t\t\t\ttoolResults.push(...(await executeToolCalls(currentContext, message, config, signal, emit)));\n\n\t\t\t\tfor (const result of toolResults) {\n\t\t\t\t\tcurrentContext.messages.push(result);\n\t\t\t\t\tnewMessages.push(result);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tawait emit({ type: \"turn_end\", message, toolResults });\n\n\t\t\tpendingMessages = (await config.getSteeringMessages?.()) || [];\n\t\t}\n\n\t\t// Agent would stop here. Check for follow-up messages.\n\t\tconst followUpMessages = (await config.getFollowUpMessages?.()) || [];\n\t\tif (followUpMessages.length > 0) {\n\t\t\t// Set as pending so inner loop processes them\n\t\t\tpendingMessages = followUpMessages;\n\t\t\tcontinue;\n\t\t}\n\n\t\t// No more messages, exit\n\t\tbreak;\n\t}\n\n\tawait emit({ type: \"agent_end\", messages: newMessages });\n}\n\n/**\n * Stream an assistant response from the LLM.\n * This is where AgentMessage[] gets transformed to Message[] for the LLM.\n */\nasync function streamAssistantResponse(\n\tcontext: AgentContext,\n\tconfig: AgentLoopConfig,\n\tsignal: AbortSignal | undefined,\n\temit: AgentEventSink,\n\tstreamFn?: StreamFn,\n): Promise<AssistantMessage> {\n\t// Apply context transform if configured (AgentMessage[] → AgentMessage[])\n\tlet messages = context.messages;\n\tif (config.transformContext) {\n\t\tmessages = await config.transformContext(messages, signal);\n\t}\n\n\t// Convert to LLM-compatible messages (AgentMessage[] → Message[])\n\tconst llmMessages = await config.convertToLlm(messages);\n\n\t// Build LLM context\n\tconst llmContext: Context = {\n\t\tsystemPrompt: context.systemPrompt,\n\t\tmessages: llmMessages,\n\t\ttools: context.tools,\n\t};\n\n\tconst streamFunction = streamFn || streamSimple;\n\n\t// Resolve API key (important for expiring tokens)\n\tconst resolvedApiKey =\n\t\t(config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;\n\n\tconst response = await streamFunction(config.model, llmContext, {\n\t\t...config,\n\t\tapiKey: resolvedApiKey,\n\t\tsignal,\n\t});\n\n\tlet partialMessage: AssistantMessage | null = null;\n\tlet addedPartial = false;\n\n\tfor await (const event of response) {\n\t\tswitch (event.type) {\n\t\t\tcase \"start\":\n\t\t\t\tpartialMessage = event.partial;\n\t\t\t\tcontext.messages.push(partialMessage);\n\t\t\t\taddedPartial = true;\n\t\t\t\tawait emit({ type: \"message_start\", message: { ...partialMessage } });\n\t\t\t\tbreak;\n\n\t\t\tcase \"text_start\":\n\t\t\tcase \"text_delta\":\n\t\t\tcase \"text_end\":\n\t\t\tcase \"thinking_start\":\n\t\t\tcase \"thinking_delta\":\n\t\t\tcase \"thinking_end\":\n\t\t\tcase \"toolcall_start\":\n\t\t\tcase \"toolcall_delta\":\n\t\t\tcase \"toolcall_end\":\n\t\t\t\tif (partialMessage) {\n\t\t\t\t\tpartialMessage = event.partial;\n\t\t\t\t\tcontext.messages[context.messages.length - 1] = partialMessage;\n\t\t\t\t\tawait emit({\n\t\t\t\t\t\ttype: \"message_update\",\n\t\t\t\t\t\tassistantMessageEvent: event,\n\t\t\t\t\t\tmessage: { ...partialMessage },\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tbreak;\n\n\t\t\tcase \"done\":\n\t\t\tcase \"error\": {\n\t\t\t\tconst finalMessage = await response.result();\n\t\t\t\tif (addedPartial) {\n\t\t\t\t\tcontext.messages[context.messages.length - 1] = finalMessage;\n\t\t\t\t} else {\n\t\t\t\t\tcontext.messages.push(finalMessage);\n\t\t\t\t}\n\t\t\t\tif (!addedPartial) {\n\t\t\t\t\tawait emit({ type: \"message_start\", message: { ...finalMessage } });\n\t\t\t\t}\n\t\t\t\tawait emit({ type: \"message_end\", message: finalMessage });\n\t\t\t\treturn finalMessage;\n\t\t\t}\n\t\t}\n\t}\n\n\tconst finalMessage = await response.result();\n\tif (addedPartial) {\n\t\tcontext.messages[context.messages.length - 1] = finalMessage;\n\t} else {\n\t\tcontext.messages.push(finalMessage);\n\t\tawait emit({ type: \"message_start\", message: { ...finalMessage } });\n\t}\n\tawait emit({ type: \"message_end\", message: finalMessage });\n\treturn finalMessage;\n}\n\n/**\n * Execute tool calls from an assistant message.\n */\nasync function executeToolCalls(\n\tcurrentContext: AgentContext,\n\tassistantMessage: AssistantMessage,\n\tconfig: AgentLoopConfig,\n\tsignal: AbortSignal | undefined,\n\temit: AgentEventSink,\n): Promise<ToolResultMessage[]> {\n\tconst toolCalls = assistantMessage.content.filter((c) => c.type === \"toolCall\");\n\tif (config.toolExecution === \"sequential\") {\n\t\treturn executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit);\n\t}\n\treturn executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, signal, emit);\n}\n\nasync function executeToolCallsSequential(\n\tcurrentContext: AgentContext,\n\tassistantMessage: AssistantMessage,\n\ttoolCalls: AgentToolCall[],\n\tconfig: AgentLoopConfig,\n\tsignal: AbortSignal | undefined,\n\temit: AgentEventSink,\n): Promise<ToolResultMessage[]> {\n\tconst results: ToolResultMessage[] = [];\n\n\tfor (const toolCall of toolCalls) {\n\t\tawait emit({\n\t\t\ttype: \"tool_execution_start\",\n\t\t\ttoolCallId: toolCall.id,\n\t\t\ttoolName: toolCall.name,\n\t\t\targs: toolCall.arguments,\n\t\t});\n\n\t\tconst preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);\n\t\tif (preparation.kind === \"immediate\") {\n\t\t\tresults.push(await emitToolCallOutcome(toolCall, preparation.result, preparation.isError, emit));\n\t\t} else {\n\t\t\tconst executed = await executePreparedToolCall(preparation, signal, emit);\n\t\t\tresults.push(\n\t\t\t\tawait finalizeExecutedToolCall(\n\t\t\t\t\tcurrentContext,\n\t\t\t\t\tassistantMessage,\n\t\t\t\t\tpreparation,\n\t\t\t\t\texecuted,\n\t\t\t\t\tconfig,\n\t\t\t\t\tsignal,\n\t\t\t\t\temit,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t}\n\n\treturn results;\n}\n\nasync function executeToolCallsParallel(\n\tcurrentContext: AgentContext,\n\tassistantMessage: AssistantMessage,\n\ttoolCalls: AgentToolCall[],\n\tconfig: AgentLoopConfig,\n\tsignal: AbortSignal | undefined,\n\temit: AgentEventSink,\n): Promise<ToolResultMessage[]> {\n\tconst results: (ToolResultMessage | null)[] = new Array(toolCalls.length).fill(null);\n\tconst runnableCalls: { index: number; prepared: PreparedToolCall }[] = [];\n\n\tfor (let i = 0; i < toolCalls.length; i++) {\n\t\tconst toolCall = toolCalls[i];\n\t\tawait emit({\n\t\t\ttype: \"tool_execution_start\",\n\t\t\ttoolCallId: toolCall.id,\n\t\t\ttoolName: toolCall.name,\n\t\t\targs: toolCall.arguments,\n\t\t});\n\n\t\tconst preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);\n\t\tif (preparation.kind === \"immediate\") {\n\t\t\tresults[i] = await emitToolCallOutcome(toolCall, preparation.result, preparation.isError, emit);\n\t\t} else {\n\t\t\trunnableCalls.push({ index: i, prepared: preparation });\n\t\t}\n\t}\n\n\tconst runningCalls = runnableCalls.map((entry) => ({\n\t\tindex: entry.index,\n\t\tprepared: entry.prepared,\n\t\texecution: executePreparedToolCall(entry.prepared, signal, emit),\n\t}));\n\n\tfor (const running of runningCalls) {\n\t\tconst executed = await running.execution;\n\t\tresults[running.index] = await finalizeExecutedToolCall(\n\t\t\tcurrentContext,\n\t\t\tassistantMessage,\n\t\t\trunning.prepared,\n\t\t\texecuted,\n\t\t\tconfig,\n\t\t\tsignal,\n\t\t\temit,\n\t\t);\n\t}\n\n\treturn results.filter((r): r is ToolResultMessage => r !== null);\n}\n\ntype PreparedToolCall = {\n\tkind: \"prepared\";\n\ttoolCall: AgentToolCall;\n\ttool: AgentTool<any>;\n\targs: unknown;\n};\n\ntype ImmediateToolCallOutcome = {\n\tkind: \"immediate\";\n\tresult: AgentToolResult<any>;\n\tisError: boolean;\n};\n\ntype ExecutedToolCallOutcome = {\n\tresult: AgentToolResult<any>;\n\tisError: boolean;\n};\n\nasync function prepareToolCall(\n\tcurrentContext: AgentContext,\n\tassistantMessage: AssistantMessage,\n\ttoolCall: AgentToolCall,\n\tconfig: AgentLoopConfig,\n\tsignal: AbortSignal | undefined,\n): Promise<PreparedToolCall | ImmediateToolCallOutcome> {\n\tconst tool = currentContext.tools?.find((t) => t.name === toolCall.name);\n\tif (!tool) {\n\t\treturn {\n\t\t\tkind: \"immediate\",\n\t\t\tresult: createErrorToolResult(`Tool ${toolCall.name} not found`),\n\t\t\tisError: true,\n\t\t};\n\t}\n\n\ttry {\n\t\tconst validatedArgs = validateToolArguments(tool, toolCall);\n\t\tif (config.beforeToolCall) {\n\t\t\tconst beforeResult = await config.beforeToolCall(\n\t\t\t\t{\n\t\t\t\t\tassistantMessage,\n\t\t\t\t\ttoolCall,\n\t\t\t\t\targs: validatedArgs,\n\t\t\t\t\tcontext: currentContext,\n\t\t\t\t},\n\t\t\t\tsignal,\n\t\t\t);\n\t\t\tif (beforeResult?.block) {\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"immediate\",\n\t\t\t\t\tresult: createErrorToolResult(beforeResult.reason || \"Tool execution was blocked\"),\n\t\t\t\t\tisError: true,\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\t\treturn {\n\t\t\tkind: \"prepared\",\n\t\t\ttoolCall,\n\t\t\ttool,\n\t\t\targs: validatedArgs,\n\t\t};\n\t} catch (error) {\n\t\treturn {\n\t\t\tkind: \"immediate\",\n\t\t\tresult: createErrorToolResult(error instanceof Error ? error.message : String(error)),\n\t\t\tisError: true,\n\t\t};\n\t}\n}\n\nasync function executePreparedToolCall(\n\tprepared: PreparedToolCall,\n\tsignal: AbortSignal | undefined,\n\temit: AgentEventSink,\n): Promise<ExecutedToolCallOutcome> {\n\tconst updateEvents: Promise<void>[] = [];\n\n\ttry {\n\t\tconst result = await prepared.tool.execute(\n\t\t\tprepared.toolCall.id,\n\t\t\tprepared.args as never,\n\t\t\tsignal,\n\t\t\t(partialResult) => {\n\t\t\t\tupdateEvents.push(\n\t\t\t\t\tPromise.resolve(\n\t\t\t\t\t\temit({\n\t\t\t\t\t\t\ttype: \"tool_execution_update\",\n\t\t\t\t\t\t\ttoolCallId: prepared.toolCall.id,\n\t\t\t\t\t\t\ttoolName: prepared.toolCall.name,\n\t\t\t\t\t\t\targs: prepared.toolCall.arguments,\n\t\t\t\t\t\t\tpartialResult,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t},\n\t\t);\n\t\tawait Promise.all(updateEvents);\n\t\treturn { result, isError: false };\n\t} catch (error) {\n\t\tawait Promise.all(updateEvents);\n\t\treturn {\n\t\t\tresult: createErrorToolResult(error instanceof Error ? error.message : String(error)),\n\t\t\tisError: true,\n\t\t};\n\t}\n}\n\nasync function finalizeExecutedToolCall(\n\tcurrentContext: AgentContext,\n\tassistantMessage: AssistantMessage,\n\tprepared: PreparedToolCall,\n\texecuted: ExecutedToolCallOutcome,\n\tconfig: AgentLoopConfig,\n\tsignal: AbortSignal | undefined,\n\temit: AgentEventSink,\n): Promise<ToolResultMessage> {\n\tlet result = executed.result;\n\tlet isError = executed.isError;\n\n\tif (config.afterToolCall) {\n\t\tconst afterResult = await config.afterToolCall(\n\t\t\t{\n\t\t\t\tassistantMessage,\n\t\t\t\ttoolCall: prepared.toolCall,\n\t\t\t\targs: prepared.args,\n\t\t\t\tresult,\n\t\t\t\tisError,\n\t\t\t\tcontext: currentContext,\n\t\t\t},\n\t\t\tsignal,\n\t\t);\n\t\tif (afterResult) {\n\t\t\tresult = {\n\t\t\t\tcontent: afterResult.content ?? result.content,\n\t\t\t\tdetails: afterResult.details ?? result.details,\n\t\t\t};\n\t\t\tisError = afterResult.isError ?? isError;\n\t\t}\n\t}\n\n\treturn await emitToolCallOutcome(prepared.toolCall, result, isError, emit);\n}\n\nfunction createErrorToolResult(message: string): AgentToolResult<any> {\n\treturn {\n\t\tcontent: [{ type: \"text\", text: message }],\n\t\tdetails: {},\n\t};\n}\n\nasync function emitToolCallOutcome(\n\ttoolCall: AgentToolCall,\n\tresult: AgentToolResult<any>,\n\tisError: boolean,\n\temit: AgentEventSink,\n): Promise<ToolResultMessage> {\n\tawait emit({\n\t\ttype: \"tool_execution_end\",\n\t\ttoolCallId: toolCall.id,\n\t\ttoolName: toolCall.name,\n\t\tresult,\n\t\tisError,\n\t});\n\n\tconst toolResultMessage: ToolResultMessage = {\n\t\trole: \"toolResult\",\n\t\ttoolCallId: toolCall.id,\n\t\ttoolName: toolCall.name,\n\t\tcontent: result.content,\n\t\tdetails: result.details,\n\t\tisError,\n\t\ttimestamp: Date.now(),\n\t};\n\n\tawait emit({ type: \"message_start\", message: toolResultMessage });\n\tawait emit({ type: \"message_end\", message: toolResultMessage });\n\treturn toolResultMessage;\n}\n"]}

package/dist/agent-loop.js

@@ -9,20 +9,15 @@ import { EventStream, streamSimple, validateToolArguments, } from "@draht/ai";
  */
 export function agentLoop(prompts, context, config, signal, streamFn) {
     const stream = createAgentStream();
-    (async () => {
-        const newMessages = [...prompts];
-        const currentContext = {
-            ...context,
-            messages: [...context.messages, ...prompts],
-        };
-        stream.push({ type: "agent_start" });
-        stream.push({ type: "turn_start" });
-        for (const prompt of prompts) {
-            stream.push({ type: "message_start", message: prompt });
-            stream.push({ type: "message_end", message: prompt });
-        }
-        await runLoop(currentContext, newMessages, config, signal, stream, streamFn);
-    })();
+    void runAgentLoop(prompts, context, config, async (event) => {
+        stream.push(event);
+    }, signal, streamFn)
+        .then((messages) => {
+        stream.end(messages);
+    })
+        .catch(() => {
+        stream.end([]);
+    });
     return stream;
 }
 /**
@@ -41,33 +36,63 @@ export function agentLoopContinue(context, config, signal, streamFn) {
         throw new Error("Cannot continue from message role: assistant");
     }
     const stream = createAgentStream();
-    (async () => {
-        const newMessages = [];
-        const currentContext = { ...context };
-        stream.push({ type: "agent_start" });
-        stream.push({ type: "turn_start" });
-        await runLoop(currentContext, newMessages, config, signal, stream, streamFn);
-    })();
+    void runAgentLoopContinue(context, config, async (event) => {
+        stream.push(event);
+    }, signal, streamFn)
+        .then((messages) => {
+        stream.end(messages);
+    })
+        .catch(() => {
+        stream.end([]);
+    });
     return stream;
 }
+export async function runAgentLoop(prompts, context, config, emit, signal, streamFn) {
+    const newMessages = [...prompts];
+    const currentContext = {
+        ...context,
+        messages: [...context.messages, ...prompts],
+    };
+    await emit({ type: "agent_start" });
+    await emit({ type: "turn_start" });
+    for (const prompt of prompts) {
+        await emit({ type: "message_start", message: prompt });
+        await emit({ type: "message_end", message: prompt });
+    }
+    await runLoop(currentContext, newMessages, config, signal, emit, streamFn);
+    return newMessages;
+}
+export async function runAgentLoopContinue(context, config, emit, signal, streamFn) {
+    if (context.messages.length === 0) {
+        throw new Error("Cannot continue: no messages in context");
+    }
+    if (context.messages[context.messages.length - 1].role === "assistant") {
+        throw new Error("Cannot continue from message role: assistant");
+    }
+    const newMessages = [];
+    const currentContext = { ...context };
+    await emit({ type: "agent_start" });
+    await emit({ type: "turn_start" });
+    await runLoop(currentContext, newMessages, config, signal, emit, streamFn);
+    return newMessages;
+}
 function createAgentStream() {
     return new EventStream((event) => event.type === "agent_end", (event) => (event.type === "agent_end" ? event.messages : []));
 }
 /**
  * Main loop logic shared by agentLoop and agentLoopContinue.
  */
-async function runLoop(currentContext, newMessages, config, signal, stream, streamFn) {
+async function runLoop(currentContext, newMessages, config, signal, emit, streamFn) {
     let firstTurn = true;
     // Check for steering messages at start (user may have typed while waiting)
     let pendingMessages = (await config.getSteeringMessages?.()) || [];
     // Outer loop: continues when queued follow-up messages arrive after agent would stop
     while (true) {
         let hasMoreToolCalls = true;
-        let steeringAfterTools = null;
         // Inner loop: process tool calls and steering messages
         while (hasMoreToolCalls || pendingMessages.length > 0) {
             if (!firstTurn) {
-                stream.push({ type: "turn_start" });
+                await emit({ type: "turn_start" });
             }
             else {
                 firstTurn = false;
@@ -75,20 +100,19 @@ async function runLoop(currentContext, newMessages, config, signal, stream, stre
             // Process pending messages (inject before next assistant response)
             if (pendingMessages.length > 0) {
                 for (const message of pendingMessages) {
-                    stream.push({ type: "message_start", message });
-                    stream.push({ type: "message_end", message });
+                    await emit({ type: "message_start", message });
+                    await emit({ type: "message_end", message });
                     currentContext.messages.push(message);
                     newMessages.push(message);
                 }
                 pendingMessages = [];
             }
             // Stream assistant response
-            const message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn);
+            const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn);
             newMessages.push(message);
             if (message.stopReason === "error" || message.stopReason === "aborted") {
-                stream.push({ type: "turn_end", message, toolResults: [] });
-                stream.push({ type: "agent_end", messages: newMessages });
-                stream.end(newMessages);
+                await emit({ type: "turn_end", message, toolResults: [] });
+                await emit({ type: "agent_end", messages: newMessages });
                 return;
             }
             // Check for tool calls
@@ -96,23 +120,14 @@ async function runLoop(currentContext, newMessages, config, signal, stream, stre
             hasMoreToolCalls = toolCalls.length > 0;
             const toolResults = [];
             if (hasMoreToolCalls) {
-                const toolExecution = await executeToolCalls(currentContext.tools, message, signal, stream, config.getSteeringMessages);
-                toolResults.push(...toolExecution.toolResults);
-                steeringAfterTools = toolExecution.steeringMessages ?? null;
+                toolResults.push(...(await executeToolCalls(currentContext, message, config, signal, emit)));
                 for (const result of toolResults) {
                     currentContext.messages.push(result);
                     newMessages.push(result);
                 }
             }
-            stream.push({ type: "turn_end", message, toolResults });
-            // Get steering messages after turn completes
-            if (steeringAfterTools && steeringAfterTools.length > 0) {
-                pendingMessages = steeringAfterTools;
-                steeringAfterTools = null;
-            }
-            else {
-                pendingMessages = (await config.getSteeringMessages?.()) || [];
-            }
+            await emit({ type: "turn_end", message, toolResults });
+            pendingMessages = (await config.getSteeringMessages?.()) || [];
         }
         // Agent would stop here. Check for follow-up messages.
         const followUpMessages = (await config.getFollowUpMessages?.()) || [];
@@ -124,14 +139,13 @@ async function runLoop(currentContext, newMessages, config, signal, stream, stre
         // No more messages, exit
         break;
     }
-    stream.push({ type: "agent_end", messages: newMessages });
-    stream.end(newMessages);
+    await emit({ type: "agent_end", messages: newMessages });
 }
 /**
  * Stream an assistant response from the LLM.
  * This is where AgentMessage[] gets transformed to Message[] for the LLM.
  */
-async function streamAssistantResponse(context, config, signal, stream, streamFn) {
+async function streamAssistantResponse(context, config, signal, emit, streamFn) {
     // Apply context transform if configured (AgentMessage[] → AgentMessage[])
     let messages = context.messages;
     if (config.transformContext) {
@@ -161,7 +175,7 @@ async function streamAssistantResponse(context, config, signal, stream, streamFn
                 partialMessage = event.partial;
                 context.messages.push(partialMessage);
                 addedPartial = true;
-                stream.push({ type: "message_start", message: { ...partialMessage } });
+                await emit({ type: "message_start", message: { ...partialMessage } });
                 break;
             case "text_start":
             case "text_delta":
@@ -175,7 +189,7 @@ async function streamAssistantResponse(context, config, signal, stream, streamFn
                 if (partialMessage) {
                     partialMessage = event.partial;
                     context.messages[context.messages.length - 1] = partialMessage;
-                    stream.push({
+                    await emit({
                         type: "message_update",
                         assistantMessageEvent: event,
                         message: { ...partialMessage },
@@ -192,117 +206,195 @@ async function streamAssistantResponse(context, config, signal, stream, streamFn
                     context.messages.push(finalMessage);
                 }
                 if (!addedPartial) {
-                    stream.push({ type: "message_start", message: { ...finalMessage } });
+                    await emit({ type: "message_start", message: { ...finalMessage } });
                 }
-                stream.push({ type: "message_end", message: finalMessage });
+                await emit({ type: "message_end", message: finalMessage });
                 return finalMessage;
             }
         }
     }
-    return await response.result();
+    const finalMessage = await response.result();
+    if (addedPartial) {
+        context.messages[context.messages.length - 1] = finalMessage;
+    }
+    else {
+        context.messages.push(finalMessage);
+        await emit({ type: "message_start", message: { ...finalMessage } });
+    }
+    await emit({ type: "message_end", message: finalMessage });
+    return finalMessage;
 }
 /**
  * Execute tool calls from an assistant message.
  */
-async function executeToolCalls(tools, assistantMessage, signal, stream, getSteeringMessages) {
+async function executeToolCalls(currentContext, assistantMessage, config, signal, emit) {
     const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
+    if (config.toolExecution === "sequential") {
+        return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit);
+    }
+    return executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, signal, emit);
+}
+async function executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit) {
     const results = [];
-    let steeringMessages;
-    for (let index = 0; index < toolCalls.length; index++) {
-        const toolCall = toolCalls[index];
-        const tool = tools?.find((t) => t.name === toolCall.name);
-        stream.push({
+    for (const toolCall of toolCalls) {
+        await emit({
             type: "tool_execution_start",
             toolCallId: toolCall.id,
             toolName: toolCall.name,
             args: toolCall.arguments,
         });
-        let result;
-        let isError = false;
-        try {
-            if (!tool)
-                throw new Error(`Tool ${toolCall.name} not found`);
-            const validatedArgs = validateToolArguments(tool, toolCall);
-            result = await tool.execute(toolCall.id, validatedArgs, signal, (partialResult) => {
-                stream.push({
-                    type: "tool_execution_update",
-                    toolCallId: toolCall.id,
-                    toolName: toolCall.name,
-                    args: toolCall.arguments,
-                    partialResult,
-                });
-            });
+        const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
+        if (preparation.kind === "immediate") {
+            results.push(await emitToolCallOutcome(toolCall, preparation.result, preparation.isError, emit));
         }
-        catch (e) {
-            result = {
-                content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
-                details: {},
-            };
-            isError = true;
+        else {
+            const executed = await executePreparedToolCall(preparation, signal, emit);
+            results.push(await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal, emit));
         }
-        stream.push({
-            type: "tool_execution_end",
+    }
+    return results;
+}
+async function executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, signal, emit) {
+    const results = new Array(toolCalls.length).fill(null);
+    const runnableCalls = [];
+    for (let i = 0; i < toolCalls.length; i++) {
+        const toolCall = toolCalls[i];
+        await emit({
+            type: "tool_execution_start",
             toolCallId: toolCall.id,
             toolName: toolCall.name,
-            result,
-            isError,
+            args: toolCall.arguments,
         });
-        const toolResultMessage = {
-            role: "toolResult",
-            toolCallId: toolCall.id,
-            toolName: toolCall.name,
-            content: result.content,
-            details: result.details,
-            isError,
-            timestamp: Date.now(),
+        const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
+        if (preparation.kind === "immediate") {
+            results[i] = await emitToolCallOutcome(toolCall, preparation.result, preparation.isError, emit);
+        }
+        else {
+            runnableCalls.push({ index: i, prepared: preparation });
+        }
+    }
+    const runningCalls = runnableCalls.map((entry) => ({
+        index: entry.index,
+        prepared: entry.prepared,
+        execution: executePreparedToolCall(entry.prepared, signal, emit),
+    }));
+    for (const running of runningCalls) {
+        const executed = await running.execution;
+        results[running.index] = await finalizeExecutedToolCall(currentContext, assistantMessage, running.prepared, executed, config, signal, emit);
+    }
+    return results.filter((r) => r !== null);
+}
+async function prepareToolCall(currentContext, assistantMessage, toolCall, config, signal) {
+    const tool = currentContext.tools?.find((t) => t.name === toolCall.name);
+    if (!tool) {
+        return {
+            kind: "immediate",
+            result: createErrorToolResult(`Tool ${toolCall.name} not found`),
+            isError: true,
         };
-        results.push(toolResultMessage);
-        stream.push({ type: "message_start", message: toolResultMessage });
-        stream.push({ type: "message_end", message: toolResultMessage });
-        // Check for steering messages - skip remaining tools if user interrupted
-        if (getSteeringMessages) {
-            const steering = await getSteeringMessages();
-            if (steering.length > 0) {
-                steeringMessages = steering;
-                const remainingCalls = toolCalls.slice(index + 1);
-                for (const skipped of remainingCalls) {
-                    results.push(skipToolCall(skipped, stream));
-                }
-                break;
+    }
+    try {
+        const validatedArgs = validateToolArguments(tool, toolCall);
+        if (config.beforeToolCall) {
+            const beforeResult = await config.beforeToolCall({
+                assistantMessage,
+                toolCall,
+                args: validatedArgs,
+                context: currentContext,
+            }, signal);
+            if (beforeResult?.block) {
+                return {
+                    kind: "immediate",
+                    result: createErrorToolResult(beforeResult.reason || "Tool execution was blocked"),
+                    isError: true,
+                };
             }
         }
+        return {
+            kind: "prepared",
+            toolCall,
+            tool,
+            args: validatedArgs,
+        };
+    }
+    catch (error) {
+        return {
+            kind: "immediate",
+            result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
+            isError: true,
+        };
+    }
+}
+async function executePreparedToolCall(prepared, signal, emit) {
+    const updateEvents = [];
+    try {
+        const result = await prepared.tool.execute(prepared.toolCall.id, prepared.args, signal, (partialResult) => {
+            updateEvents.push(Promise.resolve(emit({
+                type: "tool_execution_update",
+                toolCallId: prepared.toolCall.id,
+                toolName: prepared.toolCall.name,
+                args: prepared.toolCall.arguments,
+                partialResult,
+            })));
+        });
+        await Promise.all(updateEvents);
+        return { result, isError: false };
+    }
+    catch (error) {
+        await Promise.all(updateEvents);
+        return {
+            result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
+            isError: true,
+        };
+    }
+}
+async function finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, signal, emit) {
+    let result = executed.result;
+    let isError = executed.isError;
+    if (config.afterToolCall) {
+        const afterResult = await config.afterToolCall({
+            assistantMessage,
+            toolCall: prepared.toolCall,
+            args: prepared.args,
+            result,
+            isError,
+            context: currentContext,
+        }, signal);
+        if (afterResult) {
+            result = {
+                content: afterResult.content ?? result.content,
+                details: afterResult.details ?? result.details,
+            };
+            isError = afterResult.isError ?? isError;
+        }
     }
-    return { toolResults: results, steeringMessages };
+    return await emitToolCallOutcome(prepared.toolCall, result, isError, emit);
 }
-function skipToolCall(toolCall, stream) {
-    const result = {
-        content: [{ type: "text", text: "Skipped due to queued user message." }],
+function createErrorToolResult(message) {
+    return {
+        content: [{ type: "text", text: message }],
         details: {},
     };
-    stream.push({
-        type: "tool_execution_start",
-        toolCallId: toolCall.id,
-        toolName: toolCall.name,
-        args: toolCall.arguments,
-    });
-    stream.push({
+}
+async function emitToolCallOutcome(toolCall, result, isError, emit) {
+    await emit({
         type: "tool_execution_end",
         toolCallId: toolCall.id,
         toolName: toolCall.name,
         result,
-        isError: true,
+        isError,
     });
     const toolResultMessage = {
         role: "toolResult",
         toolCallId: toolCall.id,
         toolName: toolCall.name,
         content: result.content,
-        details: {},
-        isError: true,
+        details: result.details,
+        isError,
         timestamp: Date.now(),
     };
-    stream.push({ type: "message_start", message: toolResultMessage });
-    stream.push({ type: "message_end", message: toolResultMessage });
+    await emit({ type: "message_start", message: toolResultMessage });
+    await emit({ type: "message_end", message: toolResultMessage });
     return toolResultMessage;
 }
 //# sourceMappingURL=agent-loop.js.map