@tanstack/ai 0.38.0 → 0.39.1

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/adapter-internals.ts

@@ -10,3 +10,9 @@ export {
   toRunErrorPayload,
   toRunErrorRawEvent,
 } from './activities/error-payload'
+export {
+  getSandboxRuntime,
+  provideSandboxRuntime,
+  SandboxRuntimeCapability,
+} from './activities/chat/middleware/sandbox-runtime'
+export type { SandboxRuntime } from './activities/chat/middleware/sandbox-runtime'

package/src/index.ts

@@ -120,6 +120,8 @@ export type {
   FinishInfo,
   AbortInfo,
   ErrorInfo,
+  SandboxFileEvent,
+  ChatSandboxHooks,
 } from './activities/chat/middleware/index'
 
 // Base, activity-agnostic middleware. The observe-only superset that media
@@ -149,6 +151,8 @@ export type {
   CapabilityContext,
   CapabilityGetter,
   CapabilityProvider,
+  DefinedChatMiddleware,
+  AnyChatMiddleware,
 } from './activities/chat/middleware/index'
 
 // All types
@@ -252,6 +256,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/logger/internal-logger.ts

@@ -31,6 +31,7 @@ const CATEGORY_EMOJI: Record<keyof ResolvedCategories, string> = {
   agentLoop: '🔁',
   config: '⚙️',
   errors: '❌',
+  sandbox: '📦',
 }
 
 export class InternalLogger {
@@ -82,6 +83,11 @@ export class InternalLogger {
     this.emit('debug', 'tools', message, meta)
   }
 
+  /** Log sandbox internals (watcher, file events, hook dispatch). Chat-only. */
+  sandbox(message: string, meta?: Record<string, unknown>): void {
+    this.emit('debug', 'sandbox', message, meta)
+  }
+
   /** Log an agent-loop iteration marker or phase transition. Chat-only. */
   agentLoop(message: string, meta?: Record<string, unknown>): void {
     this.emit('debug', 'agentLoop', message, meta)

package/src/logger/resolve.ts

@@ -12,6 +12,7 @@ const ALL_OFF: ResolvedCategories = {
   config: false,
   errors: false,
   request: false,
+  sandbox: false,
 }
 
 const ALL_ON: ResolvedCategories = {
@@ -23,6 +24,7 @@ const ALL_ON: ResolvedCategories = {
   config: true,
   errors: true,
   request: true,
+  sandbox: true,
 }
 
 const errorsOnlyCategories = (): ResolvedCategories => ({
@@ -41,6 +43,7 @@ const resolveCategoriesFromPartial = (
   config: partial.config ?? true,
   errors: partial.errors ?? true,
   request: partial.request ?? true,
+  sandbox: partial.sandbox ?? true,
 })
 
 /**

package/src/logger/types.ts

@@ -60,6 +60,11 @@ export interface DebugCategories {
    * Outgoing call metadata (provider, model, message/tool counts) emitted before each adapter SDK call.
    */
   request?: boolean
+  /**
+   * Sandbox internals: watcher start/stop + mechanism, file events, sandbox
+   * hook dispatch, ensure/bootstrap and lifecycle transitions. Chat-only.
+   */
+  sandbox?: boolean
 }
 
 /**

package/src/types.ts

@@ -4,6 +4,7 @@ import type {
 } from '@standard-schema/spec'
 import type { InternalLogger } from './logger/internal-logger'
 import type { SystemPrompt } from './system-prompts'
+import type { CapabilityContext } from './activities/chat/middleware/capabilities'
 // The canonical usage types live in the leaf `@tanstack/ai-event-client`
 // package (which `@tanstack/ai` already depends on) so there is a single source
 // of truth without a dependency cycle. They are re-exported below.
@@ -159,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
 // ============================================================================
@@ -361,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
 }
 
@@ -946,6 +969,25 @@ export interface TextOptions<
    * Surfaced for observability/middleware; not consumed by the LLM call.
    */
   parentRunId?: string
+
+  /**
+   * Middleware capability context for this run. The engine populates it with
+   * the live middleware context so harness adapters that declare
+   * `requires: [SomeCapability]` can read provided capabilities from inside
+   * `chatStream` — e.g. `getSandbox(options.capabilities)`. Capabilities are
+   * provisioned by middleware `setup` before the adapter runs. Undefined for
+   * direct adapter usage outside the chat engine.
+   */
+  capabilities?: CapabilityContext
+
+  /**
+   * Client approval decisions for this run, keyed by approval id. The engine
+   * populates this from approvals carried on the incoming messages. Harness
+   * adapters consult it to resolve `ask`-policy permission requests (the agent
+   * pauses on a risky action; the client re-runs with a decision recorded
+   * here). Undefined for direct adapter usage outside the chat engine.
+   */
+  approvals?: ReadonlyMap<string, boolean>
 }
 
 // ============================================================================

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
+}