@tanstack/ai 0.42.0 → 0.43.0

package/dist/esm/activities/chat/middleware/tool-cache-middleware.js

@@ -1,76 +1,85 @@
+//#region src/activities/chat/middleware/tool-cache-middleware.ts
 function defaultKeyFn(toolName, args) {
-  return JSON.stringify([toolName, args]);
+	return JSON.stringify([toolName, args]);
 }
 function createDefaultStorage(maxSize) {
-  const cache = /* @__PURE__ */ new Map();
-  return {
-    getItem: (key) => {
-      const entry = cache.get(key);
-      if (entry !== void 0) {
-        cache.delete(key);
-        cache.set(key, entry);
-      }
-      return entry;
-    },
-    setItem: (key, value) => {
-      if (cache.has(key)) {
-        cache.delete(key);
-      } else if (cache.size >= maxSize) {
-        const firstKey = cache.keys().next().value;
-        if (firstKey !== void 0) {
-          cache.delete(firstKey);
-        }
-      }
-      cache.set(key, value);
-    },
-    deleteItem: (key) => {
-      cache.delete(key);
-    }
-  };
+	const cache = /* @__PURE__ */ new Map();
+	return {
+		getItem: (key) => {
+			const entry = cache.get(key);
+			if (entry !== void 0) {
+				cache.delete(key);
+				cache.set(key, entry);
+			}
+			return entry;
+		},
+		setItem: (key, value) => {
+			if (cache.has(key)) cache.delete(key);
+			else if (cache.size >= maxSize) {
+				const firstKey = cache.keys().next().value;
+				if (firstKey !== void 0) cache.delete(firstKey);
+			}
+			cache.set(key, value);
+		},
+		deleteItem: (key) => {
+			cache.delete(key);
+		}
+	};
 }
+/**
+* Creates a middleware that caches tool call results based on tool name + arguments.
+*
+* When a tool is called with the same name and arguments as a previous call,
+* the cached result is returned immediately without executing the tool.
+*
+* @example
+* ```ts
+* import { chat, toolCacheMiddleware } from '@tanstack/ai'
+*
+* const stream = chat({
+*   adapter,
+*   messages,
+*   tools: [weatherTool, stockTool],
+*   middleware: [
+*     toolCacheMiddleware({ ttl: 60_000, toolNames: ['getWeather'] }),
+*   ],
+* })
+* ```
+*/
 function toolCacheMiddleware(options = {}) {
-  const {
-    maxSize = 100,
-    ttl = Infinity,
-    toolNames,
-    keyFn = defaultKeyFn,
-    storage = createDefaultStorage(maxSize)
-  } = options;
-  return {
-    name: "tool-cache-middleware",
-    onBeforeToolCall: async (_ctx, hookCtx) => {
-      if (toolNames && !toolNames.includes(hookCtx.toolName)) {
-        return void 0;
-      }
-      const key = keyFn(hookCtx.toolName, hookCtx.args);
-      const entry = await storage.getItem(key);
-      if (entry) {
-        const age = Date.now() - entry.timestamp;
-        if (age < ttl) {
-          return { type: "skip", result: entry.result };
-        }
-        await storage.deleteItem(key);
-      }
-      return void 0;
-    },
-    onAfterToolCall: async (_ctx, info) => {
-      if (!info.ok) return;
-      if (toolNames && !toolNames.includes(info.toolName)) return;
-      let parsedArgs;
-      try {
-        parsedArgs = JSON.parse(info.toolCall.function.arguments.trim() || "{}");
-      } catch {
-        return;
-      }
-      const key = keyFn(info.toolName, parsedArgs);
-      await storage.setItem(key, {
-        result: info.result,
-        timestamp: Date.now()
-      });
-    }
-  };
+	const { maxSize = 100, ttl = Infinity, toolNames, keyFn = defaultKeyFn, storage = createDefaultStorage(maxSize) } = options;
+	return {
+		name: "tool-cache-middleware",
+		onBeforeToolCall: async (_ctx, hookCtx) => {
+			if (toolNames && !toolNames.includes(hookCtx.toolName)) return;
+			const key = keyFn(hookCtx.toolName, hookCtx.args);
+			const entry = await storage.getItem(key);
+			if (entry) {
+				if (Date.now() - entry.timestamp < ttl) return {
+					type: "skip",
+					result: entry.result
+				};
+				await storage.deleteItem(key);
+			}
+		},
+		onAfterToolCall: async (_ctx, info) => {
+			if (!info.ok) return;
+			if (toolNames && !toolNames.includes(info.toolName)) return;
+			let parsedArgs;
+			try {
+				parsedArgs = JSON.parse(info.toolCall.function.arguments.trim() || "{}");
+			} catch {
+				return;
+			}
+			const key = keyFn(info.toolName, parsedArgs);
+			await storage.setItem(key, {
+				result: info.result,
+				timestamp: Date.now()
+			});
+		}
+	};
 }
-export {
-  toolCacheMiddleware
-};
-//# sourceMappingURL=tool-cache-middleware.js.map
+//#endregion
+export { toolCacheMiddleware };
+
+//# sourceMappingURL=tool-cache-middleware.js.map

package/dist/esm/activities/chat/middleware/tool-cache-middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-cache-middleware.js","sources":["../../../../../src/activities/chat/middleware/tool-cache-middleware.ts"],"sourcesContent":["import type { ChatMiddleware } from './types'\n\n/**\n * A cache entry stored by the tool cache middleware.\n */\nexport interface ToolCacheEntry {\n  result: unknown\n  timestamp: number\n}\n\n/**\n * Custom storage backend for the tool cache middleware.\n *\n * When provided, the middleware delegates all cache operations to this storage\n * instead of using the built-in in-memory Map. This enables external storage\n * backends like Redis, localStorage, databases, etc.\n *\n * All methods may return a Promise for async storage backends.\n */\nexport interface ToolCacheStorage {\n  getItem: (\n    key: string,\n  ) => ToolCacheEntry | undefined | Promise<ToolCacheEntry | undefined>\n  setItem: (key: string, value: ToolCacheEntry) => void | Promise<void>\n  deleteItem: (key: string) => void | Promise<void>\n}\n\n/**\n * Options for the tool cache middleware.\n */\nexport interface ToolCacheMiddlewareOptions {\n  /**\n   * Maximum number of entries in the cache.\n   * When exceeded, the oldest entry is evicted (LRU).\n   *\n   * Only applies to the default in-memory storage.\n   * When a custom `storage` is provided, capacity management is the storage's responsibility.\n   *\n   * @default 100\n   */\n  maxSize?: number\n\n  /**\n   * Time-to-live in milliseconds. Entries older than this are not served from cache.\n   * @default Infinity (no expiry)\n   */\n  ttl?: number\n\n  /**\n   * Tool names to cache. If not provided, all tools are cached.\n   */\n  toolNames?: Array<string>\n\n  /**\n   * Custom function to generate a cache key from tool name and args.\n   * Defaults to `JSON.stringify([toolName, args])`.\n   */\n  keyFn?: (toolName: string, args: unknown) => string\n\n  /**\n   * Custom storage backend. When provided, the middleware uses this instead of\n   * the built-in in-memory Map. The storage is responsible for its own capacity\n   * management — the `maxSize` option is ignored.\n   *\n   * @example\n   * ```ts\n   * toolCacheMiddleware({\n   *   storage: {\n   *     getItem: (key) => redisClient.get(key).then(v => v ? JSON.parse(v) : undefined),\n   *     setItem: (key, value) => redisClient.set(key, JSON.stringify(value)),\n   *     deleteItem: (key) => redisClient.del(key),\n   *   },\n   * })\n   * ```\n   */\n  storage?: ToolCacheStorage\n}\n\nfunction defaultKeyFn(toolName: string, args: unknown): string {\n  return JSON.stringify([toolName, args])\n}\n\nfunction createDefaultStorage(maxSize: number): ToolCacheStorage {\n  const cache = new Map<string, ToolCacheEntry>()\n\n  return {\n    getItem: (key) => {\n      const entry = cache.get(key)\n      if (entry !== undefined) {\n        // Refresh recency: delete and re-insert so this key becomes newest\n        cache.delete(key)\n        cache.set(key, entry)\n      }\n      return entry\n    },\n    setItem: (key, value) => {\n      // Delete first so re-inserts also refresh recency\n      if (cache.has(key)) {\n        cache.delete(key)\n      } else if (cache.size >= maxSize) {\n        // LRU eviction: Map iteration order is insertion order — first key is least recently used\n        const firstKey = cache.keys().next().value\n        if (firstKey !== undefined) {\n          cache.delete(firstKey)\n        }\n      }\n      cache.set(key, value)\n    },\n    deleteItem: (key) => {\n      cache.delete(key)\n    },\n  }\n}\n\n/**\n * Creates a middleware that caches tool call results based on tool name + arguments.\n *\n * When a tool is called with the same name and arguments as a previous call,\n * the cached result is returned immediately without executing the tool.\n *\n * @example\n * ```ts\n * import { chat, toolCacheMiddleware } from '@tanstack/ai'\n *\n * const stream = chat({\n *   adapter,\n *   messages,\n *   tools: [weatherTool, stockTool],\n *   middleware: [\n *     toolCacheMiddleware({ ttl: 60_000, toolNames: ['getWeather'] }),\n *   ],\n * })\n * ```\n */\nexport function toolCacheMiddleware(\n  options: ToolCacheMiddlewareOptions = {},\n): ChatMiddleware {\n  const {\n    maxSize = 100,\n    ttl = Infinity,\n    toolNames,\n    keyFn = defaultKeyFn,\n    storage = createDefaultStorage(maxSize),\n  } = options\n\n  return {\n    name: 'tool-cache-middleware',\n\n    onBeforeToolCall: async (_ctx, hookCtx) => {\n      if (toolNames && !toolNames.includes(hookCtx.toolName)) {\n        return undefined\n      }\n\n      const key = keyFn(hookCtx.toolName, hookCtx.args)\n      const entry = await storage.getItem(key)\n\n      if (entry) {\n        const age = Date.now() - entry.timestamp\n        if (age < ttl) {\n          return { type: 'skip', result: entry.result }\n        }\n        // Expired — remove\n        await storage.deleteItem(key)\n      }\n\n      return undefined\n    },\n\n    onAfterToolCall: async (_ctx, info) => {\n      if (!info.ok) return\n      if (toolNames && !toolNames.includes(info.toolName)) return\n\n      // Re-derive the key from the raw arguments to match what onBeforeToolCall produces\n      let parsedArgs: unknown\n      try {\n        parsedArgs = JSON.parse(info.toolCall.function.arguments.trim() || '{}')\n      } catch {\n        return\n      }\n\n      const key = keyFn(info.toolName, parsedArgs)\n\n      await storage.setItem(key, {\n        result: info.result,\n        timestamp: Date.now(),\n      })\n    },\n  }\n}\n"],"names":[],"mappings":"AA8EA,SAAS,aAAa,UAAkB,MAAuB;AAC7D,SAAO,KAAK,UAAU,CAAC,UAAU,IAAI,CAAC;AACxC;AAEA,SAAS,qBAAqB,SAAmC;AAC/D,QAAM,4BAAY,IAAA;AAElB,SAAO;AAAA,IACL,SAAS,CAAC,QAAQ;AAChB,YAAM,QAAQ,MAAM,IAAI,GAAG;AAC3B,UAAI,UAAU,QAAW;AAEvB,cAAM,OAAO,GAAG;AAChB,cAAM,IAAI,KAAK,KAAK;AAAA,MACtB;AACA,aAAO;AAAA,IACT;AAAA,IACA,SAAS,CAAC,KAAK,UAAU;AAEvB,UAAI,MAAM,IAAI,GAAG,GAAG;AAClB,cAAM,OAAO,GAAG;AAAA,MAClB,WAAW,MAAM,QAAQ,SAAS;AAEhC,cAAM,WAAW,MAAM,KAAA,EAAO,OAAO;AACrC,YAAI,aAAa,QAAW;AAC1B,gBAAM,OAAO,QAAQ;AAAA,QACvB;AAAA,MACF;AACA,YAAM,IAAI,KAAK,KAAK;AAAA,IACtB;AAAA,IACA,YAAY,CAAC,QAAQ;AACnB,YAAM,OAAO,GAAG;AAAA,IAClB;AAAA,EAAA;AAEJ;AAsBO,SAAS,oBACd,UAAsC,IACtB;AAChB,QAAM;AAAA,IACJ,UAAU;AAAA,IACV,MAAM;AAAA,IACN;AAAA,IACA,QAAQ;AAAA,IACR,UAAU,qBAAqB,OAAO;AAAA,EAAA,IACpC;AAEJ,SAAO;AAAA,IACL,MAAM;AAAA,IAEN,kBAAkB,OAAO,MAAM,YAAY;AACzC,UAAI,aAAa,CAAC,UAAU,SAAS,QAAQ,QAAQ,GAAG;AACtD,eAAO;AAAA,MACT;AAEA,YAAM,MAAM,MAAM,QAAQ,UAAU,QAAQ,IAAI;AAChD,YAAM,QAAQ,MAAM,QAAQ,QAAQ,GAAG;AAEvC,UAAI,OAAO;AACT,cAAM,MAAM,KAAK,IAAA,IAAQ,MAAM;AAC/B,YAAI,MAAM,KAAK;AACb,iBAAO,EAAE,MAAM,QAAQ,QAAQ,MAAM,OAAA;AAAA,QACvC;AAEA,cAAM,QAAQ,WAAW,GAAG;AAAA,MAC9B;AAEA,aAAO;AAAA,IACT;AAAA,IAEA,iBAAiB,OAAO,MAAM,SAAS;AACrC,UAAI,CAAC,KAAK,GAAI;AACd,UAAI,aAAa,CAAC,UAAU,SAAS,KAAK,QAAQ,EAAG;AAGrD,UAAI;AACJ,UAAI;AACF,qBAAa,KAAK,MAAM,KAAK,SAAS,SAAS,UAAU,KAAA,KAAU,IAAI;AAAA,MACzE,QAAQ;AACN;AAAA,MACF;AAEA,YAAM,MAAM,MAAM,KAAK,UAAU,UAAU;AAE3C,YAAM,QAAQ,QAAQ,KAAK;AAAA,QACzB,QAAQ,KAAK;AAAA,QACb,WAAW,KAAK,IAAA;AAAA,MAAI,CACrB;AAAA,IACH;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"tool-cache-middleware.js","names":[],"sources":["../../../../../src/activities/chat/middleware/tool-cache-middleware.ts"],"sourcesContent":["import type { ChatMiddleware } from './types'\n\n/**\n * A cache entry stored by the tool cache middleware.\n */\nexport interface ToolCacheEntry {\n  result: unknown\n  timestamp: number\n}\n\n/**\n * Custom storage backend for the tool cache middleware.\n *\n * When provided, the middleware delegates all cache operations to this storage\n * instead of using the built-in in-memory Map. This enables external storage\n * backends like Redis, localStorage, databases, etc.\n *\n * All methods may return a Promise for async storage backends.\n */\nexport interface ToolCacheStorage {\n  getItem: (\n    key: string,\n  ) => ToolCacheEntry | undefined | Promise<ToolCacheEntry | undefined>\n  setItem: (key: string, value: ToolCacheEntry) => void | Promise<void>\n  deleteItem: (key: string) => void | Promise<void>\n}\n\n/**\n * Options for the tool cache middleware.\n */\nexport interface ToolCacheMiddlewareOptions {\n  /**\n   * Maximum number of entries in the cache.\n   * When exceeded, the oldest entry is evicted (LRU).\n   *\n   * Only applies to the default in-memory storage.\n   * When a custom `storage` is provided, capacity management is the storage's responsibility.\n   *\n   * @default 100\n   */\n  maxSize?: number\n\n  /**\n   * Time-to-live in milliseconds. Entries older than this are not served from cache.\n   * @default Infinity (no expiry)\n   */\n  ttl?: number\n\n  /**\n   * Tool names to cache. If not provided, all tools are cached.\n   */\n  toolNames?: Array<string>\n\n  /**\n   * Custom function to generate a cache key from tool name and args.\n   * Defaults to `JSON.stringify([toolName, args])`.\n   */\n  keyFn?: (toolName: string, args: unknown) => string\n\n  /**\n   * Custom storage backend. When provided, the middleware uses this instead of\n   * the built-in in-memory Map. The storage is responsible for its own capacity\n   * management — the `maxSize` option is ignored.\n   *\n   * @example\n   * ```ts\n   * toolCacheMiddleware({\n   *   storage: {\n   *     getItem: (key) => redisClient.get(key).then(v => v ? JSON.parse(v) : undefined),\n   *     setItem: (key, value) => redisClient.set(key, JSON.stringify(value)),\n   *     deleteItem: (key) => redisClient.del(key),\n   *   },\n   * })\n   * ```\n   */\n  storage?: ToolCacheStorage\n}\n\nfunction defaultKeyFn(toolName: string, args: unknown): string {\n  return JSON.stringify([toolName, args])\n}\n\nfunction createDefaultStorage(maxSize: number): ToolCacheStorage {\n  const cache = new Map<string, ToolCacheEntry>()\n\n  return {\n    getItem: (key) => {\n      const entry = cache.get(key)\n      if (entry !== undefined) {\n        // Refresh recency: delete and re-insert so this key becomes newest\n        cache.delete(key)\n        cache.set(key, entry)\n      }\n      return entry\n    },\n    setItem: (key, value) => {\n      // Delete first so re-inserts also refresh recency\n      if (cache.has(key)) {\n        cache.delete(key)\n      } else if (cache.size >= maxSize) {\n        // LRU eviction: Map iteration order is insertion order — first key is least recently used\n        const firstKey = cache.keys().next().value\n        if (firstKey !== undefined) {\n          cache.delete(firstKey)\n        }\n      }\n      cache.set(key, value)\n    },\n    deleteItem: (key) => {\n      cache.delete(key)\n    },\n  }\n}\n\n/**\n * Creates a middleware that caches tool call results based on tool name + arguments.\n *\n * When a tool is called with the same name and arguments as a previous call,\n * the cached result is returned immediately without executing the tool.\n *\n * @example\n * ```ts\n * import { chat, toolCacheMiddleware } from '@tanstack/ai'\n *\n * const stream = chat({\n *   adapter,\n *   messages,\n *   tools: [weatherTool, stockTool],\n *   middleware: [\n *     toolCacheMiddleware({ ttl: 60_000, toolNames: ['getWeather'] }),\n *   ],\n * })\n * ```\n */\nexport function toolCacheMiddleware(\n  options: ToolCacheMiddlewareOptions = {},\n): ChatMiddleware {\n  const {\n    maxSize = 100,\n    ttl = Infinity,\n    toolNames,\n    keyFn = defaultKeyFn,\n    storage = createDefaultStorage(maxSize),\n  } = options\n\n  return {\n    name: 'tool-cache-middleware',\n\n    onBeforeToolCall: async (_ctx, hookCtx) => {\n      if (toolNames && !toolNames.includes(hookCtx.toolName)) {\n        return undefined\n      }\n\n      const key = keyFn(hookCtx.toolName, hookCtx.args)\n      const entry = await storage.getItem(key)\n\n      if (entry) {\n        const age = Date.now() - entry.timestamp\n        if (age < ttl) {\n          return { type: 'skip', result: entry.result }\n        }\n        // Expired — remove\n        await storage.deleteItem(key)\n      }\n\n      return undefined\n    },\n\n    onAfterToolCall: async (_ctx, info) => {\n      if (!info.ok) return\n      if (toolNames && !toolNames.includes(info.toolName)) return\n\n      // Re-derive the key from the raw arguments to match what onBeforeToolCall produces\n      let parsedArgs: unknown\n      try {\n        parsedArgs = JSON.parse(info.toolCall.function.arguments.trim() || '{}')\n      } catch {\n        return\n      }\n\n      const key = keyFn(info.toolName, parsedArgs)\n\n      await storage.setItem(key, {\n        result: info.result,\n        timestamp: Date.now(),\n      })\n    },\n  }\n}\n"],"mappings":";AA8EA,SAAS,aAAa,UAAkB,MAAuB;CAC7D,OAAO,KAAK,UAAU,CAAC,UAAU,IAAI,CAAC;AACxC;AAEA,SAAS,qBAAqB,SAAmC;CAC/D,MAAM,wBAAQ,IAAI,IAA4B;CAE9C,OAAO;EACL,UAAU,QAAQ;GAChB,MAAM,QAAQ,MAAM,IAAI,GAAG;GAC3B,IAAI,UAAU,KAAA,GAAW;IAEvB,MAAM,OAAO,GAAG;IAChB,MAAM,IAAI,KAAK,KAAK;GACtB;GACA,OAAO;EACT;EACA,UAAU,KAAK,UAAU;GAEvB,IAAI,MAAM,IAAI,GAAG,GACf,MAAM,OAAO,GAAG;QACX,IAAI,MAAM,QAAQ,SAAS;IAEhC,MAAM,WAAW,MAAM,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,aAAa,KAAA,GACf,MAAM,OAAO,QAAQ;GAEzB;GACA,MAAM,IAAI,KAAK,KAAK;EACtB;EACA,aAAa,QAAQ;GACnB,MAAM,OAAO,GAAG;EAClB;CACF;AACF;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,oBACd,UAAsC,CAAC,GACvB;CAChB,MAAM,EACJ,UAAU,KACV,MAAM,UACN,WACA,QAAQ,cACR,UAAU,qBAAqB,OAAO,MACpC;CAEJ,OAAO;EACL,MAAM;EAEN,kBAAkB,OAAO,MAAM,YAAY;GACzC,IAAI,aAAa,CAAC,UAAU,SAAS,QAAQ,QAAQ,GACnD;GAGF,MAAM,MAAM,MAAM,QAAQ,UAAU,QAAQ,IAAI;GAChD,MAAM,QAAQ,MAAM,QAAQ,QAAQ,GAAG;GAEvC,IAAI,OAAO;IAET,IADY,KAAK,IAAI,IAAI,MAAM,YACrB,KACR,OAAO;KAAE,MAAM;KAAQ,QAAQ,MAAM;IAAO;IAG9C,MAAM,QAAQ,WAAW,GAAG;GAC9B;EAGF;EAEA,iBAAiB,OAAO,MAAM,SAAS;GACrC,IAAI,CAAC,KAAK,IAAI;GACd,IAAI,aAAa,CAAC,UAAU,SAAS,KAAK,QAAQ,GAAG;GAGrD,IAAI;GACJ,IAAI;IACF,aAAa,KAAK,MAAM,KAAK,SAAS,SAAS,UAAU,KAAK,KAAK,IAAI;GACzE,QAAQ;IACN;GACF;GAEA,MAAM,MAAM,MAAM,KAAK,UAAU,UAAU;GAE3C,MAAM,QAAQ,QAAQ,KAAK;IACzB,QAAQ,KAAK;IACb,WAAW,KAAK,IAAI;GACtB,CAAC;EACH;CACF;AACF"}

package/dist/esm/activities/chat/middleware/types.d.ts

@@ -1,5 +1,6 @@
-import { JSONSchema, ModelMessage, StreamChunk, TokenUsage, Tool, ToolCall } from '../../../types.js';
+import { AgentLoopState, JSONSchema, ModelMessage, RunAgentResumeItem, StreamChunk, TokenUsage, Tool, ToolCall } from '../../../types.js';
 import { SystemPrompt } from '../../../system-prompts.js';
+import { ToolApprovalResolution } from '../../../interrupts.js';
 import { Capability, CapabilityHandle, CapabilityRegistry } from './capabilities.js';
 /** A file change observed inside a sandbox during a chat run. */
 export interface SandboxFileEvent {
@@ -52,6 +53,8 @@ export interface ChatMiddlewareContext<TContext = unknown> {
     streamId: string;
     /** AG-UI run identifier for correlating client and server events */
     runId: string;
+    /** Interrupted or parent run correlated with this continuation. */
+    parentRunId?: string;
     /**
      * AG-UI thread identifier — a stable per-conversation ID used to
      * correlate client and server devtools events. Resolves to the
@@ -92,7 +95,7 @@ export interface ChatMiddlewareContext<TContext = unknown> {
     activity: 'chat';
     /** Provider name (e.g., 'openai', 'anthropic') */
     provider: string;
-    /** Model identifier (e.g., 'gpt-4o') */
+    /** Model identifier (e.g., 'gpt-5.5') */
     model: string;
     /** Source of the chat invocation — always 'server' for server-side chat */
     source: 'client' | 'server';
@@ -150,9 +153,32 @@ export interface ChatMiddlewareConfig {
     messages: Array<ModelMessage>;
     systemPrompts: Array<SystemPrompt>;
     tools: Array<Tool>;
+    resume?: Array<RunAgentResumeItem> | undefined;
+    resumeToolState?: ChatResumeToolState | undefined;
     metadata?: Record<string, unknown> | undefined;
     modelOptions?: Record<string, unknown> | undefined;
 }
+/**
+ * Tool decisions reconstructed by server-side middleware from validated resume
+ * entries. This lets empty-message interrupt resumes continue tool execution
+ * without relying on client message history.
+ */
+export interface ChatResumeToolState {
+    approvals?: ReadonlyMap<string, ToolApprovalResolution> | undefined;
+    clientToolResults?: ReadonlyMap<string, unknown> | undefined;
+    genericInterrupts?: ReadonlyMap<string, ChatResumeGenericResolution> | undefined;
+    deniedToolResults?: ReadonlyMap<string, unknown> | undefined;
+    cancelledToolCallIds?: ReadonlySet<string> | undefined;
+}
+export type ChatResumeGenericResolution = {
+    interruptId: string;
+    status: 'resolved';
+    payload: unknown;
+} | {
+    interruptId: string;
+    status: 'cancelled';
+    payload?: never;
+};
 /**
  * Config passed to onStructuredOutputConfig.
  *
@@ -287,6 +313,22 @@ export interface AbortInfo {
     reason?: string;
     /** Duration until abort in milliseconds */
     duration: number;
+    /**
+     * True only when the abort came from an explicit, out-of-band cancel (e.g. a
+     * cancel endpoint setting `RunRecord.cancelRequested`), never from a mere
+     * client disconnect.
+     *
+     * A disconnect and a user pressing "stop" are the SAME connection close on
+     * the wire, so consumers must not infer intent from an abort alone. Middleware
+     * that tears down expensive resources reads this to distinguish "the viewer
+     * left, keep going" from "the user wants this stopped". Populated from the
+     * abort reason: `true` exactly when the run was aborted with `RUN_CANCEL_REASON`
+     * (matched with `===`, so an arbitrary error message can never be read as a
+     * deliberate cancel), `false` for every other abort. The durable channel is
+     * separate — middleware that must also catch a cancel recorded on a different
+     * host reads `RunRecord.cancelRequested` in addition to this flag.
+     */
+    cancelRequested?: boolean;
 }
 /**
  * Information passed to onError.
@@ -388,6 +430,21 @@ export interface ChatMiddleware<TContext = unknown> {
      * is created. Use this to observe iteration boundaries.
      */
     onIteration?: (ctx: ChatMiddlewareContext<TContext>, info: IterationInfo) => void | Promise<void>;
+    /**
+     * Called when the engine is deciding whether to start another agent-loop
+     * iteration (after a tool phase or between model turns).
+     *
+     * Return `false` to stop further iterations. Return `true`, `void`, or
+     * `undefined` to allow continuation. Combined with AND semantics across
+     * middleware and with `agentLoopStrategy` — any `false` stops the loop.
+     *
+     * Does not abort the run: the stream finishes normally with the current
+     * messages. Use `ctx.abort()` only when you need a hard abort.
+     *
+     * Receives the same {@link AgentLoopState} passed to strategies
+     * (`iterationCount`, `toolCallCount`, `lastTurnToolCallCount`, etc.).
+     */
+    onShouldContinue?: (ctx: ChatMiddlewareContext<TContext>, state: AgentLoopState) => boolean | void | Promise<boolean | void>;
     /**
      * Called for every chunk yielded by chat().
      * Can observe, transform, expand, or drop chunks.

package/dist/esm/activities/chat/middleware/validate.js

@@ -1,30 +1,25 @@
+//#region src/activities/chat/middleware/validate.ts
+/**
+* Runtime validation: every required capability (from middleware `requires` and
+* the adapter's `requires`) must be provided by some middleware's `provides`.
+* `optionalRequires` is never gating. Throws a clear error otherwise.
+*
+* Presence only — ORDER is not validated here (a provider may appear after its
+* consumer in the array and still pass). Use the `createChatMiddleware()`
+* builder for compile-time order enforcement; at runtime, a consumer that reads
+* a not-yet-provided capability during `setup` fails loud via its getter.
+*/
 function validateCapabilities(middlewares, adapter) {
-  const provided = /* @__PURE__ */ new Set();
-  for (const mw of middlewares) {
-    for (const handle of mw.provides ?? []) provided.add(handle);
-  }
-  const providedNames = () => {
-    const names = [...provided].map((h) => h.capabilityName);
-    return names.length ? names.join(", ") : "none";
-  };
-  for (const handle of adapter.requires ?? []) {
-    if (!provided.has(handle)) {
-      throw new Error(
-        `Adapter "${adapter.name}" requires capability "${handle.capabilityName}". Provided capabilities: ${providedNames()}. Add a middleware that provides "${handle.capabilityName}".`
-      );
-    }
-  }
-  for (const mw of middlewares) {
-    for (const handle of mw.requires ?? []) {
-      if (!provided.has(handle)) {
-        throw new Error(
-          `Middleware "${mw.name ?? "unnamed"}" requires capability "${handle.capabilityName}". Provided capabilities: ${providedNames()}. Add a middleware that provides "${handle.capabilityName}".`
-        );
-      }
-    }
-  }
+	const provided = /* @__PURE__ */ new Set();
+	for (const mw of middlewares) for (const handle of mw.provides ?? []) provided.add(handle);
+	const providedNames = () => {
+		const names = [...provided].map((h) => h.capabilityName);
+		return names.length ? names.join(", ") : "none";
+	};
+	for (const handle of adapter.requires ?? []) if (!provided.has(handle)) throw new Error(`Adapter "${adapter.name}" requires capability "${handle.capabilityName}". Provided capabilities: ${providedNames()}. Add a middleware that provides "${handle.capabilityName}".`);
+	for (const mw of middlewares) for (const handle of mw.requires ?? []) if (!provided.has(handle)) throw new Error(`Middleware "${mw.name ?? "unnamed"}" requires capability "${handle.capabilityName}". Provided capabilities: ${providedNames()}. Add a middleware that provides "${handle.capabilityName}".`);
 }
-export {
-  validateCapabilities
-};
-//# sourceMappingURL=validate.js.map
+//#endregion
+export { validateCapabilities };
+
+//# sourceMappingURL=validate.js.map

package/dist/esm/activities/chat/middleware/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sources":["../../../../../src/activities/chat/middleware/validate.ts"],"sourcesContent":["import type { CapabilityHandle } from './capabilities'\nimport type { AnyChatMiddleware } from './types'\n\n/** Minimal adapter shape needed for capability validation. */\ninterface CapabilityRequiringAdapter {\n  name: string\n  requires?: ReadonlyArray<CapabilityHandle>\n}\n\n/**\n * Runtime validation: every required capability (from middleware `requires` and\n * the adapter's `requires`) must be provided by some middleware's `provides`.\n * `optionalRequires` is never gating. Throws a clear error otherwise.\n *\n * Presence only — ORDER is not validated here (a provider may appear after its\n * consumer in the array and still pass). Use the `createChatMiddleware()`\n * builder for compile-time order enforcement; at runtime, a consumer that reads\n * a not-yet-provided capability during `setup` fails loud via its getter.\n */\nexport function validateCapabilities(\n  middlewares: ReadonlyArray<AnyChatMiddleware>,\n  adapter: CapabilityRequiringAdapter,\n): void {\n  const provided = new Set<CapabilityHandle>()\n  for (const mw of middlewares) {\n    for (const handle of mw.provides ?? []) provided.add(handle)\n  }\n\n  const providedNames = (): string => {\n    const names = [...provided].map((h) => h.capabilityName)\n    return names.length ? names.join(', ') : 'none'\n  }\n\n  for (const handle of adapter.requires ?? []) {\n    if (!provided.has(handle)) {\n      throw new Error(\n        `Adapter \"${adapter.name}\" requires capability \"${handle.capabilityName}\". ` +\n          `Provided capabilities: ${providedNames()}. ` +\n          `Add a middleware that provides \"${handle.capabilityName}\".`,\n      )\n    }\n  }\n\n  for (const mw of middlewares) {\n    for (const handle of mw.requires ?? []) {\n      if (!provided.has(handle)) {\n        throw new Error(\n          `Middleware \"${mw.name ?? 'unnamed'}\" requires capability ` +\n            `\"${handle.capabilityName}\". Provided capabilities: ${providedNames()}. ` +\n            `Add a middleware that provides \"${handle.capabilityName}\".`,\n        )\n      }\n    }\n  }\n}\n"],"names":[],"mappings":"AAmBO,SAAS,qBACd,aACA,SACM;AACN,QAAM,+BAAe,IAAA;AACrB,aAAW,MAAM,aAAa;AAC5B,eAAW,UAAU,GAAG,YAAY,CAAA,EAAI,UAAS,IAAI,MAAM;AAAA,EAC7D;AAEA,QAAM,gBAAgB,MAAc;AAClC,UAAM,QAAQ,CAAC,GAAG,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,cAAc;AACvD,WAAO,MAAM,SAAS,MAAM,KAAK,IAAI,IAAI;AAAA,EAC3C;AAEA,aAAW,UAAU,QAAQ,YAAY,CAAA,GAAI;AAC3C,QAAI,CAAC,SAAS,IAAI,MAAM,GAAG;AACzB,YAAM,IAAI;AAAA,QACR,YAAY,QAAQ,IAAI,0BAA0B,OAAO,cAAc,6BAC3C,cAAA,CAAe,qCACN,OAAO,cAAc;AAAA,MAAA;AAAA,IAE9D;AAAA,EACF;AAEA,aAAW,MAAM,aAAa;AAC5B,eAAW,UAAU,GAAG,YAAY,CAAA,GAAI;AACtC,UAAI,CAAC,SAAS,IAAI,MAAM,GAAG;AACzB,cAAM,IAAI;AAAA,UACR,eAAe,GAAG,QAAQ,SAAS,0BAC7B,OAAO,cAAc,6BAA6B,cAAA,CAAe,qCAClC,OAAO,cAAc;AAAA,QAAA;AAAA,MAE9D;AAAA,IACF;AAAA,EACF;AACF;"}
+{"version":3,"file":"validate.js","names":[],"sources":["../../../../../src/activities/chat/middleware/validate.ts"],"sourcesContent":["import type { CapabilityHandle } from './capabilities'\nimport type { AnyChatMiddleware } from './types'\n\n/** Minimal adapter shape needed for capability validation. */\ninterface CapabilityRequiringAdapter {\n  name: string\n  requires?: ReadonlyArray<CapabilityHandle>\n}\n\n/**\n * Runtime validation: every required capability (from middleware `requires` and\n * the adapter's `requires`) must be provided by some middleware's `provides`.\n * `optionalRequires` is never gating. Throws a clear error otherwise.\n *\n * Presence only — ORDER is not validated here (a provider may appear after its\n * consumer in the array and still pass). Use the `createChatMiddleware()`\n * builder for compile-time order enforcement; at runtime, a consumer that reads\n * a not-yet-provided capability during `setup` fails loud via its getter.\n */\nexport function validateCapabilities(\n  middlewares: ReadonlyArray<AnyChatMiddleware>,\n  adapter: CapabilityRequiringAdapter,\n): void {\n  const provided = new Set<CapabilityHandle>()\n  for (const mw of middlewares) {\n    for (const handle of mw.provides ?? []) provided.add(handle)\n  }\n\n  const providedNames = (): string => {\n    const names = [...provided].map((h) => h.capabilityName)\n    return names.length ? names.join(', ') : 'none'\n  }\n\n  for (const handle of adapter.requires ?? []) {\n    if (!provided.has(handle)) {\n      throw new Error(\n        `Adapter \"${adapter.name}\" requires capability \"${handle.capabilityName}\". ` +\n          `Provided capabilities: ${providedNames()}. ` +\n          `Add a middleware that provides \"${handle.capabilityName}\".`,\n      )\n    }\n  }\n\n  for (const mw of middlewares) {\n    for (const handle of mw.requires ?? []) {\n      if (!provided.has(handle)) {\n        throw new Error(\n          `Middleware \"${mw.name ?? 'unnamed'}\" requires capability ` +\n            `\"${handle.capabilityName}\". Provided capabilities: ${providedNames()}. ` +\n            `Add a middleware that provides \"${handle.capabilityName}\".`,\n        )\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;AAmBA,SAAgB,qBACd,aACA,SACM;CACN,MAAM,2BAAW,IAAI,IAAsB;CAC3C,KAAK,MAAM,MAAM,aACf,KAAK,MAAM,UAAU,GAAG,YAAY,CAAC,GAAG,SAAS,IAAI,MAAM;CAG7D,MAAM,sBAA8B;EAClC,MAAM,QAAQ,CAAC,GAAG,QAAQ,CAAC,CAAC,KAAK,MAAM,EAAE,cAAc;EACvD,OAAO,MAAM,SAAS,MAAM,KAAK,IAAI,IAAI;CAC3C;CAEA,KAAK,MAAM,UAAU,QAAQ,YAAY,CAAC,GACxC,IAAI,CAAC,SAAS,IAAI,MAAM,GACtB,MAAM,IAAI,MACR,YAAY,QAAQ,KAAK,yBAAyB,OAAO,eAAe,4BAC5C,cAAc,EAAE,oCACP,OAAO,eAAe,GAC7D;CAIJ,KAAK,MAAM,MAAM,aACf,KAAK,MAAM,UAAU,GAAG,YAAY,CAAC,GACnC,IAAI,CAAC,SAAS,IAAI,MAAM,GACtB,MAAM,IAAI,MACR,eAAe,GAAG,QAAQ,UAAU,yBAC9B,OAAO,eAAe,4BAA4B,cAAc,EAAE,oCACnC,OAAO,eAAe,GAC7D;AAIR"}

package/dist/esm/activities/chat/stream/json-parser.js

@@ -1,28 +1,42 @@
 import { parse } from "partial-json";
-class PartialJSONParser {
-  /**
-   * Parse a potentially incomplete JSON string
-   * @param jsonString - The JSON string to parse (may be incomplete)
-   * @returns The parsed object, or undefined if parsing fails
-   */
-  parse(jsonString) {
-    if (!jsonString || jsonString.trim() === "") {
-      return void 0;
-    }
-    try {
-      return parse(jsonString);
-    } catch {
-      return void 0;
-    }
-  }
-}
-const defaultJSONParser = new PartialJSONParser();
+//#region src/activities/chat/stream/json-parser.ts
+/**
+* JSON Parser for partial/incomplete JSON strings
+*
+* Used during streaming to parse tool call arguments that may be incomplete.
+*/
+/**
+* Partial JSON Parser implementation using the partial-json library
+* This parser can handle incomplete JSON strings during streaming
+*/
+var PartialJSONParser = class {
+	/**
+	* Parse a potentially incomplete JSON string
+	* @param jsonString - The JSON string to parse (may be incomplete)
+	* @returns The parsed object, or undefined if parsing fails
+	*/
+	parse(jsonString) {
+		if (!jsonString || jsonString.trim() === "") return;
+		try {
+			return parse(jsonString);
+		} catch {
+			return;
+		}
+	}
+};
+/**
+* Default parser instance
+*/
+var defaultJSONParser = new PartialJSONParser();
+/**
+* Parse partial JSON string (convenience function)
+* @param jsonString - The JSON string to parse (may be incomplete)
+* @returns The parsed object, or undefined if parsing fails
+*/
 function parsePartialJSON(jsonString) {
-  return defaultJSONParser.parse(jsonString);
+	return defaultJSONParser.parse(jsonString);
 }
-export {
-  PartialJSONParser,
-  defaultJSONParser,
-  parsePartialJSON
-};
-//# sourceMappingURL=json-parser.js.map
+//#endregion
+export { PartialJSONParser, defaultJSONParser, parsePartialJSON };
+
+//# sourceMappingURL=json-parser.js.map

package/dist/esm/activities/chat/stream/json-parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"json-parser.js","sources":["../../../../../src/activities/chat/stream/json-parser.ts"],"sourcesContent":["/**\n * JSON Parser for partial/incomplete JSON strings\n *\n * Used during streaming to parse tool call arguments that may be incomplete.\n */\n\nimport { parse as parsePartialJSONLib } from 'partial-json'\n\n/**\n * JSON Parser interface - allows for custom parser implementations\n */\nexport interface JSONParser {\n  /**\n   * Parse a JSON string (may be incomplete/partial)\n   * @param jsonString - The JSON string to parse\n   * @returns The parsed object, or undefined if parsing fails\n   */\n  parse: (jsonString: string) => any\n}\n\n/**\n * Partial JSON Parser implementation using the partial-json library\n * This parser can handle incomplete JSON strings during streaming\n */\nexport class PartialJSONParser implements JSONParser {\n  /**\n   * Parse a potentially incomplete JSON string\n   * @param jsonString - The JSON string to parse (may be incomplete)\n   * @returns The parsed object, or undefined if parsing fails\n   */\n  parse(jsonString: string): any {\n    if (!jsonString || jsonString.trim() === '') {\n      return undefined\n    }\n\n    try {\n      return parsePartialJSONLib(jsonString)\n    } catch {\n      // If partial parsing fails, return undefined\n      // This is expected during early streaming when we have very little data\n      return undefined\n    }\n  }\n}\n\n/**\n * Default parser instance\n */\nexport const defaultJSONParser = new PartialJSONParser()\n\n/**\n * Parse partial JSON string (convenience function)\n * @param jsonString - The JSON string to parse (may be incomplete)\n * @returns The parsed object, or undefined if parsing fails\n */\nexport function parsePartialJSON(jsonString: string): any {\n  return defaultJSONParser.parse(jsonString)\n}\n"],"names":["parsePartialJSONLib"],"mappings":";AAwBO,MAAM,kBAAwC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMnD,MAAM,YAAyB;AAC7B,QAAI,CAAC,cAAc,WAAW,KAAA,MAAW,IAAI;AAC3C,aAAO;AAAA,IACT;AAEA,QAAI;AACF,aAAOA,MAAoB,UAAU;AAAA,IACvC,QAAQ;AAGN,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAKO,MAAM,oBAAoB,IAAI,kBAAA;AAO9B,SAAS,iBAAiB,YAAyB;AACxD,SAAO,kBAAkB,MAAM,UAAU;AAC3C;"}
+{"version":3,"file":"json-parser.js","names":[],"sources":["../../../../../src/activities/chat/stream/json-parser.ts"],"sourcesContent":["/**\n * JSON Parser for partial/incomplete JSON strings\n *\n * Used during streaming to parse tool call arguments that may be incomplete.\n */\n\nimport { parse as parsePartialJSONLib } from 'partial-json'\n\n/**\n * JSON Parser interface - allows for custom parser implementations\n */\nexport interface JSONParser {\n  /**\n   * Parse a JSON string (may be incomplete/partial)\n   * @param jsonString - The JSON string to parse\n   * @returns The parsed object, or undefined if parsing fails\n   */\n  parse: (jsonString: string) => any\n}\n\n/**\n * Partial JSON Parser implementation using the partial-json library\n * This parser can handle incomplete JSON strings during streaming\n */\nexport class PartialJSONParser implements JSONParser {\n  /**\n   * Parse a potentially incomplete JSON string\n   * @param jsonString - The JSON string to parse (may be incomplete)\n   * @returns The parsed object, or undefined if parsing fails\n   */\n  parse(jsonString: string): any {\n    if (!jsonString || jsonString.trim() === '') {\n      return undefined\n    }\n\n    try {\n      return parsePartialJSONLib(jsonString)\n    } catch {\n      // If partial parsing fails, return undefined\n      // This is expected during early streaming when we have very little data\n      return undefined\n    }\n  }\n}\n\n/**\n * Default parser instance\n */\nexport const defaultJSONParser = new PartialJSONParser()\n\n/**\n * Parse partial JSON string (convenience function)\n * @param jsonString - The JSON string to parse (may be incomplete)\n * @returns The parsed object, or undefined if parsing fails\n */\nexport function parsePartialJSON(jsonString: string): any {\n  return defaultJSONParser.parse(jsonString)\n}\n"],"mappings":";;;;;;;;;;;AAwBA,IAAa,oBAAb,MAAqD;;;;;;CAMnD,MAAM,YAAyB;EAC7B,IAAI,CAAC,cAAc,WAAW,KAAK,MAAM,IACvC;EAGF,IAAI;GACF,OAAO,MAAoB,UAAU;EACvC,QAAQ;GAGN;EACF;CACF;AACF;;;;AAKA,IAAa,oBAAoB,IAAI,kBAAkB;;;;;;AAOvD,SAAgB,iBAAiB,YAAyB;CACxD,OAAO,kBAAkB,MAAM,UAAU;AAC3C"}