@tanstack/ai 0.39.0 → 0.40.0

package/dist/esm/index.js

@@ -24,6 +24,7 @@ import { convertMessagesToModelMessages, generateMessageId, modelMessageToUIMess
 import { chatParamsFromRequest, chatParamsFromRequestBody, mergeAgentTools } from "./utilities/chat-params.js";
 import { uiMessagesToWire } from "./utilities/ag-ui-wire.js";
 import { isContentPart, isContentPartArray, normalizeToolResult } from "./utilities/tool-result.js";
+import { getProviderExecutedMetadata, isProviderExecutedToolCall } from "./utilities/provider-executed.js";
 import { createModel, extendAdapter } from "./extend-adapter.js";
 import { ConsoleLogger } from "./logger/console-logger.js";
 import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PunctuationStrategy, WordBoundaryStrategy } from "./activities/chat/stream/strategies.js";
@@ -79,9 +80,11 @@ export {
   generateSpeech,
   generateTranscription,
   generateVideo,
+  getProviderExecutedMetadata,
   getVideoJobStatus,
   isContentPart,
   isContentPartArray,
+  isProviderExecutedToolCall,
   isStandardSchema,
   maxIterations,
   mergeAgentTools,

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/types.d.ts

@@ -96,6 +96,25 @@ export interface ToolCall<TMetadata = unknown> {
      * `@tanstack/ai-gemini` sets this to `{ thoughtSignature?: string }`. */
     metadata?: TMetadata;
 }
+/**
+ * Convention for tool-call `metadata` that marks a call as **provider-executed**
+ * — run by the provider's own infrastructure (e.g. Anthropic `web_search` /
+ * `web_fetch` server tools) rather than by the agent loop. Adapters set
+ * `providerExecuted: true` so that:
+ *
+ * 1. The agent loop never tries to execute the call client-side (see
+ *    {@link isProviderExecutedToolCall} usage in the chat engine), and
+ * 2. The adapter can stash the raw provider result alongside it so the call —
+ *    and its evidence — round-trips into the next turn's request.
+ *
+ * Provider-specific payloads live under a namespaced key (e.g. `anthropic`),
+ * keeping this convention opaque to the framework core. The index signature
+ * preserves those per-adapter fields.
+ */
+export interface ProviderExecutedToolMetadata {
+    providerExecuted?: boolean;
+    [key: string]: unknown;
+}
 /**
  * Supported input modality types for multimodal content.
  * - 'text': Plain text content
@@ -252,7 +271,9 @@ export interface ToolCallPart<TMetadata = unknown> {
     /** Tool execution output (for client tools or after approval) */
     output?: any;
     /** Provider-specific metadata that round-trips with the tool call.
-     * Typed per-adapter via `TToolCallMetadata`. */
+     * Typed per-adapter via `TToolCallMetadata`. May follow the
+     * {@link ProviderExecutedToolMetadata} convention to mark provider-executed
+     * server tools (e.g. Anthropic `web_search`). */
     metadata?: TMetadata;
 }
 export interface ToolResultPart {
@@ -1133,6 +1154,119 @@ export interface UIResourceEvent extends CustomEvent {
         meta?: Record<string, unknown>;
     };
 }
+export interface SandboxFileCustomEvent extends CustomEvent {
+    name: 'sandbox.file';
+    value: {
+        type: 'create' | 'change' | 'delete';
+        path: string;
+        timestamp: number;
+    };
+}
+export interface SandboxFileDiffEvent extends CustomEvent {
+    name: 'sandbox.file.diff';
+    value: {
+        path: string;
+        diff: string;
+    };
+}
+export interface FileChangedEvent extends CustomEvent {
+    name: 'file.changed';
+    value: {
+        path: string;
+        diff: string;
+    };
+}
+export interface SessionIdEvent extends CustomEvent {
+    name: `${string}.session-id`;
+    value: {
+        sessionId: string;
+    };
+}
+export interface CodeModeExecutionStartedEvent extends CustomEvent {
+    name: 'code_mode:execution_started';
+    value: {
+        timestamp: number;
+        codeLength: number;
+    };
+}
+export interface CodeModeConsoleEvent extends CustomEvent {
+    name: 'code_mode:console';
+    value: {
+        level: 'log' | 'warn' | 'error' | 'info';
+        message: string;
+        timestamp: number;
+    };
+}
+export interface CodeModeExternalCallEvent extends CustomEvent {
+    name: 'code_mode:external_call';
+    value: {
+        function: string;
+        args: unknown;
+        timestamp: number;
+    };
+}
+export interface CodeModeExternalResultEvent extends CustomEvent {
+    name: 'code_mode:external_result';
+    value: {
+        function: string;
+        result: unknown;
+        duration: number;
+    };
+}
+export interface CodeModeExternalErrorEvent extends CustomEvent {
+    name: 'code_mode:external_error';
+    value: {
+        function: string;
+        error: string;
+        duration: number;
+    };
+}
+export interface CodeModeSkillCallEvent extends CustomEvent {
+    name: 'code_mode:skill_call';
+    value: {
+        skill: string;
+        input: unknown;
+        timestamp: number;
+    };
+}
+export interface CodeModeSkillResultEvent extends CustomEvent {
+    name: 'code_mode:skill_result';
+    value: {
+        skill: string;
+        result: unknown;
+        duration: number;
+        timestamp: number;
+    };
+}
+export interface CodeModeSkillErrorEvent extends CustomEvent {
+    name: 'code_mode:skill_error';
+    value: {
+        skill: string;
+        error: string;
+        duration: number;
+        timestamp: number;
+    };
+}
+export interface SkillRegisteredEvent extends CustomEvent {
+    name: 'skill:registered';
+    value: {
+        id: string;
+        name: string;
+        description: string;
+        timestamp: number;
+    };
+}
+/**
+ * Every CUSTOM event TanStack AI itself emits, as a discriminated union on
+ * `name`. User-emitted custom events (via `emitCustomEvent` with a custom name)
+ * are intentionally absent — they still flow at runtime.
+ */
+export type KnownCustomEvent = SandboxFileCustomEvent | SandboxFileDiffEvent | FileChangedEvent | SessionIdEvent | CodeModeExecutionStartedEvent | CodeModeConsoleEvent | CodeModeExternalCallEvent | CodeModeExternalResultEvent | CodeModeExternalErrorEvent | CodeModeSkillCallEvent | CodeModeSkillResultEvent | CodeModeSkillErrorEvent | SkillRegisteredEvent | StructuredOutputStartEvent | StructuredOutputCompleteEvent | ApprovalRequestedEvent | ToolInputAvailableEvent | UIResourceEvent;
+/** The default chat streaming result: standard chunks plus every typed
+ *  framework CUSTOM event, with the `value: any` catch-all excluded so
+ *  literal-`name` narrowing types `value`. User-emitted custom names are typed
+ *  out (still flow at runtime — branch outside the name narrows or cast). */
+export type ChatStream = AsyncIterable<Exclude<StreamChunk, CustomEvent> | KnownCustomEvent>;
 /**
  * Public type for streams returned by `chat({ outputSchema, stream: true })`.
  *
@@ -1563,6 +1697,7 @@ export interface TTSResult {
  * Options for audio transcription.
  * These are the common options supported across providers.
  */
+export type TranscriptionResponseFormat = 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
 export interface TranscriptionOptions<TProviderOptions extends object = object> {
     /** The model to use for transcription */
     model: string;
@@ -1573,7 +1708,7 @@ export interface TranscriptionOptions<TProviderOptions extends object = object>
     /** An optional prompt to guide the transcription */
     prompt?: string;
     /** The format of the transcription output */
-    responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
+    responseFormat?: TranscriptionResponseFormat;
     /** Model-specific options for transcription */
     modelOptions?: TProviderOptions;
     /**

package/dist/esm/utilities/provider-executed.d.ts

@@ -0,0 +1,18 @@
+import { ProviderExecutedToolMetadata } from '../types.js';
+/**
+ * Narrow a tool call's opaque `metadata` to the provider-executed convention.
+ * Returns the typed metadata when the call is provider-executed, else `null`.
+ *
+ * @see ProviderExecutedToolMetadata
+ */
+export declare function getProviderExecutedMetadata(toolCall: {
+    metadata?: unknown;
+} | null | undefined): ProviderExecutedToolMetadata | null;
+/**
+ * True when a tool call was executed by the provider (e.g. Anthropic
+ * `web_search` / `web_fetch` server tools) rather than the agent loop. Such
+ * calls must not be routed to client-side execution and are already "complete".
+ */
+export declare function isProviderExecutedToolCall(toolCall: {
+    metadata?: unknown;
+} | null | undefined): boolean;

package/dist/esm/utilities/provider-executed.js

@@ -0,0 +1,15 @@
+function getProviderExecutedMetadata(toolCall) {
+  const metadata = toolCall?.metadata;
+  if (typeof metadata === "object" && metadata !== null && metadata.providerExecuted === true) {
+    return metadata;
+  }
+  return null;
+}
+function isProviderExecutedToolCall(toolCall) {
+  return getProviderExecutedMetadata(toolCall) !== null;
+}
+export {
+  getProviderExecutedMetadata,
+  isProviderExecutedToolCall
+};
+//# sourceMappingURL=provider-executed.js.map

package/dist/esm/utilities/provider-executed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-executed.js","sources":["../../../src/utilities/provider-executed.ts"],"sourcesContent":["import type { ProviderExecutedToolMetadata } from '../types'\n\n/**\n * Narrow a tool call's opaque `metadata` to the provider-executed convention.\n * Returns the typed metadata when the call is provider-executed, else `null`.\n *\n * @see ProviderExecutedToolMetadata\n */\nexport function getProviderExecutedMetadata(\n  toolCall: { metadata?: unknown } | null | undefined,\n): ProviderExecutedToolMetadata | null {\n  const metadata = toolCall?.metadata\n  if (\n    typeof metadata === 'object' &&\n    metadata !== null &&\n    (metadata as ProviderExecutedToolMetadata).providerExecuted === true\n  ) {\n    return metadata as ProviderExecutedToolMetadata\n  }\n  return null\n}\n\n/**\n * True when a tool call was executed by the provider (e.g. Anthropic\n * `web_search` / `web_fetch` server tools) rather than the agent loop. Such\n * calls must not be routed to client-side execution and are already \"complete\".\n */\nexport function isProviderExecutedToolCall(\n  toolCall: { metadata?: unknown } | null | undefined,\n): boolean {\n  return getProviderExecutedMetadata(toolCall) !== null\n}\n"],"names":[],"mappings":"AAQO,SAAS,4BACd,UACqC;AACrC,QAAM,WAAW,UAAU;AAC3B,MACE,OAAO,aAAa,YACpB,aAAa,QACZ,SAA0C,qBAAqB,MAChE;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAOO,SAAS,2BACd,UACS;AACT,SAAO,4BAA4B,QAAQ,MAAM;AACnD;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.39.0",
+  "version": "0.40.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/adapter-configuration/SKILL.md

@@ -297,6 +297,16 @@ Per-provider sampling keys (all live inside `modelOptions`):
 some sampling options use provider-native names. Ollama nests all sampling under
 `modelOptions.options`.
 
+> **Anthropic `max_tokens` default:** Anthropic's API _requires_ `max_tokens`,
+> so the adapter always sends one. When you omit `modelOptions.max_tokens`, it
+> defaults to the selected model's full output ceiling (its `max_output_tokens`
+> from model metadata — e.g. 64K for Sonnet, 128K for Opus), not a low constant.
+> `max_tokens` is a ceiling, not a reservation (billing is per token generated),
+> so leaving it unset is the right default for codegen / agentic / long-form
+> output and avoids silent `stop_reason: "max_tokens"` truncation. Set it only to
+> cap output below the model ceiling. Other providers treat token limits as
+> optional and don't apply this flooring.
+
 ### 6. Capability Flag: `supportsCombinedToolsAndSchema`
 
 Adapters can declare an optional capability method:

package/skills/ai-core/adapter-configuration/references/anthropic-adapter.md

@@ -21,17 +21,23 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 
 ## Key Chat Models
 
-| Model               | Context Window | Max Output | Notes                           |
-| ------------------- | -------------- | ---------- | ------------------------------- |
-| `claude-opus-4-6`   | 200K           | 128K       | Most capable, adaptive thinking |
-| `claude-sonnet-4-6` | 1M             | 64K        | Best balance, adaptive thinking |
-| `claude-sonnet-4-5` | 200K           | 64K        | Previous gen balanced           |
-| `claude-opus-4-5`   | 200K           | 32K        | Previous gen most capable       |
-| `claude-haiku-4-5`  | 200K           | 64K        | Fast and affordable             |
-| `claude-sonnet-4`   | 200K           | 64K        | Older balanced model            |
-| `claude-opus-4`     | 200K           | 32K        | Older most capable              |
-
-Note: Model IDs use the format `claude-opus-4-6`, `claude-sonnet-4-6`, etc.
+| Model               | Context Window | Max Output | Notes                                       |
+| ------------------- | -------------- | ---------- | ------------------------------------------- |
+| `claude-fable-5`    | 1M             | 128K       | Most capable; thinking always on (adaptive) |
+| `claude-sonnet-5`   | 1M             | 128K       | Best balance; adaptive thinking by default  |
+| `claude-opus-4-8`   | 1M             | 128K       | Opus tier; adaptive thinking, no sampling   |
+| `claude-opus-4-7`   | 1M             | 128K       | Older Opus; adaptive thinking, no sampling  |
+| `claude-opus-4-6`   | 200K           | 128K       | Older Opus, adaptive + budget thinking      |
+| `claude-sonnet-4-6` | 1M             | 64K        | Previous gen balanced, adaptive + budget    |
+| `claude-sonnet-4-5` | 200K           | 64K        | Previous gen balanced                       |
+| `claude-opus-4-5`   | 200K           | 32K        | Previous gen most capable                   |
+| `claude-opus-4-1`   | 200K           | 64K        | Deprecated (retires 2026-08-05)             |
+| `claude-haiku-4-5`  | 200K           | 64K        | Fast and affordable                         |
+
+Note: Model IDs use the format `claude-sonnet-5`, `claude-opus-4-8`, etc.
+Retired models (Claude 3.x, Sonnet 3.7, Opus 4 / Sonnet 4) and the `-fast`
+variant ids were removed — every registered id resolves against the
+first-party Anthropic API.
 
 ## Provider-Specific modelOptions
 
@@ -90,11 +96,36 @@ chat({
 ANTHROPIC_API_KEY
 ```
 
+## Adaptive-era modelOptions (Sonnet 5, Fable 5, Opus 4.7/4.8)
+
+The per-model types restrict `modelOptions` on the newest models:
+
+```typescript
+chat({
+  adapter: anthropicText('claude-sonnet-5'), // or 'claude-fable-5', 'claude-opus-4-8'
+  messages,
+  modelOptions: {
+    // Adaptive thinking only — budget_tokens is rejected (400).
+    // On claude-fable-5, { type: 'disabled' } is also rejected;
+    // elsewhere it opts out of thinking.
+    thinking: { type: 'adaptive', display: 'summarized' },
+    // Effort lives under output_config; 'xhigh' is available on
+    // Opus 4.7+, Sonnet 5, and Fable 5.
+    output_config: { effort: 'xhigh' },
+    max_tokens: 64_000,
+    // NO temperature / top_p / top_k — the API rejects them on these models
+  },
+})
+```
+
 ## Gotchas
 
 - `thinking.budget_tokens` must be >= 1024 AND less than `modelOptions.max_tokens`.
   Failing either check throws a validation error.
 - Cannot set both `top_p` and `temperature` at the same time (throws error).
-- `claude-3-5-haiku` and `claude-3-haiku` do NOT support extended thinking.
+- `claude-sonnet-5`, `claude-fable-5`, `claude-opus-4-8`, and
+  `claude-opus-4-7` do NOT accept `temperature`, `top_p`, `top_k`, or
+  `thinking: { type: 'enabled', budget_tokens }` — adaptive thinking +
+  `output_config.effort` replace them (typed per model).
 - System prompts support prompt caching via `cache_control` on `TextBlockParam[]`.
 - All Claude models accept `text`, `image`, and `document` (PDF) input.

package/skills/ai-core/ag-ui-protocol/SKILL.md

@@ -13,6 +13,7 @@ sources:
   - 'TanStack/ai:docs/protocol/chunk-definitions.md'
   - 'TanStack/ai:docs/protocol/sse-protocol.md'
   - 'TanStack/ai:docs/protocol/http-stream-protocol.md'
+  - 'TanStack/ai:docs/protocol/custom-events.md'
 ---
 
 # AG-UI Protocol
@@ -218,6 +219,62 @@ RUN_STARTED -> TEXT_MESSAGE_START -> TEXT_MESSAGE_CONTENT* -> TEXT_MESSAGE_END
 union of all event interfaces). `StreamChunkType` is an alias for `AGUIEventType`
 (the string union of all event type literals).
 
+### 4. Typed CUSTOM Events — `ChatStream` and `KnownCustomEvent`
+
+The `CUSTOM` row above describes the raw `StreamChunk` union, where the single
+generic `CustomEvent` member types `value` as `any` -- once merged into a
+union, that `any` poisons every other member too, so narrowing on `name`
+still leaves `value: any`. `chat()` doesn't return raw `StreamChunk`; by
+default (no `outputSchema`, `stream` not explicitly `false`) it returns
+`ChatStream`, which swaps that generic member for `KnownCustomEvent` -- a
+discriminated union of every `CUSTOM` event TanStack AI itself emits, each
+with a literal `name` and a concrete `value`. Narrow with a plain `if` --
+no helper, no cast:
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+const stream = chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+})
+
+for await (const chunk of stream) {
+  if (chunk.type === 'CUSTOM' && chunk.name === 'sandbox.file.diff') {
+    console.log(chunk.value.path, chunk.value.diff) // typed, no helper, no cast
+  } else if (
+    chunk.type === 'CUSTOM' &&
+    chunk.name === 'structured-output.complete'
+  ) {
+    console.log(chunk.value.object) // typed, no helper, no cast
+  }
+}
+```
+
+**Caveat -- `.endsWith()` (or any non-literal check) does not narrow.**
+`SessionIdEvent['name']` is the template-literal type
+`` `${string}.session-id` ``. TypeScript's control-flow narrowing only
+understands exact comparisons (`===`) and `in`/type-predicate checks against
+a discriminant -- a runtime `chunk.name.endsWith('.session-id')` check
+doesn't inform the type system, so `chunk.value` stays the union of every
+`KnownCustomEvent`'s `value`, not `{ sessionId: string }`. Compare against
+the exact literal you expect, or write a user-defined type predicate
+(`(c): c is SessionIdEvent => c.name.endsWith('.session-id')`) and call that
+in the `if` instead.
+
+**User-emitted `emitCustomEvent` names are typed out of `ChatStream`.** Tools
+that call `context.emitCustomEvent('my-app:progress', ...)` still stream a
+`CUSTOM` chunk at runtime, but `'my-app:progress'` isn't one of
+`KnownCustomEvent`'s literal names, so it's intentionally absent from
+`ChatStream`'s type -- including a generic fallback member would reintroduce
+the `value: any` poison for every other event on the stream. To read your own
+event with a type, annotate the stream as the wider `StreamChunk` instead of
+`ChatStream` for that branch; its generic `CUSTOM` member already types
+`value` as `any`, so no cast is needed there either.
+
+Source: docs/protocol/custom-events.md
+
 ## Common Mistakes
 
 ### MEDIUM: Proxy buffering breaks SSE streaming
@@ -273,3 +330,5 @@ without transformation. See `docs/migration/ag-ui-compliance.md` for details.
 ## Cross-References
 
 - See also: `ai-core/custom-backend-integration/SKILL.md` -- Custom backends must implement SSE or HTTP stream format to work with TanStack AI client connection adapters.
+- See also: `ai-core/middleware/SKILL.md` -- `sandbox.file.diff`'s `{ path, diff }` value (one of `KnownCustomEvent`'s members) is populated from the same lazy `before()`/`after()`/`diff()` accessors documented there for `onFile*` middleware hooks.
+- Full CUSTOM event taxonomy: `docs/protocol/custom-events.md`.

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

@@ -151,7 +151,7 @@ function ImageGenerator() {
 
 Supported adapters: `openaiImage` (dall-e-2, dall-e-3, gpt-image-1,
 gpt-image-1-mini, gpt-image-2) and `geminiImage` (gemini-3.1-flash-image-preview,
-imagen-4.0-generate-001, etc.).
+gemini-3.1-flash-lite-image, imagen-4.0-generate-001, etc.).
 
 ```typescript
 import { generateImage } from '@tanstack/ai'
@@ -357,7 +357,7 @@ const { generate, result, isLoading } = useGenerateSpeech({
 ### 4. Audio Transcription
 
 Adapter: `openaiTranscription` (whisper-1, gpt-4o-transcribe,
-gpt-4o-mini-transcribe).
+gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize).
 
 > **Capturing audio in the browser:** Use `useAudioRecorder` from `@tanstack/ai-react` to record directly in the browser, then pass the recording as the `audio` input to `generate()`, or use `recording.part` as a prompt part in chat/generation calls. No transcoding or extra dependencies required — the recorder returns the native browser format (`audio/webm` or `audio/mp4`). For transcription, wrap it as a `data:` URL so the provider gets the real content type; passing raw `recording.base64` makes the adapter assume `audio/mpeg` and mislabel the webm/mp4 bytes.
 >
@@ -382,16 +382,21 @@ const result = await generateTranscription({
   language: 'en',
   responseFormat: 'verbose_json',
   modelOptions: {
-    include: ['segment', 'word'],
+    timestamp_granularities: ['word', 'segment'],
   },
 })
 
 // result.text       -- full transcribed text
 // result.language   -- detected/specified language
 // result.duration   -- audio duration in seconds
-// result.segments   -- timestamped segments with optional word-level timestamps
+// result.segments   -- timestamped segments (word-level timestamps are in result.words)
 ```
 
+For speaker diarization, use `openaiTranscription('gpt-4o-transcribe-diarize')`.
+When no response format is given it defaults the request to `response_format: 'diarized_json'`
+and `chunking_strategy: 'auto'` (a top-level `responseFormat` of `'json'`/`'text'` opts out of
+speaker segments); do not pass `prompt`, `include`, or `timestamp_granularities` with this model.
+
 Client hook:
 
 ```tsx

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

@@ -11,6 +11,7 @@ library: tanstack-ai
 library_version: '0.10.0'
 sources:
   - 'TanStack/ai:docs/advanced/middleware.md'
+  - 'TanStack/ai:docs/sandbox/observability.md'
 ---
 
 # Middleware
@@ -371,6 +372,95 @@ Options: `maxSize` (default 100), `ttl` (default Infinity), `toolNames` (default
 `keyFn` (custom cache key), `storage` (custom backend like Redis). See
 `docs/advanced/middleware.md` for custom storage examples.
 
+## Sandbox File-Event Hooks (`sandbox` group)
+
+Declare a `sandbox: ChatSandboxHooks` group on `defineChatMiddleware` to react
+to every file created/changed/deleted inside a sandbox provided by
+`withSandbox` (from `@tanstack/ai-sandbox`). These fire **per-run**,
+server-side, and each handler receives the run's `ChatMiddlewareContext` as
+the first argument:
+
+```typescript
+import { defineChatMiddleware } from '@tanstack/ai'
+import { db } from './db'
+
+const auditMiddleware = defineChatMiddleware({
+  name: 'audit',
+  sandbox: {
+    onFile: (ctx, e) => console.log(ctx.runId, e.type, e.path),
+    onFileCreate: (ctx, e) => db.log({ run: ctx.runId, event: e }),
+  },
+})
+```
+
+| Hook           | Fires for                  |
+| -------------- | -------------------------- |
+| `onFile`       | Every create/change/delete |
+| `onFileCreate` | File creates only          |
+| `onFileChange` | File changes only          |
+| `onFileDelete` | File deletes only          |
+
+These are independent of the stream: the engine also emits a `sandbox.file`
+`CUSTOM` chunk per change regardless of whether any `sandbox` hooks are
+registered, so a client can react to the same edits without middleware. See
+`ai-core/ag-ui-protocol/SKILL.md` for reading that chunk (and the opt-in
+`sandbox.file.diff` chunk) off `ChatStream`.
+
+### `before()` / `after()` / `diff()` — lazy, git-backed content accessors
+
+Each hook receives a `SandboxFileHookEvent`: the serializable
+`{ type, path, timestamp }` plus three lazy accessors for the file's content:
+
+```ts
+interface SandboxFileHookEvent {
+  type: 'create' | 'change' | 'delete'
+  path: string
+  timestamp: number
+  before(): Promise<string> // content at the session baseline ('' if new / non-git)
+  after(): Promise<string> // current content ('' if deleted)
+  diff(): Promise<string> // unified patch vs the baseline
+}
+```
+
+```typescript
+import { defineChatMiddleware } from '@tanstack/ai'
+import { db } from './db'
+
+const auditMiddleware = defineChatMiddleware({
+  name: 'audit',
+  sandbox: {
+    onFileChange: async (ctx, e) => {
+      const [before, after] = await Promise.all([e.before(), e.after()])
+      db.log({ run: ctx.runId, path: e.path, before, after })
+    },
+  },
+})
+```
+
+**Lazy — path-only hooks pay nothing.** `before()`, `after()`, and `diff()`
+are methods, not fields: each only reads the file or shells out to `git` when
+called. A hook that only reads `e.path`/`e.type` (like the `onFile` logger
+above) never touches the filesystem or spawns a process.
+
+**Git session baseline.** The sandbox snapshots `git rev-parse HEAD` once at
+setup as the session baseline (empty string if the workspace isn't a git repo
+or has no commits). `before()` and `diff()` always diff against that same
+fixed baseline for the rest of the run, so `onFileChange` reports the file's
+**cumulative** change since the run started, not just the delta since the
+last poll. `after()` always reads current on-disk content. None of the three
+accessors throw: a deleted file resolves `after()` to `''` (it still has
+`before()`); a new file resolves `before()` to `''` (it still has `after()`);
+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 `''`.
+
+**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.
+
+Source: docs/sandbox/observability.md
+
 ## Common Mistakes
 
 ### a. MEDIUM: Trying to modify StreamChunks in middleware
@@ -451,3 +541,4 @@ Source: docs/advanced/middleware.md
 
 - See also: **ai-core/chat-experience/SKILL.md** -- Middleware hooks into the chat lifecycle
 - See also: **ai-core/structured-outputs/SKILL.md** -- Middleware now wraps the final structured-output call; use `onStructuredOutputConfig` for JSON-Schema transforms
+- See also: **ai-core/ag-ui-protocol/SKILL.md** -- Reading the `sandbox.file` / `sandbox.file.diff` `CUSTOM` chunks the sandbox runtime emits alongside these `sandbox` hooks, via `ChatStream`'s typed `KnownCustomEvent` narrowing

package/src/activities/chat/index.ts

@@ -12,6 +12,7 @@ import { streamToText } from '../../stream-to-response.js'
 import { resolveDebugOption } from '../../logger/resolve'
 import { EventType } from '../../types'
 import { normalizeToolResult } from '../../utilities/tool-result'
+import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import {
   MiddlewareAbortError,
@@ -44,6 +45,7 @@ import type {
 import type {
   AgentLoopStrategy,
   AnyTool,
+  ChatStream,
   ConstrainedModelMessage,
   CustomEvent,
   InferSchemaType,
@@ -68,7 +70,7 @@ import type {
   ChatMiddleware,
   ChatMiddlewareConfig,
   ChatMiddlewareContext,
-  SandboxFileEvent,
+  SandboxFileHookEvent,
   StructuredOutputMiddlewareConfig,
 } from './middleware/types'
 import type { CheckCoverage } from './middleware/builder'
@@ -403,7 +405,7 @@ export type TextActivityResult<
     : Promise<InferSchemaType<TSchema>>
   : [TStream] extends [false]
     ? Promise<string>
-    : AsyncIterable<StreamChunk>
+    : ChatStream
 
 // ===========================
 // ChatEngine Implementation
@@ -711,11 +713,30 @@ class TextEngine<
     // a `sandbox.file` custom chunk to be drained into the public stream.
     provideSandboxRuntime(this.middlewareCtx, {
       logger: this.logger,
-      emit: (event: SandboxFileEvent) => {
-        this.logger.sandbox(`file ${event.type} ${event.path}`, { event })
-        void this.middlewareRunner.runSandboxFile(this.middlewareCtx, event)
+      emit: (event: SandboxFileHookEvent) => {
+        this.logger.sandbox(`file ${event.type} ${event.path}`, {
+          event: {
+            type: event.type,
+            path: event.path,
+            timestamp: event.timestamp,
+          },
+        })
+        void this.middlewareRunner
+          .runSandboxFile(this.middlewareCtx, event)
+          .catch((err: unknown) => {
+            this.logger.errors('sandbox file hook failed', { error: err })
+          })
         this.sandboxFileQueue.push(
-          this.createCustomEventChunk('sandbox.file', { ...event }),
+          this.createCustomEventChunk('sandbox.file', {
+            type: event.type,
+            path: event.path,
+            timestamp: event.timestamp,
+          }),
+        )
+      },
+      emitFileDiff: (value: { path: string; diff: string }) => {
+        this.sandboxFileQueue.push(
+          this.createCustomEventChunk('sandbox.file.diff', value),
         )
       },
     })
@@ -1884,6 +1905,13 @@ class TextEngine<
     for (const message of this.messages) {
       if (message.role === 'assistant' && message.toolCalls) {
         for (const toolCall of message.toolCalls) {
+          // Provider-executed tool calls (e.g. Anthropic `web_search`) were
+          // already run by the provider; they carry no client result, so they
+          // would otherwise look "pending" forever and the loop would try (and
+          // fail) to execute them client-side. Skip them.
+          if (isProviderExecutedToolCall(toolCall)) {
+            continue
+          }
           if (!completedToolIds.has(toolCall.id)) {
             pending.push(toolCall)
           }

package/src/activities/chat/middleware/compose.ts

@@ -11,7 +11,7 @@ import type {
   ErrorInfo,
   FinishInfo,
   IterationInfo,
-  SandboxFileEvent,
+  SandboxFileHookEvent,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   ToolPhaseCompleteInfo,
@@ -352,7 +352,7 @@ export class MiddlewareRunner<TContext = unknown> {
    */
   async runSandboxFile(
     ctx: ChatMiddlewareContext<TContext>,
-    event: SandboxFileEvent,
+    event: SandboxFileHookEvent,
   ): Promise<void> {
     const typed = (
       {