@tanstack/ai 0.40.0 → 0.41.0

package/dist/esm/index.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,

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?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.40.0",
+  "version": "0.41.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/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

package/src/activities/chat/messages.ts

@@ -444,12 +444,21 @@ export function modelMessageToUIMessage(
   // Handle tool calls
   if (modelMessage.toolCalls && modelMessage.toolCalls.length > 0) {
     for (const toolCall of modelMessage.toolCalls) {
+      // Model-message arguments are complete, so surface the parsed input.
+      // A malformed arguments string just leaves `input` undefined.
+      let input: unknown
+      try {
+        input = JSON.parse(toolCall.function.arguments)
+      } catch {
+        input = undefined
+      }
       parts.push({
         type: 'tool-call',
         id: toolCall.id,
         name: toolCall.function.name,
         arguments: toolCall.function.arguments,
         state: 'input-complete', // Model messages have complete arguments
+        ...(input !== undefined && { input }),
         ...(toolCall.metadata !== undefined && { metadata: toolCall.metadata }),
       })
     }

package/src/activities/chat/stream/message-updaters.ts

@@ -58,6 +58,8 @@ export function updateToolCallPart(
     name: string
     arguments: string
     state: ToolCallState
+    /** Parsed input — set when the arguments are complete. */
+    input?: unknown
     metadata?: Record<string, unknown>
   },
 ): Array<UIMessage> {
@@ -76,6 +78,9 @@ export function updateToolCallPart(
     // Gemini's thoughtSignature on TOOL_CALL_START) we must not lose it on
     // subsequent updates that don't re-supply it.
     const metadata = toolCall.metadata ?? existing?.metadata
+    // Same for the parsed input: it's supplied once at completion, so
+    // subsequent arg-less updates (approval, etc.) must not drop it.
+    const input = toolCall.input ?? existing?.input
 
     const toolCallPart: ToolCallPart = {
       type: 'tool-call',
@@ -83,9 +88,10 @@ export function updateToolCallPart(
       name: toolCall.name,
       arguments: toolCall.arguments,
       state: toolCall.state,
-      // Carry forward approval and output from the existing part
+      // Carry forward approval, output and parsed input from the existing part
       ...(existing?.approval && { approval: { ...existing.approval } }),
       ...(existing?.output !== undefined && { output: existing.output }),
+      ...(input !== undefined && { input }),
       ...(metadata !== undefined && { metadata }),
     }
 

package/src/activities/chat/stream/processor.ts

@@ -1298,15 +1298,35 @@ export class StreamProcessor {
       // received, back-fill the arguments string so the UIMessage ToolCallPart
       // carries the correct value (defensive against adapters that skip ARGS).
       if (chunk.input !== undefined && !existingToolCall.arguments) {
-        existingToolCall.arguments = JSON.stringify(chunk.input)
+        try {
+          existingToolCall.arguments = JSON.stringify(chunk.input)
+        } catch {
+          // circular refs, BigInt, etc. — leave arguments empty rather than
+          // aborting stream processing
+        }
       }
 
       const index = msgState.toolCallOrder.indexOf(chunk.toolCallId)
       this.completeToolCall(messageId, index, existingToolCall)
       // If TOOL_CALL_END provides parsed input, use it as the canonical parsed
       // arguments (overrides the accumulated string parse from completeToolCall)
+      // and refresh the rendered part's `input` so it reflects the canonical
+      // value rather than the possibly-divergent accumulated-args parse that
+      // completeToolCall wrote (e.g. an adapter that coerces values differently
+      // between the streamed args and the final structured input).
       if (chunk.input !== undefined) {
         existingToolCall.parsedArguments = chunk.input
+        this.messages = updateToolCallPart(this.messages, messageId, {
+          id: existingToolCall.id,
+          name: existingToolCall.name,
+          arguments: existingToolCall.arguments,
+          state: 'input-complete',
+          input: chunk.input,
+          ...(existingToolCall.metadata !== undefined && {
+            metadata: existingToolCall.metadata,
+          }),
+        })
+        this.emitMessagesChange()
       }
     }
 
@@ -1890,12 +1910,20 @@ export class StreamProcessor {
       return
     }
 
-    // Update UIMessage
+    // Update UIMessage. The arguments are complete now, so surface the parsed
+    // input on the part. For adapters that skip TOOL_CALL_ARGS the arguments
+    // string was back-filled from TOOL_CALL_END.input, so this parse matches
+    // the canonical input. If a TOOL_CALL_END.input diverges from the
+    // accumulated args, handleToolCallEndEvent re-updates the part with the
+    // canonical value after this call.
     this.messages = updateToolCallPart(this.messages, messageId, {
       id: toolCall.id,
       name: toolCall.name,
       arguments: toolCall.arguments,
       state: 'input-complete',
+      ...(toolCall.parsedArguments !== undefined && {
+        input: toolCall.parsedArguments,
+      }),
       ...(toolCall.metadata !== undefined && { metadata: toolCall.metadata }),
     })
     this.emitMessagesChange()

package/src/activities/chat/tools/tool-definition.ts

@@ -26,6 +26,10 @@ export interface ClientTool<
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
   TContext = unknown,
+  // Captured as a literal (`true` / `false`) so downstream types — notably
+  // the tool-call part's `approval` field — can be gated on it. Defaults to
+  // `false` when the tool config omits `needsApproval`.
+  TNeedsApproval extends boolean = false,
 > {
   __toolSide: 'client'
   name: TName
@@ -37,7 +41,7 @@ export interface ClientTool<
   // because `undefined` doesn't extend the schema constraint.
   inputSchema?: TInput
   outputSchema?: TOutput
-  needsApproval?: boolean
+  needsApproval?: TNeedsApproval
   lazy?: boolean
   metadata?: Record<string, unknown>
   execute?: ToolExecuteFunction<TInput, TOutput, TContext>
@@ -51,18 +55,22 @@ export interface ToolDefinitionInstance<
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
   TContext = unknown,
+  TNeedsApproval extends boolean = false,
 > extends Tool<TInput, TOutput, TName, TContext> {
   __toolSide: 'definition'
+  // Narrow the base `needsApproval?: boolean` to the captured literal so it
+  // survives into `ToolCallPartForTool`'s approval gate.
+  needsApproval?: TNeedsApproval
 }
 
 /**
  * Union type for any kind of client-side tool (client tool or definition)
  */
 export type AnyClientTool =
-  | (Omit<ClientTool<any, any, string, any>, 'execute'> & {
+  | (Omit<ClientTool<any, any, string, any, boolean>, 'execute'> & {
       execute?: ((args: any, context?: any) => any) | undefined
     })
-  | (Omit<ToolDefinitionInstance<any, any, string, any>, 'execute'> & {
+  | (Omit<ToolDefinitionInstance<any, any, string, any, boolean>, 'execute'> & {
       execute?: ((args: any, context?: any) => any) | undefined
     })
 
@@ -100,12 +108,13 @@ export interface ToolDefinitionConfig<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
+  TNeedsApproval extends boolean = false,
 > {
   name: TName
   description: string
   inputSchema?: TInput
   outputSchema?: TOutput
-  needsApproval?: boolean
+  needsApproval?: TNeedsApproval
   lazy?: boolean
   metadata?: Record<string, unknown>
 }
@@ -117,7 +126,14 @@ export interface ToolDefinition<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
-> extends ToolDefinitionInstance<TInput, TOutput, TName> {
+  TNeedsApproval extends boolean = false,
+> extends ToolDefinitionInstance<
+  TInput,
+  TOutput,
+  TName,
+  unknown,
+  TNeedsApproval
+> {
   /**
    * Create a server-side tool with execute function
    */
@@ -126,11 +142,13 @@ export interface ToolDefinition<
   ) => ServerTool<TInput, TOutput, TName, TContext>
 
   /**
-   * Create a client-side tool with optional execute function
+   * Create a client-side tool with optional execute function.
+   * Carries the definition's `needsApproval` literal through to the client
+   * tool so the tool-call part's `approval` field stays gated on it.
    */
   client: <TContext = unknown>(
     execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
-  ) => ClientTool<TInput, TOutput, TName, TContext>
+  ) => ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval>
 }
 
 /**
@@ -192,10 +210,14 @@ export function toolDefinition<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
+  // `const` forces the literal (`true` / `false`) to be captured from the
+  // config's optional `needsApproval` — without it TS widens to `boolean`,
+  // which collapses the approval gate in `ToolCallPartForTool`.
+  const TNeedsApproval extends boolean = false,
 >(
-  config: ToolDefinitionConfig<TInput, TOutput, TName>,
-): ToolDefinition<TInput, TOutput, TName> {
-  const definition: ToolDefinition<TInput, TOutput, TName> = {
+  config: ToolDefinitionConfig<TInput, TOutput, TName, TNeedsApproval>,
+): ToolDefinition<TInput, TOutput, TName, TNeedsApproval> {
+  const definition: ToolDefinition<TInput, TOutput, TName, TNeedsApproval> = {
     __toolSide: 'definition',
     ...config,
     server<TContext = unknown>(
@@ -210,7 +232,7 @@ export function toolDefinition<
 
     client<TContext = unknown>(
       execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
-    ): ClientTool<TInput, TOutput, TName, TContext> {
+    ): ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval> {
       return {
         __toolSide: 'client',
         ...config,

package/src/activities/generateAudio/index.ts

@@ -14,10 +14,10 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { AudioAdapter } from './adapter'
 import type { AudioGenerationResult, StreamChunk } from '../../types'
 

package/src/activities/generateImage/index.ts

@@ -14,11 +14,11 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import { resolveMediaPrompt } from '../../utilities/media-prompt'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { ImageAdapter } from './adapter'
 import type {
   ImageGenerationResult,

package/src/activities/generateSpeech/index.ts

@@ -14,10 +14,10 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { TTSAdapter } from './adapter'
 import type { StreamChunk, TTSResult } from '../../types'
 

package/src/activities/generateTranscription/index.ts

@@ -14,10 +14,10 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { TranscriptionAdapter } from './adapter'
 import type {
   StreamChunk,