@openrouter/agent 0.3.2 → 0.5.0

package/esm/lib/model-result.js

@@ -5,32 +5,48 @@ import { applyNextTurnParamsToRequest, executeNextTurnParamsFunctions, } from '.
 import { ReusableReadableStream } from './reusable-stream.js';
 import { isStopConditionMet, stepCountIs } from './stop-conditions.js';
 import { buildItemsStream, buildResponsesMessageStream, buildToolCallStream, consumeStreamForCompletion, extractReasoningDeltas, extractResponsesMessageFromResponse, extractTextDeltas, extractTextFromResponse, extractToolCallsFromResponse, extractToolDeltas, itemsStreamHandlers, streamTerminationEvents, } from './stream-transformers.js';
-import { hasTypeProperty, isFunctionCallItem, isOutputTextDeltaEvent, isReasoningDeltaEvent, isResponseCompletedEvent, isResponseFailedEvent, isResponseIncompleteEvent, } from './stream-type-guards.js';
+import { hasTypeProperty, isFunctionCallItem, isFunctionCallOutputItem, isOutputTextDeltaEvent, isReasoningDeltaEvent, isResponseCompletedEvent, isResponseFailedEvent, isResponseIncompleteEvent, isServerToolResultItem, } from './stream-type-guards.js';
 import { resolveContext, ToolContextStore } from './tool-context.js';
 import { ToolEventBroadcaster } from './tool-event-broadcaster.js';
-import { executeTool } from './tool-executor.js';
-import { hasExecuteFunction, isToolCallOutputEvent } from './tool-types.js';
+import { applyOnResponseReceivedHooks, executeTool } from './tool-executor.js';
+import { isAutoResolvableTool, isClientTool, isServerTool, isToolCallOutputEvent, } from './tool-types.js';
 /**
  * Default maximum number of tool execution steps if no stopWhen is specified.
  * This prevents infinite loops in tool execution.
  */
 const DEFAULT_MAX_STEPS = 5;
 /**
- * Type guard for stream event with toReadableStream method
- * Checks constructor name, prototype, and method availability
+ * Typeguard for plain-object records (non-null, non-array).
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Human-readable label for a value that failed the `isRecord` check. Used
+ * exclusively to make `toModelOutput` misuse errors specific.
+ */
+function describeNonRecord(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    return typeof value;
+}
+/**
+ * Type guard for stream event responses
+ * Checks constructor name and readable stream behavior
  */
 function isEventStream(value) {
     if (value === null || typeof value !== 'object') {
         return false;
     }
-    // Check constructor name for EventStream
-    const constructorName = Object.getPrototypeOf(value)?.constructor?.name;
-    if (constructorName === 'EventStream') {
+    if (typeof ReadableStream !== 'undefined' && value instanceof ReadableStream) {
         return true;
     }
-    // Fallback: check for toReadableStream method (may be on prototype)
     const maybeStream = value;
-    return typeof maybeStream.toReadableStream === 'function';
+    return typeof maybeStream.getReader === 'function';
 }
 /**
  * A wrapper around a streaming response that provides multiple consumption patterns.
@@ -236,13 +252,10 @@ export class ModelResult {
     }
     /**
      * Type guard to check if a value is a non-streaming response
-     * Only requires 'output' field and absence of 'toReadableStream' method
+     * Only requires 'output' field and absence of readable stream behavior
      */
     isNonStreamingResponse(value) {
-        return (value !== null &&
-            typeof value === 'object' &&
-            'output' in value &&
-            !('toReadableStream' in value));
+        return (value !== null && typeof value === 'object' && 'output' in value && !isEventStream(value));
     }
     // =========================================================================
     // Extracted Helper Methods for executeToolsIfNeeded
@@ -350,17 +363,23 @@ export class ModelResult {
             : [
                 stopWhen,
             ];
+        const isFunctionCallOutput = (tr) => tr.type === 'function_call_output';
+        const isServerToolResult = (tr) => tr.type !== 'function_call_output';
         return isStopConditionMet({
             stopConditions,
             steps: this.allToolExecutionRounds.map((round) => ({
                 stepType: 'continue',
                 text: extractTextFromResponse(round.response),
                 toolCalls: round.toolCalls,
-                toolResults: round.toolResults.map((tr) => ({
+                // `toolResults` is client-tool-centric; server-tool output items are
+                // surfaced on `serverToolResults` so stop conditions can react to
+                // either class of result.
+                toolResults: round.toolResults.filter(isFunctionCallOutput).map((tr) => ({
                     toolCallId: tr.callId,
                     toolName: round.toolCalls.find((tc) => tc.id === tr.callId)?.name ?? '',
                     result: typeof tr.output === 'string' ? JSON.parse(tr.output) : tr.output,
                 })),
+                serverToolResults: round.toolResults.filter(isServerToolResult),
                 response: round.response,
                 usage: round.response.usage,
                 finishReason: undefined,
@@ -368,21 +387,32 @@ export class ModelResult {
         });
     }
     /**
-     * Check if any tool calls have execute functions.
+     * Check if any tool calls can be auto-resolved in the current turn.
      * Used to determine if automatic tool execution should be attempted.
      *
+     * A tool call is auto-resolvable if its tool has either an `execute` function
+     * (regular or generator) or an `onToolCalled` hook (HITL). HITL tools are
+     * included here because their hook fires before the model's follow-up request,
+     * even when the hook ultimately decides to pause by returning `null`.
+     *
      * @param toolCalls - The tool calls to check
-     * @returns True if at least one tool call has an executable function
+     * @returns True if at least one tool call is auto-resolvable
      */
     hasExecutableToolCalls(toolCalls) {
         return toolCalls.some((toolCall) => {
-            const tool = this.options.tools?.find((t) => t.function.name === toolCall.name);
-            return tool && hasExecuteFunction(tool);
+            const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
+            return tool && isAutoResolvableTool(tool);
         });
     }
+    /**
+     * A manual tool call is one whose tool has neither an `execute` function nor
+     * an `onToolCalled` hook — i.e. the caller is expected to produce the output
+     * externally. HITL tools are auto-resolvable even when they pause, so they
+     * are not classified as manual here.
+     */
     isManualToolCall(item) {
-        const tool = this.options.tools?.find((t) => t.function.name === item.name);
-        return !!tool && !hasExecuteFunction(tool);
+        const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === item.name);
+        return !!tool && !isAutoResolvableTool(tool);
     }
     /**
      * Execute tools that can auto-execute (don't require approval) in parallel.
@@ -393,11 +423,15 @@ export class ModelResult {
      */
     async executeAutoApproveTools(toolCalls, turnContext) {
         const toolCallPromises = toolCalls.map(async (tc) => {
-            const tool = this.options.tools?.find((t) => t.function.name === tc.name);
-            if (!tool || !hasExecuteFunction(tool)) {
+            const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === tc.name);
+            if (!tool || !isAutoResolvableTool(tool)) {
                 return null;
             }
             const result = await executeTool(tool, tc, turnContext, undefined, this.contextStore ?? undefined, this.options.sharedContextSchema);
+            if (result === null) {
+                // HITL tool paused — no unsent result for this call in this round
+                return null;
+            }
             if (result.error) {
                 return createRejectedResult(tc.id, String(tc.name), result.error.message);
             }
@@ -464,18 +498,81 @@ export class ModelResult {
         this.finalResponse = currentResponse;
         return true; // Pause for approval
     }
+    /**
+     * Persist state when one or more HITL tools paused during a round.
+     *
+     * Mirrors `handleApprovalCheck` so paused HITL calls are surfaced through
+     * `pendingToolCalls` (visible via `getPendingToolCalls()` / `getState()`).
+     * Sets the status to `awaiting_hitl` so the caller can discriminate HITL
+     * pauses from approval pauses.
+     *
+     * Already-executed results from the same round are persisted on the turn's
+     * message history via `saveToolResultsToState` (called by the outer loop
+     * before this helper) — no need to duplicate them in `unsentToolResults`.
+     *
+     * @param currentResponse - The response that produced the paused tool calls
+     * @param pausedCalls - HITL tool calls whose `onToolCalled` returned `null`
+     */
+    async persistHitlPause(currentResponse, pausedCalls) {
+        this.finalResponse = currentResponse;
+        if (!this.stateAccessor) {
+            return;
+        }
+        const stateUpdates = {
+            pendingToolCalls: pausedCalls,
+            status: 'awaiting_hitl',
+        };
+        await this.saveStateSafely(stateUpdates);
+    }
+    /**
+     * Compute the `output` payload sent to the model for a successfully
+     * settled tool execution. Routes through `toModelOutput` when the tool
+     * defines one (which may itself throw to surface an error), falls back to
+     * `JSON.stringify(result)` otherwise, and emits an error envelope when the
+     * executor itself reported an error.
+     */
+    async computeToolOutputForModel(value) {
+        if (value.result.error) {
+            return JSON.stringify({
+                error: value.result.error.message,
+            });
+        }
+        if (!isAutoResolvableTool(value.tool) || !value.tool.function.toModelOutput) {
+            return JSON.stringify(value.result.result);
+        }
+        // Arguments have already been validated upstream by the tool's Zod
+        // inputSchema (which must be a ZodObject), so the runtime shape is
+        // always a record here. A non-record value here signals a real upstream
+        // bug we want surfaced, not a case to paper over with `{}`.
+        const rawArgs = value.toolCall.arguments;
+        if (!isRecord(rawArgs)) {
+            throw new Error(`toolCall.arguments for "${value.toolCall.name}" must be an object after Zod validation, got ${describeNonRecord(rawArgs)}`);
+        }
+        const modelOutputResult = await value.tool.function.toModelOutput({
+            output: value.result.result,
+            input: rawArgs,
+        });
+        if (modelOutputResult.type === 'content') {
+            return modelOutputResult.value;
+        }
+        return JSON.stringify(value.result.result);
+    }
     /**
      * Execute all tools in a single round in parallel.
      * Emits tool.result events after tool execution completes.
      *
      * @param toolCalls - The tool calls to execute
      * @param turnContext - The current turn context
-     * @returns Array of function call outputs formatted for the API
+     * @returns Object with the function call outputs formatted for the API and
+     *   the list of HITL tool calls that paused (returned `null` from
+     *   `onToolCalled`). Callers should break out of the execution loop when
+     *   `pausedCalls` is non-empty rather than sending an incomplete set of
+     *   outputs back to the model.
      */
     async executeToolRound(toolCalls, turnContext) {
         const toolCallPromises = toolCalls.map(async (toolCall) => {
-            const tool = this.options.tools?.find((t) => t.function.name === toolCall.name);
-            if (!tool || !hasExecuteFunction(tool)) {
+            const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
+            if (!tool || !isAutoResolvableTool(tool)) {
                 return null;
             }
             // Check if arguments failed to parse (remained as string instead of object)
@@ -511,6 +608,13 @@ export class ModelResult {
                 }
                 : undefined;
             const result = await executeTool(tool, toolCall, turnContext, onPreliminaryResult, this.contextStore ?? undefined, this.options.sharedContextSchema);
+            if (result === null) {
+                // HITL tool paused — surface as manual (no output this round)
+                return {
+                    type: 'paused',
+                    toolCall,
+                };
+            }
             return {
                 type: 'execution',
                 toolCall,
@@ -521,6 +625,7 @@ export class ModelResult {
         });
         const settledResults = await Promise.allSettled(toolCallPromises);
         const toolResults = [];
+        const pausedCalls = [];
         for (let i = 0; i < settledResults.length; i++) {
             const settled = settledResults[i];
             const originalToolCall = toolCalls[i];
@@ -561,32 +666,21 @@ export class ModelResult {
                 });
                 continue;
             }
+            if (value.type === 'paused') {
+                // HITL tool returned null — record the pause so the caller can break
+                // out of the outer loop before attempting a follow-up request with an
+                // incomplete set of outputs. The call will be surfaced via state
+                // (pendingToolCalls + status='awaiting_hitl') for manual resume.
+                pausedCalls.push(value.toolCall);
+                continue;
+            }
             const toolResult = (value.result.error
                 ? {
                     error: value.result.error.message,
                 }
                 : value.result.result);
             this.broadcastToolResult(value.toolCall.id, toolResult, value.preliminaryResultsForCall.length > 0 ? value.preliminaryResultsForCall : undefined);
-            let outputForModel;
-            if (value.result.error) {
-                outputForModel = JSON.stringify({
-                    error: value.result.error.message,
-                });
-            }
-            else if (value.tool.function.toModelOutput) {
-                // toModelOutput exists - call it (may throw, which surfaces the error)
-                const modelOutputResult = await value.tool.function.toModelOutput({
-                    output: value.result.result,
-                    input: value.toolCall.arguments,
-                });
-                outputForModel =
-                    modelOutputResult.type === 'content'
-                        ? modelOutputResult.value
-                        : JSON.stringify(value.result.result);
-            }
-            else {
-                outputForModel = JSON.stringify(value.result.result);
-            }
+            const outputForModel = await this.computeToolOutputForModel(value);
             const executedOutput = {
                 type: 'function_call_output',
                 id: `output_${value.toolCall.id}`,
@@ -600,7 +694,10 @@ export class ModelResult {
                 timestamp: Date.now(),
             });
         }
-        return toolResults;
+        return {
+            toolResults,
+            pausedCalls,
+        };
     }
     /**
      * Resolve async functions for the current turn.
@@ -725,6 +822,72 @@ export class ModelResult {
         const { stopWhen: _, state: _s, requireApproval: _r, approveToolCalls: _a, rejectToolCalls: _rj, context: _c, ...rest } = this.options.request;
         return rest;
     }
+    /**
+     * Apply `onResponseReceived` hooks to the freshly-supplied input items
+     * only, without re-hooking historical items that live in
+     * `currentState.messages`. Historical `function_call` items are passed to
+     * `applyOnResponseReceivedHooks` purely as callId → toolName
+     * name-resolution context and are dropped from the returned array.
+     *
+     * This keeps hooks idempotent across `callModel` invocations on the same
+     * conversation: the first call hooks the caller-supplied output, and
+     * subsequent calls (which rehydrate state) do not re-fire it.
+     *
+     * @param freshItems - Items newly supplied this turn (not yet hooked).
+     *   May contain any mix of InputsUnion array members — only
+     *   `function_call_output` items are affected by hooks; everything else
+     *   is returned unchanged.
+     * @param historicalItems - Existing messages from loaded state. Only
+     *   `function_call` entries are consulted for name resolution; no other
+     *   items are inspected and none are mutated.
+     * @param turnContext - Turn context for hook invocation
+     * @returns The fresh items in original order, with `output` rewritten on
+     *   any `function_call_output` whose matching HITL tool defines
+     *   `onResponseReceived`.
+     */
+    async applyHooksToFreshItems(freshItems, historicalItems, turnContext) {
+        if (freshItems.length === 0) {
+            return freshItems;
+        }
+        // Collect function_call items from history so the hook executor can
+        // resolve callId -> toolName without us having to mirror that logic.
+        const historyArray = Array.isArray(historicalItems)
+            ? historicalItems
+            : [
+                historicalItems,
+            ];
+        const functionCallItems = [];
+        for (const item of historyArray) {
+            if (isFunctionCallItem(item)) {
+                functionCallItems.push(item);
+            }
+        }
+        // Build a synthetic input that puts the historical function_calls
+        // BEFORE the fresh items. `applyOnResponseReceivedHooks` only rewrites
+        // function_call_output items, so the function_call items are seen only
+        // as name-resolution context.
+        const syntheticInput = [
+            ...functionCallItems,
+            ...freshItems,
+        ];
+        const hookedInput = await applyOnResponseReceivedHooks(syntheticInput, this.options.tools, turnContext, this.contextStore ?? undefined, this.options.sharedContextSchema);
+        if (hookedInput === syntheticInput) {
+            // No rewrites; return the originals unchanged.
+            return freshItems;
+        }
+        // Drop the leading function_call items we prepended; what remains is
+        // the fresh items in their original order (some with rewritten outputs).
+        const hookedArray = Array.isArray(hookedInput)
+            ? hookedInput
+            : [
+                hookedInput,
+            ];
+        if (hookedArray.length !== syntheticInput.length) {
+            // Shouldn't happen (hooks only rewrite in-place), but be conservative.
+            return freshItems;
+        }
+        return hookedArray.slice(functionCallItems.length);
+    }
     /**
      * Safely persist state with error handling.
      * Wraps state save operations to ensure failures are properly reported.
@@ -779,8 +942,14 @@ export class ModelResult {
                 const loadedState = await this.stateAccessor.load();
                 if (loadedState) {
                     this.currentState = loadedState;
-                    // Check if we're resuming from awaiting_approval with decisions
-                    if (loadedState.status === 'awaiting_approval' &&
+                    // Check if we're resuming from awaiting_approval or awaiting_hitl
+                    // with decisions. `awaiting_hitl` reuses `processApprovalDecisions`
+                    // because the resume mechanism is identical — the caller supplies
+                    // `approveToolCalls`/`rejectToolCalls` for paused call IDs, and we
+                    // re-invoke `executeTool` on approved calls (which re-runs
+                    // `onToolCalled` for HITL tools).
+                    const isResumableStatus = loadedState.status === 'awaiting_approval' || loadedState.status === 'awaiting_hitl';
+                    if (isResumableStatus &&
                         (this.approvedToolCalls.length > 0 || this.rejectedToolCalls.length > 0)) {
                         // Initialize context store before resuming so tools have access
                         if (this.options.context !== undefined) {
@@ -826,29 +995,55 @@ export class ModelResult {
             }
             // Resolve any async functions first
             let baseRequest = await this.resolveRequestForContext(initialContext);
-            // If we have state with existing messages, use those as input
-            if (this.currentState?.messages &&
+            // Split input into "historical" (already in state.messages) and "fresh"
+            // (newly supplied this turn). `onResponseReceived` must fire only for
+            // fresh items — re-hooking historical outputs on every callModel call
+            // would double-invoke non-idempotent hooks.
+            const hasLoadedHistory = !!this.currentState?.messages &&
                 Array.isArray(this.currentState.messages) &&
-                this.currentState.messages.length > 0) {
-                // Append new input to existing messages
+                this.currentState.messages.length > 0;
+            if (hasLoadedHistory && this.currentState) {
+                // `currentState.messages` is InputsUnion — keep it as that union so
+                // appendToMessages (which expects InputsUnion) accepts it directly.
+                const historicalMessages = this.currentState.messages;
+                // Normalize the caller-supplied input for this turn into an array of
+                // fresh items. Undefined stays undefined (no new items). The widening
+                // to BaseInputsUnion[] matches the signature of appendToMessages and
+                // mirrors the pre-existing pattern elsewhere in this file; the two
+                // union shapes (InputsUnion1 vs BaseInputsUnion1) describe the same
+                // SDK input items with different nominal types, and BaseInputsUnion
+                // already includes `any` in its element type, so the runtime shape
+                // is preserved either way.
                 const newInput = baseRequest.input;
-                if (newInput) {
-                    const inputArray = Array.isArray(newInput)
+                let freshItems;
+                if (newInput !== undefined) {
+                    freshItems = Array.isArray(newInput)
                         ? newInput
                         : [
                             newInput,
                         ];
-                    baseRequest = {
-                        ...baseRequest,
-                        input: appendToMessages(this.currentState.messages, inputArray),
-                    };
-                }
-                else {
-                    baseRequest = {
-                        ...baseRequest,
-                        input: this.currentState.messages,
-                    };
                 }
+                // Hook fresh items only (historical function_calls serve as
+                // name-resolution context). Leave historical items untouched.
+                const hookedFresh = freshItems
+                    ? await this.applyHooksToFreshItems(freshItems, historicalMessages, initialContext)
+                    : undefined;
+                baseRequest = {
+                    ...baseRequest,
+                    input: hookedFresh
+                        ? appendToMessages(historicalMessages, hookedFresh)
+                        : historicalMessages,
+                };
+            }
+            else if (baseRequest.input !== undefined) {
+                // No loaded history — everything in input is fresh. Hook the whole
+                // thing (non-array inputs pass through applyOnResponseReceivedHooks
+                // unchanged).
+                const hookedInput = await applyOnResponseReceivedHooks(baseRequest.input, this.options.tools, initialContext, this.contextStore ?? undefined, this.options.sharedContextSchema);
+                baseRequest = {
+                    ...baseRequest,
+                    input: hookedInput,
+                };
             }
             // Store resolved request with stream mode
             this.resolvedRequest = {
@@ -895,19 +1090,28 @@ export class ModelResult {
             numberOfTurns: this.allToolExecutionRounds.length + 1,
             // context is handled via contextStore, not on TurnContext
         };
+        // Track approved HITL calls that paused (onToolCalled returned null) —
+        // these stay in pendingToolCalls so the caller can resume them later.
+        const hitlPausedIds = new Set();
         // Process approvals - execute the approved tools
         for (const callId of this.approvedToolCalls) {
             const toolCall = pendingCalls.find((tc) => tc.id === callId);
             if (!toolCall) {
                 continue;
             }
-            const tool = this.options.tools?.find((t) => t.function.name === toolCall.name);
-            if (!tool || !hasExecuteFunction(tool)) {
+            const tool = this.options.tools?.find((t) => isClientTool(t) && t.function.name === toolCall.name);
+            if (!tool || !isAutoResolvableTool(tool)) {
                 // Can't execute, create error result
                 unsentResults.push(createRejectedResult(callId, String(toolCall.name), 'Tool not found or not executable'));
                 continue;
             }
             const result = await executeTool(tool, toolCall, turnContext, undefined, this.contextStore ?? undefined, this.options.sharedContextSchema);
+            if (result === null) {
+                // HITL tool paused on approval — keep the call visible to the caller
+                // via pendingToolCalls (status becomes 'awaiting_hitl' below).
+                hitlPausedIds.add(callId);
+                continue;
+            }
             if (result.error) {
                 unsentResults.push(createRejectedResult(callId, String(toolCall.name), result.error.message));
             }
@@ -923,15 +1127,32 @@ export class ModelResult {
             }
             unsentResults.push(createRejectedResult(callId, String(toolCall.name), 'Rejected by user'));
         }
-        // Remove processed calls from pending
+        // Remove processed calls from pending. Approved HITL calls that paused are
+        // NOT considered processed — they stay on pendingToolCalls so getPendingToolCalls()
+        // still surfaces them to the caller on resume.
         const processedIds = new Set([
             ...this.approvedToolCalls,
             ...this.rejectedToolCalls,
-        ]);
+        ].filter((id) => !hitlPausedIds.has(id)));
         const remainingPending = pendingCalls.filter((tc) => !processedIds.has(tc.id));
+        // Determine status:
+        //   - Any still-unprocessed approval-required call keeps us in 'awaiting_approval'
+        //   - Otherwise, any HITL paused call moves us to 'awaiting_hitl'
+        //   - Otherwise, we continue with 'in_progress'
+        const remainingUnresolvedApprovals = remainingPending.filter((tc) => !hitlPausedIds.has(tc.id));
+        let nextStatus;
+        if (remainingUnresolvedApprovals.length > 0) {
+            nextStatus = 'awaiting_approval';
+        }
+        else if (hitlPausedIds.size > 0) {
+            nextStatus = 'awaiting_hitl';
+        }
+        else {
+            nextStatus = 'in_progress';
+        }
         // Update state - conditionally include optional properties only if they have values
         const stateUpdates = {
-            status: remainingPending.length > 0 ? 'awaiting_approval' : 'in_progress',
+            status: nextStatus,
         };
         if (remainingPending.length > 0) {
             stateUpdates.pendingToolCalls = remainingPending;
@@ -952,8 +1173,8 @@ export class ModelResult {
             this.clearOptionalStateProperties(propsToClear);
             await this.saveStateSafely();
         }
-        // If we still have pending approvals, stop here
-        if (remainingPending.length > 0) {
+        // If we are paused (for approval or for HITL), stop here
+        if (nextStatus !== 'in_progress') {
             return;
         }
         // Otherwise, continue with tool execution using unsent results
@@ -972,7 +1193,16 @@ export class ModelResult {
         }
         // Convert to API format
         const toolOutputs = unsentResultsToAPIFormat(unsentResults);
-        // Build new input with tool results
+        // Build turn context for hook resolution
+        // numberOfTurns represents the current turn number (1-indexed after initial)
+        const turnContext = {
+            numberOfTurns: this.allToolExecutionRounds.length + 1,
+        };
+        // Append SDK-generated tool outputs directly — `onResponseReceived` is
+        // reserved for caller-supplied outputs (the resume-with-function-call-
+        // output path, hooked during init). SDK-produced outputs from auto-
+        // executed tools already went through the tool's own execute/generator
+        // pipeline and must not be mutated by the resume hook.
         const currentMessages = this.currentState.messages;
         const newInput = appendToMessages(currentMessages, toolOutputs);
         // Clear unsent results from state
@@ -984,12 +1214,11 @@ export class ModelResult {
         ]);
         await this.saveStateSafely();
         // Build request with the updated input
-        // numberOfTurns represents the current turn number (1-indexed after initial)
-        const turnContext = {
-            numberOfTurns: this.allToolExecutionRounds.length + 1,
-        };
         const baseRequest = await this.resolveRequestForContext(turnContext);
-        // Create request with the accumulated messages
+        // No hooking here: SDK-generated outputs are appended as-is and any
+        // caller-supplied items in `newInput` (carried over from init) were
+        // already hooked during `initStream` — re-hooking would double-fire
+        // non-idempotent hooks.
         const request = {
             ...baseRequest,
             input: newInput,
@@ -1025,8 +1254,12 @@ export class ModelResult {
         // biome-ignore lint: IIFE used for lazy initialization pattern
         this.toolExecutionPromise = (async () => {
             await this.initStream();
-            // If resuming from approval and still pending, don't continue
-            if (this.isResumingFromApproval && this.currentState?.status === 'awaiting_approval') {
+            // If resuming from approval or HITL pause and still pending, don't continue.
+            // `processApprovalDecisions` runs in initStream for resumes; if it left us
+            // paused (any remaining pending calls), the outer loop should not execute.
+            if (this.isResumingFromApproval &&
+                (this.currentState?.status === 'awaiting_approval' ||
+                    this.currentState?.status === 'awaiting_hitl')) {
                 return;
             }
             // Get initial response
@@ -1082,16 +1315,46 @@ export class ModelResult {
                 // Resolve async functions for this turn
                 await this.resolveAsyncFunctionsForTurn(turnContext);
                 // Execute tools
-                const toolResults = await this.executeToolRound(currentToolCalls, turnContext);
+                const { toolResults, pausedCalls } = await this.executeToolRound(currentToolCalls, turnContext);
+                // Server-tool output items are already-executed results in the
+                // response; collect them so toolResults presents a unified list.
+                const serverToolItems = [];
+                for (const item of currentResponse.output) {
+                    if (!hasTypeProperty(item)) {
+                        continue;
+                    }
+                    if (item.type === 'message' ||
+                        item.type === 'reasoning' ||
+                        item.type === 'function_call') {
+                        continue;
+                    }
+                    // Everything else is a server-tool output item (web_search_call,
+                    // image_generation_call, file_search_call, or generic
+                    // OutputServerToolItem covering openrouter:datetime and any new
+                    // SDK server tool types).
+                    if (isServerToolResultItem(item)) {
+                        serverToolItems.push(item);
+                    }
+                }
                 // Track execution round
                 this.allToolExecutionRounds.push({
                     round: currentRound,
                     toolCalls: currentToolCalls,
                     response: currentResponse,
-                    toolResults,
+                    toolResults: [
+                        ...toolResults,
+                        ...serverToolItems,
+                    ],
                 });
                 // Save tool results to state
                 await this.saveToolResultsToState(toolResults);
+                // If any HITL tools paused this round, stop here without making a
+                // follow-up request — sending an incomplete set of outputs would be
+                // incorrect. Persist the paused calls so the caller can resume later.
+                if (pausedCalls.length > 0) {
+                    await this.persistHitlPause(currentResponse, pausedCalls);
+                    return;
+                }
                 // Apply nextTurnParams
                 await this.applyNextTurnParams(currentToolCalls);
                 currentResponse = await this.makeFollowupRequest(currentResponse, toolResults, turnNumber);
@@ -1208,6 +1471,30 @@ export class ModelResult {
      * - function_call_output: Results from executed tools
      */
     getItemsStream() {
+        // Build the allowed-item-type scope from the tools actually passed to
+        // callModel, mirroring the compile-time rules that produce
+        // StreamableOutputItem<TTools>. A runtime predicate then drops items
+        // whose type isn't reachable in the narrowed union. The predicate's
+        // claim (`item is StreamableOutputItem<TTools>`) is sound because:
+        //   - `allowed` is constructed from the same tools that produced TTools
+        //   - `OutputServerToolItem.type` is `string` (open), so any non-client
+        //     item type is structurally assignable to it, covering generic /
+        //     unmapped server-tool outputs.
+        const scope = this.computeItemStreamScope();
+        const isInScope = (item) => {
+            if (scope.acceptAll) {
+                return true;
+            }
+            if (scope.allowed.has(item.type)) {
+                return true;
+            }
+            if (scope.acceptGenericServerItem &&
+                item.type !== 'function_call' &&
+                item.type !== 'function_call_output') {
+                return true;
+            }
+            return false;
+        };
         return async function* () {
             await this.initStream();
             if (!this.reusableStream && !this.finalResponse) {
@@ -1216,7 +1503,11 @@ export class ModelResult {
             // No tools — stream single turn directly (no broadcaster needed)
             if (!this.options.tools?.length) {
                 if (this.reusableStream) {
-                    yield* buildItemsStream(this.reusableStream);
+                    for await (const item of buildItemsStream(this.reusableStream)) {
+                        if (isInScope(item)) {
+                            yield item;
+                        }
+                    }
                 }
                 return;
             }
@@ -1228,7 +1519,9 @@ export class ModelResult {
             for await (const event of consumer) {
                 // Tool call outputs → yield directly as function_call_output items
                 if (isToolCallOutputEvent(event)) {
-                    yield event.output;
+                    if (isInScope(event.output)) {
+                        yield event.output;
+                    }
                     continue;
                 }
                 // Stream termination → reset items map for next turn
@@ -1243,7 +1536,7 @@ export class ModelResult {
                     const handler = itemsStreamHandlers[event.type];
                     if (handler) {
                         const result = handler(event, itemsInProgress);
-                        if (result) {
+                        if (result && isInScope(result)) {
                             yield result;
                         }
                     }
@@ -1252,6 +1545,98 @@ export class ModelResult {
             await executionPromise;
         }.call(this);
     }
+    /**
+     * Compute the runtime allow-list of item types that `getItemsStream()`
+     * may yield, derived from the tools actually passed to callModel. The
+     * three return modes correspond to the compile-time narrowing:
+     *
+     * - `acceptAll: true` — no tools or fully-unconstrained TTools; the
+     *   yielded union is the widest `StreamableOutputItem`.
+     * - Specific `allowed` set — client tools contribute
+     *   `function_call` / `function_call_output`; mapped server tools
+     *   contribute their SDK output item type literal
+     *   (`web_search_call`, `file_search_call`, `image_generation_call`).
+     * - `acceptGenericServerItem: true` — at least one server tool has a
+     *   type the agent SDK does not have a dedicated output mapping for
+     *   (e.g. `openrouter:datetime`, `mcp`, new SDK additions). Any
+     *   non-client item type is accepted because these items pass through
+     *   as `OutputServerToolItem`, whose `type` field is an open `string`.
+     */
+    computeItemStreamScope() {
+        const tools = this.options.tools ?? [];
+        if (tools.length === 0) {
+            // No tools passed: runtime only emits message/reasoning, but the
+            // widest StreamableOutputItem<readonly Tool[]> includes every item
+            // type. Accept all so the default unconstrained case matches its
+            // compile-time union.
+            return {
+                acceptAll: true,
+                allowed: new Set(),
+                acceptGenericServerItem: false,
+            };
+        }
+        const allowed = new Set([
+            'message',
+            'reasoning',
+        ]);
+        let acceptGenericServerItem = false;
+        for (const tool of tools) {
+            if (isClientTool(tool)) {
+                allowed.add('function_call');
+                allowed.add('function_call_output');
+                continue;
+            }
+            if (!isServerTool(tool)) {
+                continue;
+            }
+            const requestType = tool.config.type;
+            switch (requestType) {
+                case 'web_search':
+                case 'web_search_2025_08_26':
+                case 'web_search_preview':
+                case 'web_search_preview_2025_03_11':
+                    allowed.add('web_search_call');
+                    break;
+                case 'openrouter:web_search':
+                    // Defensive: OpenRouter's web_search variant may emit either the
+                    // standard OutputWebSearchCallItem (type='web_search_call') OR be
+                    // wrapped in OutputServerToolItem with type='openrouter:web_search'.
+                    // Accept both literals so the runtime filter doesn't silently drop
+                    // valid items. Do NOT set acceptGenericServerItem — we know the
+                    // tool type and want the filter narrow.
+                    allowed.add('web_search_call');
+                    allowed.add('openrouter:web_search');
+                    break;
+                case 'file_search':
+                    allowed.add('file_search_call');
+                    break;
+                case 'image_generation':
+                    allowed.add('image_generation_call');
+                    break;
+                case 'openrouter:datetime':
+                    // Known server tool whose SDK output item uses the same literal
+                    // as the request type. Mirrors `KnownServerToolOutputs` in
+                    // stream-transformers.ts so the runtime filter stays as narrow
+                    // as the compile-time union (no acceptGenericServerItem widening).
+                    allowed.add('openrouter:datetime');
+                    break;
+                default:
+                    // Unknown / generic server tool — at runtime its output items
+                    // pass through as the request-type literal or as the SDK's
+                    // OutputServerToolItem wrapper. Accept the literal plus the
+                    // generic fallback. See `StreamableOutputItem` narrowing in
+                    // stream-transformers.ts for the matching type-level rules.
+                    allowed.add(requestType);
+                    acceptGenericServerItem = true;
+                    break;
+            }
+        }
+        return {
+            acceptAll: false,
+            allowed,
+            acceptGenericServerItem,
+        };
+    }
     /**
      * @deprecated Use `getItemsStream()` instead. This method only streams messages,
      * while `getItemsStream()` streams all output item types (messages, function_calls,
@@ -1286,9 +1671,12 @@ export class ModelResult {
                         yield item;
                     }
                 }
-                // Then yield the function_call_output results
+                // Then yield the function_call_output results (client tools only;
+                // server-tool output items are surfaced through getItemsStream).
                 for (const toolResult of round.toolResults) {
-                    yield toolResult;
+                    if (isFunctionCallOutputItem(toolResult)) {
+                        yield toolResult;
+                    }
                 }
             }
             // Yield manual tool function_call items from finalResponse, skipping duplicates
@@ -1489,13 +1877,16 @@ export class ModelResult {
     // Multi-Turn Conversation State Methods
     // =========================================================================
     /**
-     * Check if the conversation requires human approval to continue.
-     * Returns true if there are pending tool calls awaiting approval.
+     * Check if the conversation requires human input to continue.
+     * Returns true when the conversation is paused waiting for caller-supplied
+     * decisions — either approval/rejection (`awaiting_approval`) or HITL tool
+     * resume (`awaiting_hitl`). Also returns true whenever `pendingToolCalls`
+     * is populated regardless of status.
      */
     async requiresApproval() {
         await this.initStream();
-        // If we have pending tool calls in state, approval is required
-        if (this.currentState?.status === 'awaiting_approval') {
+        const status = this.currentState?.status;
+        if (status === 'awaiting_approval' || status === 'awaiting_hitl') {
             return true;
         }
         // Also check if pendingToolCalls is populated