@tanstack/ai 0.40.0 → 0.42.0

package/dist/esm/index.d.ts

@@ -16,7 +16,7 @@ export { ToolCallManager } from './activities/chat/tools/tool-calls.js';
 export { DISCOVERY_TOOL_NAME } from './activities/chat/tools/lazy-tool-manager.js';
 export type { ProviderTool } from './tools/provider-tool.js';
 export { brandProviderTool } from './tools/provider-tool.js';
-export { maxIterations, untilFinishReason, combineStrategies, } from './activities/chat/agent-loop-strategies.js';
+export { maxIterations, maxToolCalls, untilFinishReason, combineStrategies, } from './activities/chat/agent-loop-strategies.js';
 export { createToolRegistry, createFrozenRegistry, type ToolRegistry, } from './tool-registry.js';
 export type { ChatMiddleware, ChatMiddlewareContext, ChatMiddlewarePhase, ChatMiddlewareConfig, StructuredOutputMiddlewareConfig, ToolCallHookContext, BeforeToolCallDecision, AfterToolCallInfo, IterationInfo, ToolPhaseCompleteInfo, UsageInfo, FinishInfo, AbortInfo, ErrorInfo, SandboxFileEvent, SandboxFileHookEvent, ChatSandboxHooks, } from './activities/chat/middleware/index.js';
 export type { GenerationMiddleware, GenerationMiddlewareContext, GenerationActivity, GenerationUsageInfo, GenerationFinishInfo, GenerationAbortInfo, GenerationErrorInfo, AnyGenerationMiddleware, } from './activities/middleware/index.js';
@@ -30,8 +30,8 @@ export type { ResolvedMediaPrompt } from './utilities/media-prompt.js';
 export type { SystemPrompt, NormalizedSystemPrompt } from './system-prompts.js';
 export { normalizeSystemPrompts } from './system-prompts.js';
 export { detectImageMimeType } from './utils.js';
-export { realtimeToken } from './realtime/index.js';
-export type { RealtimeToken, RealtimeTokenAdapter, RealtimeTokenOptions, RealtimeSessionConfig, VADConfig, RealtimeMessage, RealtimeMessagePart, RealtimeTextPart, RealtimeAudioPart, RealtimeToolCallPart, RealtimeToolResultPart, RealtimeImagePart, RealtimeStatus, RealtimeMode, AudioVisualization, RealtimeEvent, RealtimeEventPayloads, RealtimeEventHandler, RealtimeErrorCode, RealtimeError, RealtimeAdapter, RealtimeConnection, } from './realtime/index.js';
+export { realtimeToken, createRealtimeEventEmitter } from './realtime/index.js';
+export type { RealtimeToken, RealtimeTokenAdapter, RealtimeTokenOptions, RealtimeSessionConfig, RealtimeToolConfig, VADConfig, RealtimeMessage, RealtimeMessagePart, RealtimeTextPart, RealtimeAudioPart, RealtimeToolCallPart, RealtimeToolResultPart, RealtimeImagePart, RealtimeStatus, RealtimeMode, AudioVisualization, RealtimeEvent, RealtimeEventPayloads, RealtimeEventHandler, RealtimeErrorCode, RealtimeError, RealtimeAdapter, RealtimeConnection, } from './realtime/index.js';
 export { convertMessagesToModelMessages, generateMessageId, uiMessageToModelMessages, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, } from './activities/chat/messages.js';
 export { StreamProcessor, createReplayStream, ImmediateStrategy, PunctuationStrategy, BatchStrategy, WordBoundaryStrategy, CompositeStrategy, PartialJSONParser, defaultJSONParser, parsePartialJSON, } from './activities/chat/stream/index.js';
 export type { ChunkStrategy, ChunkRecording, InternalToolCallState, ProcessorResult, ProcessorState, StreamProcessorEvents, StreamProcessorOptions, ToolCallState, ToolResultState, JSONParser, } from './activities/chat/stream/index.js';

package/dist/esm/index.js

@@ -12,7 +12,7 @@ import { streamToText, toHttpResponse, toHttpStream, toServerSentEventsResponse,
 import { ToolCallManager } from "./activities/chat/tools/tool-calls.js";
 import { DISCOVERY_TOOL_NAME } from "./activities/chat/tools/lazy-tool-manager.js";
 import { brandProviderTool } from "./tools/provider-tool.js";
-import { combineStrategies, maxIterations, untilFinishReason } from "./activities/chat/agent-loop-strategies.js";
+import { combineStrategies, maxIterations, maxToolCalls, untilFinishReason } from "./activities/chat/agent-loop-strategies.js";
 import { createFrozenRegistry, createToolRegistry } from "./tool-registry.js";
 import { firstSentence, renderLazyCatalogEntry } from "./activities/chat/tools/lazy-tools.js";
 import { buildBaseUsage } from "./utilities/usage.js";
@@ -33,6 +33,7 @@ import { PartialJSONParser, defaultJSONParser, parsePartialJSON } from "./activi
 import { StreamProcessor, createReplayStream } from "./activities/chat/stream/processor.js";
 import { createCapability } from "./activities/chat/middleware/capabilities.js";
 import { createChatMiddleware } from "./activities/chat/middleware/builder.js";
+import { createRealtimeEventEmitter } from "./realtime/event-emitter.js";
 import { defineChatMiddleware } from "./activities/chat/middleware/define.js";
 export {
   BatchStrategy,
@@ -63,6 +64,7 @@ export {
   createFrozenRegistry,
   createImageOptions,
   createModel,
+  createRealtimeEventEmitter,
   createReplayStream,
   createSpeechOptions,
   createSummarizeOptions,
@@ -87,6 +89,7 @@ export {
   isProviderExecutedToolCall,
   isStandardSchema,
   maxIterations,
+  maxToolCalls,
   mergeAgentTools,
   modelMessageToUIMessage,
   modelMessagesToUIMessages,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/realtime/event-emitter.d.ts

@@ -0,0 +1,5 @@
+import { RealtimeEvent, RealtimeEventHandler, RealtimeEventPayloads } from './types.js';
+export declare function createRealtimeEventEmitter(): {
+    emit<TEvent extends RealtimeEvent>(event: TEvent, payload: RealtimeEventPayloads[TEvent]): void;
+    on<TEvent extends RealtimeEvent>(event: TEvent, handler: RealtimeEventHandler<TEvent>): () => void;
+};

package/dist/esm/realtime/event-emitter.js

@@ -0,0 +1,27 @@
+function createRealtimeEventEmitter() {
+  const eventHandlers = /* @__PURE__ */ new Map();
+  return {
+    emit(event, payload) {
+      const handlers = eventHandlers.get(event);
+      if (!handlers) return;
+      for (const handler of handlers) {
+        handler(payload);
+      }
+    },
+    on(event, handler) {
+      let handlers = eventHandlers.get(event);
+      if (!handlers) {
+        handlers = /* @__PURE__ */ new Set();
+        eventHandlers.set(event, handlers);
+      }
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    }
+  };
+}
+export {
+  createRealtimeEventEmitter
+};
+//# sourceMappingURL=event-emitter.js.map

package/dist/esm/realtime/event-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-emitter.js","sources":["../../../src/realtime/event-emitter.ts"],"sourcesContent":["import type {\n  RealtimeEvent,\n  RealtimeEventHandler,\n  RealtimeEventPayloads,\n} from './types'\n\n/**\n * Handlers are stored with a `never` payload so any specific\n * `RealtimeEventHandler<TEvent>` is assignable in (contravariance), keeping the\n * heterogeneous handler map type-safe without `any`. `emit` narrows back to the\n * event's real payload type via its signature; the lone `as never` at the call\n * site is the inverse of that stored `never`.\n */\ntype StoredHandler = (payload: never) => void\n\nexport function createRealtimeEventEmitter() {\n  const eventHandlers = new Map<RealtimeEvent, Set<StoredHandler>>()\n\n  return {\n    emit<TEvent extends RealtimeEvent>(\n      event: TEvent,\n      payload: RealtimeEventPayloads[TEvent],\n    ) {\n      const handlers = eventHandlers.get(event)\n      if (!handlers) return\n      for (const handler of handlers) {\n        handler(payload as never)\n      }\n    },\n    on<TEvent extends RealtimeEvent>(\n      event: TEvent,\n      handler: RealtimeEventHandler<TEvent>,\n    ): () => void {\n      let handlers = eventHandlers.get(event)\n      if (!handlers) {\n        handlers = new Set<StoredHandler>()\n        eventHandlers.set(event, handlers)\n      }\n      handlers.add(handler)\n\n      return () => {\n        handlers.delete(handler)\n      }\n    },\n  }\n}\n"],"names":[],"mappings":"AAeO,SAAS,6BAA6B;AAC3C,QAAM,oCAAoB,IAAA;AAE1B,SAAO;AAAA,IACL,KACE,OACA,SACA;AACA,YAAM,WAAW,cAAc,IAAI,KAAK;AACxC,UAAI,CAAC,SAAU;AACf,iBAAW,WAAW,UAAU;AAC9B,gBAAQ,OAAgB;AAAA,MAC1B;AAAA,IACF;AAAA,IACA,GACE,OACA,SACY;AACZ,UAAI,WAAW,cAAc,IAAI,KAAK;AACtC,UAAI,CAAC,UAAU;AACb,uCAAe,IAAA;AACf,sBAAc,IAAI,OAAO,QAAQ;AAAA,MACnC;AACA,eAAS,IAAI,OAAO;AAEpB,aAAO,MAAM;AACX,iBAAS,OAAO,OAAO;AAAA,MACzB;AAAA,IACF;AAAA,EAAA;AAEJ;"}

package/dist/esm/realtime/index.d.ts

@@ -1,4 +1,5 @@
 import { RealtimeToken, RealtimeTokenOptions } from './types.js';
+export { createRealtimeEventEmitter } from './event-emitter.js';
 export type * from './types.js';
 /**
  * Generate a realtime token using the provided adapter.

package/dist/esm/realtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/realtime/index.ts"],"sourcesContent":["import type { RealtimeToken, RealtimeTokenOptions } from './types'\n\n// Re-export all types\nexport type * from './types'\n\n/**\n * Generate a realtime token using the provided adapter.\n *\n * This function is used on the server to generate ephemeral tokens\n * that clients can use to establish realtime connections.\n *\n * @param options - Token generation options including the adapter\n * @returns Promise resolving to a RealtimeToken\n *\n * @example\n * ```typescript\n * import { realtimeToken } from '@tanstack/ai'\n * import { openaiRealtimeToken } from '@tanstack/ai-openai'\n *\n * // Server function (TanStack Start example)\n * export const getRealtimeToken = createServerFn()\n *   .handler(async () => {\n *     return realtimeToken({\n *       adapter: openaiRealtimeToken({\n *         model: 'gpt-realtime',\n *       }),\n *     })\n *   })\n * ```\n */\nexport async function realtimeToken(\n  options: RealtimeTokenOptions,\n): Promise<RealtimeToken> {\n  const { adapter } = options\n  return adapter.generateToken()\n}\n"],"names":[],"mappings":"AA8BA,eAAsB,cACpB,SACwB;AACxB,QAAM,EAAE,YAAY;AACpB,SAAO,QAAQ,cAAA;AACjB;"}
+{"version":3,"file":"index.js","sources":["../../../src/realtime/index.ts"],"sourcesContent":["import type { RealtimeToken, RealtimeTokenOptions } from './types'\n\nexport { createRealtimeEventEmitter } from './event-emitter'\n\n// Re-export all types\nexport type * from './types'\n\n/**\n * Generate a realtime token using the provided adapter.\n *\n * This function is used on the server to generate ephemeral tokens\n * that clients can use to establish realtime connections.\n *\n * @param options - Token generation options including the adapter\n * @returns Promise resolving to a RealtimeToken\n *\n * @example\n * ```typescript\n * import { realtimeToken } from '@tanstack/ai'\n * import { openaiRealtimeToken } from '@tanstack/ai-openai'\n *\n * // Server function (TanStack Start example)\n * export const getRealtimeToken = createServerFn()\n *   .handler(async () => {\n *     return realtimeToken({\n *       adapter: openaiRealtimeToken({\n *         model: 'gpt-realtime',\n *       }),\n *     })\n *   })\n * ```\n */\nexport async function realtimeToken(\n  options: RealtimeTokenOptions,\n): Promise<RealtimeToken> {\n  const { adapter } = options\n  return adapter.generateToken()\n}\n"],"names":[],"mappings":"AAgCA,eAAsB,cACpB,SACwB;AACxB,QAAM,EAAE,YAAY;AACpB,SAAO,QAAQ,cAAA;AACjB;"}

package/dist/esm/realtime/types.d.ts

@@ -1,4 +1,5 @@
 import { AnyClientTool } from '../activities/chat/tools/tool-definition.js';
+import { UsageInfo } from '../activities/chat/middleware/types.js';
 /**
  * Voice activity detection configuration
  */
@@ -18,6 +19,7 @@ export interface RealtimeToolConfig {
     name: string;
     description: string;
     inputSchema?: Record<string, any>;
+    outputSchema?: Record<string, any>;
 }
 /**
  * Configuration for a realtime session
@@ -182,7 +184,7 @@ export interface AudioVisualization {
 /**
  * Events emitted by the realtime connection
  */
-export type RealtimeEvent = 'status_change' | 'mode_change' | 'transcript' | 'audio_chunk' | 'tool_call' | 'message_complete' | 'interrupted' | 'error';
+export type RealtimeEvent = 'status_change' | 'mode_change' | 'transcript' | 'audio_chunk' | 'tool_call' | 'message_complete' | 'interrupted' | 'error' | 'go_away' | 'usage';
 /**
  * Event payloads for realtime events
  */
@@ -216,6 +218,10 @@ export interface RealtimeEventPayloads {
     error: {
         error: Error;
     };
+    go_away: {
+        timeLeft?: string;
+    };
+    usage: UsageInfo;
 }
 /**
  * Handler type for realtime events
@@ -273,6 +279,8 @@ export interface RealtimeConnection {
     sendToolResult: (callId: string, result: string) => void;
     /** Update session configuration */
     updateSession: (config: Partial<RealtimeSessionConfig>) => void;
+    /** Update the ephemeral token (e.g. on refresh); provider may reconnect */
+    updateToken?: (token: RealtimeToken) => void;
     /** Interrupt the current response */
     interrupt: () => void;
     /** Subscribe to connection events */

package/dist/esm/types.d.ts

@@ -261,6 +261,15 @@ export interface ToolCallPart<TMetadata = unknown> {
     id: string;
     name: string;
     arguments: string;
+    /**
+     * Parsed tool input. Set from the parsed arguments once they are complete
+     * (`state: 'input-complete'` and later). `undefined` while the raw
+     * `arguments` string is still streaming, and may stay `undefined` for a call
+     * that terminates in an error state — the raw `arguments` string is always
+     * available as a fallback. Typed per-tool on the client `ToolCallPart` (see
+     * `@tanstack/ai-client`); `unknown` on this base type.
+     */
+    input?: unknown;
     state: ToolCallState;
     /** Approval metadata if tool requires user approval */
     approval?: {
@@ -645,12 +654,24 @@ export interface ResponseFormat<TData = any> {
  * State passed to agent loop strategy for determining whether to continue
  */
 export interface AgentLoopState {
-    /** Current iteration count (0-indexed) */
+    /** Current iteration count (0-indexed). One iteration = one model turn. */
     iterationCount: number;
     /** Current messages array */
     messages: Array<ModelMessage>;
     /** Finish reason from the last response */
     finishReason: string | null;
+    /**
+     * Cumulative tool calls counted so far in this run (model-emitted during the
+     * agent loop, including ones skipped by `maxToolCallsPerTurn`, and pending
+     * tools from the inbound message list when resumed). Not a recount of full
+     * message history; not model turns.
+     */
+    toolCallCount: number;
+    /**
+     * Tool calls in the most recent budgeted batch — a live model turn or a
+     * pending/resume batch (0 when the last phase produced no tool calls).
+     */
+    lastTurnToolCallCount: number;
 }
 /**
  * Strategy function that determines whether the agent loop should continue
@@ -660,8 +681,10 @@ export interface AgentLoopState {
  *
  * @example
  * ```typescript
- * // Continue for up to 5 iterations
+ * // Continue for up to 5 iterations (model turns, not tool calls)
  * const strategy: AgentLoopStrategy = ({ iterationCount }) => iterationCount < 5;
+ * // Cap total tool calls across the run
+ * const byTools: AgentLoopStrategy = ({ toolCallCount }) => toolCallCount < 20;
  * ```
  */
 export type AgentLoopStrategy = (state: AgentLoopState) => boolean;
@@ -693,6 +716,24 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
      */
     systemPrompts?: Array<SystemPrompt>;
     agentLoopStrategy?: AgentLoopStrategy;
+    /**
+     * Maximum number of tool calls to **execute** from a single model turn (or
+     * pending/resume batch). `0` skips all execution for that batch.
+     *
+     * Models can emit many parallel tool calls in one turn. `agentLoopStrategy`
+     * (including `maxIterations` / `maxToolCalls`) is only evaluated between
+     * turns, so without this cap a single runaway turn can still execute an
+     * unbounded fan-out.
+     *
+     * When set, only the first `maxToolCallsPerTurn` calls are executed; the
+     * remainder receive error tool results so the message history stays
+     * consistent. Unset means no per-turn execution cap. Must be a non-negative
+     * finite number when set.
+     *
+     * Pair with the `maxToolCalls(n)` strategy for a cumulative **emitted**-call
+     * budget across the run (skipped calls still count toward that budget).
+     */
+    maxToolCallsPerTurn?: number;
     /**
      * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
      * Tunes how much of each lazy tool's description appears in the discovery

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",

package/skills/ai-core/chat-experience/SKILL.md

@@ -409,6 +409,64 @@ export const Route = createFileRoute('/api/chat')({
 })
 ```
 
+### 7. Queueing Messages Sent While Streaming
+
+By default, a `sendMessage` call that arrives while a stream is in flight is
+**queued** and sent automatically once the run settles **successfully** —
+this is a behavior change: such sends used to be silently dropped. Configure
+it with the `queue` option on `useChat`:
+
+```typescript
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+
+const { messages, queue, sendMessage, cancelQueued, isLoading } = useChat({
+  connection: fetchServerSentEvents('/api/chat'),
+  queue: { whenBusy: 'queue', drain: 'fifo', maxSize: 5, onOverflow: 'reject' },
+})
+```
+
+- **`whenBusy`** — `'queue'` (default) holds the message until a successful
+  settle; `'drop'` ignores the send (never appears in `queue`/`messages`);
+  `'interrupt'` aborts the current stream and sends immediately (unlike
+  `stop()`, does **not** flush already-queued items — they drain after the
+  interrupting send **succeeds**).
+- **`drain`** — `'fifo'` (default) sends queued items one at a time in
+  order; `'batch'` merges everything queued into a single send once the
+  run settles successfully.
+- **`maxSize`** / **`onOverflow`** — cap the queue length; `'reject'`
+  (default) silently ignores overflow sends (does not throw),
+  `'drop-oldest'` evicts the oldest queued item to make room.
+
+The top-level `queue` option also accepts a plain `WhenBusy` string
+shorthand (e.g. `queue: 'interrupt'`) or a `QueueStrategy` function for
+per-send action control. Strategy form always drains FIFO; actions are
+`'queue' | 'drop' | 'interrupt'`.
+
+**Drain vs flush:** queued messages auto-send only after a **successful**
+settle. They are **discarded** on stream error/abort of the active
+generation, `stop()`, `clear()`, `unsubscribe()`, and `reload()`.
+`interrupt` does not flush.
+
+`queue: Array<QueuedMessage>` (`{ id, content, createdAt }`) is separate
+from `messages` — render pending sends distinctly and cancel with
+`cancelQueued(id)`:
+
+```typescript
+{queue.map((q) => (
+  <div key={q.id}>
+    {typeof q.content === 'string' ? q.content : '[attachment]'}
+    <button onClick={() => cancelQueued(q.id)}>Cancel</button>
+  </div>
+))}
+```
+
+Override the configured policy for a single send with the second argument
+to `sendMessage`:
+
+```typescript
+sendMessage('Never mind, do this instead', { whenBusy: 'interrupt' })
+```
+
 ## Common Mistakes
 
 ### a. CRITICAL: Using Vercel AI SDK patterns (streamText, generateText)

package/skills/ai-core/media-generation/SKILL.md

@@ -261,6 +261,17 @@ await generateVideo({
 })
 ```
 
+**URL inputs that require an upload throw by default.** Most adapters pass a
+`type: 'url'` source straight through to the provider. Three paths can't —
+OpenAI `images.edit()`, OpenAI Sora `input_reference`, and Gemini **Veo** —
+because the provider only accepts uploaded bytes (Veo also takes a `gs://`
+reference). For those, an HTTP(S) URL would have to be downloaded and buffered
+in memory, which can OOM constrained runtimes, so they **throw** on an HTTP(S)
+URL image input by default. Pass a `data:` URI (or `gs://` for Veo), or opt in
+with `allowUrlFetch: true` on the adapter config
+(`createOpenaiImage(model, apiKey, { allowUrlFetch: true })`, and likewise on
+`createOpenaiVideo` / `createGeminiVideo`). `data:` URIs never need the flag.
+
 **Role hints** (`metadata.role`):
 
 | Role            | Maps to                                                                                               |
@@ -448,8 +459,8 @@ return toServerSentEventsResponse(stream)
 ```
 
 Google Veo (`@tanstack/ai-gemini`) uses the same jobs/polling flow. Its
-`duration` option is typed per model (e.g. `4 | 6 | 8` for Veo 3.x,
-`5 | 6 | 8` for Veo 2); use `adapter.snapDuration(seconds)` to coerce raw
+`duration` option is typed per model (`4 | 6 | 8` for the Veo 3.1 models);
+use `adapter.snapDuration(seconds)` to coerce raw
 seconds and `adapter.availableDurations()` to enumerate the valid set.
 Image prompt parts route by `metadata.role`: first un-roled /
 `'start_frame'` image → input image, `'end_frame'` → `lastFrame`,
@@ -472,6 +483,35 @@ const { jobId } = await generateVideo({
 // (x-goog-api-key header or ?key= query parameter).
 ```
 
+Gemini Omni Flash (`geminiVideo('gemini-omni-flash-preview')`) is served by
+the Interactions API instead of Veo's operations flow — same adapter, routed
+by model. Clips are 720p; `duration` is any number of seconds in the 3–10
+range (fractional ok, default 10 — availableDurations() reports the range),
+`size` is the aspect ratio (`'16:9' | '9:16'`), and the finished video arrives
+**inline** as a `data:video/mp4;base64,…` URL (no key needed to use it).
+Image/video prompt parts are sent as interaction content blocks, grouped
+as images, then videos, then text (no
+`metadata.role` routing); `data` sources go inline, `url` sources pass
+through as-is (never downloaded — use Gemini Files API URIs for remote
+media). For conversational editing, pass a prior generation's `jobId` as
+`modelOptions.previous_interaction_id` with a prompt describing the change:
+
+```typescript
+import { geminiVideo } from '@tanstack/ai-gemini'
+
+const omni = geminiVideo('gemini-omni-flash-preview')
+const first = await generateVideo({
+  adapter: omni,
+  prompt: 'A violinist outdoors',
+})
+// …poll first.jobId to completion, then edit it:
+const edited = await generateVideo({
+  adapter: omni,
+  prompt: 'Make the violin invisible',
+  modelOptions: { previous_interaction_id: first.jobId },
+})
+```
+
 Other video adapters: `openaiVideo('sora-2')` (pixel sizes like `'1280x720'`,
 durations 4/8/12s, single `input_reference` image prompt part), `grokVideo(...)`
 (`grok-imagine-video` does text-to-video + image-to-video; `grok-imagine-video-1.5` is

package/skills/ai-core/middleware/SKILL.md

@@ -453,11 +453,26 @@ accessors throw: a deleted file resolves `after()` to `''` (it still has
 a non-git workspace resolves **both** `before()` and `after()` to `''` and
 makes `diff()` fall back to a synthesized add-patch built from `after()` —
 except for a `delete` event in a non-git workspace, where there's nothing to
-synthesize and `diff()` resolves to `''`.
+synthesize and `diff()` resolves to `''`. In a git workspace a file git
+**isn't tracking yet** (a file the agent created, and every later edit to it)
+diffs empty because `git diff` ignores untracked files, so `diff()` falls
+back to the same synthesized add-patch whenever the file is absent at the
+baseline — a create-or-edit of an untracked file never streams an empty diff.
+An empty diff for a **tracked** file (identical to the baseline) stays empty,
+as it should. A **git-ignored** file is withheld: the file event still fires
+(you're notified it changed) but `diff()` returns `''`, so a secret like a
+`.env` never has its contents surfaced in the diff feed.
+
+**Failures are logged, not silent.** Every git/exec/fs failure behind these
+accessors (and behind the `find`-poll watcher) still falls back to `''`/an
+empty snapshot, but logs first: real anomalies (a failed `git diff`, an
+unreadable file, a lost `find` poll) under the `errors` category (on by
+default); expected-empty conditions (a new file's `before()`, a non-git
+baseline) under the `sandbox` debug category.
 
 **Hook errors are swallowed per hook.** A throwing `sandbox` hook is caught
-and logged under the `sandbox` debug category — it cannot break the run or
-stop other hooks (or the `sandbox.file` chunk) from continuing.
+and logged under the `errors` category (on by default) — it cannot break the
+run or stop other hooks (or the `sandbox.file` chunk) from continuing.
 
 Source: docs/sandbox/observability.md
 

package/skills/ai-core/tool-calling/SKILL.md

@@ -289,7 +289,10 @@ function ChatPage() {
               return (
                 <div key={part.id}>
                   <p>Approve "{part.name}"?</p>
-                  <pre>{part.arguments}</pre>
+                  {/* `part.input` is the parsed, typed object (populated once
+                      the arguments are complete, as they are at approval
+                      time); `part.arguments` remains the raw JSON string. */}
+                  <pre>{JSON.stringify(part.input, null, 2)}</pre>
                   <button
                     onClick={() =>
                       addToolApprovalResponse({
@@ -322,6 +325,15 @@ function ChatPage() {
 }
 ```
 
+> **Type-safe approval:** With typed `tools`, `part.approval` exists **only**
+> on parts for tools defined with `needsApproval: true`. Tools without approval
+> have no `approval` field (reading it is a compile error). For a
+> tool-agnostic handler over a typed union, narrow with `'approval' in part`
+> (`if (part.type === 'tool-call' && 'approval' in part && part.approval)`),
+> or type a shared component against the base `ToolCallPart`. An untyped
+> `useChat()` keeps `approval` on every tool-call part, which is why the
+> snippet above (no `tools` generic) reads it directly.
+
 ### Pattern 4: Lazy Tool Discovery
 
 Set `lazy: true` on rarely-needed tools. The LLM sees their names via a synthetic
@@ -363,6 +375,8 @@ export async function POST(request: Request) {
     adapter: openaiText('gpt-5.5'),
     messages,
     tools: [getProducts, compareProducts],
+    // maxIterations bounds model turns, not tool calls. Prefer maxToolCalls
+    // (and maxToolCallsPerTurn) when you need a tool-call budget.
     agentLoopStrategy: maxIterations(20),
   })
   return toServerSentEventsResponse(stream)

package/src/activities/chat/agent-loop-strategies.ts

@@ -1,9 +1,14 @@
 import type { AgentLoopStrategy } from '../../types'
 
 /**
- * Creates a strategy that continues for a maximum number of iterations
+ * Creates a strategy that continues for a maximum number of **model turns**
+ * (iterations), not tool calls.
  *
- * @param max - Maximum number of iterations to allow
+ * One iteration can still emit many parallel tool calls. Prefer
+ * {@link maxToolCalls} (and optionally `maxToolCallsPerTurn` on `chat()`)
+ * when you need a tool-call budget.
+ *
+ * @param max - Maximum number of model turns to allow
  * @returns AgentLoopStrategy that stops after max iterations
  *
  * @example
@@ -13,7 +18,7 @@ import type { AgentLoopStrategy } from '../../types'
  *   model: "gpt-4o",
  *   messages: [...],
  *   tools: [weatherTool],
- *   agentLoopStrategy: maxIterations(3), // Max 3 iterations
+ *   agentLoopStrategy: maxIterations(3), // Max 3 model turns
  * });
  * ```
  */
@@ -21,6 +26,40 @@ export function maxIterations(max: number): AgentLoopStrategy {
   return ({ iterationCount }) => iterationCount < max
 }
 
+/**
+ * Creates a strategy that continues while `toolCallCount < max`.
+ *
+ * Unlike {@link maxIterations} (which counts model turns), this bounds
+ * **emitted** tool calls counted during the run (including ones skipped by
+ * `maxToolCallsPerTurn`). Strategies only run between turns, so the turn that
+ * crosses `max` is not truncated — the final count (and executions, unless
+ * `maxToolCallsPerTurn` is set) may exceed `max`. Pair with
+ * `chat({ maxToolCallsPerTurn })` to also cap parallel fan-out inside a single
+ * turn.
+ *
+ * @param max - Maximum cumulative emitted tool calls before stopping further turns
+ * @returns AgentLoopStrategy that returns true while `toolCallCount < max`
+ *
+ * @example
+ * ```typescript
+ * import { chat, combineStrategies, maxIterations, maxToolCalls } from '@tanstack/ai'
+ *
+ * const stream = chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [...],
+ *   tools: [weatherTool],
+ *   maxToolCallsPerTurn: 10,
+ *   agentLoopStrategy: combineStrategies([
+ *     maxIterations(20),
+ *     maxToolCalls(20),
+ *   ]),
+ * })
+ * ```
+ */
+export function maxToolCalls(max: number): AgentLoopStrategy {
+  return ({ toolCallCount }) => toolCallCount < max
+}
+
 /**
  * Creates a strategy that continues until a specific finish reason is encountered
  *
@@ -71,6 +110,7 @@ export function untilFinishReason(
  *   tools: [weatherTool],
  *   agentLoopStrategy: combineStrategies([
  *     maxIterations(10),
+ *     maxToolCalls(20),
  *     ({ messages }) => messages.length < 100,
  *   ]),
  * });