@openai/agents-core 0.8.5 → 0.9.1

package/dist/runState.js

@@ -37,7 +37,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RunState = exports.SerializedRunState = exports.CURRENT_SCHEMA_VERSION = void 0;
+exports.rehydrateProcessedResponseTools = rehydrateProcessedResponseTools;
 exports.buildAgentMap = buildAgentMap;
+exports.buildAgentIdentityMap = buildAgentIdentityMap;
 exports.deserializeSpan = deserializeSpan;
 exports.deserializeModelResponse = deserializeModelResponse;
 exports.deserializeItem = deserializeItem;
@@ -56,11 +58,13 @@ const tracing_1 = require("./tracing/index.js");
 const logger_1 = __importDefault(require("./logger.js"));
 const handoff_1 = require("./handoff.js");
 const protocol = __importStar(require("./types/protocol.js"));
+const session_1 = require("./sandbox/session.js");
 const safeExecute_1 = require("./utils/safeExecute.js");
 const tool_1 = require("./tool.js");
 const toolIdentity_1 = require("./toolIdentity.js");
 const toolSearch_1 = require("./utils/toolSearch.js");
 const toolSearch_2 = require("./runner/toolSearch.js");
+const toolRehydration_1 = require("./sandbox/runtime/toolRehydration.js");
 /**
  * The schema version of the serialized run state. This is used to ensure that the serialized
  * run state is compatible with the current version of the SDK.
@@ -79,8 +83,12 @@ const toolSearch_2 = require("./runner/toolSearch.js");
  * - 1.7: Adds optional approval rejection messages.
  * - 1.8: Adds tool search item variants, batched computer actions, and GA computer tool
  *   aliasing to serialized run state payloads.
+ * - 1.9: Adds optional sandbox session persistence with a versioned session-state
+ *   envelope for sandbox-agent resume.
+ * - 1.10: Adds optional stable agent identity keys so duplicate-name agent graphs can
+ *   serialize and resume without ambiguous name resolution.
  */
-exports.CURRENT_SCHEMA_VERSION = '1.8';
+exports.CURRENT_SCHEMA_VERSION = '1.10';
 const SUPPORTED_SCHEMA_VERSIONS = [
     '1.0',
     '1.1',
@@ -90,11 +98,14 @@ const SUPPORTED_SCHEMA_VERSIONS = [
     '1.5',
     '1.6',
     '1.7',
+    '1.8',
+    '1.9',
     exports.CURRENT_SCHEMA_VERSION,
 ];
 const $schemaVersion = zod_1.z.enum(SUPPORTED_SCHEMA_VERSIONS);
 const serializedAgentSchema = zod_1.z.object({
     name: zod_1.z.string(),
+    identity: zod_1.z.string().optional(),
 });
 const serializedSpanBase = zod_1.z.object({
     object: zod_1.z.literal('trace.span'),
@@ -203,6 +214,32 @@ const serializedTraceSchema = zod_1.z.object({
     // and serialization opts in to include it. By default this is omitted to avoid persisting secrets.
     tracing_api_key: zod_1.z.string().optional().nullable(),
 });
+const sandboxSessionStateEnvelopeSchema = zod_1.z.object({
+    version: zod_1.z.literal(session_1.SANDBOX_SESSION_STATE_VERSION),
+    backendId: zod_1.z.string(),
+    manifest: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
+    snapshot: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).nullable().optional(),
+    snapshotFingerprint: zod_1.z.string().nullable().optional(),
+    snapshotFingerprintVersion: zod_1.z.string().nullable().optional(),
+    workspaceReady: zod_1.z.boolean(),
+    exposedPorts: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+    providerState: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
+});
+const sandboxSessionEntrySchema = zod_1.z.object({
+    backendId: zod_1.z.string(),
+    currentAgentKey: zod_1.z.string(),
+    currentAgentName: zod_1.z.string(),
+    sessionState: sandboxSessionStateEnvelopeSchema,
+    preservedOwnedSession: zod_1.z.boolean().optional(),
+    reuseLiveSession: zod_1.z.boolean().optional(),
+});
+const sandboxStateSchema = zod_1.z.object({
+    backendId: zod_1.z.string(),
+    currentAgentKey: zod_1.z.string(),
+    currentAgentName: zod_1.z.string(),
+    sessionState: sandboxSessionStateEnvelopeSchema,
+    sessionsByAgent: zod_1.z.record(zod_1.z.string(), sandboxSessionEntrySchema),
+});
 const serializedProcessedResponseSchema = zod_1.z.object({
     newItems: zod_1.z.array(itemSchema),
     toolsUsed: zod_1.z.array(zod_1.z.string()),
@@ -343,6 +380,7 @@ exports.SerializedRunState = zod_1.z.object({
     previousResponseId: zod_1.z.string().optional(),
     reasoningItemIdPolicy: zod_1.z.enum(['preserve', 'omit']).optional(),
     trace: serializedTraceSchema.nullable(),
+    sandbox: sandboxStateSchema.optional(),
 });
 /**
  * Serializable snapshot of an agent's run, including context, usage and trace.
@@ -481,10 +519,14 @@ class RunState {
      */
     _trace = null;
     /**
-     * Runtime-only tool_search-loaded tools, scoped by agent name and preserved across turns for
+     * Runtime-only tool_search-loaded tools, scoped by agent object and preserved across turns for
      * the lifetime of this in-memory run.
      */
-    _toolSearchRuntimeToolsByAgentName = new Map();
+    _toolSearchRuntimeToolsByAgent = new Map();
+    /**
+     * Persisted sandbox session metadata for sandbox-agent resume.
+     */
+    _sandbox = undefined;
     constructor(context, originalInput, startingAgent, maxTurns) {
         this._context = context;
         this._agentToolInvocation = undefined;
@@ -524,20 +566,20 @@ class RunState {
     setCurrentAgentSpan(span) {
         this._currentAgentSpan = span;
     }
-    getOrCreateToolSearchRuntimeToolState(agentName) {
-        let state = this._toolSearchRuntimeToolsByAgentName.get(agentName);
+    getOrCreateToolSearchRuntimeToolState(agent) {
+        let state = this._toolSearchRuntimeToolsByAgent.get(agent);
         if (!state) {
             state = {
                 anonymousEntries: [],
                 keyedEntries: new Map(),
                 nextOrder: 0,
             };
-            this._toolSearchRuntimeToolsByAgentName.set(agentName, state);
+            this._toolSearchRuntimeToolsByAgent.set(agent, state);
         }
         return state;
     }
     recordToolSearchRuntimeTools(agent, toolSearchOutput, tools) {
-        const runtimeState = this.getOrCreateToolSearchRuntimeToolState(agent.name);
+        const runtimeState = this.getOrCreateToolSearchRuntimeToolState(agent);
         const entry = {
             order: runtimeState.nextOrder++,
             tools,
@@ -550,7 +592,7 @@ class RunState {
         runtimeState.anonymousEntries.push(entry);
     }
     getToolSearchRuntimeTools(agent) {
-        const runtimeState = this._toolSearchRuntimeToolsByAgentName.get(agent.name);
+        const runtimeState = this._toolSearchRuntimeToolsByAgent.get(agent);
         if (!runtimeState) {
             return [];
         }
@@ -687,15 +729,13 @@ class RunState {
      * rehydrate in a separate process that lacks the original environment variables).
      */
     toJSON(options = {}) {
-        buildAgentMap(this.#startingAgent);
+        const agentIdentity = buildAgentIdentityMap(this.#startingAgent);
         const includeTracingApiKey = options.includeTracingApiKey === true;
         const contextJson = this._context.toJSON();
         const output = {
             $schemaVersion: exports.CURRENT_SCHEMA_VERSION,
             currentTurn: this._currentTurn,
-            currentAgent: {
-                name: this._currentAgent.name,
-            },
+            currentAgent: serializeAgentReference(this._currentAgent, agentIdentity.byAgent),
             originalInput: this._originalInput,
             modelResponses: this._modelResponses.map((response) => {
                 return {
@@ -727,7 +767,9 @@ class RunState {
                 };
             }),
             context: contextJson,
-            toolUseTracker: this._toolUseTracker.toJSON(),
+            toolUseTracker: this._toolUseTracker.toJSON({
+                agentIdentityKeys: agentIdentity.byAgent,
+            }),
             maxTurns: this._maxTurns,
             currentAgentSpan: this._currentAgentSpan?.toJSON(),
             noActiveAgentRun: this._noActiveAgentRun,
@@ -735,22 +777,25 @@ class RunState {
             inputGuardrailResults: this._inputGuardrailResults,
             outputGuardrailResults: this._outputGuardrailResults.map((r) => ({
                 ...r,
-                agent: r.agent.toJSON(),
+                agent: serializeAgentReference(r.agent, agentIdentity.byAgent),
             })),
             toolInputGuardrailResults: this._toolInputGuardrailResults,
             toolOutputGuardrailResults: this._toolOutputGuardrailResults,
-            currentStep: this._currentStep,
+            currentStep: serializeCurrentStep(this._currentStep, agentIdentity.byAgent),
             lastModelResponse: this._lastTurnResponse,
-            generatedItems: this._generatedItems.map((item) => item.toJSON()),
+            generatedItems: this._generatedItems.map((item) => serializeRunItem(item, agentIdentity.byAgent)),
             pendingAgentToolRuns: Object.fromEntries(this._pendingAgentToolRuns.entries()),
             currentTurnPersistedItemCount: this._currentTurnPersistedItemCount,
-            lastProcessedResponse: this._lastProcessedResponse,
+            lastProcessedResponse: this._lastProcessedResponse
+                ? serializeProcessedResponse(this._lastProcessedResponse, agentIdentity.byAgent)
+                : undefined,
             conversationId: this._conversationId,
             previousResponseId: this._previousResponseId,
             reasoningItemIdPolicy: this._reasoningItemIdPolicy,
             trace: this._trace
                 ? this._trace.toJSON({ includeTracingApiKey })
                 : null,
+            sandbox: this._sandbox,
         };
         // parsing the schema to ensure the output is valid for reparsing
         const parsed = exports.SerializedRunState.safeParse(output);
@@ -804,7 +849,9 @@ async function buildRunStateFromString(initialAgent, str, options = {}) {
     return buildRunStateFromJson(initialAgent, stateJson, options);
 }
 function assertSchemaVersionSupportsToolSearch(schemaVersion, stateJson) {
-    if (schemaVersion === '1.8') {
+    if (schemaVersion === '1.8' ||
+        schemaVersion === '1.9' ||
+        schemaVersion === exports.CURRENT_SCHEMA_VERSION) {
         return;
     }
     if (!containsSerializedToolSearchState(stateJson)) {
@@ -812,6 +859,9 @@ function assertSchemaVersionSupportsToolSearch(schemaVersion, stateJson) {
     }
     throw new errors_1.UserError(`Run state schema version ${schemaVersion} does not support tool_search items. Please reserialize the run state with schema ${exports.CURRENT_SCHEMA_VERSION}.`);
 }
+function schemaVersionSupportsAgentIdentity(schemaVersion) {
+    return schemaVersion === exports.CURRENT_SCHEMA_VERSION;
+}
 function containsSerializedToolSearchState(stateJson) {
     return (containsToolSearchProtocolItems(stateJson.originalInput) ||
         containsToolSearchInModelResponses(stateJson.modelResponses) ||
@@ -915,17 +965,17 @@ function assertRuntimeToolKeysMatch(args) {
     throw new errors_1.UserError(`RunState cannot resume custom client tool_search call ${callId} for agent ${agent.name} because the registered execute callback returned runtime tools [${formatRuntimeToolKeys(actualRuntimeToolKeys)}] but the serialized state expects [${formatRuntimeToolKeys(expectedRuntimeToolKeys)}].`);
 }
 async function getConfiguredAgentTools(args) {
-    const { agent, context, configuredToolsByAgentName } = args;
-    const existing = configuredToolsByAgentName.get(agent.name);
+    const { agent, context, configuredToolsByAgent } = args;
+    const existing = configuredToolsByAgent.get(agent);
     if (existing) {
         return existing;
     }
     const configuredTools = (await agent.getAllTools(context));
-    configuredToolsByAgentName.set(agent.name, configuredTools);
+    configuredToolsByAgent.set(agent, configuredTools);
     return configuredTools;
 }
 async function rehydrateToolSearchRuntimeTools(state) {
-    const configuredToolsByAgentName = new Map();
+    const configuredToolsByAgent = new Map();
     const pendingToolSearchCalls = new Map();
     for (const item of state._generatedItems) {
         if (item instanceof items_1.RunToolSearchCallItem) {
@@ -933,10 +983,14 @@ async function rehydrateToolSearchRuntimeTools(state) {
                 continue;
             }
             const callId = (0, toolSearch_1.resolveToolSearchCallId)(item.rawItem);
-            pendingToolSearchCalls.set(`${item.agent.name}:${callId}`, {
+            const agent = item.agent;
+            const pendingCallsById = pendingToolSearchCalls.get(agent) ??
+                new Map();
+            pendingCallsById.set(callId, {
                 agent: item.agent,
                 toolSearchCall: item.rawItem,
             });
+            pendingToolSearchCalls.set(agent, pendingCallsById);
             continue;
         }
         if (!(item instanceof items_1.RunToolSearchOutputItem)) {
@@ -948,7 +1002,7 @@ async function rehydrateToolSearchRuntimeTools(state) {
         const configuredTools = await getConfiguredAgentTools({
             agent: item.agent,
             context: state._context,
-            configuredToolsByAgentName,
+            configuredToolsByAgent,
         });
         const configuredToolKeys = getRuntimeToolKeys(configuredTools, {
             allowUnsupported: true,
@@ -958,7 +1012,9 @@ async function rehydrateToolSearchRuntimeTools(state) {
             continue;
         }
         const callId = (0, toolSearch_1.resolveToolSearchCallId)(item.rawItem);
-        const pendingCall = pendingToolSearchCalls.get(`${item.agent.name}:${callId}`);
+        const pendingCall = pendingToolSearchCalls
+            .get(item.agent)
+            ?.get(callId);
         if (!pendingCall) {
             throw new errors_1.UserError(`RunState cannot resume custom client tool_search output ${callId} for agent ${item.agent.name} because the serialized state is missing the matching tool_search call item.`);
         }
@@ -1001,7 +1057,9 @@ async function rehydrateToolSearchRuntimeTools(state) {
     }
 }
 async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
-    const agentMap = buildAgentMap(initialAgent);
+    const agentMap = schemaVersionSupportsAgentIdentity(stateJson.$schemaVersion)
+        ? buildAgentIdentityMap(initialAgent).byIdentity
+        : buildAgentMap(initialAgent);
     const contextOverride = options.contextOverride;
     const contextStrategy = options.contextStrategy ?? 'merge';
     //
@@ -1026,10 +1084,7 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     //
     // Find the current agent from the initial agent
     //
-    const currentAgent = agentMap.get(stateJson.currentAgent.name);
-    if (!currentAgent) {
-        throw new errors_1.UserError(`Agent ${stateJson.currentAgent.name} not found`);
-    }
+    const currentAgent = resolveSerializedAgent(stateJson.currentAgent, agentMap);
     const state = new RunState(context, '', initialAgent, stateJson.maxTurns);
     state._currentAgent = currentAgent;
     state._currentTurn = stateJson.currentTurn;
@@ -1040,7 +1095,13 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     // rebuild tool use tracker
     state._toolUseTracker = new toolUseTracker_1.AgentToolUseTracker();
     for (const [agentName, toolNames] of Object.entries(stateJson.toolUseTracker)) {
-        state._toolUseTracker.addToolUse(agentMap.get(agentName), toolNames, { allowEmpty: true });
+        const agent = agentMap.get(agentName);
+        if (!agent) {
+            throw new errors_1.UserError(`Agent ${agentName} not found`);
+        }
+        state._toolUseTracker.addToolUse(agent, toolNames, {
+            allowEmpty: true,
+        });
     }
     state._pendingAgentToolRuns = new Map(Object.entries(stateJson.pendingAgentToolRuns ?? {}));
     // rebuild current agent span
@@ -1063,7 +1124,7 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
         stateJson.inputGuardrailResults;
     state._outputGuardrailResults = stateJson.outputGuardrailResults.map((r) => ({
         ...r,
-        agent: agentMap.get(r.agent.name),
+        agent: resolveSerializedAgent(r.agent, agentMap),
     }));
     state._toolInputGuardrailResults =
         stateJson.toolInputGuardrailResults;
@@ -1078,6 +1139,7 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     state._generatedItems = stateJson.generatedItems.map((item) => deserializeItem(item, agentMap));
     state._currentTurnPersistedItemCount =
         stateJson.currentTurnPersistedItemCount ?? 0;
+    state._sandbox = stateJson.sandbox ?? undefined;
     await rehydrateToolSearchRuntimeTools(state);
     state._lastProcessedResponse = stateJson.lastProcessedResponse
         ? await deserializeProcessedResponse(agentMap, state, stateJson.lastProcessedResponse)
@@ -1085,7 +1147,7 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     if (stateJson.currentStep?.type === 'next_step_handoff') {
         state._currentStep = {
             type: 'next_step_handoff',
-            newAgent: agentMap.get(stateJson.currentStep.newAgent.name),
+            newAgent: resolveSerializedAgent(stateJson.currentStep.newAgent, agentMap),
         };
     }
     else if (stateJson.currentStep?.type === 'next_step_interruption') {
@@ -1099,6 +1161,20 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     }
     return state;
 }
+/**
+ * @internal
+ */
+async function rehydrateProcessedResponseTools(initialAgent, state, executionTools) {
+    if (!state._lastProcessedResponse) {
+        return;
+    }
+    const agentIdentity = buildAgentIdentityMap(initialAgent);
+    const serializedProcessedResponse = serializeProcessedResponse(state._lastProcessedResponse, agentIdentity.byAgent);
+    state._lastProcessedResponse = await deserializeProcessedResponse(agentIdentity.byIdentity, state, serializedProcessedResponse, {
+        executionTools,
+        allowSerializedExecutionToolPlaceholder: false,
+    });
+}
 /**
  * @internal
  */
@@ -1134,6 +1210,249 @@ function buildAgentMap(initialAgent) {
     }
     return map;
 }
+/**
+ * @internal
+ */
+function buildAgentIdentityMap(initialAgent) {
+    const agents = collectAgentGraph(initialAgent);
+    const groups = new Map();
+    const literalNames = new Set();
+    for (const entry of agents) {
+        literalNames.add(entry.agent.name);
+        const group = groups.get(entry.agent.name) ?? [];
+        group.push(entry);
+        groups.set(entry.agent.name, group);
+    }
+    const byIdentity = new Map();
+    const byAgent = new Map();
+    const usedIdentities = new Set();
+    for (const [agentName, group] of groups) {
+        const sortedGroup = group.length === 1
+            ? group
+            : [...group].sort((left, right) => {
+                if (left.agent === initialAgent) {
+                    return -1;
+                }
+                if (right.agent === initialAgent) {
+                    return 1;
+                }
+                const leftSignature = getAgentIdentitySignature(left.agent);
+                const rightSignature = getAgentIdentitySignature(right.agent);
+                if (leftSignature !== rightSignature) {
+                    return leftSignature < rightSignature ? -1 : 1;
+                }
+                return left.index - right.index;
+            });
+        let nextSuffix = 0;
+        for (const { agent } of sortedGroup) {
+            let identity;
+            do {
+                identity =
+                    nextSuffix === 0 ? agentName : `${agentName}#${nextSuffix + 1}`;
+                nextSuffix += 1;
+            } while (usedIdentities.has(identity) ||
+                (identity !== agent.name && literalNames.has(identity)));
+            usedIdentities.add(identity);
+            byIdentity.set(identity, agent);
+            byAgent.set(agent, identity);
+        }
+    }
+    return { byIdentity, byAgent };
+}
+function collectAgentGraph(initialAgent) {
+    const agents = [];
+    const visitedAgents = new Set();
+    const queue = [initialAgent];
+    while (queue.length > 0) {
+        const currentAgent = queue.shift();
+        if (visitedAgents.has(currentAgent)) {
+            continue;
+        }
+        visitedAgents.add(currentAgent);
+        agents.push({ agent: currentAgent, index: agents.length });
+        for (const handoff of currentAgent.handoffs) {
+            if (handoff instanceof agent_1.Agent) {
+                queue.push(handoff);
+            }
+            else if (handoff.agent) {
+                queue.push(handoff.agent);
+            }
+        }
+        for (const tool of currentAgent.tools) {
+            const sourceAgent = (0, agentToolSourceRegistry_1.getAgentToolSourceAgent)(tool);
+            if (sourceAgent) {
+                queue.push(sourceAgent);
+            }
+        }
+    }
+    return agents;
+}
+function getAgentIdentitySignature(agent) {
+    const sandboxAgent = agent;
+    const signature = {
+        type: agent.constructor?.name,
+        name: agent.name,
+        handoffDescription: agent.handoffDescription,
+        instructions: summarizeIdentityValue(agent.instructions),
+        prompt: summarizeIdentityValue(agent.prompt),
+        model: summarizeIdentityValue(agent.model),
+        modelSettings: summarizeIdentityValue(agent.modelSettings),
+        tools: agent.tools.map(summarizeToolIdentity),
+        handoffs: agent.handoffs.map((entry) => entry instanceof agent_1.Agent
+            ? { type: 'agent', name: entry.name }
+            : {
+                type: 'handoff',
+                toolName: entry.toolName,
+                agentName: entry.agentName,
+                targetName: entry.agent?.name,
+            }),
+        mcpServers: agent.mcpServers.map(summarizeIdentityValue),
+        inputGuardrails: agent.inputGuardrails.map(summarizeIdentityValue),
+        outputGuardrails: agent.outputGuardrails.map(summarizeIdentityValue),
+        outputType: summarizeIdentityValue(agent.outputType),
+        toolUseBehavior: summarizeIdentityValue(agent.toolUseBehavior),
+        resetToolChoice: agent.resetToolChoice,
+        defaultManifest: summarizeIdentityValue(sandboxAgent.defaultManifest),
+        baseInstructions: summarizeIdentityValue(sandboxAgent.baseInstructions),
+        capabilities: sandboxAgent.capabilities?.map(summarizeIdentityValue),
+        runAs: summarizeIdentityValue(sandboxAgent.runAs),
+    };
+    return stableStringify(signature);
+}
+function summarizeToolIdentity(tool) {
+    return {
+        type: tool.type,
+        name: tool.name,
+        namespace: tool.namespace,
+        strict: tool.strict,
+        parameters: summarizeIdentityValue(tool.parameters),
+    };
+}
+function summarizeIdentityValue(value) {
+    return normalizeForIdentity(value, new WeakSet(), 0);
+}
+function normalizeForIdentity(value, seen, depth) {
+    if (value === null || typeof value === 'undefined') {
+        return value;
+    }
+    if (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'function') {
+        return `[function:${value.name || 'anonymous'}]`;
+    }
+    if (typeof value !== 'object') {
+        return String(value);
+    }
+    if (seen.has(value)) {
+        return '[circular]';
+    }
+    if (depth >= 4) {
+        return `[${value.constructor?.name ?? 'Object'}]`;
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeForIdentity(item, seen, depth + 1));
+    }
+    if (value instanceof Map) {
+        return [...value.entries()]
+            .map(([key, entryValue]) => [
+            normalizeForIdentity(key, seen, depth + 1),
+            normalizeForIdentity(entryValue, seen, depth + 1),
+        ])
+            .sort((left, right) => stableStringify(left).localeCompare(stableStringify(right)));
+    }
+    if (value instanceof Set) {
+        return [...value.values()]
+            .map((entry) => normalizeForIdentity(entry, seen, depth + 1))
+            .sort((left, right) => stableStringify(left).localeCompare(stableStringify(right)));
+    }
+    const record = value;
+    const normalized = {
+        constructor: value.constructor?.name,
+    };
+    for (const key of Object.keys(record).sort()) {
+        normalized[key] = normalizeForIdentity(record[key], seen, depth + 1);
+    }
+    return normalized;
+}
+function stableStringify(value) {
+    return JSON.stringify(value, (_key, currentValue) => {
+        if (!currentValue ||
+            typeof currentValue !== 'object' ||
+            Array.isArray(currentValue)) {
+            return currentValue;
+        }
+        return Object.fromEntries(Object.entries(currentValue).sort(([left], [right]) => left.localeCompare(right)));
+    });
+}
+function serializeAgentReference(agent, agentIdentityKeys) {
+    const identity = agentIdentityKeys.get(agent);
+    if (!identity || identity === agent.name) {
+        return { name: agent.name };
+    }
+    return { name: agent.name, identity };
+}
+function resolveSerializedAgent(serializedAgent, agentMap, fallbackAgent) {
+    const identity = serializedAgent.identity ?? serializedAgent.name;
+    const agent = agentMap.get(identity);
+    if (agent) {
+        return agent;
+    }
+    if (!serializedAgent.identity && fallbackAgent) {
+        return fallbackAgent;
+    }
+    if (serializedAgent.identity) {
+        throw new errors_1.UserError(`Agent identity ${serializedAgent.identity} not found`);
+    }
+    throw new errors_1.UserError(`Agent ${serializedAgent.name} not found`);
+}
+function serializeRunItem(item, agentIdentityKeys) {
+    const serialized = item.toJSON();
+    switch (item.type) {
+        case 'handoff_output_item':
+            serialized.sourceAgent = serializeAgentReference(item.sourceAgent, agentIdentityKeys);
+            serialized.targetAgent = serializeAgentReference(item.targetAgent, agentIdentityKeys);
+            return serialized;
+        default:
+            serialized.agent = serializeAgentReference(item.agent, agentIdentityKeys);
+            return serialized;
+    }
+}
+function serializeCurrentStep(currentStep, agentIdentityKeys) {
+    if (!currentStep) {
+        return undefined;
+    }
+    if (currentStep.type === 'next_step_handoff') {
+        return {
+            ...currentStep,
+            newAgent: serializeAgentReference(currentStep.newAgent, agentIdentityKeys),
+        };
+    }
+    if (currentStep.type === 'next_step_interruption') {
+        const interruptions = Array.isArray(currentStep.data?.interruptions)
+            ? currentStep.data.interruptions.map((item) => item instanceof items_1.RunToolApprovalItem
+                ? serializeRunItem(item, agentIdentityKeys)
+                : item)
+            : currentStep.data?.interruptions;
+        return {
+            ...currentStep,
+            data: {
+                ...currentStep.data,
+                interruptions,
+            },
+        };
+    }
+    return currentStep;
+}
+function serializeProcessedResponse(processedResponse, agentIdentityKeys) {
+    return {
+        ...processedResponse,
+        newItems: processedResponse.newItems.map((item) => serializeRunItem(item, agentIdentityKeys)),
+    };
+}
 /**
  * @internal
  */
@@ -1172,23 +1491,23 @@ function deserializeModelResponse(serializedModelResponse) {
 function deserializeItem(serializedItem, agentMap) {
     switch (serializedItem.type) {
         case 'message_output_item':
-            return new items_1.RunMessageOutputItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new items_1.RunMessageOutputItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'tool_search_call_item':
-            return new items_1.RunToolSearchCallItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new items_1.RunToolSearchCallItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'tool_search_output_item':
-            return new items_1.RunToolSearchOutputItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new items_1.RunToolSearchOutputItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'tool_call_item':
-            return new items_1.RunToolCallItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new items_1.RunToolCallItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'tool_call_output_item':
-            return new items_1.RunToolCallOutputItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name), serializedItem.output);
+            return new items_1.RunToolCallOutputItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap), serializedItem.output);
         case 'reasoning_item':
-            return new items_1.RunReasoningItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new items_1.RunReasoningItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'handoff_call_item':
-            return new items_1.RunHandoffCallItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new items_1.RunHandoffCallItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'handoff_output_item':
-            return new items_1.RunHandoffOutputItem(serializedItem.rawItem, agentMap.get(serializedItem.sourceAgent.name), agentMap.get(serializedItem.targetAgent.name));
+            return new items_1.RunHandoffOutputItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.sourceAgent, agentMap), resolveSerializedAgent(serializedItem.targetAgent, agentMap));
         case 'tool_approval_item':
-            return new items_1.RunToolApprovalItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name), serializedItem.toolName);
+            return new items_1.RunToolApprovalItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap), serializedItem.toolName);
     }
 }
 function deserializeInterruptionItem(serializedItem, agentMap, currentAgent) {
@@ -1198,7 +1517,7 @@ function deserializeInterruptionItem(serializedItem, agentMap, currentAgent) {
     const parsed = itemSchema.safeParse(serializedItem);
     if (parsed.success) {
         if (parsed.data.type === 'tool_approval_item') {
-            const mappedAgent = agentMap.get(parsed.data.agent.name) ?? currentAgent;
+            const mappedAgent = resolveSerializedAgent(parsed.data.agent, agentMap, currentAgent);
             return new items_1.RunToolApprovalItem(parsed.data.rawItem, mappedAgent, parsed.data.toolName);
         }
         const item = deserializeItem(parsed.data, agentMap);
@@ -1222,7 +1541,15 @@ function deserializeInterruptionItem(serializedItem, agentMap, currentAgent) {
     const agentName = value.agent && typeof value.agent.name === 'string'
         ? value.agent.name
         : undefined;
-    const mappedAgent = (agentName ? agentMap.get(agentName) : undefined) ?? currentAgent;
+    const agentIdentity = value.agent && typeof value.agent.identity === 'string'
+        ? value.agent.identity
+        : undefined;
+    const mappedAgent = agentName || agentIdentity
+        ? resolveSerializedAgent({
+            name: agentName ?? currentAgent.name,
+            identity: agentIdentity,
+        }, agentMap, currentAgent)
+        : currentAgent;
     const toolName = typeof value.toolName === 'string'
         ? value.toolName
         : typeof rawItem.name === 'string'
@@ -1241,13 +1568,15 @@ function deserializeInterruptions(serializedInterruptions, agentMap, currentAgen
 /**
  * @internal
  */
-async function deserializeProcessedResponse(agentMap, state, serializedProcessedResponse) {
+async function deserializeProcessedResponse(agentMap, state, serializedProcessedResponse, options = {}) {
     const currentAgent = state._currentAgent;
-    const configuredTools = await currentAgent.getAllTools(state._context);
+    const configuredTools = options.executionTools ?? (await currentAgent.getAllTools(state._context));
     const allTools = [
         ...configuredTools,
         ...state.getToolSearchRuntimeTools(currentAgent),
     ];
+    const baseAgentTools = currentAgent.tools;
+    const allowSerializedExecutionToolPlaceholder = options.allowSerializedExecutionToolPlaceholder ?? true;
     const tools = new Map(allTools
         .filter((tool) => tool.type === 'function')
         .map((tool) => [(0, toolIdentity_1.getFunctionToolQualifiedName)(tool) ?? tool.name, tool]));
@@ -1294,17 +1623,33 @@ async function deserializeProcessedResponse(agentMap, state, serializedProcessed
         functions: await Promise.all(serializedProcessedResponse.functions.map(async (functionCall) => {
             const toolIdentity = (0, toolIdentity_1.resolveFunctionToolCallName)(functionCall.toolCall, tools) ??
                 functionCall.tool.name;
-            if (!tools.has(toolIdentity)) {
+            const resolvedTool = tools.get(toolIdentity) ??
+                (0, toolRehydration_1.getSerializedFunctionToolPlaceholder)({
+                    agent: currentAgent,
+                    baseAgentTools,
+                    serializedTool: functionCall.tool,
+                    toolCall: functionCall.toolCall,
+                    toolIdentity,
+                    allowSerializedExecutionToolPlaceholder,
+                });
+            if (!resolvedTool) {
                 throw new errors_1.UserError(`Tool ${toolIdentity} not found`);
             }
             return {
                 toolCall: functionCall.toolCall,
-                tool: tools.get(toolIdentity),
+                tool: resolvedTool,
             };
         })),
         computerActions: serializedProcessedResponse.computerActions.map((computerAction) => {
             const toolName = computerAction.computer.name;
-            const computerTool = resolveComputerTool(toolName);
+            const computerTool = resolveComputerTool(toolName) ??
+                (0, toolRehydration_1.getSerializedComputerToolPlaceholder)({
+                    agent: currentAgent,
+                    baseAgentTools,
+                    serializedTool: computerAction.computer,
+                    toolName,
+                    allowSerializedExecutionToolPlaceholder,
+                });
             if (!computerTool) {
                 throw new errors_1.UserError(`Computer tool ${toolName} not found`);
             }
@@ -1315,22 +1660,38 @@ async function deserializeProcessedResponse(agentMap, state, serializedProcessed
         }),
         shellActions: (serializedProcessedResponse.shellActions ?? []).map((shellAction) => {
             const toolName = shellAction.shell.name;
-            if (!shellTools.has(toolName)) {
+            const shellTool = shellTools.get(toolName) ??
+                (0, toolRehydration_1.getSerializedShellToolPlaceholder)({
+                    agent: currentAgent,
+                    baseAgentTools,
+                    serializedTool: shellAction.shell,
+                    toolName,
+                    allowSerializedExecutionToolPlaceholder,
+                });
+            if (!shellTool) {
                 throw new errors_1.UserError(`Shell tool ${toolName} not found`);
             }
             return {
                 toolCall: shellAction.toolCall,
-                shell: shellTools.get(toolName),
+                shell: shellTool,
             };
         }),
         applyPatchActions: (serializedProcessedResponse.applyPatchActions ?? []).map((applyPatchAction) => {
             const toolName = applyPatchAction.applyPatch.name;
-            if (!applyPatchTools.has(toolName)) {
+            const applyPatchTool = applyPatchTools.get(toolName) ??
+                (0, toolRehydration_1.getSerializedApplyPatchToolPlaceholder)({
+                    agent: currentAgent,
+                    baseAgentTools,
+                    serializedTool: applyPatchAction.applyPatch,
+                    toolName,
+                    allowSerializedExecutionToolPlaceholder,
+                });
+            if (!applyPatchTool) {
                 throw new errors_1.UserError(`Apply patch tool ${toolName} not found`);
             }
             return {
                 toolCall: applyPatchAction.toolCall,
-                applyPatch: applyPatchTools.get(toolName),
+                applyPatch: applyPatchTool,
             };
         }),
         mcpApprovalRequests: (serializedProcessedResponse.mcpApprovalRequests ?? []).map((approvalRequest) => ({