@tanstack/ai 0.39.0 → 0.40.0

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

@@ -14,6 +14,7 @@ export type {
   AbortInfo,
   ErrorInfo,
   SandboxFileEvent,
+  SandboxFileHookEvent,
   ChatSandboxHooks,
 } from './types'
 

package/src/activities/chat/middleware/sandbox-runtime.ts

@@ -7,10 +7,12 @@
  */
 import { createCapability } from './capabilities'
 import type { InternalLogger } from '../../../logger/internal-logger'
-import type { SandboxFileEvent } from './types'
+import type { SandboxFileHookEvent } from './types'
 
 export interface SandboxRuntime {
-  emit: (event: SandboxFileEvent) => void
+  emit: (event: SandboxFileHookEvent) => void
+  /** Emit an opt-in per-file `sandbox.file.diff` CUSTOM chunk. */
+  emitFileDiff: (value: { path: string; diff: string }) => void
   logger: InternalLogger
 }
 

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

@@ -21,6 +21,19 @@ export interface SandboxFileEvent {
   timestamp: number
 }
 
+/** The file event a sandbox hook receives: the serializable {@link SandboxFileEvent}
+ *  plus lazy, git-backed content accessors. Accessors compute on call, so a hook
+ *  that only reads `path`/`type` pays nothing. Never present on the serialized
+ *  `sandbox.file` CUSTOM chunk. */
+export interface SandboxFileHookEvent extends SandboxFileEvent {
+  /** Content at the session baseline (`''` for a new file or non-git workspace). */
+  before: () => Promise<string>
+  /** Current content (`''` when the event is a delete). */
+  after: () => Promise<string>
+  /** Unified patch vs the session baseline (synthesized add-patch when non-git). */
+  diff: () => Promise<string>
+}
+
 /**
  * Sandbox file-event hooks a chat middleware can declare. Fire server-side for
  * every file create/change/delete observed in the sandbox during the run.
@@ -28,19 +41,19 @@ export interface SandboxFileEvent {
 export interface ChatSandboxHooks<TContext = unknown> {
   onFile?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
   onFileCreate?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
   onFileChange?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
   onFileDelete?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
 }
 

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

@@ -23,6 +23,7 @@ import {
   uiMessageToModelMessages,
 } from '../messages.js'
 import { normalizeToolResult } from '../../../utilities/tool-result'
+import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
 import { defaultJSONParser } from './json-parser'
 import {
   appendStructuredOutputDelta,
@@ -403,12 +404,15 @@ export class StreamProcessor {
     // 1. It was approved/denied (approval-responded state)
     // 2. It has an output field set (client tool completed via addToolResult)
     // 3. It has a corresponding tool-result part (server tool completed)
+    // 4. It is provider-executed (e.g. Anthropic web_search) — already run by
+    //    the provider, so there is no client result to wait for.
     return toolParts.every(
       (part) =>
         part.state === 'complete' ||
         part.state === 'approval-responded' ||
         (part.output !== undefined && !part.approval) ||
-        toolResultIds.has(part.id),
+        toolResultIds.has(part.id) ||
+        isProviderExecutedToolCall(part),
     )
   }
 
@@ -881,10 +885,140 @@ export class StreamProcessor {
     // them directly to UIMessage[] is unsafe and causes "Cannot read properties
     // of undefined (reading 'find')" when code later reads message.parts (e.g.
     // the onToolCallStateChange devtools handler).
-    this.messages = chunk.messages.map(aguiSnapshotMessageToUIMessage)
+    //
+    // The AG-UI `MESSAGES_SNAPSHOT` wire shape cannot reconstruct client-side
+    // tool-call metadata a server may omit: a `role: 'tool'` message only carries
+    // `toolCallId` + `content`, and an assistant message in the snapshot may
+    // drop `toolCalls` the client already observed via `TOOL_CALL_*` events.
+    // Without the matching `tool-call` part, later `addToolResult(toolCallId)`
+    // calls cannot locate the call and warn + no-op (see #859). To keep the
+    // UI representation consistent with the streaming fan-out and preserve the
+    // unreconstructable metadata, reconcile the normalized snapshot against
+    // the pre-snapshot state; see `reconcileSnapshotToolCalls`.
+    const prevMessages = this.messages
+    const normalized = chunk.messages.map(aguiSnapshotMessageToUIMessage)
+    this.messages = this.reconcileSnapshotToolCalls(normalized, prevMessages)
     this.emitMessagesChange()
   }
 
+  /**
+   * Reconcile a freshly normalized snapshot with the pre-snapshot message
+   * state so unreconstructable tool-call metadata is preserved.
+   *
+   * Post-pass (a): anchor `tool-result`-only assistant messages (the shape
+   * `aguiSnapshotMessageToUIMessage` emits for AG-UI `role: 'tool'` wire
+   * messages) into the message containing the matching `tool-call` part, or —
+   * when the snapshot supplies no such part — the nearest earlier anchorable
+   * assistant message, matching the in-stream fan-out shape
+   * `assistant: [text, tool-call, tool-result, ...]`. Detached messages with
+   * no earlier anchorable assistant are kept verbatim.
+   *
+   * Post-pass (b): when a `tool-result` part references a `toolCallId` whose
+   * `tool-call` part is absent from the snapshot, carry the `tool-call` part
+   * forward from the pre-snapshot state (state and output untouched) so a
+   * subsequent `addToolResult(toolCallId)` can still locate the call.
+   */
+  private reconcileSnapshotToolCalls(
+    snapshot: Array<UIMessage>,
+    prevMessages: Array<UIMessage>,
+  ): Array<UIMessage> {
+    // Index tool-call parts observed before the snapshot by id so we can
+    // restore metadata the snapshot cannot re-emit. Duplicate ids resolve
+    // last-write-wins: the same tool call can appear in multiple messages
+    // across reconnects, and the most recent part carries the freshest state.
+    const prevToolCalls = new Map<string, ToolCallPart>()
+    for (const msg of prevMessages) {
+      for (const part of msg.parts) {
+        if (part.type === 'tool-call') {
+          prevToolCalls.set(part.id, part)
+        }
+      }
+    }
+    // Index tool-call parts already present in the snapshot so (b) only fills
+    // genuine gaps rather than duplicating a tool-call the snapshot supplies.
+    const snapshotToolCallIds = new Set<string>()
+    for (const msg of snapshot) {
+      for (const part of msg.parts) {
+        if (part.type === 'tool-call') {
+          snapshotToolCallIds.add(part.id)
+        }
+      }
+    }
+
+    const reconciled: Array<UIMessage> = []
+    for (const msg of snapshot) {
+      const toolResultPart =
+        msg.role === 'assistant' && msg.parts.length === 1
+          ? msg.parts.find((p): p is ToolResultPart => p.type === 'tool-result')
+          : undefined
+
+      if (!toolResultPart) {
+        reconciled.push(msg)
+        continue
+      }
+
+      // Prefer the message that actually contains the matching tool-call
+      // part. AG-UI `reasoning`/`activity` messages also normalize to
+      // `role: 'assistant'`, so anchoring into the nearest assistant alone
+      // could separate a result from its call (and a later
+      // `addToolResult(toolCallId)` would then append a duplicate result
+      // next to the call).
+      const target =
+        reconciled.findLast((m) =>
+          m.parts.some(
+            (p) => p.type === 'tool-call' && p.id === toolResultPart.toolCallId,
+          ),
+        ) ??
+        reconciled.findLast(
+          (m) =>
+            m.role === 'assistant' &&
+            !(m.parts.length === 1 && m.parts[0]?.type === 'tool-result'),
+        )
+
+      if (!target) {
+        // No assistant to anchor into — keep the detached message intact.
+        if (!snapshotToolCallIds.has(toolResultPart.toolCallId)) {
+          console.warn(
+            `[StreamProcessor] MESSAGES_SNAPSHOT contains a tool-result for "${toolResultPart.toolCallId}" but no matching tool-call exists in the snapshot, and there is no assistant message to anchor into; addToolResult("${toolResultPart.toolCallId}") will not be able to locate this call`,
+          )
+        }
+        reconciled.push(msg)
+        continue
+      }
+
+      const parts = [...target.parts]
+      // (b) Fill in a missing tool-call part from the pre-snapshot state when
+      // the snapshot references its id via a tool-result but supplies no
+      // tool-call metadata of its own.
+      if (
+        !snapshotToolCallIds.has(toolResultPart.toolCallId) &&
+        !parts.some(
+          (p) => p.type === 'tool-call' && p.id === toolResultPart.toolCallId,
+        )
+      ) {
+        const prev = prevToolCalls.get(toolResultPart.toolCallId)
+        if (prev) {
+          // Insert the carried-over tool-call before its tool-result (pushed
+          // below) so call→result ordering matches the streaming fan-out.
+          parts.push({ ...prev })
+          snapshotToolCallIds.add(prev.id)
+        } else {
+          console.warn(
+            `[StreamProcessor] MESSAGES_SNAPSHOT contains a tool-result for "${toolResultPart.toolCallId}" but no matching tool-call exists in the snapshot or the pre-snapshot state; addToolResult("${toolResultPart.toolCallId}") will not be able to locate this call`,
+          )
+        }
+      }
+      parts.push(toolResultPart)
+      // Replace rather than push into `target.parts`: a snapshot message that
+      // arrived already carrying `parts` (TanStack server echoing UIMessages)
+      // shares its array with the incoming chunk, and mutating it in place
+      // would corrupt the caller's event object.
+      target.parts = parts
+    }
+
+    return reconciled
+  }
+
   /**
    * Handle TEXT_MESSAGE_CONTENT event.
    *
@@ -1781,8 +1915,12 @@ export class StreamProcessor {
    * downgrading a failed call back to 'input-complete'.
    */
   private isToolCallPartErrored(toolCallId: string): boolean {
+    // `initialMessages` may be ModelMessage-shaped (no `parts`) — e.g. the
+    // common pattern of seeding a processor with the same messages passed to
+    // `chat()`. Guard the access so iterating them never throws.
     return this.messages.some((msg) =>
-      msg.parts.some(
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- `parts` is typed as required, but seeded ModelMessage-shaped messages can lack it at runtime.
+      msg.parts?.some(
         (part) =>
           part.type === 'tool-call' &&
           part.id === toolCallId &&

package/src/activities/generateTranscription/index.ts

@@ -19,7 +19,11 @@ import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { GenerationMiddleware } from '../middleware'
 import type { TranscriptionAdapter } from './adapter'
-import type { StreamChunk, TranscriptionResult } from '../../types'
+import type {
+  StreamChunk,
+  TranscriptionResponseFormat,
+  TranscriptionResult,
+} from '../../types'
 
 // ===========================
 // Activity Kind
@@ -67,7 +71,7 @@ export interface TranscriptionActivityOptions<
   /** An optional prompt to guide the transcription */
   prompt?: string
   /** The format of the transcription output */
-  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
+  responseFormat?: TranscriptionResponseFormat
   /** Provider-specific options for transcription */
   modelOptions?: TranscriptionProviderOptions<TAdapter>
   /**

package/src/index.ts

@@ -121,6 +121,7 @@ export type {
   AbortInfo,
   ErrorInfo,
   SandboxFileEvent,
+  SandboxFileHookEvent,
   ChatSandboxHooks,
 } from './activities/chat/middleware/index'
 
@@ -256,6 +257,11 @@ export {
   normalizeToolResult,
 } from './utilities/tool-result'
 
+export {
+  getProviderExecutedMetadata,
+  isProviderExecutedToolCall,
+} from './utilities/provider-executed'
+
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
 export type { ExtendedModelDef, ModelCapabilities } from './extend-adapter'

package/src/types.ts

@@ -160,6 +160,26 @@ export interface ToolCall<TMetadata = unknown> {
   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
+}
+
 // ============================================================================
 // Multimodal Content Types
 // ============================================================================
@@ -362,7 +382,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
 }
 
@@ -1359,6 +1381,105 @@ export interface UIResourceEvent extends CustomEvent {
   }
 }
 
+// ── Sandbox events ──────────────────────────────────────────────────────────
+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 }
+}
+
+// ── Harness events ──────────────────────────────────────────────────────────
+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 }
+}
+
+// ── Code-mode events ────────────────────────────────────────────────────────
+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 })`.
  *
@@ -1908,6 +2029,13 @@ 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,
 > {
@@ -1920,7 +2048,7 @@ export interface TranscriptionOptions<
   /** 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/src/utilities/provider-executed.ts

@@ -0,0 +1,32 @@
+import type { ProviderExecutedToolMetadata } from '../types'
+
+/**
+ * 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 function getProviderExecutedMetadata(
+  toolCall: { metadata?: unknown } | null | undefined,
+): ProviderExecutedToolMetadata | null {
+  const metadata = toolCall?.metadata
+  if (
+    typeof metadata === 'object' &&
+    metadata !== null &&
+    (metadata as ProviderExecutedToolMetadata).providerExecuted === true
+  ) {
+    return metadata as ProviderExecutedToolMetadata
+  }
+  return 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 function isProviderExecutedToolCall(
+  toolCall: { metadata?: unknown } | null | undefined,
+): boolean {
+  return getProviderExecutedMetadata(toolCall) !== null
+}