@openai/agents-core 0.2.1 → 0.3.1

package/dist/runImplementation.mjs

@@ -7,25 +7,75 @@ import { getLastTextFromOutputMessage } from "./utils/messages.mjs";
 import { withFunctionSpan, withHandoffSpan } from "./tracing/createSpans.mjs";
 import { getSchemaAndParserFromInputType } from "./utils/tools.mjs";
 import { encodeUint8ArrayToBase64 } from "./utils/base64.mjs";
+import { isArrayBufferView, isNodeBuffer, isSerializedBufferSnapshot, toSmartString, } from "./utils/smartString.mjs";
 import { safeExecute } from "./utils/safeExecute.mjs";
 import { addErrorToCurrentSpan } from "./tracing/context.mjs";
 import { RunItemStreamEvent } from "./events.mjs";
 import { z } from 'zod';
-import { toSmartString } from "./utils/smartString.mjs";
 import { isZodObject } from "./utils/index.mjs";
+function isApprovalItemLike(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    if (!('rawItem' in value)) {
+        return false;
+    }
+    const rawItem = value.rawItem;
+    if (!rawItem || typeof rawItem !== 'object') {
+        return false;
+    }
+    const itemType = rawItem.type;
+    return itemType === 'function_call' || itemType === 'hosted_tool_call';
+}
+function getApprovalIdentity(approval) {
+    const rawItem = approval.rawItem;
+    if (!rawItem) {
+        return undefined;
+    }
+    if (rawItem.type === 'function_call' && rawItem.callId) {
+        return `function_call:${rawItem.callId}`;
+    }
+    if ('callId' in rawItem && rawItem.callId) {
+        return `${rawItem.type}:${rawItem.callId}`;
+    }
+    const id = 'id' in rawItem ? rawItem.id : undefined;
+    if (id) {
+        return `${rawItem.type}:${id}`;
+    }
+    const providerData = typeof rawItem.providerData === 'object' && rawItem.providerData
+        ? rawItem.providerData
+        : undefined;
+    if (providerData?.id) {
+        return `${rawItem.type}:provider:${providerData.id}`;
+    }
+    const agentName = 'agent' in approval && approval.agent ? approval.agent.name : '';
+    try {
+        return `${agentName}:${rawItem.type}:${JSON.stringify(rawItem)}`;
+    }
+    catch {
+        return `${agentName}:${rawItem.type}`;
+    }
+}
 /**
  * @internal
+ * Walks a raw model response and classifies each item so the runner can schedule follow-up work.
+ * Returns both the serializable RunItems (for history/streaming) and the actionable tool metadata.
  */
 export function processModelResponse(modelResponse, agent, tools, handoffs) {
     const items = [];
     const runHandoffs = [];
     const runFunctions = [];
     const runComputerActions = [];
+    const runShellActions = [];
+    const runApplyPatchActions = [];
     const runMCPApprovalRequests = [];
     const toolsUsed = [];
     const handoffMap = new Map(handoffs.map((h) => [h.toolName, h]));
+    // Resolve tools upfront so we can look up the concrete handler in O(1) while iterating outputs.
     const functionMap = new Map(tools.filter((t) => t.type === 'function').map((t) => [t.name, t]));
     const computerTool = tools.find((t) => t.type === 'computer');
+    const shellTool = tools.find((t) => t.type === 'shell');
+    const applyPatchTool = tools.find((t) => t.type === 'apply_patch');
     const mcpToolMap = new Map(tools
         .filter((t) => t.type === 'hosted_tool' && t.providerData?.type === 'mcp')
         .map((t) => t)
@@ -95,6 +145,40 @@ export function processModelResponse(modelResponse, agent, tools, handoffs) {
                 computer: computerTool,
             });
         }
+        else if (output.type === 'shell_call') {
+            items.push(new RunToolCallItem(output, agent));
+            toolsUsed.push('shell');
+            if (!shellTool) {
+                addErrorToCurrentSpan({
+                    message: 'Model produced shell action without a shell tool.',
+                    data: {
+                        agent_name: agent.name,
+                    },
+                });
+                throw new ModelBehaviorError('Model produced shell action without a shell tool.');
+            }
+            runShellActions.push({
+                toolCall: output,
+                shell: shellTool,
+            });
+        }
+        else if (output.type === 'apply_patch_call') {
+            items.push(new RunToolCallItem(output, agent));
+            toolsUsed.push('apply_patch');
+            if (!applyPatchTool) {
+                addErrorToCurrentSpan({
+                    message: 'Model produced apply_patch action without an apply_patch tool.',
+                    data: {
+                        agent_name: agent.name,
+                    },
+                });
+                throw new ModelBehaviorError('Model produced apply_patch action without an apply_patch tool.');
+            }
+            runApplyPatchActions.push({
+                toolCall: output,
+                applyPatch: applyPatchTool,
+            });
+        }
         if (output.type !== 'function_call') {
             continue;
         }
@@ -131,13 +215,17 @@ export function processModelResponse(modelResponse, agent, tools, handoffs) {
         handoffs: runHandoffs,
         functions: runFunctions,
         computerActions: runComputerActions,
+        shellActions: runShellActions,
+        applyPatchActions: runApplyPatchActions,
         mcpApprovalRequests: runMCPApprovalRequests,
         toolsUsed: toolsUsed,
         hasToolsOrApprovalsToRun() {
             return (runHandoffs.length > 0 ||
                 runFunctions.length > 0 ||
                 runMCPApprovalRequests.length > 0 ||
-                runComputerActions.length > 0);
+                runComputerActions.length > 0 ||
+                runShellActions.length > 0 ||
+                runApplyPatchActions.length > 0);
         },
     };
 }
@@ -158,6 +246,10 @@ export const nextStepSchema = z.discriminatedUnion('type', [
         data: z.record(z.string(), z.any()),
     }),
 ]);
+/**
+ * Internal convenience wrapper that groups the outcome of a single agent turn. It lets the caller
+ * update the RunState in one shot and decide which step to execute next.
+ */
 class SingleStepResult {
     originalInput;
     modelResponse;
@@ -166,7 +258,7 @@ class SingleStepResult {
     nextStep;
     constructor(
     /**
-     * The input items i.e. the items before run() was called. May be muted by handoff input filters
+     * The input items (i.e., the items before run() was called). May be mutated by handoff input filters.
      */
     originalInput, 
     /**
@@ -200,6 +292,8 @@ class SingleStepResult {
 }
 /**
  * @internal
+ * Resets the tool choice when the agent is configured to prefer a fresh tool selection after
+ * any tool usage. This prevents the provider from reusing stale tool hints across turns.
  */
 export function maybeResetToolChoice(agent, toolUseTracker, modelSettings) {
     if (agent.resetToolChoice && toolUseTracker.hasUsedTools(agent)) {
@@ -209,33 +303,104 @@ export function maybeResetToolChoice(agent, toolUseTracker, modelSettings) {
 }
 /**
  * @internal
+ * Continues a turn that was previously interrupted waiting for tool approval. Executes the now
+ * approved tools and returns the resulting step transition.
  */
-export async function executeInterruptedToolsAndSideEffects(agent, originalInput, originalPreStepItems, newResponse, processedResponse, runner, state) {
+export async function resolveInterruptedTurn(agent, originalInput, originalPreStepItems, newResponse, processedResponse, runner, state) {
     // call_ids for function tools
     const functionCallIds = originalPreStepItems
         .filter((item) => item instanceof RunToolApprovalItem &&
         'callId' in item.rawItem &&
         item.rawItem.type === 'function_call')
         .map((item) => item.rawItem.callId);
+    // We already persisted the turn once when the approval interrupt was raised, so the
+    // counter reflects the approval items as "flushed". When we resume the same turn we need
+    // to rewind it so the eventual tool output for this call is still written to the session.
+    const pendingApprovalItems = state
+        .getInterruptions()
+        .filter(isApprovalItemLike);
+    if (pendingApprovalItems.length > 0) {
+        const pendingApprovalIdentities = new Set();
+        for (const approval of pendingApprovalItems) {
+            const identity = getApprovalIdentity(approval);
+            if (identity) {
+                pendingApprovalIdentities.add(identity);
+            }
+        }
+        if (pendingApprovalIdentities.size > 0) {
+            let rewindCount = 0;
+            for (let index = originalPreStepItems.length - 1; index >= 0; index--) {
+                const item = originalPreStepItems[index];
+                if (!(item instanceof RunToolApprovalItem)) {
+                    continue;
+                }
+                const identity = getApprovalIdentity(item);
+                if (!identity) {
+                    continue;
+                }
+                if (!pendingApprovalIdentities.has(identity)) {
+                    continue;
+                }
+                rewindCount++;
+                pendingApprovalIdentities.delete(identity);
+                if (pendingApprovalIdentities.size === 0) {
+                    break;
+                }
+            }
+            // Persisting the approval request already advanced the counter once, so undo the increment
+            // to make sure we write the final tool output back to the session when the turn resumes.
+            if (rewindCount > 0) {
+                state._currentTurnPersistedItemCount = Math.max(0, state._currentTurnPersistedItemCount - rewindCount);
+            }
+        }
+    }
     // Run function tools that require approval after they get their approval results
     const functionToolRuns = processedResponse.functions.filter((run) => {
         return functionCallIds.includes(run.toolCall.callId);
     });
     const functionResults = await executeFunctionToolCalls(agent, functionToolRuns, runner, state);
-    // Create the initial set of the output items
-    const newItems = functionResults.map((r) => r.runItem);
+    // There is no built-in HITL approval surface for computer tools today, so every pending action
+    // is executed immediately when the turn resumes.
+    const computerResults = processedResponse.computerActions.length > 0
+        ? await executeComputerActions(agent, processedResponse.computerActions, runner, state._context)
+        : [];
+    // When resuming we receive the original RunItem references; suppress duplicates so history and streaming do not double-emit the same items.
+    const originalPreStepItemSet = new Set(originalPreStepItems);
+    const newItems = [];
+    const newItemsSet = new Set();
+    const appendIfNew = (item) => {
+        if (originalPreStepItemSet.has(item) || newItemsSet.has(item)) {
+            return;
+        }
+        newItems.push(item);
+        newItemsSet.add(item);
+    };
+    for (const result of functionResults) {
+        appendIfNew(result.runItem);
+    }
+    for (const result of computerResults) {
+        appendIfNew(result);
+    }
     // Run MCP tools that require approval after they get their approval results
     const mcpApprovalRuns = processedResponse.mcpApprovalRequests.filter((run) => {
         return (run.requestItem.type === 'tool_approval_item' &&
             run.requestItem.rawItem.type === 'hosted_tool_call' &&
             run.requestItem.rawItem.providerData?.type === 'mcp_approval_request');
     });
+    // Hosted MCP approvals may still be waiting on a human decision when the turn resumes.
+    const pendingHostedMCPApprovals = new Set();
+    const pendingHostedMCPApprovalIds = new Set();
+    // Keep track of approvals we still need to surface next turn so HITL flows can resume cleanly.
     for (const run of mcpApprovalRuns) {
         // the approval_request_id "mcpr_123..."
-        const approvalRequestId = run.requestItem.rawItem.id;
+        const rawItem = run.requestItem.rawItem;
+        if (rawItem.type !== 'hosted_tool_call') {
+            continue;
+        }
+        const approvalRequestId = rawItem.id;
         const approved = state._context.isToolApproved({
             // Since this item name must be the same with the one sent from Responses API server
-            toolName: run.requestItem.rawItem.name,
+            toolName: rawItem.name,
             callId: approvalRequestId,
         });
         if (typeof approved !== 'undefined') {
@@ -245,50 +410,101 @@ export async function executeInterruptedToolsAndSideEffects(agent, originalInput
                 reason: undefined,
             };
             // Tell Responses API server the approval result in the next turn
-            newItems.push(new RunToolCallItem({
+            const responseItem = new RunToolCallItem({
                 type: 'hosted_tool_call',
                 name: 'mcp_approval_response',
                 providerData,
-            }, agent));
+            }, agent);
+            appendIfNew(responseItem);
+        }
+        else {
+            pendingHostedMCPApprovals.add(run.requestItem);
+            pendingHostedMCPApprovalIds.add(approvalRequestId);
+            functionResults.push({
+                type: 'hosted_mcp_tool_approval',
+                tool: run.mcpTool,
+                runItem: run.requestItem,
+            });
+            appendIfNew(run.requestItem);
         }
     }
-    const checkToolOutput = await checkForFinalOutputFromTools(agent, functionResults, state);
-    // Exclude the tool approval items, which should not be sent to Responses API,
-    // from the SingleStepResult's preStepItems
+    // Server-managed conversations rely on preStepItems to re-surface pending approvals.
+    // Keep unresolved hosted MCP approvals in place so HITL flows still have something to approve next turn.
+    // Drop resolved approval placeholders so they are not replayed on the next turn, but keep
+    // pending approvals in place to signal the outstanding work to the UI and session store.
     const preStepItems = originalPreStepItems.filter((item) => {
-        return !(item instanceof RunToolApprovalItem);
+        if (!(item instanceof RunToolApprovalItem)) {
+            return true;
+        }
+        if (item.rawItem.type === 'hosted_tool_call' &&
+            item.rawItem.providerData?.type === 'mcp_approval_request') {
+            if (pendingHostedMCPApprovals.has(item)) {
+                return true;
+            }
+            const approvalRequestId = item.rawItem.id;
+            if (approvalRequestId) {
+                return pendingHostedMCPApprovalIds.has(approvalRequestId);
+            }
+            return false;
+        }
+        return false;
     });
-    if (checkToolOutput.isFinalOutput) {
-        runner.emit('agent_end', state._context, agent, checkToolOutput.finalOutput);
-        agent.emit('agent_end', state._context, checkToolOutput.finalOutput);
-        return new SingleStepResult(originalInput, newResponse, preStepItems, newItems, {
-            type: 'next_step_final_output',
-            output: checkToolOutput.finalOutput,
-        });
-    }
-    else if (checkToolOutput.isInterrupted) {
-        return new SingleStepResult(originalInput, newResponse, preStepItems, newItems, {
-            type: 'next_step_interruption',
-            data: {
-                interruptions: checkToolOutput.interruptions,
-            },
-        });
+    const completedStep = await maybeCompleteTurnFromToolResults({
+        agent,
+        runner,
+        state,
+        functionResults,
+        originalInput,
+        newResponse,
+        preStepItems,
+        newItems,
+    });
+    if (completedStep) {
+        return completedStep;
     }
     // we only ran new tools and side effects. We need to run the rest of the agent
     return new SingleStepResult(originalInput, newResponse, preStepItems, newItems, { type: 'next_step_run_again' });
 }
 /**
  * @internal
+ * Executes every follow-up action the model requested (function tools, computer actions, MCP flows),
+ * appends their outputs to the run history, and determines the next step for the agent loop.
  */
-export async function executeToolsAndSideEffects(agent, originalInput, originalPreStepItems, newResponse, processedResponse, runner, state) {
+export async function resolveTurnAfterModelResponse(agent, originalInput, originalPreStepItems, newResponse, processedResponse, runner, state) {
+    // Reuse the same array reference so we can compare object identity when deciding whether to
+    // append new items, ensuring we never double-stream existing RunItems.
     const preStepItems = originalPreStepItems;
-    let newItems = processedResponse.newItems;
-    const [functionResults, computerResults] = await Promise.all([
+    const seenItems = new Set(originalPreStepItems);
+    const newItems = [];
+    const appendIfNew = (item) => {
+        if (seenItems.has(item)) {
+            return;
+        }
+        newItems.push(item);
+        seenItems.add(item);
+    };
+    for (const item of processedResponse.newItems) {
+        appendIfNew(item);
+    }
+    // Run function tools and computer actions in parallel; neither depends on the other's side effects.
+    const [functionResults, computerResults, shellResults, applyPatchResults] = await Promise.all([
         executeFunctionToolCalls(agent, processedResponse.functions, runner, state),
         executeComputerActions(agent, processedResponse.computerActions, runner, state._context),
+        executeShellActions(agent, processedResponse.shellActions, runner, state._context),
+        executeApplyPatchOperations(agent, processedResponse.applyPatchActions, runner, state._context),
     ]);
-    newItems = newItems.concat(functionResults.map((r) => r.runItem));
-    newItems = newItems.concat(computerResults);
+    for (const result of functionResults) {
+        appendIfNew(result.runItem);
+    }
+    for (const item of computerResults) {
+        appendIfNew(item);
+    }
+    for (const item of shellResults) {
+        appendIfNew(item);
+    }
+    for (const item of applyPatchResults) {
+        appendIfNew(item);
+    }
     // run hosted MCP approval requests
     if (processedResponse.mcpApprovalRequests.length > 0) {
         for (const approvalRequest of processedResponse.mcpApprovalRequests) {
@@ -334,28 +550,26 @@ export async function executeToolsAndSideEffects(agent, originalInput, originalP
     if (processedResponse.handoffs.length > 0) {
         return await executeHandoffCalls(agent, originalInput, preStepItems, newItems, newResponse, processedResponse.handoffs, runner, state._context);
     }
-    const checkToolOutput = await checkForFinalOutputFromTools(agent, functionResults, state);
-    if (checkToolOutput.isFinalOutput) {
-        runner.emit('agent_end', state._context, agent, checkToolOutput.finalOutput);
-        agent.emit('agent_end', state._context, checkToolOutput.finalOutput);
-        return new SingleStepResult(originalInput, newResponse, preStepItems, newItems, {
-            type: 'next_step_final_output',
-            output: checkToolOutput.finalOutput,
-        });
-    }
-    else if (checkToolOutput.isInterrupted) {
-        return new SingleStepResult(originalInput, newResponse, preStepItems, newItems, {
-            type: 'next_step_interruption',
-            data: {
-                interruptions: checkToolOutput.interruptions,
-            },
-        });
+    const completedStep = await maybeCompleteTurnFromToolResults({
+        agent,
+        runner,
+        state,
+        functionResults,
+        originalInput,
+        newResponse,
+        preStepItems,
+        newItems,
+    });
+    if (completedStep) {
+        return completedStep;
     }
     // If the model issued any tool calls or handoffs in this turn,
     // we must NOT treat any assistant message in the same turn as the final output.
     // We should run the loop again so the model can see the tool results and respond.
     const hadToolCallsOrActions = (processedResponse.functions?.length ?? 0) > 0 ||
         (processedResponse.computerActions?.length ?? 0) > 0 ||
+        (processedResponse.shellActions?.length ?? 0) > 0 ||
+        (processedResponse.applyPatchActions?.length ?? 0) > 0 ||
         (processedResponse.mcpApprovalRequests?.length ?? 0) > 0 ||
         (processedResponse.handoffs?.length ?? 0) > 0;
     if (hadToolCallsOrActions) {
@@ -371,6 +585,7 @@ export async function executeToolsAndSideEffects(agent, originalInput, originalP
     if (typeof potentialFinalOutput === 'undefined') {
         return new SingleStepResult(originalInput, newResponse, preStepItems, newItems, { type: 'next_step_run_again' });
     }
+    // Keep looping if any tool output placeholders still require an approval follow-up.
     const hasPendingToolsOrApprovals = functionResults.some((result) => result.runItem instanceof RunToolApprovalItem);
     if (!hasPendingToolsOrApprovals) {
         if (agent.outputType === 'text') {
@@ -397,8 +612,32 @@ export async function executeToolsAndSideEffects(agent, originalInput, originalP
     }
     return new SingleStepResult(originalInput, newResponse, preStepItems, newItems, { type: 'next_step_run_again' });
 }
+// Consolidates the logic that determines whether tool results yielded a final answer,
+// triggered an interruption, or require the agent loop to continue running.
+async function maybeCompleteTurnFromToolResults({ agent, runner, state, functionResults, originalInput, newResponse, preStepItems, newItems, }) {
+    const toolOutcome = await checkForFinalOutputFromTools(agent, functionResults, state);
+    if (toolOutcome.isFinalOutput) {
+        runner.emit('agent_end', state._context, agent, toolOutcome.finalOutput);
+        agent.emit('agent_end', state._context, toolOutcome.finalOutput);
+        return new SingleStepResult(originalInput, newResponse, preStepItems, newItems, {
+            type: 'next_step_final_output',
+            output: toolOutcome.finalOutput,
+        });
+    }
+    if (toolOutcome.isInterrupted) {
+        return new SingleStepResult(originalInput, newResponse, preStepItems, newItems, {
+            type: 'next_step_interruption',
+            data: {
+                interruptions: toolOutcome.interruptions,
+            },
+        });
+    }
+    return null;
+}
 /**
  * @internal
+ * Normalizes tool outputs once so downstream code works with fully structured protocol items.
+ * Doing this here keeps API surface stable even when providers add new shapes.
  */
 export function getToolCallOutputItem(toolCall, output) {
     const maybeStructuredOutputs = normalizeStructuredToolOutputs(output);
@@ -423,283 +662,57 @@ export function getToolCallOutputItem(toolCall, output) {
         },
     };
 }
-/**
- * Accepts whatever the tool returned and attempts to coerce it into the structured protocol
- * shapes we expose to downstream model adapters (input_text/input_image/input_file). Tools are
- * allowed to return either a single structured object or an array of them; anything else falls
- * back to the legacy string pipeline.
- */
-function normalizeStructuredToolOutputs(output) {
-    if (Array.isArray(output)) {
-        const structured = [];
-        for (const item of output) {
-            const normalized = normalizeStructuredToolOutput(item);
-            if (!normalized) {
-                return null;
-            }
-            structured.push(normalized);
-        }
-        return structured;
+function normalizeFileValue(value) {
+    const directFile = value.file;
+    if (typeof directFile === 'string' && directFile.length > 0) {
+        return directFile;
     }
-    const normalized = normalizeStructuredToolOutput(output);
-    return normalized ? [normalized] : null;
+    const normalizedObject = normalizeFileObjectCandidate(directFile);
+    if (normalizedObject) {
+        return normalizedObject;
+    }
+    const legacyValue = normalizeLegacyFileValue(value);
+    if (legacyValue) {
+        return legacyValue;
+    }
+    return null;
 }
-/**
- * Best-effort normalization of a single tool output item. If the object already matches the
- * protocol shape we simply cast it; otherwise we copy the recognised fields into the canonical
- * structure. Returning null lets the caller know we should revert to plain-string handling.
- */
-function normalizeStructuredToolOutput(value) {
+function normalizeFileObjectCandidate(value) {
     if (!isRecord(value)) {
         return null;
     }
-    const type = value.type;
-    if (type === 'text' && typeof value.text === 'string') {
-        const output = { type: 'text', text: value.text };
-        if (isRecord(value.providerData)) {
-            output.providerData = value.providerData;
-        }
-        return output;
-    }
-    if (type === 'image') {
-        const output = { type: 'image' };
-        let imageString;
-        let imageFileId;
-        const fallbackImageMediaType = isNonEmptyString(value.mediaType)
-            ? value.mediaType
-            : undefined;
-        const imageField = value.image;
-        if (typeof imageField === 'string' && imageField.length > 0) {
-            imageString = imageField;
-        }
-        else if (isRecord(imageField)) {
-            const imageObj = imageField;
-            const inlineMediaType = isNonEmptyString(imageObj.mediaType)
-                ? imageObj.mediaType
-                : fallbackImageMediaType;
-            if (isNonEmptyString(imageObj.url)) {
-                imageString = imageObj.url;
-            }
-            else if (isNonEmptyString(imageObj.data)) {
-                imageString = toInlineImageString(imageObj.data, inlineMediaType);
-            }
-            else if (imageObj.data instanceof Uint8Array &&
-                imageObj.data.length > 0) {
-                imageString = toInlineImageString(imageObj.data, inlineMediaType);
-            }
-            if (!imageString) {
-                const candidateId = (isNonEmptyString(imageObj.fileId) && imageObj.fileId) ||
-                    (isNonEmptyString(imageObj.id) && imageObj.id) ||
-                    undefined;
-                if (candidateId) {
-                    imageFileId = candidateId;
-                }
-            }
-        }
-        if (!imageString &&
-            typeof value.imageUrl === 'string' &&
-            value.imageUrl.length > 0) {
-            imageString = value.imageUrl;
-        }
-        if (!imageFileId &&
-            typeof value.fileId === 'string' &&
-            value.fileId.length > 0) {
-            imageFileId = value.fileId;
-        }
-        if (!imageString &&
-            typeof value.data === 'string' &&
-            value.data.length > 0) {
-            imageString = fallbackImageMediaType
-                ? toInlineImageString(value.data, fallbackImageMediaType)
-                : value.data;
-        }
-        else if (!imageString &&
-            value.data instanceof Uint8Array &&
-            value.data.length > 0) {
-            imageString = toInlineImageString(value.data, fallbackImageMediaType);
-        }
-        if (typeof value.detail === 'string' && value.detail.length > 0) {
-            output.detail = value.detail;
-        }
-        if (imageString) {
-            output.image = imageString;
-        }
-        else if (imageFileId) {
-            output.image = { fileId: imageFileId };
-        }
-        else {
+    if ('data' in value && value.data !== undefined) {
+        const dataValue = value.data;
+        const hasStringData = typeof dataValue === 'string' && dataValue.length > 0;
+        const hasBinaryData = dataValue instanceof Uint8Array && dataValue.length > 0;
+        if (!hasStringData && !hasBinaryData) {
             return null;
         }
-        if (isRecord(value.providerData)) {
-            output.providerData = value.providerData;
+        if (!isNonEmptyString(value.mediaType) ||
+            !isNonEmptyString(value.filename)) {
+            return null;
         }
-        return output;
+        return {
+            data: typeof dataValue === 'string' ? dataValue : new Uint8Array(dataValue),
+            mediaType: value.mediaType,
+            filename: value.filename,
+        };
     }
-    if (type === 'file') {
-        const fileValue = normalizeFileValue(value);
-        if (!fileValue) {
-            return null;
+    if (isNonEmptyString(value.url)) {
+        const result = { url: value.url };
+        if (isNonEmptyString(value.filename)) {
+            result.filename = value.filename;
         }
-        const output = { type: 'file', file: fileValue };
-        if (isRecord(value.providerData)) {
-            output.providerData = value.providerData;
+        return result;
+    }
+    const referencedId = (isNonEmptyString(value.id) && value.id) ||
+        (isNonEmptyString(value.fileId) && value.fileId);
+    if (referencedId) {
+        const result = { id: referencedId };
+        if (isNonEmptyString(value.filename)) {
+            result.filename = value.filename;
         }
-        return output;
-    }
-    return null;
-}
-/**
- * Translates the normalized tool output into the protocol `input_*` items. This is the last hop
- * before we hand the data to model-specific adapters, so we generate the exact schema expected by
- * the protocol definitions.
- */
-function convertStructuredToolOutputToInputItem(output) {
-    if (output.type === 'text') {
-        const result = {
-            type: 'input_text',
-            text: output.text,
-        };
-        if (output.providerData) {
-            result.providerData = output.providerData;
-        }
-        return result;
-    }
-    if (output.type === 'image') {
-        const result = { type: 'input_image' };
-        if (typeof output.detail === 'string' && output.detail.length > 0) {
-            result.detail = output.detail;
-        }
-        if (typeof output.image === 'string' && output.image.length > 0) {
-            result.image = output.image;
-        }
-        else if (isRecord(output.image)) {
-            const imageObj = output.image;
-            const inlineMediaType = isNonEmptyString(imageObj.mediaType)
-                ? imageObj.mediaType
-                : undefined;
-            if (isNonEmptyString(imageObj.url)) {
-                result.image = imageObj.url;
-            }
-            else if (isNonEmptyString(imageObj.data)) {
-                result.image =
-                    inlineMediaType && !imageObj.data.startsWith('data:')
-                        ? asDataUrl(imageObj.data, inlineMediaType)
-                        : imageObj.data;
-            }
-            else if (imageObj.data instanceof Uint8Array &&
-                imageObj.data.length > 0) {
-                const base64 = encodeUint8ArrayToBase64(imageObj.data);
-                result.image = asDataUrl(base64, inlineMediaType);
-            }
-            else {
-                const referencedId = (isNonEmptyString(imageObj.fileId) && imageObj.fileId) ||
-                    (isNonEmptyString(imageObj.id) && imageObj.id) ||
-                    undefined;
-                if (referencedId) {
-                    result.image = { id: referencedId };
-                }
-            }
-        }
-        if (output.providerData) {
-            result.providerData = output.providerData;
-        }
-        return result;
-    }
-    if (output.type === 'file') {
-        const result = { type: 'input_file' };
-        const fileValue = output.file;
-        if (typeof fileValue === 'string') {
-            result.file = fileValue;
-        }
-        else if (fileValue && typeof fileValue === 'object') {
-            const record = fileValue;
-            if ('data' in record && record.data) {
-                const mediaType = record.mediaType ?? 'text/plain';
-                if (typeof record.data === 'string') {
-                    result.file = asDataUrl(record.data, mediaType);
-                }
-                else {
-                    const base64 = encodeUint8ArrayToBase64(record.data);
-                    result.file = asDataUrl(base64, mediaType);
-                }
-            }
-            else if (typeof record.url === 'string' && record.url.length > 0) {
-                result.file = { url: record.url };
-            }
-            else {
-                const referencedId = (typeof record.id === 'string' &&
-                    record.id.length > 0 &&
-                    record.id) ||
-                    (typeof record.fileId === 'string' && record.fileId.length > 0
-                        ? record.fileId
-                        : undefined);
-                if (referencedId) {
-                    result.file = { id: referencedId };
-                }
-            }
-            if (typeof record.filename === 'string' && record.filename.length > 0) {
-                result.filename = record.filename;
-            }
-        }
-        if (output.providerData) {
-            result.providerData = output.providerData;
-        }
-        return result;
-    }
-    const exhaustiveCheck = output;
-    return exhaustiveCheck;
-}
-function normalizeFileValue(value) {
-    const directFile = value.file;
-    if (typeof directFile === 'string' && directFile.length > 0) {
-        return directFile;
-    }
-    const normalizedObject = normalizeFileObjectCandidate(directFile);
-    if (normalizedObject) {
-        return normalizedObject;
-    }
-    const legacyValue = normalizeLegacyFileValue(value);
-    if (legacyValue) {
-        return legacyValue;
-    }
-    return null;
-}
-function normalizeFileObjectCandidate(value) {
-    if (!isRecord(value)) {
-        return null;
-    }
-    if ('data' in value && value.data !== undefined) {
-        const dataValue = value.data;
-        const hasStringData = typeof dataValue === 'string' && dataValue.length > 0;
-        const hasBinaryData = dataValue instanceof Uint8Array && dataValue.length > 0;
-        if (!hasStringData && !hasBinaryData) {
-            return null;
-        }
-        if (!isNonEmptyString(value.mediaType) ||
-            !isNonEmptyString(value.filename)) {
-            return null;
-        }
-        return {
-            data: typeof dataValue === 'string' ? dataValue : new Uint8Array(dataValue),
-            mediaType: value.mediaType,
-            filename: value.filename,
-        };
-    }
-    if (isNonEmptyString(value.url)) {
-        const result = { url: value.url };
-        if (isNonEmptyString(value.filename)) {
-            result.filename = value.filename;
-        }
-        return result;
-    }
-    const referencedId = (isNonEmptyString(value.id) && value.id) ||
-        (isNonEmptyString(value.fileId) && value.fileId);
-    if (referencedId) {
-        const result = { id: referencedId };
-        if (isNonEmptyString(value.filename)) {
-            result.filename = value.filename;
-        }
-        return result;
+        return result;
     }
     return null;
 }
@@ -759,6 +772,8 @@ function asDataUrl(base64, mediaType) {
 }
 /**
  * @internal
+ * Runs every function tool call requested by the model and returns their outputs alongside
+ * the `RunItem` instances that should be appended to history.
  */
 export async function executeFunctionToolCalls(agent, toolRuns, runner, state) {
     async function runSingleTool(toolRun) {
@@ -771,6 +786,7 @@ export async function executeFunctionToolCalls(agent, toolRuns, runner, state) {
                 parsedArgs = JSON.parse(parsedArgs);
             }
         }
+        // Some tools require a human or policy check before execution; defer until approval is recorded.
         const needsApproval = await toolRun.tool.needsApproval(state._context, parsedArgs, toolRun.toolCall.callId);
         if (needsApproval) {
             const approval = state._context.isToolApproved({
@@ -922,8 +938,210 @@ async function _runComputerActionAndScreenshot(computer, toolCall) {
     }
     throw new Error('Computer does not implement screenshot()');
 }
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message || error.toString();
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+export async function executeShellActions(agent, actions, runner, runContext, customLogger = undefined) {
+    const _logger = customLogger ?? logger;
+    const results = [];
+    for (const action of actions) {
+        const shellTool = action.shell;
+        const toolCall = action.toolCall;
+        const approvalItem = new RunToolApprovalItem(toolCall, agent, shellTool.name);
+        const requiresApproval = await shellTool.needsApproval(runContext, toolCall.action, toolCall.callId);
+        if (requiresApproval) {
+            if (shellTool.onApproval) {
+                const decision = await shellTool.onApproval(runContext, approvalItem);
+                if (decision.approve === true) {
+                    runContext.approveTool(approvalItem);
+                }
+                else if (decision.approve === false) {
+                    runContext.rejectTool(approvalItem);
+                }
+            }
+            const approval = runContext.isToolApproved({
+                toolName: shellTool.name,
+                callId: toolCall.callId,
+            });
+            if (approval === false) {
+                const response = 'Tool execution was not approved.';
+                const rejectionOutput = {
+                    stdout: '',
+                    stderr: response,
+                    outcome: { type: 'exit', exitCode: null },
+                };
+                results.push(new RunToolCallOutputItem({
+                    type: 'shell_call_output',
+                    callId: toolCall.callId,
+                    output: [rejectionOutput],
+                }, agent, response));
+                continue;
+            }
+            if (approval !== true) {
+                results.push(approvalItem);
+                continue;
+            }
+        }
+        runner.emit('agent_tool_start', runContext, agent, shellTool, {
+            toolCall,
+        });
+        if (typeof agent.emit === 'function') {
+            agent.emit('agent_tool_start', runContext, shellTool, { toolCall });
+        }
+        let shellOutputs;
+        const providerMeta = {};
+        let maxOutputLength;
+        try {
+            const shellResult = await shellTool.shell.run(toolCall.action);
+            shellOutputs = shellResult.output ?? [];
+            if (shellResult.providerData) {
+                Object.assign(providerMeta, shellResult.providerData);
+            }
+            if (typeof shellResult.maxOutputLength === 'number') {
+                maxOutputLength = shellResult.maxOutputLength;
+            }
+        }
+        catch (err) {
+            const errorText = toErrorMessage(err);
+            shellOutputs = [
+                {
+                    stdout: '',
+                    stderr: errorText,
+                    outcome: { type: 'exit', exitCode: null },
+                },
+            ];
+            _logger.error('Failed to execute shell action:', err);
+        }
+        shellOutputs = shellOutputs ?? [];
+        runner.emit('agent_tool_end', runContext, agent, shellTool, JSON.stringify(shellOutputs), {
+            toolCall,
+        });
+        if (typeof agent.emit === 'function') {
+            agent.emit('agent_tool_end', runContext, shellTool, JSON.stringify(shellOutputs), {
+                toolCall,
+            });
+        }
+        const rawItem = {
+            type: 'shell_call_output',
+            callId: toolCall.callId,
+            output: shellOutputs ?? [],
+        };
+        if (typeof maxOutputLength === 'number') {
+            rawItem.maxOutputLength = maxOutputLength;
+        }
+        if (Object.keys(providerMeta).length > 0) {
+            rawItem.providerData = providerMeta;
+        }
+        results.push(new RunToolCallOutputItem(rawItem, agent, rawItem.output));
+    }
+    return results;
+}
+export async function executeApplyPatchOperations(agent, actions, runner, runContext, customLogger = undefined) {
+    const _logger = customLogger ?? logger;
+    const results = [];
+    for (const action of actions) {
+        const applyPatchTool = action.applyPatch;
+        const toolCall = action.toolCall;
+        const approvalItem = new RunToolApprovalItem(toolCall, agent, applyPatchTool.name);
+        const requiresApproval = await applyPatchTool.needsApproval(runContext, toolCall.operation, toolCall.callId);
+        if (requiresApproval) {
+            if (applyPatchTool.onApproval) {
+                const decision = await applyPatchTool.onApproval(runContext, approvalItem);
+                if (decision.approve === true) {
+                    runContext.approveTool(approvalItem);
+                }
+                else if (decision.approve === false) {
+                    runContext.rejectTool(approvalItem);
+                }
+            }
+            const approval = runContext.isToolApproved({
+                toolName: applyPatchTool.name,
+                callId: toolCall.callId,
+            });
+            if (approval === false) {
+                const response = 'Tool execution was not approved.';
+                results.push(new RunToolCallOutputItem({
+                    type: 'apply_patch_call_output',
+                    callId: toolCall.callId,
+                    status: 'failed',
+                    output: response,
+                }, agent, response));
+                continue;
+            }
+            if (approval !== true) {
+                results.push(approvalItem);
+                continue;
+            }
+        }
+        runner.emit('agent_tool_start', runContext, agent, applyPatchTool, {
+            toolCall,
+        });
+        if (typeof agent.emit === 'function') {
+            agent.emit('agent_tool_start', runContext, applyPatchTool, {
+                toolCall,
+            });
+        }
+        let status = 'completed';
+        let output = '';
+        try {
+            let result;
+            switch (toolCall.operation.type) {
+                case 'create_file':
+                    result = await applyPatchTool.editor.createFile(toolCall.operation);
+                    break;
+                case 'update_file':
+                    result = await applyPatchTool.editor.updateFile(toolCall.operation);
+                    break;
+                case 'delete_file':
+                    result = await applyPatchTool.editor.deleteFile(toolCall.operation);
+                    break;
+                default:
+                    throw new Error('Unsupported apply_patch operation');
+            }
+            if (result && typeof result.status === 'string') {
+                status = result.status;
+            }
+            if (result && typeof result.output === 'string') {
+                output = result.output;
+            }
+        }
+        catch (err) {
+            status = 'failed';
+            output = toErrorMessage(err);
+            _logger.error('Failed to execute apply_patch operation:', err);
+        }
+        runner.emit('agent_tool_end', runContext, agent, applyPatchTool, output, {
+            toolCall,
+        });
+        if (typeof agent.emit === 'function') {
+            agent.emit('agent_tool_end', runContext, applyPatchTool, output, {
+                toolCall,
+            });
+        }
+        const rawItem = {
+            type: 'apply_patch_call_output',
+            callId: toolCall.callId,
+            status,
+        };
+        if (output) {
+            rawItem.output = output;
+        }
+        results.push(new RunToolCallOutputItem(rawItem, agent, output));
+    }
+    return results;
+}
 /**
  * @internal
+ * Executes any computer-use actions emitted by the model and returns the resulting items so the
+ * run history reflects the computer session.
  */
 export async function executeComputerActions(agent, actions, runner, runContext, customLogger = undefined) {
     const _logger = customLogger ?? logger;
@@ -956,7 +1174,7 @@ export async function executeComputerActions(agent, actions, runner, runContext,
                 toolCall,
             });
         }
-        // Always return a screenshot as a base64 data URL
+        // Return the screenshot as a data URL when available; fall back to an empty string on failures.
         const imageUrl = output ? `data:image/png;base64,${output}` : '';
         const rawItem = {
             type: 'computer_call_result',
@@ -969,6 +1187,8 @@ export async function executeComputerActions(agent, actions, runner, runContext,
 }
 /**
  * @internal
+ * Drives handoff calls by invoking the downstream agent and capturing any generated items so
+ * the current agent can continue with the new context.
  */
 export async function executeHandoffCalls(agent, originalInput, preStepItems, newStepItems, newResponse, runHandoffs, runner, runContext) {
     newStepItems = [...newStepItems];
@@ -1037,6 +1257,8 @@ const NOT_FINAL_OUTPUT = {
 };
 /**
  * @internal
+ * Determines whether tool executions produced a final agent output, triggered an interruption,
+ * or whether the agent loop should continue collecting more responses.
  */
 export async function checkForFinalOutputFromTools(agent, toolResults, state) {
     if (toolResults.length === 0) {
@@ -1163,4 +1385,571 @@ export class AgentToolUseTracker {
         }));
     }
 }
+/**
+ * @internal
+ * Convert a user-provided input into a list of input items.
+ */
+export function toInputItemList(input) {
+    if (typeof input === 'string') {
+        return [
+            {
+                type: 'message',
+                role: 'user',
+                content: input,
+            },
+        ];
+    }
+    return [...input];
+}
+/**
+ * @internal
+ * Extract model output items from run items, excluding tool approval items.
+ */
+export function extractOutputItemsFromRunItems(items) {
+    return items
+        .filter((item) => item.type !== 'tool_approval_item')
+        .map((item) => item.rawItem);
+}
+function normalizeItemsForSessionPersistence(items) {
+    // Persisted sessions must avoid raw binary so we convert every item into a JSON-safe shape before writing to storage.
+    return items.map((item) => sanitizeValueForSession(stripTransientCallIds(item)));
+}
+function sanitizeValueForSession(value, context = {}) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    // Convert supported binary payloads into ArrayBuffer views before serialization.
+    const binary = toUint8ArrayIfBinary(value);
+    if (binary) {
+        return toDataUrlFromBytes(binary, context.mediaType);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => sanitizeValueForSession(entry, context));
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const record = value;
+    const result = {};
+    const mediaType = typeof record.mediaType === 'string' && record.mediaType.length > 0
+        ? record.mediaType
+        : context.mediaType;
+    for (const [key, entry] of Object.entries(record)) {
+        // Propagate explicit media type only when walking into binary payload containers.
+        const nextContext = key === 'data' || key === 'fileData' ? { mediaType } : context;
+        result[key] = sanitizeValueForSession(entry, nextContext);
+    }
+    return result;
+}
+function toUint8ArrayIfBinary(value) {
+    // Normalize the diverse binary containers we may receive into a shared Uint8Array view.
+    if (value instanceof ArrayBuffer) {
+        return new Uint8Array(value);
+    }
+    if (isArrayBufferView(value)) {
+        const view = value;
+        return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    }
+    if (isNodeBuffer(value)) {
+        const view = value;
+        return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    }
+    if (isSerializedBufferSnapshot(value)) {
+        const snapshot = value;
+        return Uint8Array.from(snapshot.data);
+    }
+    return undefined;
+}
+function toDataUrlFromBytes(bytes, mediaType) {
+    // Convert binary payloads into a durable data URL so session files remain self-contained.
+    const base64 = encodeUint8ArrayToBase64(bytes);
+    // Note that OpenAI Responses API never accepts application/octet-stream as a media type,
+    // so we fall back to text/plain; that said, tools are supposed to return a valid media type when this utility is used.
+    const type = mediaType && !mediaType.startsWith('data:') ? mediaType : 'text/plain';
+    return `data:${type};base64,${base64}`;
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function stripTransientCallIds(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => stripTransientCallIds(entry));
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const record = value;
+    const result = {};
+    const isProtocolItem = typeof record.type === 'string' && record.type.length > 0;
+    const shouldStripId = isProtocolItem && shouldStripIdForType(record.type);
+    for (const [key, entry] of Object.entries(record)) {
+        if (shouldStripId && key === 'id') {
+            continue;
+        }
+        result[key] = stripTransientCallIds(entry);
+    }
+    return result;
+}
+function shouldStripIdForType(type) {
+    switch (type) {
+        case 'function_call':
+        case 'function_call_result':
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * @internal
+ * Persist full turn (input + outputs) for non-streaming runs.
+ */
+// Persists the combination of user inputs (possibly filtered) and model outputs for a completed turn.
+export async function saveToSession(session, sessionInputItems, result) {
+    if (!session) {
+        return;
+    }
+    const inputItems = sessionInputItems ?? [];
+    const state = result.state;
+    const alreadyPersisted = state._currentTurnPersistedItemCount ?? 0;
+    // Persist only the portion of _generatedItems that has not yet been stored for this turn.
+    const newRunItems = result.newItems.slice(alreadyPersisted);
+    if (process.env.OPENAI_AGENTS__DEBUG_SAVE_SESSION) {
+        console.debug('saveToSession:newRunItems', newRunItems.map((item) => item.type));
+    }
+    const outputItems = extractOutputItemsFromRunItems(newRunItems);
+    const itemsToSave = [...inputItems, ...outputItems];
+    if (itemsToSave.length === 0) {
+        state._currentTurnPersistedItemCount =
+            alreadyPersisted + newRunItems.length;
+        return;
+    }
+    const sanitizedItems = normalizeItemsForSessionPersistence(itemsToSave);
+    await session.addItems(sanitizedItems);
+    state._currentTurnPersistedItemCount = alreadyPersisted + newRunItems.length;
+}
+/**
+ * @internal
+ * Persist only the user input for streaming runs at start.
+ */
+// For streaming runs we persist user input as soon as it is sent so reconnections can resume.
+export async function saveStreamInputToSession(session, sessionInputItems) {
+    if (!session) {
+        return;
+    }
+    if (!sessionInputItems || sessionInputItems.length === 0) {
+        return;
+    }
+    const sanitizedInput = normalizeItemsForSessionPersistence(sessionInputItems);
+    await session.addItems(sanitizedInput);
+}
+/**
+ * @internal
+ * Persist only the model outputs for streaming runs at the end of a turn.
+ */
+// Complements saveStreamInputToSession by recording the streaming outputs at the end of the turn.
+export async function saveStreamResultToSession(session, result) {
+    if (!session) {
+        return;
+    }
+    const state = result.state;
+    const alreadyPersisted = state._currentTurnPersistedItemCount ?? 0;
+    const newRunItems = result.newItems.slice(alreadyPersisted);
+    const itemsToSave = extractOutputItemsFromRunItems(newRunItems);
+    if (itemsToSave.length === 0) {
+        state._currentTurnPersistedItemCount =
+            alreadyPersisted + newRunItems.length;
+        return;
+    }
+    const sanitizedItems = normalizeItemsForSessionPersistence(itemsToSave);
+    await session.addItems(sanitizedItems);
+    state._currentTurnPersistedItemCount = alreadyPersisted + newRunItems.length;
+}
+export async function prepareInputItemsWithSession(input, session, sessionInputCallback, options) {
+    if (!session) {
+        return {
+            preparedInput: input,
+            sessionItems: undefined,
+        };
+    }
+    const includeHistoryInPreparedInput = options?.includeHistoryInPreparedInput ?? true;
+    const preserveDroppedNewItems = options?.preserveDroppedNewItems ?? false;
+    const history = await session.getItems();
+    const newInputItems = Array.isArray(input)
+        ? [...input]
+        : toInputItemList(input);
+    if (!sessionInputCallback) {
+        return {
+            preparedInput: includeHistoryInPreparedInput
+                ? [...history, ...newInputItems]
+                : newInputItems,
+            sessionItems: newInputItems,
+        };
+    }
+    // Capture snapshots before invoking the callback so we can reason about the original state even
+    // if the callback mutates the history array in-place.
+    const historySnapshot = history.slice();
+    const newInputSnapshot = newInputItems.slice();
+    // Delegate history reconciliation to the user-supplied callback. It must return a concrete list
+    // to keep downstream model requests well-typed.
+    const combined = await sessionInputCallback(history, newInputItems);
+    if (!Array.isArray(combined)) {
+        throw new UserError('Session input callback must return an array of AgentInputItem objects.');
+    }
+    const historyCounts = buildItemFrequencyMap(historySnapshot);
+    const newInputCounts = buildItemFrequencyMap(newInputSnapshot);
+    const historyRefs = buildItemReferenceMap(historySnapshot);
+    const newInputRefs = buildItemReferenceMap(newInputSnapshot);
+    const appended = [];
+    for (const item of combined) {
+        const key = sessionItemKey(item);
+        if (consumeReference(newInputRefs, key, item)) {
+            decrementCount(newInputCounts, key);
+            appended.push(item);
+            continue;
+        }
+        // Prioritize exact history matches before payload-based counts so callbacks that surface
+        // history ahead of identical new inputs keep previously persisted items out of the new queue.
+        if (consumeReference(historyRefs, key, item)) {
+            decrementCount(historyCounts, key);
+            continue;
+        }
+        const historyRemaining = historyCounts.get(key) ?? 0;
+        if (historyRemaining > 0) {
+            historyCounts.set(key, historyRemaining - 1);
+            continue;
+        }
+        const newRemaining = newInputCounts.get(key) ?? 0;
+        if (newRemaining > 0) {
+            newInputCounts.set(key, newRemaining - 1);
+            appended.push(item);
+            continue;
+        }
+        appended.push(item);
+    }
+    // Preserve redacted inputs for model delivery when requested (e.g. server-managed histories).
+    const preparedItems = includeHistoryInPreparedInput
+        ? combined
+        : appended.length > 0
+            ? appended
+            : preserveDroppedNewItems
+                ? newInputSnapshot
+                : [];
+    return {
+        preparedInput: preparedItems,
+        // Respect callbacks that intentionally drop the latest inputs (e.g. to redact sensitive
+        // values) by persisting only the items they kept in the combined array.
+        sessionItems: appended,
+    };
+}
+/**
+ * Accepts whatever the tool returned and attempts to coerce it into the structured protocol
+ * shapes we expose to downstream model adapters (input_text/input_image/input_file). Tools are
+ * allowed to return either a single structured object or an array of them; anything else falls
+ * back to the legacy string pipeline.
+ */
+function normalizeStructuredToolOutputs(output) {
+    if (Array.isArray(output)) {
+        const structured = [];
+        for (const item of output) {
+            const normalized = normalizeStructuredToolOutput(item);
+            if (!normalized) {
+                return null;
+            }
+            structured.push(normalized);
+        }
+        return structured;
+    }
+    const normalized = normalizeStructuredToolOutput(output);
+    return normalized ? [normalized] : null;
+}
+/**
+ * Best-effort normalization of a single tool output item. If the object already matches the
+ * protocol shape we simply cast it; otherwise we copy the recognised fields into the canonical
+ * structure. Returning null lets the caller know we should revert to plain-string handling.
+ */
+function normalizeStructuredToolOutput(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const type = value.type;
+    if (type === 'text' && typeof value.text === 'string') {
+        const output = { type: 'text', text: value.text };
+        if (isRecord(value.providerData)) {
+            output.providerData = value.providerData;
+        }
+        return output;
+    }
+    if (type === 'image') {
+        const output = { type: 'image' };
+        let imageString;
+        let imageFileId;
+        const fallbackImageMediaType = isNonEmptyString(value.mediaType)
+            ? value.mediaType
+            : undefined;
+        const imageField = value.image;
+        if (typeof imageField === 'string' && imageField.length > 0) {
+            imageString = imageField;
+        }
+        else if (isRecord(imageField)) {
+            const imageObj = imageField;
+            const inlineMediaType = isNonEmptyString(imageObj.mediaType)
+                ? imageObj.mediaType
+                : fallbackImageMediaType;
+            if (isNonEmptyString(imageObj.url)) {
+                imageString = imageObj.url;
+            }
+            else if (isNonEmptyString(imageObj.data)) {
+                imageString = toInlineImageString(imageObj.data, inlineMediaType);
+            }
+            else if (imageObj.data instanceof Uint8Array &&
+                imageObj.data.length > 0) {
+                imageString = toInlineImageString(imageObj.data, inlineMediaType);
+            }
+            if (!imageString) {
+                const candidateId = (isNonEmptyString(imageObj.fileId) && imageObj.fileId) ||
+                    (isNonEmptyString(imageObj.id) && imageObj.id) ||
+                    undefined;
+                if (candidateId) {
+                    imageFileId = candidateId;
+                }
+            }
+        }
+        if (!imageString &&
+            typeof value.imageUrl === 'string' &&
+            value.imageUrl.length > 0) {
+            imageString = value.imageUrl;
+        }
+        if (!imageFileId &&
+            typeof value.fileId === 'string' &&
+            value.fileId.length > 0) {
+            imageFileId = value.fileId;
+        }
+        if (!imageString &&
+            typeof value.data === 'string' &&
+            value.data.length > 0) {
+            imageString = fallbackImageMediaType
+                ? toInlineImageString(value.data, fallbackImageMediaType)
+                : value.data;
+        }
+        else if (!imageString &&
+            value.data instanceof Uint8Array &&
+            value.data.length > 0) {
+            imageString = toInlineImageString(value.data, fallbackImageMediaType);
+        }
+        if (typeof value.detail === 'string' && value.detail.length > 0) {
+            output.detail = value.detail;
+        }
+        if (imageString) {
+            output.image = imageString;
+        }
+        else if (imageFileId) {
+            output.image = { fileId: imageFileId };
+        }
+        else {
+            return null;
+        }
+        if (isRecord(value.providerData)) {
+            output.providerData = value.providerData;
+        }
+        return output;
+    }
+    if (type === 'file') {
+        const fileValue = normalizeFileValue(value);
+        if (!fileValue) {
+            return null;
+        }
+        const output = { type: 'file', file: fileValue };
+        if (isRecord(value.providerData)) {
+            output.providerData = value.providerData;
+        }
+        return output;
+    }
+    return null;
+}
+/**
+ * Translates the normalized tool output into the protocol `input_*` items. This is the last hop
+ * before we hand the data to model-specific adapters, so we generate the exact schema expected by
+ * the protocol definitions.
+ */
+function convertStructuredToolOutputToInputItem(output) {
+    if (output.type === 'text') {
+        const result = {
+            type: 'input_text',
+            text: output.text,
+        };
+        if (output.providerData) {
+            result.providerData = output.providerData;
+        }
+        return result;
+    }
+    if (output.type === 'image') {
+        const result = { type: 'input_image' };
+        if (typeof output.detail === 'string' && output.detail.length > 0) {
+            result.detail = output.detail;
+        }
+        if (typeof output.image === 'string' && output.image.length > 0) {
+            result.image = output.image;
+        }
+        else if (isRecord(output.image)) {
+            const imageObj = output.image;
+            const inlineMediaType = isNonEmptyString(imageObj.mediaType)
+                ? imageObj.mediaType
+                : undefined;
+            if (isNonEmptyString(imageObj.url)) {
+                result.image = imageObj.url;
+            }
+            else if (isNonEmptyString(imageObj.data)) {
+                result.image =
+                    inlineMediaType && !imageObj.data.startsWith('data:')
+                        ? asDataUrl(imageObj.data, inlineMediaType)
+                        : imageObj.data;
+            }
+            else if (imageObj.data instanceof Uint8Array &&
+                imageObj.data.length > 0) {
+                const base64 = encodeUint8ArrayToBase64(imageObj.data);
+                result.image = asDataUrl(base64, inlineMediaType);
+            }
+            else {
+                const referencedId = (isNonEmptyString(imageObj.fileId) && imageObj.fileId) ||
+                    (isNonEmptyString(imageObj.id) && imageObj.id) ||
+                    undefined;
+                if (referencedId) {
+                    result.image = { id: referencedId };
+                }
+            }
+        }
+        if (output.providerData) {
+            result.providerData = output.providerData;
+        }
+        return result;
+    }
+    if (output.type === 'file') {
+        const result = { type: 'input_file' };
+        const fileValue = output.file;
+        if (typeof fileValue === 'string') {
+            result.file = fileValue;
+        }
+        else if (fileValue && typeof fileValue === 'object') {
+            const record = fileValue;
+            if ('data' in record && record.data) {
+                const mediaType = record.mediaType ?? 'text/plain';
+                if (typeof record.data === 'string') {
+                    result.file = asDataUrl(record.data, mediaType);
+                }
+                else {
+                    const base64 = encodeUint8ArrayToBase64(record.data);
+                    result.file = asDataUrl(base64, mediaType);
+                }
+            }
+            else if (typeof record.url === 'string' && record.url.length > 0) {
+                result.file = { url: record.url };
+            }
+            else {
+                const referencedId = (typeof record.id === 'string' &&
+                    record.id.length > 0 &&
+                    record.id) ||
+                    (typeof record.fileId === 'string' && record.fileId.length > 0
+                        ? record.fileId
+                        : undefined);
+                if (referencedId) {
+                    result.file = { id: referencedId };
+                }
+            }
+            if (typeof record.filename === 'string' && record.filename.length > 0) {
+                result.filename = record.filename;
+            }
+        }
+        if (output.providerData) {
+            result.providerData = output.providerData;
+        }
+        return result;
+    }
+    const exhaustiveCheck = output;
+    return exhaustiveCheck;
+}
+function buildItemFrequencyMap(items) {
+    const counts = new Map();
+    for (const item of items) {
+        const key = sessionItemKey(item);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return counts;
+}
+function buildItemReferenceMap(items) {
+    const refs = new Map();
+    for (const item of items) {
+        const key = sessionItemKey(item);
+        const list = refs.get(key);
+        if (list) {
+            list.push(item);
+        }
+        else {
+            refs.set(key, [item]);
+        }
+    }
+    return refs;
+}
+function consumeReference(refs, key, target) {
+    const candidates = refs.get(key);
+    if (!candidates || candidates.length === 0) {
+        return false;
+    }
+    const index = candidates.findIndex((candidate) => candidate === target);
+    if (index === -1) {
+        return false;
+    }
+    candidates.splice(index, 1);
+    if (candidates.length === 0) {
+        refs.delete(key);
+    }
+    return true;
+}
+function decrementCount(map, key) {
+    const remaining = (map.get(key) ?? 0) - 1;
+    if (remaining <= 0) {
+        map.delete(key);
+    }
+    else {
+        map.set(key, remaining);
+    }
+}
+function sessionItemKey(item) {
+    return JSON.stringify(item, sessionSerializationReplacer);
+}
+function sessionSerializationReplacer(_key, value) {
+    if (value instanceof ArrayBuffer) {
+        return {
+            __type: 'ArrayBuffer',
+            data: encodeUint8ArrayToBase64(new Uint8Array(value)),
+        };
+    }
+    if (isArrayBufferView(value)) {
+        const view = value;
+        return {
+            __type: view.constructor.name,
+            data: encodeUint8ArrayToBase64(new Uint8Array(view.buffer, view.byteOffset, view.byteLength)),
+        };
+    }
+    if (isNodeBuffer(value)) {
+        const view = value;
+        return {
+            __type: 'Buffer',
+            data: encodeUint8ArrayToBase64(new Uint8Array(view.buffer, view.byteOffset, view.byteLength)),
+        };
+    }
+    if (isSerializedBufferSnapshot(value)) {
+        return {
+            __type: 'Buffer',
+            data: encodeUint8ArrayToBase64(Uint8Array.from(value.data)),
+        };
+    }
+    return value;
+}
 //# sourceMappingURL=runImplementation.mjs.map