@xandout/libra-harness 0.1.33 → 0.1.90

package/README.md

@@ -14,7 +14,7 @@ pnpm add @xandout/libra-harness
 
 ```typescript
 import { Agent } from '@xandout/libra-harness'
-import { resolveModel } from '@xandout/libra-harness/extras/models'
+import { resolveModel } from '@xandout/libra-harness/models'
 
 // Resolve a model from environment variables (DEEPSEEK_API_KEY, OPENAI_API_KEY, etc.)
 const model = await resolveModel('deepseek/deepseek-v4-flash')
@@ -140,8 +140,8 @@ agent.use(loggingExtension)
 Libra ships with a set of optional extensions under `@xandout/libra-harness/extras`. Each is importable via its own subpath — import only what you need:
 
 ```typescript
-import { createLoggerExtension } from '@xandout/libra-harness/extras/logger'
-import { createDiskSessionExtension } from '@xandout/libra-harness/extras/disk-session'
+import { createLoggerExtension } from '@xandout/libra-harness/extensions/logger'
+import { createDiskSessionExtension } from '@xandout/libra-harness/extensions/disk-session'
 
 agent.use(createLoggerExtension())
 agent.use(createDiskSessionExtension({ dir: './sessions' }))
@@ -149,37 +149,37 @@ agent.use(createDiskSessionExtension({ dir: './sessions' }))
 
 | Extension | Import | Description |
 |-----------|--------|-------------|
-| logger | `@xandout/libra-harness/extras/logger` | Logs each lifecycle stage |
-| streaming | `@xandout/libra-harness/extras/streaming` | Streams text/reasoning/tool-input deltas |
-| otel | `@xandout/libra-harness/extras/otel` | OpenTelemetry tracing (JSONL or OTLP export) |
-| weather-tool | `@xandout/libra-harness/extras/weather-tool` | Registers a `get_weather` tool |
-| structured-output | `@xandout/libra-harness/extras/structured-output` | Validates LLM output against a JSON schema |
-| mcp | `@xandout/libra-harness/extras/mcp` | Connects to MCP servers, registers tools |
-| skills | `@xandout/libra-harness/extras/skills` | Loads Agent Skills from directories |
-| filesystem | `@xandout/libra-harness/extras/filesystem` | File read/write/list tools |
-| scripts | `@xandout/libra-harness/extras/scripts` | Runs shell scripts in pipeline stages |
-| keyword-extractor | `@xandout/libra-harness/extras/keyword-extractor` | Extracts keywords from messages (local NLP) |
-| token-stats | `@xandout/libra-harness/extras/token-stats` | Tracks token usage per turn |
-| tool-buffer | `@xandout/libra-harness/extras/tool-buffer` | Buffers and replays tool results |
-| auto-steer | `@xandout/libra-harness/extras/auto-steer` | Auto-injects steering messages based on conditions |
-| emoji | `@xandout/libra-harness/extras/emoji` | Decorates responses with an emoji prefix |
-| timestamp | `@xandout/libra-harness/extras/timestamp` | Records start/finish timestamps in metadata |
-| disk-session | `@xandout/libra-harness/extras/disk-session` | Disk-backed session history per session ID |
-| mem-session | `@xandout/libra-harness/extras/mem-session` | In-memory session history per session ID |
-| memory | `@xandout/libra-harness/extras/memory` | Long-term memory with LLM-based extraction |
+| logger | `@xandout/libra-harness/extensions/logger` | Logs each lifecycle stage |
+| streaming | `@xandout/libra-harness/extensions/streaming` | Streams text/reasoning/tool-input deltas |
+| otel | `@xandout/libra-harness/extensions/otel` | OpenTelemetry tracing (JSONL or OTLP export) |
+| weather-tool | `@xandout/libra-harness/extensions/weather-tool` | Registers a `get_weather` tool |
+| structured-output | `@xandout/libra-harness/extensions/structured-output` | Validates LLM output against a JSON schema |
+| mcp | `@xandout/libra-harness/extensions/mcp` | Connects to MCP servers, registers tools |
+| skills | `@xandout/libra-harness/extensions/skills` | Loads Agent Skills from directories |
+| filesystem | `@xandout/libra-harness/extensions/filesystem` | File read/write/list tools |
+| scripts | `@xandout/libra-harness/extensions/scripts` | Runs shell scripts in pipeline stages |
+| keyword-extractor | `@xandout/libra-harness/extensions/keyword-extractor` | Extracts keywords from messages (local NLP) |
+| token-stats | `@xandout/libra-harness/extensions/token-stats` | Tracks token usage per turn |
+| tool-buffer | `@xandout/libra-harness/extensions/tool-buffer` | Buffers and replays tool results |
+| auto-steer | `@xandout/libra-harness/extensions/auto-steer` | Auto-injects steering messages based on conditions |
+| emoji | `@xandout/libra-harness/extensions/emoji` | Decorates responses with an emoji prefix |
+| timestamp | `@xandout/libra-harness/extensions/timestamp` | Records start/finish timestamps in metadata |
+| disk-session | `@xandout/libra-harness/extensions/disk-session` | Disk-backed session history per session ID |
+| mem-session | `@xandout/libra-harness/extensions/mem-session` | In-memory session history per session ID |
+| memory | `@xandout/libra-harness/extensions/memory` | Long-term memory with LLM-based extraction |
 
 **Priority** controls hook execution order within each lifecycle stage (higher = runs first, ties keep registration order). Set `priority` on any extension whose hooks must run before or after another extension's hooks.
 
-See [`src/extras/README.md`](src/extras/README.md) for full API docs.
+See [`src/extensions/README.md`](src/extensions/README.md) for full API docs.
 
 ### Extension loader
 
 For larger setups, `loadExtensions` accepts a mix of factory functions, `Extension` objects, and directory paths. It passes a shared config object to each factory, sorts by priority, and handles cleanup:
 
 ```typescript
-import { loadExtensions, installExtensions, closeExtensions } from '@xandout/libra-harness/extras'
-import { createLoggerExtension } from '@xandout/libra-harness/extras/logger'
-import { createMcpExtension } from '@xandout/libra-harness/extras/mcp'
+import { loadExtensions, installExtensions, closeExtensions } from '@xandout/libra-harness/extensions'
+import { createLoggerExtension } from '@xandout/libra-harness/extensions/logger'
+import { createMcpExtension } from '@xandout/libra-harness/extensions/mcp'
 
 const loaded = await loadExtensions(
   [
@@ -201,10 +201,10 @@ await closeExtensions(loaded)     // calls close() on extensions that have one (
 
 ### Native resolver
 
-The easiest way to get a model is `resolveModel` from `@xandout/libra-harness/extras/models`. It reads API keys from environment variables and loads the appropriate AI SDK provider package dynamically:
+The easiest way to get a model is `resolveModel` from `@xandout/libra-harness/models`. It reads API keys from environment variables and loads the appropriate AI SDK provider package dynamically:
 
 ```typescript
-import { resolveModel } from '@xandout/libra-harness/extras/models'
+import { resolveModel } from '@xandout/libra-harness/models'
 
 // Reads DEEPSEEK_API_KEY from env, loads @ai-sdk/deepseek
 const model = await resolveModel('deepseek/deepseek-v4-flash')
@@ -244,7 +244,7 @@ const model = new AISdkModel(openai('gpt-4.1-mini'))
 Route requests to different models based on input content — e.g. send images to a vision model:
 
 ```typescript
-import { createRoutingModel, hasImageInput } from '@xandout/libra-harness/extras/models'
+import { createRoutingModel, hasImageInput } from '@xandout/libra-harness/models'
 
 const model = createRoutingModel({
   default: await resolveModel('deepseek/deepseek-v4-flash'),
@@ -274,8 +274,8 @@ Expose Libra agents as OpenAI-compatible models. Any framework that supports a c
 
 ```typescript
 import { Agent } from '@xandout/libra-harness'
-import { resolveModel } from '@xandout/libra-harness/extras/models'
-import { createOpenAICompatibleServer } from '@xandout/libra-harness/extras/openai-provider'
+import { resolveModel } from '@xandout/libra-harness/models'
+import { createOpenAICompatibleServer } from '@xandout/libra-harness/openai-provider'
 
 const model = await resolveModel('deepseek/deepseek-v4-flash')
 

package/dist/agent.d.ts

@@ -89,6 +89,8 @@ export declare class Agent {
     private installingExtension?;
     private readonly activeHandles;
     constructor(config: AgentConfig);
+    /** The configured model for this agent. */
+    get model(): Model;
     /**
      * Append content to the system prompt. This is a one-time mutation
      * typically called by extensions at install time (e.g. the skills
@@ -157,6 +159,10 @@ export declare class Agent {
     run(request: AgentRequest): RunHandle;
     private mergeTools;
     private executeTurn;
+    private executeTurnIteration;
+    private handleNoToolCalls;
+    private handleTurnError;
+    private generateModelResponse;
     /**
      * Build the response, run beforeResponse + afterTurn hooks, and return.
      * All turn exit paths go through here so extensions (session, memory,
@@ -171,6 +177,8 @@ export declare class Agent {
      * observability extensions can inspect it via `afterTurn`.
      */
     private finishWithError;
+    private processInternalCalls;
+    private executeToolBatch;
     private executeToolCall;
     /**
      * Race a promise against an abort signal. Returns `undefined` if the

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -34,6 +34,10 @@ export class Agent {
             this.tools.set(tool.name, tool);
         }
     }
+    /** The configured model for this agent. */
+    get model() {
+        return this.config.model;
+    }
     // ── System Prompt ──────────────────────────────────────────────────
     /**
      * Append content to the system prompt. This is a one-time mutation
@@ -198,7 +202,7 @@ export class Agent {
         turn.halt = (reason) => handle.halt(reason);
         // Kick off the turn. We store the promise on the handle so `handle.done`
         // and `await handle` both resolve to the same result.
-        handle.done = this.executeTurn(turn, maxIter, steeringQueue).finally(() => {
+        handle.done = this.executeTurn(turn, maxIter, steeringQueue, handle).finally(() => {
             this.activeHandles.delete(handle);
         });
         return handle;
@@ -209,7 +213,7 @@ export class Agent {
             all.set(t.name, t);
         return [...all.values()];
     }
-    async executeTurn(turn, maxIter, steeringQueue) {
+    async executeTurn(turn, maxIter, steeringQueue, handle) {
         let iterations = 0;
         const allToolCalls = [];
         try {
@@ -218,197 +222,161 @@ export class Agent {
             // beforeContext — last chance to modify context before the LLM loop.
             await this.runHooks('beforeContext', { turn });
             for (;;) {
-                // ── Check halt ──
-                if (turn.signal.aborted) {
-                    return await this.finishTurn(turn, '', 'halted', iterations, allToolCalls);
-                }
-                // ── Check max iterations ──
-                if (iterations >= maxIter) {
-                    return await this.finishTurn(turn, '', 'max_iterations', iterations, allToolCalls);
-                }
-                // ── Drain steering messages ──
-                this.drainSteering(turn, steeringQueue);
-                // ── beforeLLM ──
-                const modelRequest = {
-                    messages: turn.messages,
-                    tools: turn.tools.length > 0 ? turn.tools.map(toToolDefinition) : undefined,
-                    systemPrompt: turn.systemPrompt,
-                    temperature: this.config.temperature,
-                    maxTokens: this.config.maxTokens,
-                    reasoningEffort: this.config.reasoningEffort,
-                    providerOptions: this.config.providerOptions,
-                    signal: turn.signal,
-                };
-                const beforeLLMResult = await this.runHooks('beforeLLM', { turn, modelRequest });
-                // Halt may have been called during beforeLLM hooks.
-                if (turn.signal.aborted) {
-                    return await this.finishTurn(turn, '', 'halted', iterations, allToolCalls);
-                }
-                let modelResponse;
-                if (beforeLLMResult.skipped && beforeLLMResult.value) {
-                    modelResponse = beforeLLMResult.value;
-                }
-                else {
-                    try {
-                        modelResponse = await this.config.model.generate(modelRequest);
-                    }
-                    catch (err) {
-                        if (turn.signal.aborted) {
-                            return await this.finishTurn(turn, '', 'halted', iterations, allToolCalls);
-                        }
-                        throw err;
-                    }
-                }
-                // ── afterLLM ──
-                await this.runHooks('afterLLM', { turn, modelRequest, modelResponse });
+                const result = await this.executeTurnIteration(turn, maxIter, steeringQueue, handle, iterations, allToolCalls);
+                if (result.status === 'finish')
+                    return result.response;
                 iterations++;
-                // Add the assistant message to the conversation.
-                turn.messages.push(modelResponse.message);
-                // ── Halt may have been called during afterLLM hooks ──
-                if (turn.signal.aborted) {
-                    return await this.finishTurn(turn, messageContentToText(modelResponse.message.content), 'halted', iterations, allToolCalls);
-                }
-                // ── No tool calls → final response (unless steering pending) ──
-                const toolCalls = modelResponse.message.toolCalls;
-                if (!toolCalls || toolCalls.length === 0) {
-                    // If steering messages arrived during the LLM call, don't end
-                    // the turn — drain them and loop so the agent can respond.
-                    if (steeringQueue.length > 0) {
-                        this.drainSteering(turn, steeringQueue);
-                        continue;
-                    }
-                    return await this.finishTurn(turn, messageContentToText(modelResponse.message.content), 'stop', iterations, allToolCalls);
-                }
-                // ── Separate external (pass-through) from internal (execute) tool calls ──
-                const externalCalls = [];
-                const internalCalls = [];
-                for (const tc of toolCalls) {
-                    const tool = turn.tools.find((t) => t.name === tc.name);
-                    if (tool?.external)
-                        externalCalls.push(tc);
-                    else
-                        internalCalls.push(tc);
-                }
-                // ── External tool calls → return to caller for execution ──
-                if (externalCalls.length > 0) {
-                    allToolCalls.push(...externalCalls);
-                    // If there are also internal calls in this batch, execute those first
-                    // (the model may have mixed both in one response). The external calls
-                    // are still returned — the caller will see them and the internal results.
-                    if (internalCalls.length > 0) {
-                        allToolCalls.push(...internalCalls);
-                        if (turn.signal.aborted) {
-                            return await this.finishTurn(turn, '', 'halted', iterations, allToolCalls);
-                        }
-                        const mixedResults = await Promise.all(internalCalls.map(async (toolCall) => {
-                            const beforeToolCtx = { turn, toolCall };
-                            const beforeToolResult = await this.runHooks('beforeTool', beforeToolCtx);
-                            let toolResult;
-                            if (beforeToolResult.skipped && beforeToolResult.value) {
-                                toolResult = beforeToolResult.value;
-                            }
-                            else {
-                                toolResult = await this.executeToolCall(toolCall, turn);
-                            }
-                            const afterToolCtx = { turn, toolCall, toolResult };
-                            const afterToolResult = await this.runHooks('afterTool', afterToolCtx);
-                            if (afterToolResult.value) {
-                                toolResult = afterToolResult.value;
-                            }
-                            return { toolCall, toolResult };
-                        }));
-                        for (const { toolCall, toolResult } of mixedResults) {
-                            turn.messages.push({
-                                role: 'tool',
-                                content: toolResult.content,
-                                toolCallId: toolCall.id,
-                                name: toolCall.name,
-                            });
-                        }
-                        // Drain steering after mixed tool results too.
-                        this.drainSteering(turn, steeringQueue);
-                    }
-                    // Return external tool calls to the caller. The assistant message
-                    // (with toolCalls) is already in turn.messages from the push above.
-                    return await this.finishTurn(turn, messageContentToText(modelResponse.message.content), 'tool_calls', iterations, allToolCalls, externalCalls);
-                }
-                // ── Execute internal tool calls ──
-                allToolCalls.push(...internalCalls);
-                // Check halt before starting the batch.
-                if (turn.signal.aborted) {
-                    return await this.finishTurn(turn, '', 'halted', iterations, allToolCalls);
-                }
-                // Execute all internal tool calls in the batch concurrently.
-                // Each tool call runs its beforeTool → execute → afterTool pipeline
-                // independently. Results are collected in order and appended to
-                // turn.messages after all complete, preserving the model's ordering.
-                const results = await Promise.all(internalCalls.map(async (toolCall) => {
-                    // beforeTool — can short-circuit with a synthetic result.
-                    const beforeToolCtx = { turn, toolCall };
-                    const beforeToolResult = await this.runHooks('beforeTool', beforeToolCtx);
-                    let toolResult;
-                    if (beforeToolResult.skipped && beforeToolResult.value) {
-                        toolResult = beforeToolResult.value;
-                    }
-                    else {
-                        toolResult = await this.executeToolCall(toolCall, turn);
-                    }
-                    // afterTool — can modify the result.
-                    const afterToolCtx = { turn, toolCall, toolResult };
-                    const afterToolResult = await this.runHooks('afterTool', afterToolCtx);
-                    if (afterToolResult.value) {
-                        toolResult = afterToolResult.value;
-                    }
-                    return { toolCall, toolResult };
-                }));
-                // Append results to messages in the original order.
-                for (const { toolCall, toolResult } of results) {
-                    turn.messages.push({
-                        role: 'tool',
-                        content: toolResult.content,
-                        toolCallId: toolCall.id,
-                        name: toolCall.name,
-                    });
-                }
-                // ── Drain steering messages right after tool results ──
-                // This ensures the model sees steering directives immediately
-                // alongside tool results, rather than waiting for the next
-                // loop iteration's drain at the top.
-                this.drainSteering(turn, steeringQueue);
-                // Loop continues — the model will see the tool results.
             }
         }
         catch (err) {
-            if (turn.signal.aborted) {
-                return await this.finishTurn(turn, '', 'halted', iterations, allToolCalls);
+            return await this.handleTurnError(turn, err, iterations, allToolCalls);
+        }
+    }
+    async executeTurnIteration(turn, maxIter, steeringQueue, handle, iterations, allToolCalls) {
+        // ── Check halt ──
+        if (turn.signal.aborted) {
+            return { status: 'finish', response: await this.finishTurn(turn, '', 'halted', iterations, allToolCalls) };
+        }
+        // ── Check max iterations ──
+        if (iterations >= maxIter) {
+            return { status: 'finish', response: await this.finishTurn(turn, '', 'max_iterations', iterations, allToolCalls) };
+        }
+        // ── Drain steering messages ──
+        this.drainSteering(turn, steeringQueue);
+        const modelResponse = await this.generateModelResponse(turn);
+        if (!modelResponse) {
+            return { status: 'finish', response: await this.finishTurn(turn, '', 'halted', iterations, allToolCalls) };
+        }
+        // Add the assistant message to the conversation.
+        turn.messages.push(modelResponse.message);
+        // ── Emit text blurb immediately upon arrival ──
+        const blurbText = messageContentToText(modelResponse.message.content);
+        if (blurbText.trim()) {
+            try {
+                turn.request.onMessage?.(blurbText);
             }
-            // Fire onError hooks — extensions can observe or recover.
-            // Hooks take precedence over the error policy.
-            const errorResult = await this.runHooks('onError', { turn, error: err });
-            if (errorResult.skipped && errorResult.value) {
-                const response = errorResult.value;
-                turn.response = response;
-                await this.runHooks('afterTurn', { turn });
-                return response;
+            catch (err) {
+                console.error('[agent] request.onMessage error:', err);
             }
-            // No hook recovered — apply the configured error policy.
-            const policy = this.config.errorPolicy ?? DEFAULT_ERROR_POLICY;
-            if (policy === 'throw') {
-                throw err;
+            handle?.emitMessage(blurbText);
+        }
+        // ── Halt may have been called during afterLLM hooks ──
+        if (turn.signal.aborted) {
+            return { status: 'finish', response: await this.finishTurn(turn, blurbText, 'halted', iterations + 1, allToolCalls) };
+        }
+        // ── No tool calls → final response (unless steering pending) ──
+        const toolCalls = modelResponse.message.toolCalls;
+        if (!toolCalls || toolCalls.length === 0) {
+            const result = await this.handleNoToolCalls(turn, modelResponse, steeringQueue, iterations + 1, allToolCalls);
+            if (result.status === 'finish')
+                return { status: 'finish', response: result.response };
+            return { status: 'continue' };
+        }
+        // ── Separate external (pass-through) from internal (execute) tool calls ──
+        const externalCalls = [];
+        const internalCalls = [];
+        for (const tc of toolCalls) {
+            const tool = turn.tools.find((t) => t.name === tc.name);
+            if (tool?.external)
+                externalCalls.push(tc);
+            else
+                internalCalls.push(tc);
+        }
+        // ── External tool calls → return to caller for execution ──
+        if (externalCalls.length > 0) {
+            allToolCalls.push(...externalCalls);
+            if (internalCalls.length > 0) {
+                const haltedResponse = await this.processInternalCalls(turn, internalCalls, allToolCalls, steeringQueue, iterations + 1);
+                if (haltedResponse)
+                    return { status: 'finish', response: haltedResponse };
             }
-            if (policy === 'fallback') {
-                return await this.finishWithError(turn, err, iterations, allToolCalls);
+            // Return external tool calls to the caller. The assistant message
+            // (with toolCalls) is already in turn.messages from the push above.
+            return { status: 'finish', response: await this.finishTurn(turn, messageContentToText(modelResponse.message.content), 'tool_calls', iterations + 1, allToolCalls, externalCalls) };
+        }
+        // ── Execute internal tool calls ──
+        const haltedResponse = await this.processInternalCalls(turn, internalCalls, allToolCalls, steeringQueue, iterations + 1);
+        if (haltedResponse)
+            return { status: 'finish', response: haltedResponse };
+        return { status: 'continue' };
+    }
+    async handleNoToolCalls(turn, modelResponse, steeringQueue, iterations, allToolCalls) {
+        const textContent = messageContentToText(modelResponse.message.content).trim();
+        if (!textContent) {
+            turn.messages.push({
+                role: 'user',
+                content: 'You sent an empty response. Please provide a meaningful response to the last completed task. Do not acknowledge this empty response, just provide the expected output.'
+            });
+            return { status: 'continue' };
+        }
+        if (steeringQueue.length > 0) {
+            this.drainSteering(turn, steeringQueue);
+            return { status: 'continue' };
+        }
+        return { status: 'finish', response: await this.finishTurn(turn, textContent, 'stop', iterations, allToolCalls) };
+    }
+    async handleTurnError(turn, err, iterations, allToolCalls) {
+        if (turn.signal.aborted) {
+            return await this.finishTurn(turn, '', 'halted', iterations, allToolCalls);
+        }
+        // Fire onError hooks — extensions can observe or recover.
+        // Hooks take precedence over the error policy.
+        const errorResult = await this.runHooks('onError', { turn, error: err });
+        if (errorResult.skipped && errorResult.value) {
+            const response = errorResult.value;
+            turn.response = response;
+            await this.runHooks('afterTurn', { turn });
+            return response;
+        }
+        // No hook recovered — apply the configured error policy.
+        const policy = this.config.errorPolicy ?? DEFAULT_ERROR_POLICY;
+        if (policy === 'throw') {
+            throw err;
+        }
+        if (policy === 'fallback') {
+            return await this.finishWithError(turn, err, iterations, allToolCalls);
+        }
+        // Custom policy function — return a response to recover,
+        // return undefined to rethrow.
+        const customResponse = await policy({ error: err, turn });
+        if (customResponse) {
+            turn.response = customResponse;
+            await this.runHooks('afterTurn', { turn });
+            return customResponse;
+        }
+        throw err;
+    }
+    async generateModelResponse(turn) {
+        const modelRequest = {
+            messages: turn.messages,
+            tools: turn.tools.length > 0 ? turn.tools.map(toToolDefinition) : undefined,
+            systemPrompt: turn.systemPrompt,
+            temperature: this.config.temperature,
+            maxTokens: this.config.maxTokens,
+            reasoningEffort: this.config.reasoningEffort,
+            providerOptions: this.config.providerOptions,
+            signal: turn.signal,
+        };
+        const beforeLLMResult = await this.runHooks('beforeLLM', { turn, modelRequest });
+        // Halt may have been called during beforeLLM hooks.
+        if (turn.signal.aborted)
+            return undefined;
+        let modelResponse;
+        if (beforeLLMResult.skipped && beforeLLMResult.value) {
+            modelResponse = beforeLLMResult.value;
+        }
+        else {
+            try {
+                modelResponse = await this.config.model.generate(modelRequest);
             }
-            // Custom policy function — return a response to recover,
-            // return undefined to rethrow.
-            const customResponse = await policy({ error: err, turn });
-            if (customResponse) {
-                turn.response = customResponse;
-                await this.runHooks('afterTurn', { turn });
-                return customResponse;
+            catch (err) {
+                if (turn.signal.aborted)
+                    return undefined;
+                throw err;
             }
-            throw err;
         }
+        await this.runHooks('afterLLM', { turn, modelRequest, modelResponse });
+        return modelResponse;
     }
     /**
      * Build the response, run beforeResponse + afterTurn hooks, and return.
@@ -440,6 +408,42 @@ export class Agent {
         await this.runHooks('afterTurn', { turn });
         return response;
     }
+    async processInternalCalls(turn, internalCalls, allToolCalls, steeringQueue, iterations) {
+        allToolCalls.push(...internalCalls);
+        if (turn.signal.aborted) {
+            return await this.finishTurn(turn, '', 'halted', iterations, allToolCalls);
+        }
+        await this.executeToolBatch(turn, internalCalls);
+        this.drainSteering(turn, steeringQueue);
+        return undefined;
+    }
+    async executeToolBatch(turn, internalCalls) {
+        const results = await Promise.all(internalCalls.map(async (toolCall) => {
+            const beforeToolCtx = { turn, toolCall };
+            const beforeToolResult = await this.runHooks('beforeTool', beforeToolCtx);
+            let toolResult;
+            if (beforeToolResult.skipped && beforeToolResult.value) {
+                toolResult = beforeToolResult.value;
+            }
+            else {
+                toolResult = await this.executeToolCall(toolCall, turn);
+            }
+            const afterToolCtx = { turn, toolCall, toolResult };
+            const afterToolResult = await this.runHooks('afterTool', afterToolCtx);
+            if (afterToolResult.value) {
+                toolResult = afterToolResult.value;
+            }
+            return { toolCall, toolResult };
+        }));
+        for (const { toolCall, toolResult } of results) {
+            turn.messages.push({
+                role: 'tool',
+                content: toolResult.content,
+                toolCallId: toolCall.id,
+                name: toolCall.name,
+            });
+        }
+    }
     async executeToolCall(toolCall, turn) {
         const tool = turn.tools.find((t) => t.name === toolCall.name);
         if (!tool) {
@@ -524,16 +528,9 @@ export class Agent {
     drainSteering(turn, steeringQueue) {
         while (steeringQueue.length > 0) {
             const msg = steeringQueue.shift();
-            // Inject a system directive + user message pair. The system
-            // message tells the model to treat the steering as an
-            // interruption; the user message carries the actual content.
-            // Models deprioritize mid-conversation system messages, so we
-            // pair it with a user message (which models can't ignore) and
-            // use the system message to frame it as a hard redirect.
-            turn.messages.push({
-                role: 'system',
-                content: '[steering] The user has sent a new directive. You must address it immediately. Do not continue the previous task — pivot to the user\'s new request now.',
-            });
+            // Inject the steering directive as a user message. We do not inject a
+            // role: 'system' message here because LLM providers (Anthropic, Gemini,
+            // OpenAI) forbid or reject mid-conversation system messages.
             turn.messages.push({
                 role: 'user',
                 content: `[steering] ${msg}`,
@@ -578,6 +575,7 @@ export class Agent {
 class RunHandleImpl {
     abort;
     steeringQueue;
+    messageListeners = [];
     _done;
     constructor(abort, steeringQueue) {
         this.abort = abort;
@@ -606,6 +604,20 @@ class RunHandleImpl {
     halt(reason = 'halted') {
         this.abort.abort(reason);
     }
+    onMessage(callback) {
+        this.messageListeners.push(callback);
+        return this;
+    }
+    emitMessage(message) {
+        for (const listener of this.messageListeners) {
+            try {
+                listener(message);
+            }
+            catch (err) {
+                console.error('[handle] onMessage listener error:', err);
+            }
+        }
+    }
     // Thenable — allows `await handle` to work.
     then(onfulfilled, onrejected) {
         return this.done.then(onfulfilled, onrejected);