@openai/agents-core 0.13.1 → 0.13.3

package/dist/mcpShared.mjs

@@ -0,0 +1,127 @@
+import debug from 'debug';
+import { z } from 'zod';
+import { getLogger } from "./logger.mjs";
+export const DEFAULT_STDIO_MCP_CLIENT_LOGGER_NAME = 'openai-agents:stdio-mcp-client';
+export const DEFAULT_STREAMABLE_HTTP_MCP_CLIENT_LOGGER_NAME = 'openai-agents:streamable-http-mcp-client';
+export const DEFAULT_SSE_MCP_CLIENT_LOGGER_NAME = 'openai-agents:sse-mcp-client';
+export class BaseMCPServerStdio {
+    cacheToolsList;
+    _cachedTools = undefined;
+    toolFilter;
+    toolMetaResolver;
+    customDataExtractor;
+    useStructuredContent;
+    errorFunction;
+    logger;
+    constructor(options) {
+        this.logger =
+            options.logger ?? getLogger(DEFAULT_STDIO_MCP_CLIENT_LOGGER_NAME);
+        this.cacheToolsList = options.cacheToolsList ?? false;
+        this.toolFilter = options.toolFilter;
+        this.toolMetaResolver = options.toolMetaResolver;
+        this.customDataExtractor = options.customDataExtractor;
+        this.useStructuredContent = options.useStructuredContent;
+        this.errorFunction = options.errorFunction;
+    }
+    /**
+     * Logs a debug message when debug logging is enabled.
+     * @param buildMessage A function that returns the message to log.
+     */
+    debugLog(buildMessage) {
+        if (debug.enabled(this.logger.namespace)) {
+            // Only build the message when debug logging is enabled.
+            this.logger.debug(buildMessage());
+        }
+    }
+}
+export class BaseMCPServerStreamableHttp {
+    cacheToolsList;
+    _cachedTools = undefined;
+    toolFilter;
+    toolMetaResolver;
+    customDataExtractor;
+    useStructuredContent;
+    errorFunction;
+    logger;
+    constructor(options) {
+        this.logger =
+            options.logger ??
+                getLogger(DEFAULT_STREAMABLE_HTTP_MCP_CLIENT_LOGGER_NAME);
+        this.cacheToolsList = options.cacheToolsList ?? false;
+        this.toolFilter = options.toolFilter;
+        this.toolMetaResolver = options.toolMetaResolver;
+        this.customDataExtractor = options.customDataExtractor;
+        this.useStructuredContent = options.useStructuredContent;
+        this.errorFunction = options.errorFunction;
+    }
+    /**
+     * Logs a debug message when debug logging is enabled.
+     * @param buildMessage A function that returns the message to log.
+     */
+    debugLog(buildMessage) {
+        if (debug.enabled(this.logger.namespace)) {
+            // Only build the message when debug logging is enabled.
+            this.logger.debug(buildMessage());
+        }
+    }
+}
+export class BaseMCPServerSSE {
+    cacheToolsList;
+    _cachedTools = undefined;
+    toolFilter;
+    toolMetaResolver;
+    customDataExtractor;
+    useStructuredContent;
+    errorFunction;
+    logger;
+    constructor(options) {
+        this.logger =
+            options.logger ?? getLogger(DEFAULT_SSE_MCP_CLIENT_LOGGER_NAME);
+        this.cacheToolsList = options.cacheToolsList ?? false;
+        this.toolFilter = options.toolFilter;
+        this.toolMetaResolver = options.toolMetaResolver;
+        this.customDataExtractor = options.customDataExtractor;
+        this.useStructuredContent = options.useStructuredContent;
+        this.errorFunction = options.errorFunction;
+    }
+    /**
+     * Logs a debug message when debug logging is enabled.
+     * @param buildMessage A function that returns the message to log.
+     */
+    debugLog(buildMessage) {
+        if (debug.enabled(this.logger.namespace)) {
+            // Only build the message when debug logging is enabled.
+            this.logger.debug(buildMessage());
+        }
+    }
+}
+/**
+ * Minimum MCP tool data definition.
+ * This type definition does not intend to cover all possible properties.
+ * It supports the properties that are used in this SDK.
+ */
+export const MCPTool = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    inputSchema: z.object({
+        type: z.literal('object'),
+        properties: z.record(z.string(), z.any()),
+        required: z.array(z.string()),
+        additionalProperties: z.boolean(),
+    }),
+});
+export function attachCallToolResultMetadata(content, metadata) {
+    const result = content;
+    for (const [key, value] of Object.entries(metadata)) {
+        if (typeof value === 'undefined') {
+            continue;
+        }
+        Object.defineProperty(result, key, {
+            value,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=mcpShared.mjs.map

package/dist/mcpShared.mjs.map

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

package/dist/mcpToolCache.d.ts

@@ -0,0 +1,9 @@
+import type { MCPTool } from './mcpShared';
+export declare const cachedMcpTools: Record<string, MCPTool[]>;
+export declare const cachedMcpToolKeysByServer: Record<string, Set<string>>;
+/**
+ * Remove cached tools for the given server so the next lookup fetches fresh data.
+ *
+ * @param serverName - Name of the MCP server whose cache should be cleared.
+ */
+export declare function invalidateServerToolsCache(serverName: string): Promise<void>;

package/dist/mcpToolCache.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cachedMcpToolKeysByServer = exports.cachedMcpTools = void 0;
+exports.invalidateServerToolsCache = invalidateServerToolsCache;
+exports.cachedMcpTools = {};
+exports.cachedMcpToolKeysByServer = {};
+/**
+ * Remove cached tools for the given server so the next lookup fetches fresh data.
+ *
+ * @param serverName - Name of the MCP server whose cache should be cleared.
+ */
+async function invalidateServerToolsCache(serverName) {
+    const cachedKeys = exports.cachedMcpToolKeysByServer[serverName];
+    if (cachedKeys) {
+        for (const cacheKey of cachedKeys) {
+            delete exports.cachedMcpTools[cacheKey];
+        }
+        delete exports.cachedMcpToolKeysByServer[serverName];
+        return;
+    }
+    delete exports.cachedMcpTools[serverName];
+    for (const cacheKey of Object.keys(exports.cachedMcpTools)) {
+        if (cacheKey.startsWith(`${serverName}:`)) {
+            delete exports.cachedMcpTools[cacheKey];
+        }
+    }
+}
+//# sourceMappingURL=mcpToolCache.js.map

package/dist/mcpToolCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpToolCache.js","sourceRoot":"","sources":["../src/mcpToolCache.ts"],"names":[],"mappings":";;;AAUA,gEAgBC;AAxBY,QAAA,cAAc,GAA8B,EAAE,CAAC;AAC/C,QAAA,yBAAyB,GAAgC,EAAE,CAAC;AAEzE;;;;GAIG;AACI,KAAK,UAAU,0BAA0B,CAAC,UAAkB;IACjE,MAAM,UAAU,GAAG,iCAAyB,CAAC,UAAU,CAAC,CAAC;IACzD,IAAI,UAAU,EAAE,CAAC;QACf,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,OAAO,sBAAc,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,iCAAyB,CAAC,UAAU,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IAED,OAAO,sBAAc,CAAC,UAAU,CAAC,CAAC;IAClC,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,sBAAc,CAAC,EAAE,CAAC;QACnD,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,GAAG,CAAC,EAAE,CAAC;YAC1C,OAAO,sBAAc,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/mcpToolCache.mjs

@@ -0,0 +1,24 @@
+export const cachedMcpTools = {};
+export const cachedMcpToolKeysByServer = {};
+/**
+ * Remove cached tools for the given server so the next lookup fetches fresh data.
+ *
+ * @param serverName - Name of the MCP server whose cache should be cleared.
+ */
+export async function invalidateServerToolsCache(serverName) {
+    const cachedKeys = cachedMcpToolKeysByServer[serverName];
+    if (cachedKeys) {
+        for (const cacheKey of cachedKeys) {
+            delete cachedMcpTools[cacheKey];
+        }
+        delete cachedMcpToolKeysByServer[serverName];
+        return;
+    }
+    delete cachedMcpTools[serverName];
+    for (const cacheKey of Object.keys(cachedMcpTools)) {
+        if (cacheKey.startsWith(`${serverName}:`)) {
+            delete cachedMcpTools[cacheKey];
+        }
+    }
+}
+//# sourceMappingURL=mcpToolCache.mjs.map

package/dist/mcpToolCache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpToolCache.mjs","sourceRoot":"","sources":["../src/mcpToolCache.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAA8B,EAAE,CAAC;AAC5D,MAAM,CAAC,MAAM,yBAAyB,GAAgC,EAAE,CAAC;AAEzE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,UAAkB;IACjE,MAAM,UAAU,GAAG,yBAAyB,CAAC,UAAU,CAAC,CAAC;IACzD,IAAI,UAAU,EAAE,CAAC;QACf,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,yBAAyB,CAAC,UAAU,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IAED,OAAO,cAAc,CAAC,UAAU,CAAC,CAAC;IAClC,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;QACnD,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,GAAG,CAAC,EAAE,CAAC;YAC1C,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/metadata.js

@@ -4,9 +4,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.METADATA = void 0;
 exports.METADATA = {
     "name": "@openai/agents-core",
-    "version": "0.13.1",
+    "version": "0.13.3",
     "versions": {
-        "@openai/agents-core": "0.13.1",
+        "@openai/agents-core": "0.13.3",
         "openai": "^6.46.0"
     }
 };

package/dist/metadata.mjs

@@ -1,9 +1,9 @@
 // This file is automatically generated
 export const METADATA = {
     "name": "@openai/agents-core",
-    "version": "0.13.1",
+    "version": "0.13.3",
     "versions": {
-        "@openai/agents-core": "0.13.1",
+        "@openai/agents-core": "0.13.3",
         "openai": "^6.46.0"
     }
 };

package/dist/model.d.ts

@@ -15,12 +15,20 @@ export type ModelSettingsReasoningEffort = 'none' | 'minimal' | 'low' | 'medium'
  * Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
  */
 export type ModelSettingsReasoning = {
+    /**
+     * Controls which reasoning items are rendered back to the model on later turns.
+     */
+    context?: 'auto' | 'current_turn' | 'all_turns' | null;
     /**
      * Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
      * Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
      * Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
      */
     effort?: ModelSettingsReasoningEffort | null;
+    /**
+     * Controls the reasoning execution mode for the request.
+     */
+    mode?: 'standard' | 'pro' | (string & {});
     /**
      * A summary of the reasoning performed by the model.
      * This can be useful for debugging and understanding the model's reasoning process.
@@ -28,6 +36,19 @@ export type ModelSettingsReasoning = {
      */
     summary?: 'auto' | 'concise' | 'detailed' | null;
 };
+/**
+ * Prompt-cache configuration for supported model providers.
+ */
+export type ModelSettingsPromptCacheOptions = {
+    /**
+     * Controls whether the provider creates an implicit cache breakpoint.
+     */
+    mode?: 'implicit' | 'explicit';
+    /**
+     * The minimum lifetime applied to cache breakpoints written by the request.
+     */
+    ttl?: '30m';
+};
 export interface ModelSettingsText {
     /**
      * Constrains the verbosity of the model's response.
@@ -224,6 +245,10 @@ export type ModelSettings = {
      * See https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention for the available options.
      */
     promptCacheRetention?: 'in-memory' | '24h' | null;
+    /**
+     * Controls implicit and explicit prompt caching for supported model providers.
+     */
+    promptCacheOptions?: ModelSettingsPromptCacheOptions;
     /**
      * Context-management strategies to apply when calling the model.
      * This setting is available on OpenAI Responses requests, including server-side compaction.

package/dist/runState.d.ts

@@ -126,6 +126,9 @@ export declare const SerializedRunState: z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             type: z.ZodLiteral<"input_text">;
             text: z.ZodString;
+            promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodLiteral<"explicit">;
+            }, z.core.$strip>>;
         }, z.core.$strip>, z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             type: z.ZodLiteral<"input_image">;
@@ -133,6 +136,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 id: z.ZodString;
             }, z.core.$strip>]>>;
             detail: z.ZodOptional<z.ZodString>;
+            promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodLiteral<"explicit">;
+            }, z.core.$strip>>;
         }, z.core.$strip>, z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             type: z.ZodLiteral<"input_file">;
@@ -142,6 +148,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 url: z.ZodString;
             }, z.core.$strip>]>>;
             filename: z.ZodOptional<z.ZodString>;
+            promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodLiteral<"explicit">;
+            }, z.core.$strip>>;
         }, z.core.$strip>, z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             type: z.ZodLiteral<"audio">;
@@ -150,6 +159,9 @@ export declare const SerializedRunState: z.ZodObject<{
             }, z.core.$strip>]>;
             format: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             transcript: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodLiteral<"explicit">;
+            }, z.core.$strip>>;
         }, z.core.$strip>], "type">>, z.ZodString]>;
     }, z.core.$strip>, z.ZodObject<{
         providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -177,6 +189,9 @@ export declare const SerializedRunState: z.ZodObject<{
             }, z.core.$strip>]>;
             format: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             transcript: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodLiteral<"explicit">;
+            }, z.core.$strip>>;
         }, z.core.$strip>, z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             type: z.ZodLiteral<"image">;
@@ -410,6 +425,9 @@ export declare const SerializedRunState: z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             type: z.ZodLiteral<"input_text">;
             text: z.ZodString;
+            promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodLiteral<"explicit">;
+            }, z.core.$strip>>;
         }, z.core.$strip>, z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             type: z.ZodLiteral<"input_image">;
@@ -417,6 +435,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 id: z.ZodString;
             }, z.core.$strip>]>>;
             detail: z.ZodOptional<z.ZodString>;
+            promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodLiteral<"explicit">;
+            }, z.core.$strip>>;
         }, z.core.$strip>, z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             type: z.ZodLiteral<"input_file">;
@@ -426,6 +447,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 url: z.ZodString;
             }, z.core.$strip>]>>;
             filename: z.ZodOptional<z.ZodString>;
+            promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodLiteral<"explicit">;
+            }, z.core.$strip>>;
         }, z.core.$strip>], "type">>]>;
     }, z.core.$strip>, z.ZodObject<{
         providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -471,6 +495,9 @@ export declare const SerializedRunState: z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             type: z.ZodLiteral<"input_text">;
             text: z.ZodString;
+            promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodLiteral<"explicit">;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
         rawContent: z.ZodOptional<z.ZodArray<z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -531,6 +558,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 }, z.core.$strip>]>;
                 format: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 transcript: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"image">;
@@ -758,6 +788,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_text">;
                 text: z.ZodString;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_image">;
@@ -765,6 +798,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     id: z.ZodString;
                 }, z.core.$strip>]>>;
                 detail: z.ZodOptional<z.ZodString>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_file">;
@@ -774,6 +810,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     url: z.ZodString;
                 }, z.core.$strip>]>>;
                 filename: z.ZodOptional<z.ZodString>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>], "type">>]>;
         }, z.core.$strip>, z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -809,6 +848,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_text">;
                 text: z.ZodString;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>>;
             rawContent: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -975,6 +1017,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 }, z.core.$strip>]>;
                 format: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 transcript: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"image">;
@@ -1202,6 +1247,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_text">;
                 text: z.ZodString;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_image">;
@@ -1209,6 +1257,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     id: z.ZodString;
                 }, z.core.$strip>]>>;
                 detail: z.ZodOptional<z.ZodString>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_file">;
@@ -1218,6 +1269,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     url: z.ZodString;
                 }, z.core.$strip>]>>;
                 filename: z.ZodOptional<z.ZodString>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>], "type">>]>;
         }, z.core.$strip>, z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1253,6 +1307,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_text">;
                 text: z.ZodString;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>>;
             rawContent: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1302,6 +1359,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 }, z.core.$strip>]>;
                 format: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 transcript: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"image">;
@@ -1565,6 +1625,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_text">;
                 text: z.ZodString;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_image">;
@@ -1572,6 +1635,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     id: z.ZodString;
                 }, z.core.$strip>]>>;
                 detail: z.ZodOptional<z.ZodString>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_file">;
@@ -1581,6 +1647,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     url: z.ZodString;
                 }, z.core.$strip>]>>;
                 filename: z.ZodOptional<z.ZodString>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>], "type">>]>;
         }, z.core.$strip>, z.ZodObject<{
             providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1635,6 +1704,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_text">;
                 text: z.ZodString;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>>;
             rawContent: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1714,6 +1786,9 @@ export declare const SerializedRunState: z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_text">;
                 text: z.ZodString;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_image">;
@@ -1721,6 +1796,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     id: z.ZodString;
                 }, z.core.$strip>]>>;
                 detail: z.ZodOptional<z.ZodString>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                 type: z.ZodLiteral<"input_file">;
@@ -1730,6 +1808,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     url: z.ZodString;
                 }, z.core.$strip>]>>;
                 filename: z.ZodOptional<z.ZodString>;
+                promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                    mode: z.ZodLiteral<"explicit">;
+                }, z.core.$strip>>;
             }, z.core.$strip>], "type">>]>;
         }, z.core.$strip>;
         sourceAgent: z.ZodObject<{
@@ -1931,6 +2012,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     }, z.core.$strip>]>;
                     format: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                     transcript: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                        mode: z.ZodLiteral<"explicit">;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>, z.ZodObject<{
                     providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                     type: z.ZodLiteral<"image">;
@@ -2194,6 +2278,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                     type: z.ZodLiteral<"input_text">;
                     text: z.ZodString;
+                    promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                        mode: z.ZodLiteral<"explicit">;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>, z.ZodObject<{
                     providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                     type: z.ZodLiteral<"input_image">;
@@ -2201,6 +2288,9 @@ export declare const SerializedRunState: z.ZodObject<{
                         id: z.ZodString;
                     }, z.core.$strip>]>>;
                     detail: z.ZodOptional<z.ZodString>;
+                    promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                        mode: z.ZodLiteral<"explicit">;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>, z.ZodObject<{
                     providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                     type: z.ZodLiteral<"input_file">;
@@ -2210,6 +2300,9 @@ export declare const SerializedRunState: z.ZodObject<{
                         url: z.ZodString;
                     }, z.core.$strip>]>>;
                     filename: z.ZodOptional<z.ZodString>;
+                    promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                        mode: z.ZodLiteral<"explicit">;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>], "type">>]>;
             }, z.core.$strip>, z.ZodObject<{
                 providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -2264,6 +2357,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                     type: z.ZodLiteral<"input_text">;
                     text: z.ZodString;
+                    promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                        mode: z.ZodLiteral<"explicit">;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>>;
                 rawContent: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -2343,6 +2439,9 @@ export declare const SerializedRunState: z.ZodObject<{
                     providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                     type: z.ZodLiteral<"input_text">;
                     text: z.ZodString;
+                    promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                        mode: z.ZodLiteral<"explicit">;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>, z.ZodObject<{
                     providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                     type: z.ZodLiteral<"input_image">;
@@ -2350,6 +2449,9 @@ export declare const SerializedRunState: z.ZodObject<{
                         id: z.ZodString;
                     }, z.core.$strip>]>>;
                     detail: z.ZodOptional<z.ZodString>;
+                    promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                        mode: z.ZodLiteral<"explicit">;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>, z.ZodObject<{
                     providerData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
                     type: z.ZodLiteral<"input_file">;
@@ -2359,6 +2461,9 @@ export declare const SerializedRunState: z.ZodObject<{
                         url: z.ZodString;
                     }, z.core.$strip>]>>;
                     filename: z.ZodOptional<z.ZodString>;
+                    promptCacheBreakpoint: z.ZodOptional<z.ZodObject<{
+                        mode: z.ZodLiteral<"explicit">;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>], "type">>]>;
             }, z.core.$strip>;
             sourceAgent: z.ZodObject<{

package/dist/runState.js

@@ -1130,6 +1130,18 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
         typeof context.toolInput === 'undefined') {
         context.toolInput = stateJson.context.toolInput;
     }
+    // Restore the aggregated run usage. toJSON serializes context.usage, but a
+    // freshly constructed RunContext starts with an empty Usage, so without this
+    // a resumed run reports zero token usage.
+    //
+    // Only restore on the no-override path. A caller-supplied RunContext is
+    // authoritative and owns its usage accounting: its counters do not reveal
+    // whether its Usage is newly owned or shared with another run (for example a
+    // nested agent-tool resume passes a context whose usage aggregate is shared
+    // with the outer run), so it is left untouched.
+    if (!contextOverride) {
+        context.usage = new usage_1.Usage(stateJson.context.usage);
+    }
     //
     // Find the current agent from the initial agent
     //