@openai/agents-core 0.2.1 → 0.3.1

package/dist/run.mjs

@@ -7,8 +7,8 @@ import { RunHooks } from "./lifecycle.mjs";
 import logger from "./logger.mjs";
 import { serializeTool, serializeHandoff } from "./utils/serialize.mjs";
 import { GuardrailExecutionError, InputGuardrailTripwireTriggered, MaxTurnsExceededError, ModelBehaviorError, OutputGuardrailTripwireTriggered, UserError, } from "./errors.mjs";
-import { addStepToRunResult, executeInterruptedToolsAndSideEffects, executeToolsAndSideEffects, maybeResetToolChoice, processModelResponse, streamStepItemsToRunResult, } from "./runImplementation.mjs";
-import { getOrCreateTrace, resetCurrentSpan, setCurrentSpan, withNewSpanContext, withTrace, } from "./tracing/context.mjs";
+import { addStepToRunResult, resolveInterruptedTurn, resolveTurnAfterModelResponse, maybeResetToolChoice, processModelResponse, streamStepItemsToRunResult, saveStreamInputToSession, saveStreamResultToSession, saveToSession, prepareInputItemsWithSession, } from "./runImplementation.mjs";
+import { getOrCreateTrace, addErrorToCurrentSpan, resetCurrentSpan, setCurrentSpan, withNewSpanContext, withTrace, } from "./tracing/context.mjs";
 import { createAgentSpan, withGuardrailSpan } from "./tracing/index.mjs";
 import { Usage } from "./usage.mjs";
 import { RunAgentUpdatedStreamEvent, RunRawModelStreamEvent } from "./events.mjs";
@@ -16,142 +16,28 @@ import { RunState } from "./runState.mjs";
 import { StreamEventResponseCompleted } from "./types/protocol.mjs";
 import { convertAgentOutputTypeToSerializable } from "./utils/tools.mjs";
 import { gpt5ReasoningSettingsRequired, isGpt5Default } from "./defaultModel.mjs";
-const DEFAULT_MAX_TURNS = 10;
-/**
- * @internal
- */
-export function getTracing(tracingDisabled, traceIncludeSensitiveData) {
-    if (tracingDisabled) {
-        return false;
-    }
-    if (traceIncludeSensitiveData) {
-        return true;
-    }
-    return 'enabled_without_data';
-}
-function toAgentInputList(originalInput) {
-    if (typeof originalInput === 'string') {
-        return [{ type: 'message', role: 'user', content: originalInput }];
-    }
-    return [...originalInput];
-}
-/**
- * Internal module for tracking the items in turns and ensuring that we don't send duplicate items.
- * This logic is vital for properly handling the items to send during multiple turns
- * when you use either `conversationId` or `previousResponseId`.
- * Both scenarios expect an agent loop to send only new items for each Responses API call.
- *
- * see also: https://platform.openai.com/docs/guides/conversation-state?api-mode=responses
- */
-class ServerConversationTracker {
-    // Conversation ID:
-    // - https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#using-the-conversations-api
-    // - https://platform.openai.com/docs/api-reference/conversations/create
-    conversationId;
-    // Previous Response ID:
-    // https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#passing-context-from-the-previous-response
-    previousResponseId;
-    // Using this flag because WeakSet does not provide a way to check its size
-    sentInitialInput = false;
-    // The items already sent to the model; using WeakSet for memory efficiency
-    sentItems = new WeakSet();
-    // The items received from the server; using WeakSet for memory efficiency
-    serverItems = new WeakSet();
-    constructor({ conversationId, previousResponseId, }) {
-        this.conversationId = conversationId ?? undefined;
-        this.previousResponseId = previousResponseId ?? undefined;
-    }
-    /**
-     * Pre-populates tracker caches from an existing RunState when resuming server-managed runs.
-     */
-    primeFromState({ originalInput, generatedItems, modelResponses, }) {
-        if (this.sentInitialInput) {
-            return;
-        }
-        for (const item of toAgentInputList(originalInput)) {
-            if (item && typeof item === 'object') {
-                this.sentItems.add(item);
-            }
-        }
-        this.sentInitialInput = true;
-        const latestResponse = modelResponses[modelResponses.length - 1];
-        for (const response of modelResponses) {
-            for (const item of response.output) {
-                if (item && typeof item === 'object') {
-                    this.serverItems.add(item);
-                }
-            }
-        }
-        if (!this.conversationId && latestResponse?.responseId) {
-            this.previousResponseId = latestResponse.responseId;
-        }
-        for (const item of generatedItems) {
-            const rawItem = item.rawItem;
-            if (!rawItem || typeof rawItem !== 'object') {
-                continue;
-            }
-            if (this.serverItems.has(rawItem)) {
-                this.sentItems.add(rawItem);
-            }
-        }
-    }
-    trackServerItems(modelResponse) {
-        if (!modelResponse) {
-            return;
-        }
-        for (const item of modelResponse.output) {
-            if (item && typeof item === 'object') {
-                this.serverItems.add(item);
-            }
-        }
-        if (!this.conversationId &&
-            this.previousResponseId !== undefined &&
-            modelResponse.responseId) {
-            this.previousResponseId = modelResponse.responseId;
-        }
+import { encodeUint8ArrayToBase64 } from "./utils/base64.mjs";
+import { isArrayBufferView, isNodeBuffer, isSerializedBufferSnapshot, } from "./utils/smartString.mjs";
+export async function run(agent, input, options) {
+    const runner = getDefaultRunner();
+    if (options?.stream) {
+        return await runner.run(agent, input, options);
     }
-    prepareInput(originalInput, generatedItems) {
-        const inputItems = [];
-        if (!this.sentInitialInput) {
-            const initialItems = toAgentInputList(originalInput);
-            for (const item of initialItems) {
-                inputItems.push(item);
-                if (item && typeof item === 'object') {
-                    this.sentItems.add(item);
-                }
-            }
-            this.sentInitialInput = true;
-        }
-        for (const item of generatedItems) {
-            if (item.type === 'tool_approval_item') {
-                continue;
-            }
-            const rawItem = item.rawItem;
-            if (!rawItem || typeof rawItem !== 'object') {
-                continue;
-            }
-            if (this.sentItems.has(rawItem) || this.serverItems.has(rawItem)) {
-                continue;
-            }
-            inputItems.push(rawItem);
-            this.sentItems.add(rawItem);
-        }
-        return inputItems;
+    else {
+        return await runner.run(agent, input, options);
     }
 }
-export function getTurnInput(originalInput, generatedItems) {
-    const rawItems = generatedItems
-        .filter((item) => item.type !== 'tool_approval_item') // don't include approval items to avoid double function calls
-        .map((item) => item.rawItem);
-    return [...toAgentInputList(originalInput), ...rawItems];
-}
 /**
- * A Runner is responsible for running an agent workflow.
+ * Orchestrates agent execution, including guardrails, tool calls, session persistence, and
+ * tracing. Reuse a `Runner` instance when you want consistent configuration across multiple runs.
  */
 export class Runner extends RunHooks {
     config;
-    inputGuardrailDefs;
-    outputGuardrailDefs;
+    /**
+     * Creates a runner with optional defaults that apply to every subsequent run invocation.
+     *
+     * @param config - Overrides for models, guardrails, tracing, or session behavior.
+     */
     constructor(config = {}) {
         super();
         this.config = {
@@ -167,14 +53,270 @@ export class Runner extends RunHooks {
             traceId: config.traceId,
             groupId: config.groupId,
             traceMetadata: config.traceMetadata,
+            sessionInputCallback: config.sessionInputCallback,
+            callModelInputFilter: config.callModelInputFilter,
         };
         this.inputGuardrailDefs = (config.inputGuardrails ?? []).map(defineInputGuardrail);
         this.outputGuardrailDefs = (config.outputGuardrails ?? []).map(defineOutputGuardrail);
     }
+    async run(agent, input, options = {
+        stream: false,
+        context: undefined,
+    }) {
+        const resolvedOptions = options ?? { stream: false, context: undefined };
+        // Per-run options take precedence over runner defaults for session memory behavior.
+        const sessionInputCallback = resolvedOptions.sessionInputCallback ?? this.config.sessionInputCallback;
+        // Likewise allow callers to override callModelInputFilter on individual runs.
+        const callModelInputFilter = resolvedOptions.callModelInputFilter ?? this.config.callModelInputFilter;
+        const hasCallModelInputFilter = Boolean(callModelInputFilter);
+        const effectiveOptions = {
+            ...resolvedOptions,
+            sessionInputCallback,
+            callModelInputFilter,
+        };
+        const serverManagesConversation = Boolean(effectiveOptions.conversationId) ||
+            Boolean(effectiveOptions.previousResponseId);
+        // When the server tracks conversation history we defer to it for previous turns so local session
+        // persistence can focus solely on the new delta being generated in this process.
+        const session = effectiveOptions.session;
+        const resumingFromState = input instanceof RunState;
+        let sessionInputOriginalSnapshot = session && resumingFromState ? [] : undefined;
+        let sessionInputFilteredSnapshot = undefined;
+        // Tracks remaining persistence slots per AgentInputItem key so resumed sessions only write each original occurrence once.
+        let sessionInputPendingWriteCounts = session && resumingFromState ? new Map() : undefined;
+        // Keeps track of which inputs should be written back to session memory. `sourceItems` reflects
+        // the original objects (so we can respect resume counts) while `filteredItems`, when present,
+        // contains the filtered/redacted clones that must be persisted for history.
+        // The helper reconciles the filtered copies produced by callModelInputFilter with their original
+        // counterparts so resume-from-state bookkeeping stays consistent and duplicate references only
+        // consume a single persistence slot.
+        const recordSessionItemsForPersistence = (sourceItems, filteredItems) => {
+            const pendingWriteCounts = sessionInputPendingWriteCounts;
+            if (filteredItems !== undefined) {
+                if (!pendingWriteCounts) {
+                    sessionInputFilteredSnapshot = filteredItems.map((item) => structuredClone(item));
+                    return;
+                }
+                const persistableItems = [];
+                const sourceOccurrenceCounts = new WeakMap();
+                // Track how many times each original object appears so duplicate references only consume one persistence slot.
+                for (const source of sourceItems) {
+                    if (!source || typeof source !== 'object') {
+                        continue;
+                    }
+                    const nextCount = (sourceOccurrenceCounts.get(source) ?? 0) + 1;
+                    sourceOccurrenceCounts.set(source, nextCount);
+                }
+                // Let filtered items without a one-to-one source match claim any remaining persistence count.
+                const consumeAnyPendingWriteSlot = () => {
+                    for (const [key, remaining] of pendingWriteCounts) {
+                        if (remaining > 0) {
+                            pendingWriteCounts.set(key, remaining - 1);
+                            return true;
+                        }
+                    }
+                    return false;
+                };
+                for (let i = 0; i < filteredItems.length; i++) {
+                    const filteredItem = filteredItems[i];
+                    if (!filteredItem) {
+                        continue;
+                    }
+                    let allocated = false;
+                    const source = sourceItems[i];
+                    if (source && typeof source === 'object') {
+                        const pendingOccurrences = (sourceOccurrenceCounts.get(source) ?? 0) - 1;
+                        sourceOccurrenceCounts.set(source, pendingOccurrences);
+                        if (pendingOccurrences > 0) {
+                            continue;
+                        }
+                        const sourceKey = getAgentInputItemKey(source);
+                        const remaining = pendingWriteCounts.get(sourceKey) ?? 0;
+                        if (remaining > 0) {
+                            pendingWriteCounts.set(sourceKey, remaining - 1);
+                            persistableItems.push(structuredClone(filteredItem));
+                            allocated = true;
+                            continue;
+                        }
+                    }
+                    const filteredKey = getAgentInputItemKey(filteredItem);
+                    const filteredRemaining = pendingWriteCounts.get(filteredKey) ?? 0;
+                    if (filteredRemaining > 0) {
+                        pendingWriteCounts.set(filteredKey, filteredRemaining - 1);
+                        persistableItems.push(structuredClone(filteredItem));
+                        allocated = true;
+                        continue;
+                    }
+                    if (!source && consumeAnyPendingWriteSlot()) {
+                        persistableItems.push(structuredClone(filteredItem));
+                        allocated = true;
+                    }
+                    if (!allocated &&
+                        !source &&
+                        sessionInputFilteredSnapshot === undefined) {
+                        // Preserve at least one copy so later persistence resolves even when no counters remain.
+                        persistableItems.push(structuredClone(filteredItem));
+                    }
+                }
+                if (persistableItems.length > 0 ||
+                    sessionInputFilteredSnapshot === undefined) {
+                    sessionInputFilteredSnapshot = persistableItems;
+                }
+                return;
+            }
+            const filtered = [];
+            if (!pendingWriteCounts) {
+                for (const item of sourceItems) {
+                    if (!item) {
+                        continue;
+                    }
+                    filtered.push(structuredClone(item));
+                }
+            }
+            else {
+                for (const item of sourceItems) {
+                    if (!item) {
+                        continue;
+                    }
+                    const key = getAgentInputItemKey(item);
+                    const remaining = pendingWriteCounts.get(key) ?? 0;
+                    if (remaining <= 0) {
+                        continue;
+                    }
+                    pendingWriteCounts.set(key, remaining - 1);
+                    filtered.push(structuredClone(item));
+                }
+            }
+            if (filtered.length > 0) {
+                sessionInputFilteredSnapshot = filtered;
+            }
+            else if (sessionInputFilteredSnapshot === undefined) {
+                sessionInputFilteredSnapshot = [];
+            }
+        };
+        // Determine which items should be committed to session memory for this turn.
+        // Filters take precedence because they reflect the exact payload delivered to the model.
+        const resolveSessionItemsForPersistence = () => {
+            if (sessionInputFilteredSnapshot !== undefined) {
+                return sessionInputFilteredSnapshot;
+            }
+            if (hasCallModelInputFilter) {
+                return undefined;
+            }
+            return sessionInputOriginalSnapshot;
+        };
+        let preparedInput = input;
+        if (!(preparedInput instanceof RunState)) {
+            if (session && Array.isArray(preparedInput) && !sessionInputCallback) {
+                throw new UserError('RunConfig.sessionInputCallback must be provided when using session history with list inputs.');
+            }
+            const prepared = await prepareInputItemsWithSession(preparedInput, session, sessionInputCallback, {
+                // When the server tracks conversation state we only send the new turn inputs;
+                // previous messages are recovered via conversationId/previousResponseId.
+                includeHistoryInPreparedInput: !serverManagesConversation,
+                preserveDroppedNewItems: serverManagesConversation,
+            });
+            if (serverManagesConversation && session) {
+                // When the server manages memory we only persist the new turn inputs locally so the
+                // conversation service stays the single source of truth for prior exchanges.
+                const sessionItems = prepared.sessionItems;
+                if (sessionItems && sessionItems.length > 0) {
+                    preparedInput = sessionItems;
+                }
+                else {
+                    preparedInput = prepared.preparedInput;
+                }
+            }
+            else {
+                preparedInput = prepared.preparedInput;
+            }
+            if (session) {
+                const items = prepared.sessionItems ?? [];
+                // Clone the items that will be persisted so later mutations (filters, hooks) cannot desync history.
+                sessionInputOriginalSnapshot = items.map((item) => structuredClone(item));
+                // Reset pending counts so each prepared item reserves exactly one write slot until filters resolve matches.
+                sessionInputPendingWriteCounts = new Map();
+                for (const item of items) {
+                    const key = getAgentInputItemKey(item);
+                    sessionInputPendingWriteCounts.set(key, (sessionInputPendingWriteCounts.get(key) ?? 0) + 1);
+                }
+            }
+        }
+        // Streaming runs persist the input asynchronously, so track a one-shot helper
+        // that can be awaited from multiple branches without double-writing.
+        let ensureStreamInputPersisted;
+        // Sessions remain usable alongside server-managed conversations (e.g., OpenAIConversationsSession)
+        // so callers can reuse callbacks, resume-from-state logic, and other helpers without duplicating
+        // remote history, so persistence is gated on serverManagesConversation.
+        if (session && !serverManagesConversation) {
+            let persisted = false;
+            ensureStreamInputPersisted = async () => {
+                if (persisted) {
+                    return;
+                }
+                const itemsToPersist = resolveSessionItemsForPersistence();
+                if (!itemsToPersist || itemsToPersist.length === 0) {
+                    return;
+                }
+                persisted = true;
+                await saveStreamInputToSession(session, itemsToPersist);
+            };
+        }
+        const executeRun = async () => {
+            if (effectiveOptions.stream) {
+                const streamResult = await this.#runIndividualStream(agent, preparedInput, effectiveOptions, ensureStreamInputPersisted, recordSessionItemsForPersistence);
+                return streamResult;
+            }
+            const runResult = await this.#runIndividualNonStream(agent, preparedInput, effectiveOptions, recordSessionItemsForPersistence);
+            // See note above: allow sessions to run for callbacks/state but skip writes when the server
+            // is the source of truth for transcript history.
+            if (session && !serverManagesConversation) {
+                await saveToSession(session, resolveSessionItemsForPersistence(), runResult);
+            }
+            return runResult;
+        };
+        if (preparedInput instanceof RunState && preparedInput._trace) {
+            return withTrace(preparedInput._trace, async () => {
+                if (preparedInput._currentAgentSpan) {
+                    setCurrentSpan(preparedInput._currentAgentSpan);
+                }
+                return executeRun();
+            });
+        }
+        return getOrCreateTrace(async () => executeRun(), {
+            traceId: this.config.traceId,
+            name: this.config.workflowName,
+            groupId: this.config.groupId,
+            metadata: this.config.traceMetadata,
+        });
+    }
+    // --------------------------------------------------------------
+    //  Internals
+    // --------------------------------------------------------------
+    inputGuardrailDefs;
+    outputGuardrailDefs;
+    /**
+     * @internal
+     * Resolves the effective model once so both run loops obey the same precedence rules.
+     */
+    async #resolveModelForAgent(agent) {
+        const explictlyModelSet = (agent.model !== undefined &&
+            agent.model !== Agent.DEFAULT_MODEL_PLACEHOLDER) ||
+            (this.config.model !== undefined &&
+                this.config.model !== Agent.DEFAULT_MODEL_PLACEHOLDER);
+        let resolvedModel = selectModel(agent.model, this.config.model);
+        if (typeof resolvedModel === 'string') {
+            resolvedModel = await this.config.modelProvider.getModel(resolvedModel);
+        }
+        return { model: resolvedModel, explictlyModelSet };
+    }
     /**
      * @internal
      */
-    async #runIndividualNonStream(startingAgent, input, options) {
+    async #runIndividualNonStream(startingAgent, input, options, 
+    // sessionInputUpdate lets the caller adjust queued session items after filters run so we
+    // persist exactly what we send to the model (e.g., after redactions or truncation).
+    sessionInputUpdate) {
         return withNewSpanContext(async () => {
             // if we have a saved state we use that one, otherwise we create a new one
             const isResumedState = input instanceof RunState;
@@ -198,13 +340,6 @@ export class Runner extends RunHooks {
             }
             try {
                 while (true) {
-                    const explictlyModelSet = (state._currentAgent.model !== undefined &&
-                        state._currentAgent.model !== '') ||
-                        (this.config.model !== undefined && this.config.model !== '');
-                    let model = selectModel(state._currentAgent.model, this.config.model);
-                    if (typeof model === 'string') {
-                        model = await this.config.modelProvider.getModel(model);
-                    }
                     // if we don't have a current step, we treat this as a new run
                     state._currentStep = state._currentStep ?? {
                         type: 'next_step_run_again',
@@ -214,10 +349,13 @@ export class Runner extends RunHooks {
                         if (!state._lastTurnResponse || !state._lastProcessedResponse) {
                             throw new UserError('No model response found in previous state', state);
                         }
-                        const turnResult = await executeInterruptedToolsAndSideEffects(state._currentAgent, state._originalInput, state._generatedItems, state._lastTurnResponse, state._lastProcessedResponse, this, state);
+                        const turnResult = await resolveInterruptedTurn(state._currentAgent, state._originalInput, state._generatedItems, state._lastTurnResponse, state._lastProcessedResponse, this, state);
                         state._toolUseTracker.addToolUse(state._currentAgent, state._lastProcessedResponse.toolsUsed);
                         state._originalInput = turnResult.originalInput;
                         state._generatedItems = turnResult.generatedItems;
+                        if (turnResult.nextStep.type === 'next_step_run_again') {
+                            state._currentTurnPersistedItemCount = 0;
+                        }
                         state._currentStep = turnResult.nextStep;
                         if (turnResult.nextStep.type === 'next_step_interruption') {
                             // we are still in an interruption, so we need to avoid an infinite loop
@@ -226,26 +364,9 @@ export class Runner extends RunHooks {
                         continue;
                     }
                     if (state._currentStep.type === 'next_step_run_again') {
-                        const handoffs = await state._currentAgent.getEnabledHandoffs(state._context);
-                        if (!state._currentAgentSpan) {
-                            const handoffNames = handoffs.map((h) => h.agentName);
-                            state._currentAgentSpan = createAgentSpan({
-                                data: {
-                                    name: state._currentAgent.name,
-                                    handoffs: handoffNames,
-                                    output_type: state._currentAgent.outputSchemaName,
-                                },
-                            });
-                            state._currentAgentSpan.start();
-                            setCurrentSpan(state._currentAgentSpan);
-                        }
-                        const tools = await state._currentAgent.getAllTools(state._context);
-                        const serializedTools = tools.map((t) => serializeTool(t));
-                        const serializedHandoffs = handoffs.map((h) => serializeHandoff(h));
-                        if (state._currentAgentSpan) {
-                            state._currentAgentSpan.spanData.tools = tools.map((t) => t.name);
-                        }
+                        const artifacts = await prepareAgentArtifacts(state);
                         state._currentTurn++;
+                        state._currentTurnPersistedItemCount = 0;
                         if (state._currentTurn > state._maxTurns) {
                             state._currentAgentSpan?.setError({
                                 message: 'Max turns exceeded',
@@ -264,42 +385,39 @@ export class Runner extends RunHooks {
                             state._currentAgent.emit('agent_start', state._context, state._currentAgent);
                             this.emit('agent_start', state._context, state._currentAgent);
                         }
-                        let modelSettings = {
-                            ...this.config.modelSettings,
-                            ...state._currentAgent.modelSettings,
-                        };
-                        const agentModelSettings = state._currentAgent.modelSettings;
-                        modelSettings = adjustModelSettingsForNonGPT5RunnerModel(explictlyModelSet, agentModelSettings, model, modelSettings);
-                        modelSettings = maybeResetToolChoice(state._currentAgent, state._toolUseTracker, modelSettings);
-                        const previousResponseId = serverConversationTracker?.previousResponseId ??
-                            options.previousResponseId;
-                        const conversationId = serverConversationTracker?.conversationId ??
-                            options.conversationId;
-                        state._lastTurnResponse = await model.getResponse({
-                            systemInstructions: await state._currentAgent.getSystemPrompt(state._context),
-                            prompt: await state._currentAgent.getPrompt(state._context),
+                        const preparedCall = await this.#prepareModelCall(state, options, artifacts, turnInput, serverConversationTracker, sessionInputUpdate);
+                        state._lastTurnResponse = await preparedCall.model.getResponse({
+                            systemInstructions: preparedCall.modelInput.instructions,
+                            prompt: preparedCall.prompt,
                             // Explicit agent/run config models should take precedence over prompt defaults.
-                            ...(explictlyModelSet ? { overridePromptModel: true } : {}),
-                            input: turnInput,
-                            previousResponseId,
-                            conversationId,
-                            modelSettings,
-                            tools: serializedTools,
+                            ...(preparedCall.explictlyModelSet
+                                ? { overridePromptModel: true }
+                                : {}),
+                            input: preparedCall.modelInput.input,
+                            previousResponseId: preparedCall.previousResponseId,
+                            conversationId: preparedCall.conversationId,
+                            modelSettings: preparedCall.modelSettings,
+                            tools: preparedCall.serializedTools,
                             outputType: convertAgentOutputTypeToSerializable(state._currentAgent.outputType),
-                            handoffs: serializedHandoffs,
+                            handoffs: preparedCall.serializedHandoffs,
                             tracing: getTracing(this.config.tracingDisabled, this.config.traceIncludeSensitiveData),
                             signal: options.signal,
                         });
                         state._modelResponses.push(state._lastTurnResponse);
                         state._context.usage.add(state._lastTurnResponse.usage);
                         state._noActiveAgentRun = false;
+                        // After each turn record the items echoed by the server so future requests only
+                        // include the incremental inputs that have not yet been acknowledged.
                         serverConversationTracker?.trackServerItems(state._lastTurnResponse);
-                        const processedResponse = processModelResponse(state._lastTurnResponse, state._currentAgent, tools, handoffs);
+                        const processedResponse = processModelResponse(state._lastTurnResponse, state._currentAgent, preparedCall.tools, preparedCall.handoffs);
                         state._lastProcessedResponse = processedResponse;
-                        const turnResult = await executeToolsAndSideEffects(state._currentAgent, state._originalInput, state._generatedItems, state._lastTurnResponse, state._lastProcessedResponse, this, state);
+                        const turnResult = await resolveTurnAfterModelResponse(state._currentAgent, state._originalInput, state._generatedItems, state._lastTurnResponse, state._lastProcessedResponse, this, state);
                         state._toolUseTracker.addToolUse(state._currentAgent, state._lastProcessedResponse.toolsUsed);
                         state._originalInput = turnResult.originalInput;
                         state._generatedItems = turnResult.generatedItems;
+                        if (turnResult.nextStep.type === 'next_step_run_again') {
+                            state._currentTurnPersistedItemCount = 0;
+                        }
                         state._currentStep = turnResult.nextStep;
                     }
                     if (state._currentStep &&
@@ -351,92 +469,27 @@ export class Runner extends RunHooks {
             }
         });
     }
-    async #runInputGuardrails(state) {
-        const guardrails = this.inputGuardrailDefs.concat(state._currentAgent.inputGuardrails.map(defineInputGuardrail));
-        if (guardrails.length > 0) {
-            const guardrailArgs = {
-                agent: state._currentAgent,
-                input: state._originalInput,
-                context: state._context,
-            };
-            try {
-                const results = await Promise.all(guardrails.map(async (guardrail) => {
-                    return withGuardrailSpan(async (span) => {
-                        const result = await guardrail.run(guardrailArgs);
-                        span.spanData.triggered = result.output.tripwireTriggered;
-                        return result;
-                    }, { data: { name: guardrail.name } }, state._currentAgentSpan);
-                }));
-                for (const result of results) {
-                    if (result.output.tripwireTriggered) {
-                        if (state._currentAgentSpan) {
-                            state._currentAgentSpan.setError({
-                                message: 'Guardrail tripwire triggered',
-                                data: { guardrail: result.guardrail.name },
-                            });
-                        }
-                        throw new InputGuardrailTripwireTriggered(`Input guardrail triggered: ${JSON.stringify(result.output.outputInfo)}`, result, state);
-                    }
-                }
-            }
-            catch (e) {
-                if (e instanceof InputGuardrailTripwireTriggered) {
-                    throw e;
-                }
-                // roll back the current turn to enable reruns
-                state._currentTurn--;
-                throw new GuardrailExecutionError(`Input guardrail failed to complete: ${e}`, e, state);
+    /**
+     * @internal
+     */
+    async #runStreamLoop(result, options, isResumedState, ensureStreamInputPersisted, sessionInputUpdate) {
+        const serverManagesConversation = Boolean(options.conversationId) || Boolean(options.previousResponseId);
+        const serverConversationTracker = serverManagesConversation
+            ? new ServerConversationTracker({
+                conversationId: options.conversationId,
+                previousResponseId: options.previousResponseId,
+            })
+            : undefined;
+        let handedInputToModel = false;
+        let streamInputPersisted = false;
+        const persistStreamInputIfNeeded = async () => {
+            if (streamInputPersisted || !ensureStreamInputPersisted) {
+                return;
             }
-        }
-    }
-    async #runOutputGuardrails(state, output) {
-        const guardrails = this.outputGuardrailDefs.concat(state._currentAgent.outputGuardrails.map(defineOutputGuardrail));
-        if (guardrails.length > 0) {
-            const agentOutput = state._currentAgent.processFinalOutput(output);
-            const guardrailArgs = {
-                agent: state._currentAgent,
-                agentOutput,
-                context: state._context,
-                details: { modelResponse: state._lastTurnResponse },
-            };
-            try {
-                const results = await Promise.all(guardrails.map(async (guardrail) => {
-                    return withGuardrailSpan(async (span) => {
-                        const result = await guardrail.run(guardrailArgs);
-                        span.spanData.triggered = result.output.tripwireTriggered;
-                        return result;
-                    }, { data: { name: guardrail.name } }, state._currentAgentSpan);
-                }));
-                for (const result of results) {
-                    if (result.output.tripwireTriggered) {
-                        if (state._currentAgentSpan) {
-                            state._currentAgentSpan.setError({
-                                message: 'Guardrail tripwire triggered',
-                                data: { guardrail: result.guardrail.name },
-                            });
-                        }
-                        throw new OutputGuardrailTripwireTriggered(`Output guardrail triggered: ${JSON.stringify(result.output.outputInfo)}`, result, state);
-                    }
-                }
-            }
-            catch (e) {
-                if (e instanceof OutputGuardrailTripwireTriggered) {
-                    throw e;
-                }
-                throw new GuardrailExecutionError(`Output guardrail failed to complete: ${e}`, e, state);
-            }
-        }
-    }
-    /**
-     * @internal
-     */
-    async #runStreamLoop(result, options, isResumedState) {
-        const serverConversationTracker = options.conversationId || options.previousResponseId
-            ? new ServerConversationTracker({
-                conversationId: options.conversationId,
-                previousResponseId: options.previousResponseId,
-            })
-            : undefined;
+            // Both success and error paths call this helper, so guard against multiple writes.
+            await ensureStreamInputPersisted();
+            streamInputPersisted = true;
+        };
         if (serverConversationTracker && isResumedState) {
             serverConversationTracker.primeFromState({
                 originalInput: result.state._originalInput,
@@ -447,10 +500,6 @@ export class Runner extends RunHooks {
         try {
             while (true) {
                 const currentAgent = result.state._currentAgent;
-                const handoffs = await currentAgent.getEnabledHandoffs(result.state._context);
-                const tools = await currentAgent.getAllTools(result.state._context);
-                const serializedTools = tools.map((t) => serializeTool(t));
-                const serializedHandoffs = handoffs.map((h) => serializeHandoff(h));
                 result.state._currentStep = result.state._currentStep ?? {
                     type: 'next_step_run_again',
                 };
@@ -460,11 +509,14 @@ export class Runner extends RunHooks {
                         !result.state._lastProcessedResponse) {
                         throw new UserError('No model response found in previous state', result.state);
                     }
-                    const turnResult = await executeInterruptedToolsAndSideEffects(result.state._currentAgent, result.state._originalInput, result.state._generatedItems, result.state._lastTurnResponse, result.state._lastProcessedResponse, this, result.state);
+                    const turnResult = await resolveInterruptedTurn(result.state._currentAgent, result.state._originalInput, result.state._generatedItems, result.state._lastTurnResponse, result.state._lastProcessedResponse, this, result.state);
                     addStepToRunResult(result, turnResult);
                     result.state._toolUseTracker.addToolUse(result.state._currentAgent, result.state._lastProcessedResponse.toolsUsed);
                     result.state._originalInput = turnResult.originalInput;
                     result.state._generatedItems = turnResult.generatedItems;
+                    if (turnResult.nextStep.type === 'next_step_run_again') {
+                        result.state._currentTurnPersistedItemCount = 0;
+                    }
                     result.state._currentStep = turnResult.nextStep;
                     if (turnResult.nextStep.type === 'next_step_interruption') {
                         // we are still in an interruption, so we need to avoid an infinite loop
@@ -473,20 +525,9 @@ export class Runner extends RunHooks {
                     continue;
                 }
                 if (result.state._currentStep.type === 'next_step_run_again') {
-                    if (!result.state._currentAgentSpan) {
-                        const handoffNames = handoffs.map((h) => h.agentName);
-                        result.state._currentAgentSpan = createAgentSpan({
-                            data: {
-                                name: currentAgent.name,
-                                handoffs: handoffNames,
-                                tools: tools.map((t) => t.name),
-                                output_type: currentAgent.outputSchemaName,
-                            },
-                        });
-                        result.state._currentAgentSpan.start();
-                        setCurrentSpan(result.state._currentAgentSpan);
-                    }
+                    const artifacts = await prepareAgentArtifacts(result.state);
                     result.state._currentTurn++;
+                    result.state._currentTurnPersistedItemCount = 0;
                     if (result.state._currentTurn > result.state._maxTurns) {
                         result.state._currentAgentSpan?.setError({
                             message: 'Max turns exceeded',
@@ -495,22 +536,9 @@ export class Runner extends RunHooks {
                         throw new MaxTurnsExceededError(`Max turns (${result.state._maxTurns}) exceeded`, result.state);
                     }
                     logger.debug(`Running agent ${currentAgent.name} (turn ${result.state._currentTurn})`);
-                    const explictlyModelSet = (currentAgent.model !== undefined && currentAgent.model !== '') ||
-                        (this.config.model !== undefined && this.config.model !== '');
-                    let model = selectModel(currentAgent.model, this.config.model);
-                    if (typeof model === 'string') {
-                        model = await this.config.modelProvider.getModel(model);
-                    }
                     if (result.state._currentTurn === 1) {
                         await this.#runInputGuardrails(result.state);
                     }
-                    let modelSettings = {
-                        ...this.config.modelSettings,
-                        ...currentAgent.modelSettings,
-                    };
-                    const agentModelSettings = currentAgent.modelSettings;
-                    modelSettings = adjustModelSettingsForNonGPT5RunnerModel(explictlyModelSet, agentModelSettings, model, modelSettings);
-                    modelSettings = maybeResetToolChoice(currentAgent, result.state._toolUseTracker, modelSettings);
                     const turnInput = serverConversationTracker
                         ? serverConversationTracker.prepareInput(result.input, result.newItems)
                         : getTurnInput(result.input, result.newItems);
@@ -519,20 +547,22 @@ export class Runner extends RunHooks {
                         this.emit('agent_start', result.state._context, currentAgent);
                     }
                     let finalResponse = undefined;
-                    const previousResponseId = serverConversationTracker?.previousResponseId ??
-                        options.previousResponseId;
-                    const conversationId = serverConversationTracker?.conversationId ?? options.conversationId;
-                    for await (const event of model.getStreamedResponse({
-                        systemInstructions: await currentAgent.getSystemPrompt(result.state._context),
-                        prompt: await currentAgent.getPrompt(result.state._context),
+                    const preparedCall = await this.#prepareModelCall(result.state, options, artifacts, turnInput, serverConversationTracker, sessionInputUpdate);
+                    handedInputToModel = true;
+                    await persistStreamInputIfNeeded();
+                    for await (const event of preparedCall.model.getStreamedResponse({
+                        systemInstructions: preparedCall.modelInput.instructions,
+                        prompt: preparedCall.prompt,
                         // Streaming requests should also honor explicitly chosen models.
-                        ...(explictlyModelSet ? { overridePromptModel: true } : {}),
-                        input: turnInput,
-                        previousResponseId,
-                        conversationId,
-                        modelSettings,
-                        tools: serializedTools,
-                        handoffs: serializedHandoffs,
+                        ...(preparedCall.explictlyModelSet
+                            ? { overridePromptModel: true }
+                            : {}),
+                        input: preparedCall.modelInput.input,
+                        previousResponseId: preparedCall.previousResponseId,
+                        conversationId: preparedCall.conversationId,
+                        modelSettings: preparedCall.modelSettings,
+                        tools: preparedCall.serializedTools,
+                        handoffs: preparedCall.serializedHandoffs,
                         outputType: convertAgentOutputTypeToSerializable(currentAgent.outputType),
                         tracing: getTracing(this.config.tracingDisabled, this.config.traceIncludeSensitiveData),
                         signal: options.signal,
@@ -557,9 +587,10 @@ export class Runner extends RunHooks {
                         throw new ModelBehaviorError('Model did not produce a final response!', result.state);
                     }
                     result.state._lastTurnResponse = finalResponse;
+                    // Keep the tracker in sync with the streamed response so reconnections remain accurate.
                     serverConversationTracker?.trackServerItems(finalResponse);
                     result.state._modelResponses.push(result.state._lastTurnResponse);
-                    const processedResponse = processModelResponse(result.state._lastTurnResponse, currentAgent, tools, handoffs);
+                    const processedResponse = processModelResponse(result.state._lastTurnResponse, currentAgent, preparedCall.tools, preparedCall.handoffs);
                     result.state._lastProcessedResponse = processedResponse;
                     // Record the items emitted directly from the model response so we do not
                     // stream them again after tools and other side effects finish.
@@ -567,23 +598,35 @@ export class Runner extends RunHooks {
                     if (preToolItems.size > 0) {
                         streamStepItemsToRunResult(result, processedResponse.newItems);
                     }
-                    const turnResult = await executeToolsAndSideEffects(currentAgent, result.state._originalInput, result.state._generatedItems, result.state._lastTurnResponse, result.state._lastProcessedResponse, this, result.state);
+                    const turnResult = await resolveTurnAfterModelResponse(currentAgent, result.state._originalInput, result.state._generatedItems, result.state._lastTurnResponse, result.state._lastProcessedResponse, this, result.state);
                     addStepToRunResult(result, turnResult, {
                         skipItems: preToolItems,
                     });
                     result.state._toolUseTracker.addToolUse(currentAgent, processedResponse.toolsUsed);
                     result.state._originalInput = turnResult.originalInput;
                     result.state._generatedItems = turnResult.generatedItems;
+                    if (turnResult.nextStep.type === 'next_step_run_again') {
+                        result.state._currentTurnPersistedItemCount = 0;
+                    }
                     result.state._currentStep = turnResult.nextStep;
                 }
                 if (result.state._currentStep.type === 'next_step_final_output') {
                     await this.#runOutputGuardrails(result.state, result.state._currentStep.output);
+                    await persistStreamInputIfNeeded();
+                    // Guardrails must succeed before persisting session memory to avoid storing blocked outputs.
+                    if (!serverManagesConversation) {
+                        await saveStreamResultToSession(options.session, result);
+                    }
                     this.emit('agent_end', result.state._context, currentAgent, result.state._currentStep.output);
                     currentAgent.emit('agent_end', result.state._context, result.state._currentStep.output);
                     return;
                 }
                 else if (result.state._currentStep.type === 'next_step_interruption') {
                     // we are done for now. Don't run any output guardrails
+                    await persistStreamInputIfNeeded();
+                    if (!serverManagesConversation) {
+                        await saveStreamResultToSession(options.session, result);
+                    }
                     return;
                 }
                 else if (result.state._currentStep.type === 'next_step_handoff') {
@@ -607,6 +650,9 @@ export class Runner extends RunHooks {
             }
         }
         catch (error) {
+            if (handedInputToModel && !streamInputPersisted) {
+                await persistStreamInputIfNeeded();
+            }
             if (result.state._currentAgentSpan) {
                 result.state._currentAgentSpan.setError({
                     message: 'Error in agent run',
@@ -627,7 +673,7 @@ export class Runner extends RunHooks {
     /**
      * @internal
      */
-    async #runIndividualStream(agent, input, options) {
+    async #runIndividualStream(agent, input, options, ensureStreamInputPersisted, sessionInputUpdate) {
         options = options ?? {};
         return withNewSpanContext(async () => {
             // Initialize or reuse existing state
@@ -645,7 +691,7 @@ export class Runner extends RunHooks {
             // Setup defaults
             result.maxTurns = options.maxTurns ?? state._maxTurns;
             // Continue the stream loop without blocking
-            const streamLoopPromise = this.#runStreamLoop(result, options, isResumedState).then(() => {
+            const streamLoopPromise = this.#runStreamLoop(result, options, isResumedState, ensureStreamInputPersisted, sessionInputUpdate).then(() => {
                 result._done();
             }, (err) => {
                 result._raiseError(err);
@@ -655,38 +701,137 @@ export class Runner extends RunHooks {
             return result;
         });
     }
-    run(agent, input, options = {
-        stream: false,
-        context: undefined,
-    }) {
-        if (input instanceof RunState && input._trace) {
-            return withTrace(input._trace, async () => {
-                if (input._currentAgentSpan) {
-                    setCurrentSpan(input._currentAgentSpan);
-                }
-                if (options?.stream) {
-                    return this.#runIndividualStream(agent, input, options);
+    async #runInputGuardrails(state) {
+        const guardrails = this.inputGuardrailDefs.concat(state._currentAgent.inputGuardrails.map(defineInputGuardrail));
+        if (guardrails.length > 0) {
+            const guardrailArgs = {
+                agent: state._currentAgent,
+                input: state._originalInput,
+                context: state._context,
+            };
+            try {
+                const results = await Promise.all(guardrails.map(async (guardrail) => {
+                    return withGuardrailSpan(async (span) => {
+                        const result = await guardrail.run(guardrailArgs);
+                        span.spanData.triggered = result.output.tripwireTriggered;
+                        return result;
+                    }, { data: { name: guardrail.name } }, state._currentAgentSpan);
+                }));
+                for (const result of results) {
+                    if (result.output.tripwireTriggered) {
+                        if (state._currentAgentSpan) {
+                            state._currentAgentSpan.setError({
+                                message: 'Guardrail tripwire triggered',
+                                data: { guardrail: result.guardrail.name },
+                            });
+                        }
+                        throw new InputGuardrailTripwireTriggered(`Input guardrail triggered: ${JSON.stringify(result.output.outputInfo)}`, result, state);
+                    }
                 }
-                else {
-                    return this.#runIndividualNonStream(agent, input, options);
+            }
+            catch (e) {
+                if (e instanceof InputGuardrailTripwireTriggered) {
+                    throw e;
                 }
-            });
+                // roll back the current turn to enable reruns
+                state._currentTurn--;
+                throw new GuardrailExecutionError(`Input guardrail failed to complete: ${e}`, e, state);
+            }
         }
-        return getOrCreateTrace(async () => {
-            if (options?.stream) {
-                return this.#runIndividualStream(agent, input, options);
+    }
+    async #runOutputGuardrails(state, output) {
+        const guardrails = this.outputGuardrailDefs.concat(state._currentAgent.outputGuardrails.map(defineOutputGuardrail));
+        if (guardrails.length > 0) {
+            const agentOutput = state._currentAgent.processFinalOutput(output);
+            const guardrailArgs = {
+                agent: state._currentAgent,
+                agentOutput,
+                context: state._context,
+                details: { modelResponse: state._lastTurnResponse },
+            };
+            try {
+                const results = await Promise.all(guardrails.map(async (guardrail) => {
+                    return withGuardrailSpan(async (span) => {
+                        const result = await guardrail.run(guardrailArgs);
+                        span.spanData.triggered = result.output.tripwireTriggered;
+                        return result;
+                    }, { data: { name: guardrail.name } }, state._currentAgentSpan);
+                }));
+                for (const result of results) {
+                    if (result.output.tripwireTriggered) {
+                        if (state._currentAgentSpan) {
+                            state._currentAgentSpan.setError({
+                                message: 'Guardrail tripwire triggered',
+                                data: { guardrail: result.guardrail.name },
+                            });
+                        }
+                        throw new OutputGuardrailTripwireTriggered(`Output guardrail triggered: ${JSON.stringify(result.output.outputInfo)}`, result, state);
+                    }
+                }
             }
-            else {
-                return this.#runIndividualNonStream(agent, input, options);
+            catch (e) {
+                if (e instanceof OutputGuardrailTripwireTriggered) {
+                    throw e;
+                }
+                throw new GuardrailExecutionError(`Output guardrail failed to complete: ${e}`, e, state);
             }
-        }, {
-            traceId: this.config.traceId,
-            name: this.config.workflowName,
-            groupId: this.config.groupId,
-            metadata: this.config.traceMetadata,
-        });
+        }
+    }
+    /**
+     * @internal
+     * Applies call-level filters and merges session updates so the model request mirrors exactly
+     * what we persisted for history.
+     */
+    async #prepareModelCall(state, options, artifacts, turnInput, serverConversationTracker, sessionInputUpdate) {
+        const { model, explictlyModelSet } = await this.#resolveModelForAgent(state._currentAgent);
+        let modelSettings = {
+            ...this.config.modelSettings,
+            ...state._currentAgent.modelSettings,
+        };
+        modelSettings = adjustModelSettingsForNonGPT5RunnerModel(explictlyModelSet, state._currentAgent.modelSettings, model, modelSettings);
+        modelSettings = maybeResetToolChoice(state._currentAgent, state._toolUseTracker, modelSettings);
+        const systemInstructions = await state._currentAgent.getSystemPrompt(state._context);
+        const prompt = await state._currentAgent.getPrompt(state._context);
+        const { modelInput, sourceItems, persistedItems, filterApplied } = await applyCallModelInputFilter(state._currentAgent, options.callModelInputFilter, state._context, turnInput, systemInstructions);
+        // Inform the tracker which exact original objects made it to the provider so future turns
+        // only send the delta that has not yet been acknowledged by the server.
+        serverConversationTracker?.markInputAsSent(sourceItems);
+        // Provide filtered clones whenever filters run so session history mirrors the model payload.
+        // Returning an empty array is intentional: it tells the session layer to persist "nothing"
+        // instead of falling back to the unfiltered originals when the filter redacts everything.
+        sessionInputUpdate?.(sourceItems, filterApplied ? persistedItems : undefined);
+        const previousResponseId = serverConversationTracker?.previousResponseId ??
+            options.previousResponseId;
+        const conversationId = serverConversationTracker?.conversationId ?? options.conversationId;
+        return {
+            ...artifacts,
+            model,
+            explictlyModelSet,
+            modelSettings,
+            modelInput,
+            prompt,
+            previousResponseId,
+            conversationId,
+        };
     }
 }
+/**
+ * Constructs the model input array for the current turn by combining the original turn input with
+ * any new run items (excluding tool approval placeholders). This helps ensure that repeated calls
+ * to the Responses API only send newly generated content.
+ *
+ * See: https://platform.openai.com/docs/guides/conversation-state?api-mode=responses.
+ */
+export function getTurnInput(originalInput, generatedItems) {
+    const rawItems = generatedItems
+        .filter((item) => item.type !== 'tool_approval_item') // don't include approval items to avoid double function calls
+        .map((item) => item.rawItem);
+    return [...toAgentInputList(originalInput), ...rawItems];
+}
+// --------------------------------------------------------------
+//  Internal helpers
+// --------------------------------------------------------------
+const DEFAULT_MAX_TURNS = 10;
 let _defaultRunner = undefined;
 function getDefaultRunner() {
     if (_defaultRunner) {
@@ -695,9 +840,13 @@ function getDefaultRunner() {
     _defaultRunner = new Runner();
     return _defaultRunner;
 }
+/**
+ * Resolves the effective model for the next turn by giving precedence to the agent-specific
+ * configuration when present, otherwise falling back to the runner-level default.
+ */
 export function selectModel(agentModel, runConfigModel) {
     // When initializing an agent without model name, the model property is set to an empty string. So,
-    // * agentModel === '' & runConfigModel exists, runConfigModel will be used
+    // * agentModel === Agent.DEFAULT_MODEL_PLACEHOLDER & runConfigModel exists, runConfigModel will be used
     // * agentModel is set, the agentModel will be used over runConfigModel
     if ((typeof agentModel === 'string' &&
         agentModel !== Agent.DEFAULT_MODEL_PLACEHOLDER) ||
@@ -707,13 +856,259 @@ export function selectModel(agentModel, runConfigModel) {
     }
     return runConfigModel ?? agentModel ?? Agent.DEFAULT_MODEL_PLACEHOLDER;
 }
-export async function run(agent, input, options) {
-    const runner = getDefaultRunner();
-    if (options?.stream) {
-        return await runner.run(agent, input, options);
+/**
+ * Normalizes tracing configuration into the format expected by model providers.
+ * Returns `false` to disable tracing, `true` to include full payload data, or
+ * `'enabled_without_data'` to omit sensitive content while still emitting spans.
+ */
+export function getTracing(tracingDisabled, traceIncludeSensitiveData) {
+    if (tracingDisabled) {
+        return false;
     }
-    else {
-        return await runner.run(agent, input, options);
+    if (traceIncludeSensitiveData) {
+        return true;
+    }
+    return 'enabled_without_data';
+}
+/**
+ * @internal
+ */
+async function applyCallModelInputFilter(agent, callModelInputFilter, context, inputItems, systemInstructions) {
+    const cloneInputItems = (items, map) => items.map((item) => {
+        const cloned = structuredClone(item);
+        if (map && cloned && typeof cloned === 'object') {
+            map.set(cloned, item);
+        }
+        return cloned;
+    });
+    // Record the relationship between the cloned array passed to filters and the original inputs.
+    const cloneMap = new WeakMap();
+    const originalPool = buildAgentInputPool(inputItems);
+    const fallbackOriginals = [];
+    // Track any original object inputs so filtered replacements can still mark them as delivered.
+    for (const item of inputItems) {
+        if (item && typeof item === 'object') {
+            fallbackOriginals.push(item);
+        }
+    }
+    const removeFromFallback = (candidate) => {
+        if (!candidate || typeof candidate !== 'object') {
+            return;
+        }
+        const index = fallbackOriginals.findIndex((original) => original === candidate);
+        if (index !== -1) {
+            fallbackOriginals.splice(index, 1);
+        }
+    };
+    const takeFallbackOriginal = () => {
+        const next = fallbackOriginals.shift();
+        if (next) {
+            removeAgentInputFromPool(originalPool, next);
+        }
+        return next;
+    };
+    // Always create a deep copy so downstream mutations inside filters cannot affect
+    // the cached turn state.
+    const clonedBaseInput = cloneInputItems(inputItems, cloneMap);
+    const base = {
+        input: clonedBaseInput,
+        instructions: systemInstructions,
+    };
+    if (!callModelInputFilter) {
+        return {
+            modelInput: base,
+            sourceItems: [...inputItems],
+            persistedItems: [],
+            filterApplied: false,
+        };
+    }
+    try {
+        const result = await callModelInputFilter({
+            modelData: base,
+            agent,
+            context: context.context,
+        });
+        if (!result || !Array.isArray(result.input)) {
+            throw new UserError('callModelInputFilter must return a ModelInputData object with an input array.');
+        }
+        // Preserve a pointer to the original object backing each filtered clone so downstream
+        // trackers can keep their bookkeeping consistent even after redaction.
+        const sourceItems = result.input.map((item) => {
+            if (!item || typeof item !== 'object') {
+                return undefined;
+            }
+            const original = cloneMap.get(item);
+            if (original) {
+                removeFromFallback(original);
+                removeAgentInputFromPool(originalPool, original);
+                return original;
+            }
+            const key = getAgentInputItemKey(item);
+            const matchedByContent = takeAgentInputFromPool(originalPool, key);
+            if (matchedByContent) {
+                removeFromFallback(matchedByContent);
+                return matchedByContent;
+            }
+            const fallback = takeFallbackOriginal();
+            if (fallback) {
+                return fallback;
+            }
+            return undefined;
+        });
+        const clonedFilteredInput = cloneInputItems(result.input);
+        return {
+            modelInput: {
+                input: clonedFilteredInput,
+                instructions: typeof result.instructions === 'undefined'
+                    ? systemInstructions
+                    : result.instructions,
+            },
+            sourceItems,
+            persistedItems: clonedFilteredInput.map((item) => structuredClone(item)),
+            filterApplied: true,
+        };
+    }
+    catch (error) {
+        addErrorToCurrentSpan({
+            message: 'Error in callModelInputFilter',
+            data: { error: String(error) },
+        });
+        throw error;
+    }
+}
+// Tracks which items have already been sent to or received from the Responses API when the caller
+// supplies `conversationId`/`previousResponseId`. This ensures we only send the delta each turn.
+class ServerConversationTracker {
+    // Conversation ID:
+    // - https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#using-the-conversations-api
+    // - https://platform.openai.com/docs/api-reference/conversations/create
+    conversationId;
+    // Previous Response ID:
+    // https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#passing-context-from-the-previous-response
+    previousResponseId;
+    // Using this flag because WeakSet does not provide a way to check its size
+    sentInitialInput = false;
+    // The items already sent to the model; using WeakSet for memory efficiency
+    sentItems = new WeakSet();
+    // The items received from the server; using WeakSet for memory efficiency
+    serverItems = new WeakSet();
+    // Track initial input items that have not yet been sent so they can be retried on later turns.
+    remainingInitialInput = null;
+    constructor({ conversationId, previousResponseId, }) {
+        this.conversationId = conversationId ?? undefined;
+        this.previousResponseId = previousResponseId ?? undefined;
+    }
+    /**
+     * Pre-populates tracker caches from an existing RunState when resuming server-managed runs.
+     */
+    primeFromState({ originalInput, generatedItems, modelResponses, }) {
+        if (this.sentInitialInput) {
+            return;
+        }
+        for (const item of toAgentInputList(originalInput)) {
+            if (item && typeof item === 'object') {
+                this.sentItems.add(item);
+            }
+        }
+        this.sentInitialInput = true;
+        this.remainingInitialInput = null;
+        const latestResponse = modelResponses[modelResponses.length - 1];
+        for (const response of modelResponses) {
+            for (const item of response.output) {
+                if (item && typeof item === 'object') {
+                    this.serverItems.add(item);
+                }
+            }
+        }
+        if (!this.conversationId && latestResponse?.responseId) {
+            this.previousResponseId = latestResponse.responseId;
+        }
+        for (const item of generatedItems) {
+            const rawItem = item.rawItem;
+            if (!rawItem || typeof rawItem !== 'object') {
+                continue;
+            }
+            if (this.serverItems.has(rawItem)) {
+                this.sentItems.add(rawItem);
+            }
+        }
+    }
+    /**
+     * Records the raw items returned by the server so future delta calculations skip them.
+     * Also captures the latest response identifier to chain follow-up calls when possible.
+     */
+    trackServerItems(modelResponse) {
+        if (!modelResponse) {
+            return;
+        }
+        for (const item of modelResponse.output) {
+            if (item && typeof item === 'object') {
+                this.serverItems.add(item);
+            }
+        }
+        if (!this.conversationId && modelResponse.responseId) {
+            this.previousResponseId = modelResponse.responseId;
+        }
+    }
+    /**
+     * Returns the minimum set of items that still need to be delivered to the server for the
+     * current turn. This includes the original turn inputs (until acknowledged) plus any
+     * newly generated items that have not yet been echoed back by the API.
+     */
+    prepareInput(originalInput, generatedItems) {
+        const inputItems = [];
+        if (!this.sentInitialInput) {
+            const initialItems = toAgentInputList(originalInput);
+            // Preserve the full initial payload so a filter can drop items without losing their originals.
+            inputItems.push(...initialItems);
+            this.remainingInitialInput = initialItems.filter((item) => Boolean(item) && typeof item === 'object');
+            this.sentInitialInput = true;
+        }
+        else if (this.remainingInitialInput &&
+            this.remainingInitialInput.length > 0) {
+            // Re-queue prior initial items until the tracker confirms they were delivered to the API.
+            inputItems.push(...this.remainingInitialInput);
+        }
+        for (const item of generatedItems) {
+            if (item.type === 'tool_approval_item') {
+                continue;
+            }
+            const rawItem = item.rawItem;
+            if (!rawItem || typeof rawItem !== 'object') {
+                continue;
+            }
+            if (this.sentItems.has(rawItem) || this.serverItems.has(rawItem)) {
+                continue;
+            }
+            inputItems.push(rawItem);
+        }
+        return inputItems;
+    }
+    /**
+     * Marks the provided originals as delivered so future turns do not resend them and any
+     * pending initial inputs can be dropped once the server acknowledges receipt.
+     */
+    markInputAsSent(items) {
+        if (!items.length) {
+            return;
+        }
+        const delivered = new Set();
+        for (const item of items) {
+            if (!item || typeof item !== 'object' || delivered.has(item)) {
+                continue;
+            }
+            // Some inputs may be repeated in the filtered list; only mark unique originals once.
+            delivered.add(item);
+            this.sentItems.add(item);
+        }
+        if (!this.remainingInitialInput ||
+            this.remainingInitialInput.length === 0) {
+            return;
+        }
+        this.remainingInitialInput = this.remainingInitialInput.filter((item) => !delivered.has(item));
+        if (this.remainingInitialInput.length === 0) {
+            this.remainingInitialInput = null;
+        }
     }
 }
 /**
@@ -750,4 +1145,121 @@ function adjustModelSettingsForNonGPT5RunnerModel(explictlyModelSet, agentModelS
     }
     return modelSettings;
 }
+/**
+ * @internal
+ * Collects tools/handoffs early so we can annotate spans before model execution begins.
+ */
+async function prepareAgentArtifacts(state) {
+    const handoffs = await state._currentAgent.getEnabledHandoffs(state._context);
+    const tools = await state._currentAgent.getAllTools(state._context);
+    if (!state._currentAgentSpan) {
+        const handoffNames = handoffs.map((h) => h.agentName);
+        state._currentAgentSpan = createAgentSpan({
+            data: {
+                name: state._currentAgent.name,
+                handoffs: handoffNames,
+                tools: tools.map((t) => t.name),
+                output_type: state._currentAgent.outputSchemaName,
+            },
+        });
+        state._currentAgentSpan.start();
+        setCurrentSpan(state._currentAgentSpan);
+    }
+    else {
+        state._currentAgentSpan.spanData.tools = tools.map((t) => t.name);
+    }
+    return {
+        handoffs,
+        tools,
+        serializedHandoffs: handoffs.map((handoff) => serializeHandoff(handoff)),
+        serializedTools: tools.map((tool) => serializeTool(tool)),
+    };
+}
+function getAgentInputItemKey(item) {
+    // Deep serialization keeps binary inputs comparable after filters clone them.
+    return JSON.stringify(item, agentInputSerializationReplacer);
+}
+function buildAgentInputPool(items) {
+    // Track every original object so filters can safely return cloned copies.
+    const pool = new Map();
+    for (const item of items) {
+        const key = getAgentInputItemKey(item);
+        const existing = pool.get(key);
+        if (existing) {
+            existing.push(item);
+        }
+        else {
+            pool.set(key, [item]);
+        }
+    }
+    return pool;
+}
+function takeAgentInputFromPool(pool, key) {
+    // Prefer reusing the earliest untouched original to keep ordering stable.
+    const candidates = pool.get(key);
+    if (!candidates || candidates.length === 0) {
+        return undefined;
+    }
+    const [first] = candidates;
+    candidates.shift();
+    if (candidates.length === 0) {
+        pool.delete(key);
+    }
+    return first;
+}
+function removeAgentInputFromPool(pool, item) {
+    // Remove exactly the matched instance so duplicate payloads remain available.
+    const key = getAgentInputItemKey(item);
+    const candidates = pool.get(key);
+    if (!candidates || candidates.length === 0) {
+        return;
+    }
+    const index = candidates.findIndex((candidate) => candidate === item);
+    if (index === -1) {
+        return;
+    }
+    candidates.splice(index, 1);
+    if (candidates.length === 0) {
+        pool.delete(key);
+    }
+}
+function agentInputSerializationReplacer(_key, value) {
+    // Mirror runImplementation serialization so buffer snapshots round-trip.
+    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;
+}
+// Normalizes user-provided input into the structure the model expects. Strings become user messages,
+// arrays are kept as-is so downstream loops can treat both scenarios uniformly.
+function toAgentInputList(originalInput) {
+    // Allow callers to pass plain strings while preserving original item order.
+    if (typeof originalInput === 'string') {
+        return [{ type: 'message', role: 'user', content: originalInput }];
+    }
+    return [...originalInput];
+}
 //# sourceMappingURL=run.mjs.map