@tanstack/ai 0.37.0 → 0.39.0

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

@@ -278,7 +278,35 @@ if (part.type === 'image') {
 }
 ```
 
-### 4. HTTP Stream Format (Alternative to SSE)
+### 4. Sending Audio Messages (Browser Recording)
+
+Use `useAudioRecorder` from `@tanstack/ai-react` (or `createAudioRecorder` in Svelte) to capture audio in the browser. The resolved `AudioRecording` includes a ready-to-use `part` that slots directly into `sendMessage`.
+
+```typescript
+import {
+  useAudioRecorder,
+  useChat,
+  fetchServerSentEvents,
+} from '@tanstack/ai-react'
+
+const { isRecording, isSupported, start, stop } = useAudioRecorder()
+const { sendMessage } = useChat({
+  connection: fetchServerSentEvents('/api/chat'),
+})
+
+async function toggle() {
+  if (!isRecording) {
+    await start()
+    return
+  }
+  const recording = await stop()
+  await sendMessage({ content: [recording.part] })
+}
+```
+
+`recording.part` is `{ type: 'audio', source: { type: 'data', value: base64, mimeType } }`. Returns the recorder's native format (`audio/webm` or `audio/mp4`) with no transcoding.
+
+### 5. HTTP Stream Format (Alternative to SSE)
 
 Use `toHttpResponse` + `fetchHttpStream` for newline-delimited JSON instead of SSE.
 
@@ -310,7 +338,7 @@ const { messages, sendMessage } = useChat({
 The only difference is swapping `toServerSentEventsResponse` / `fetchServerSentEvents`
 for `toHttpResponse` / `fetchHttpStream`. Everything else stays identical.
 
-### 5. MCP Tool Discovery via `chat({ mcp })`
+### 6. MCP Tool Discovery via `chat({ mcp })`
 
 Pass `mcp` to let `chat()` own discovery **and** lifecycle for one or more MCP
 clients. Useful when you want minimal boilerplate and don't need to reuse the

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

@@ -359,6 +359,19 @@ const { generate, result, isLoading } = useGenerateSpeech({
 Adapter: `openaiTranscription` (whisper-1, gpt-4o-transcribe,
 gpt-4o-mini-transcribe).
 
+> **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.
+>
+> ```typescript
+> const { isRecording, start, stop } = useAudioRecorder()
+> const { generate } = useTranscription({
+>   connection: fetchServerSentEvents('/api/transcribe'),
+> })
+> // ...
+> const recording = await stop()
+> const mimeType = recording.mimeType.split(';')[0] // strip ;codecs=...
+> await generate({ audio: `data:${mimeType};base64,${recording.base64}` })
+> ```
+
 ```typescript
 import { generateTranscription } from '@tanstack/ai'
 import { openaiTranscription } from '@tanstack/ai-openai'

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

@@ -75,7 +75,7 @@ import { updateCartUIDef } from '@/tools/definitions'
 export async function POST(request: Request) {
   const { messages } = await request.json()
   const stream = chat({
-    adapter: openaiText('gpt-4o'),
+    adapter: openaiText('gpt-5.5'),
     messages,
     tools: [getProducts, updateCartUIDef], // server tool + client definition
   })
@@ -158,7 +158,7 @@ const getUserData = getUserDataDef.server(async ({ userId }) => {
 
 // In your route handler:
 const stream = chat({
-  adapter: openaiText('gpt-4o'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   tools: [getUserData],
 })
@@ -188,7 +188,7 @@ Server -- pass definition only (no execute function):
 
 ```typescript
 const stream = chat({
-  adapter: openaiText('gpt-4o'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   tools: [showNotificationDef],
 })
@@ -405,6 +405,13 @@ The post-discovery payload always returns the full description and schema regard
 `@tanstack/ai-mcp` lets a server-side `chat()` call discover and invoke tools
 hosted on any MCP server (Streamable HTTP, SSE, or stdio).
 
+**MCP tools and UI resources:** When an MCP tool result carries a `ui://`
+resource URI (via `_meta.ui.resourceUri`), TanStack AI surfaces it as a
+`UIResourcePart` on the assistant `UIMessage` in the client message list.
+`UIResourcePart` is a presentational-only part — it never enters model input.
+See the `@tanstack/ai-mcp` skill for the full MCP Apps API
+(`createMcpAppCallHandler`, `createMcpAppBridge`, `MCPAppResource`).
+
 ### Basic usage — auto-discovery
 
 ```typescript

package/src/activities/chat/index.ts

@@ -27,6 +27,7 @@ import {
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import { convertMessagesToModelMessages, generateMessageId } from './messages'
 import { MiddlewareRunner } from './middleware/compose'
+import { provideSandboxRuntime } from './middleware/sandbox-runtime'
 import { CapabilityRegistry } from './middleware/capabilities'
 import { validateCapabilities } from './middleware/validate'
 import { MCPManager } from './mcp/manager'
@@ -67,6 +68,7 @@ import type {
   ChatMiddleware,
   ChatMiddlewareConfig,
   ChatMiddlewareContext,
+  SandboxFileEvent,
   StructuredOutputMiddlewareConfig,
 } from './middleware/types'
 import type { CheckCoverage } from './middleware/builder'
@@ -542,6 +544,7 @@ class TextEngine<
   // Middleware support
   private readonly middlewareRunner: MiddlewareRunner<TContext>
   private readonly middlewareCtx: ChatMiddlewareContext<TContext>
+  private readonly sandboxFileQueue: Array<StreamChunk> = []
   private readonly deferredPromises: Array<Promise<unknown>> = []
   private abortReason?: string
   private readonly middlewareAbortController?: AbortController
@@ -701,6 +704,21 @@ class TextEngine<
         capability[0](this.middlewareCtx, { optional: true }),
       provide: (capability, value) => capability[1](this.middlewareCtx, value),
     }
+
+    // Provide the internal SandboxRuntime capability so harness adapters and
+    // sandbox middleware can emit file events. The sink logs, fans the event
+    // out through the middleware `onFile*` hooks (fire-and-forget), and queues
+    // 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)
+        this.sandboxFileQueue.push(
+          this.createCustomEventChunk('sandbox.file', { ...event }),
+        )
+      },
+    })
   }
 
   /** Get the accumulated content after the chat loop completes */
@@ -1021,6 +1039,10 @@ class TextEngine<
       threadId: this.threadId,
       runId: this.runIdOverride,
       parentRunId: this.parentRunIdOverride,
+      // Expose provided capabilities (e.g. sandbox) to harness adapters.
+      capabilities: this.middlewareCtx,
+      // Client approval decisions, for harness interactive-approval resolution.
+      approvals: this.initialApprovals,
       ...(combinedSchema ? { outputSchema: combinedSchema } : {}),
     })) {
       if (this.isCancelled()) {
@@ -1105,10 +1127,16 @@ class TextEngine<
         await this.middlewareRunner.runOnUsage(this.middlewareCtx, chunk.usage)
       }
 
+      // Drain any sandbox.file events emitted while processing this chunk.
+      yield* this.drainSandboxFileQueue()
+
       if (this.earlyTermination) {
         break
       }
     }
+
+    // Drain any remaining sandbox.file events emitted after the stream ended.
+    yield* this.drainSandboxFileQueue()
   }
 
   private handleStreamChunk(chunk: StreamChunk): void {
@@ -2502,6 +2530,17 @@ class TextEngine<
     }
   }
 
+  /**
+   * Drain queued `sandbox.file` chunks (emitted via the SandboxRuntime sink)
+   * through the middleware pipeline and into the public stream.
+   */
+  private async *drainSandboxFileQueue(): AsyncGenerator<StreamChunk> {
+    while (this.sandboxFileQueue.length > 0) {
+      const chunk = this.sandboxFileQueue.shift()
+      if (chunk) yield* this.pipeThroughMiddleware(chunk)
+    }
+  }
+
   /**
    * Drain an executeToolCalls async generator, yielding any CustomEvent chunks
    * through the middleware pipeline and returning the final ExecuteToolCallsResult.

package/src/activities/chat/mcp/manager.ts

@@ -1,6 +1,33 @@
 import type { ServerTool } from '../tools/tool-definition'
 import type { ChatMCPOptions, MCPToolSource } from './types'
 
+/**
+ * Bind the source's `readResource` onto a ui-linked tool's `metadata.mcp` so it
+ * travels with the tool to the server-tool execution/emit site (`tool-calls.ts`).
+ *
+ * `discover()` is the single place in `@tanstack/ai` that has both a tool and
+ * its originating source, and `@tanstack/ai` must not import `@tanstack/ai-mcp`,
+ * so this is where the source handle is threaded onto the tool. Only tools that
+ * actually link a `ui://` resource (their discovery stamped
+ * `metadata.mcp.uiResourceUri`) and whose source can read resources get bound;
+ * everything else is left untouched.
+ *
+ * This mutates the discovered tool's `metadata.mcp` in place. That is safe
+ * because discovery returns fresh tool objects per `discover()` call: the bound
+ * `readResource` closes over `source`, whose connection stays live until the run
+ * drains. If discovery results were ever cached and reused across runs, this
+ * would bind a closure over an already-closed source — bind onto a copy then.
+ */
+function bindReadResource(tool: ServerTool, source: MCPToolSource): void {
+  if (!source.readResource) return
+  const meta = (
+    tool.metadata as { mcp?: { uiResourceUri?: string } } | undefined
+  )?.mcp
+  if (!meta?.uiResourceUri) return
+  ;(meta as { readResource?: MCPToolSource['readResource'] }).readResource =
+    source.readResource.bind(source)
+}
+
 export class MCPDuplicateToolNameError extends Error {
   constructor(public readonly toolName: string) {
     super(
@@ -57,7 +84,10 @@ export class MCPManager {
       for (const [source, result] of zipped) {
         if (result === undefined) continue
         if (result.status === 'fulfilled') {
-          tools.push(...result.value)
+          for (const t of result.value) {
+            bindReadResource(t, source)
+            tools.push(t)
+          }
         } else if (this.#onDiscoveryError) {
           // throw/reject inside handler ⇒ propagate (fail-fast); return ⇒ skip
           await this.#onDiscoveryError(result.reason, source)

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

@@ -1,5 +1,20 @@
 import type { ServerTool } from '../tools/tool-definition'
 
+/**
+ * The shape `readResource` resolves to — a structural subset of MCP's
+ * `ReadResourceResult`. Single source of truth shared by
+ * `MCPToolSource.readResource` (this file) and the tool-bound
+ * `McpToolAppMeta.readResource` (tool-calls.ts) so the two copies cannot drift.
+ */
+export interface McpResourceReadResult {
+  contents: Array<{
+    uri: string
+    mimeType?: string
+    text?: string
+    blob?: string
+  }>
+}
+
 /**
  * Minimal structural shape that `chat({ mcp })` needs from an MCP client.
  *
@@ -13,6 +28,14 @@ export interface MCPToolSource {
   // forwards what is declared here.
   tools: (options?: { lazy?: boolean }) => Promise<Array<ServerTool>>
   close: () => Promise<void>
+  /**
+   * Reads an MCP resource by URI. Used by the chat manager to eagerly fetch
+   * `ui://` resource widgets (MCP Apps) after a tool result resolves.
+   *
+   * Optional — sources that do not serve `ui://` resources need not implement
+   * this method. `ai-mcp`'s `MCPClient` satisfies this structurally.
+   */
+  readResource?: (uri: string) => Promise<McpResourceReadResult>
 }
 
 /**

package/src/activities/chat/messages.ts

@@ -322,6 +322,11 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         }
         break
 
+      case 'ui-resource':
+        // MCP Apps widget — rendered client-side only. It must never enter
+        // model input, so it is intentionally dropped from the model message.
+        break
+
       default:
         break
     }

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

@@ -11,6 +11,7 @@ import type {
   ErrorInfo,
   FinishInfo,
   IterationInfo,
+  SandboxFileEvent,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   ToolPhaseCompleteInfo,
@@ -344,6 +345,39 @@ export class MiddlewareRunner<TContext = unknown> {
     return chunks
   }
 
+  /**
+   * Dispatch a sandbox file event to every middleware's `sandbox` hooks, in
+   * array order: the catch-all `onFile` then the type-specific hook. Errors are
+   * logged and swallowed so one bad hook can't break the run.
+   */
+  async runSandboxFile(
+    ctx: ChatMiddlewareContext<TContext>,
+    event: SandboxFileEvent,
+  ): Promise<void> {
+    const typed = (
+      {
+        create: 'onFileCreate',
+        change: 'onFileChange',
+        delete: 'onFileDelete',
+      } as const
+    )[event.type]
+    for (const mw of this.middlewares) {
+      const hooks = mw.sandbox
+      if (!hooks) continue
+      for (const fn of [hooks.onFile, hooks[typed]]) {
+        if (!fn) continue
+        try {
+          await fn(ctx, event)
+        } catch (error) {
+          this.logger.sandbox(
+            `hook=${typed} middleware=${mw.name ?? 'unnamed'} threw`,
+            { middleware: mw.name ?? 'unnamed', error },
+          )
+        }
+      }
+    }
+  }
+
   /**
    * Run onBeforeToolCall through middleware in order.
    * Returns the first non-void decision, or undefined to continue normally.

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

@@ -13,6 +13,8 @@ export type {
   FinishInfo,
   AbortInfo,
   ErrorInfo,
+  SandboxFileEvent,
+  ChatSandboxHooks,
 } from './types'
 
 export { MiddlewareRunner } from './compose'

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

@@ -0,0 +1,21 @@
+/**
+ * Internal runtime seam the chat engine PROVIDES so the sandbox middleware can
+ * surface file events without a public ctx method. `emit` runs every
+ * middleware's `sandbox` hooks AND emits a CUSTOM `sandbox.file` chunk into the
+ * stream; `logger` lets the sandbox layer log under the `sandbox` debug
+ * category. Consumed (optionally) by `withSandbox` in `@tanstack/ai-sandbox`.
+ */
+import { createCapability } from './capabilities'
+import type { InternalLogger } from '../../../logger/internal-logger'
+import type { SandboxFileEvent } from './types'
+
+export interface SandboxRuntime {
+  emit: (event: SandboxFileEvent) => void
+  logger: InternalLogger
+}
+
+export const SandboxRuntimeCapability =
+  createCapability<SandboxRuntime>()('sandbox-runtime')
+
+export const [getSandboxRuntime, provideSandboxRuntime] =
+  SandboxRuntimeCapability

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

@@ -13,6 +13,37 @@ import type {
   CapabilityRegistry,
 } from './capabilities'
 
+/** A file change observed inside a sandbox during a chat run. */
+export interface SandboxFileEvent {
+  type: 'create' | 'change' | 'delete'
+  /** Absolute path inside the sandbox (under the workspace root). */
+  path: string
+  timestamp: number
+}
+
+/**
+ * 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.
+ */
+export interface ChatSandboxHooks<TContext = unknown> {
+  onFile?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+  onFileCreate?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+  onFileChange?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+  onFileDelete?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+}
+
 // ===========================
 // Middleware Context
 // ===========================
@@ -539,6 +570,12 @@ export interface ChatMiddleware<TContext = unknown> {
     ctx: ChatMiddlewareContext<TContext>,
     info: ErrorInfo,
   ) => void | Promise<void>
+
+  /**
+   * Sandbox file-event hooks. Fire when a sandbox provided by `withSandbox` is
+   * active during the run and a file is created/changed/deleted. Server-side.
+   */
+  sandbox?: ChatSandboxHooks<TContext>
 }
 
 /** A `ChatMiddleware` with a permissive context — for use as a constraint. */

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

@@ -56,6 +56,8 @@ import type {
   ToolCallPart,
   ToolResultPart,
   UIMessage,
+  UIResourceEvent,
+  UIResourcePart,
 } from '../../../types'
 
 /**
@@ -1624,6 +1626,46 @@ export class StreamProcessor {
       return
     }
 
+    // Handle MCP Apps ui-resource events — materialize a UIResourcePart on the
+    // active assistant message. Never falls through to onCustomEvent because
+    // ui-resource is a system event, not a user-defined custom event.
+    if (chunk.name === 'ui-resource' && chunk.value) {
+      const v: UIResourceEvent['value'] = chunk.value
+      // Resolve the target assistant message. When a toolCallId is present, the
+      // tool call's OWNER message is authoritative, so prefer it first; fall
+      // back to the active assistant id only if the tool call isn't mapped.
+      // This avoids misattaching the widget to a different active message in a
+      // multi-message session.
+      const resolvedMessageId =
+        this.toolCallToMessage.get(v.toolCallId) ?? messageId
+      if (resolvedMessageId) {
+        const part: UIResourcePart = {
+          type: 'ui-resource',
+          resource: v.resource,
+          toolCallId: v.toolCallId,
+          toolName: v.toolName,
+          ...(v.serverId !== undefined && { serverId: v.serverId }),
+          ...(v.meta !== undefined && { meta: v.meta }),
+        }
+        this.messages = this.messages.map((msg) =>
+          msg.id === resolvedMessageId
+            ? { ...msg, parts: [...msg.parts, part] }
+            : msg,
+        )
+        this.emitMessagesChange()
+      } else {
+        // No owner message and no active assistant id — the server read and
+        // streamed a widget that has nowhere to attach (e.g. a toolCallId never
+        // registered, or the event arrived after the run cleared its active
+        // ids). Drop fail-soft, but warn: a vanished widget is otherwise
+        // undebuggable from the client.
+        console.warn(
+          `[mcp-apps] dropped ui-resource: no target message for toolCallId "${v.toolCallId}" (toolName "${v.toolName}")`,
+        )
+      }
+      return
+    }
+
     // Forward non-system custom events to onCustomEvent callback
     if (this.events.onCustomEvent) {
       const toolCallId =

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

@@ -18,6 +18,7 @@ import type {
   AfterToolCallInfo,
   BeforeToolCallDecision,
 } from '../middleware/types'
+import type { McpResourceReadResult } from '../mcp/types'
 import type {
   ContextFromTool,
   DefinedContext,
@@ -33,6 +34,92 @@ function safeJsonParse(value: string): unknown {
   }
 }
 
+/**
+ * MCP Apps metadata attached to a server tool at discovery (see
+ * `@tanstack/ai-mcp` discovery + `MCPManager.discover()`).
+ *
+ * - `uiResourceUri` / `serverId` are stamped by ai-mcp at tool discovery.
+ * - `readResource` is bound by `MCPManager.discover()` (the one site that has
+ *   both the tool and its originating source) so the resource can be eagerly
+ *   read at the emit site. Under `chat()`-managed MCP lifecycle
+ *   (`connection:'close'`), the MCP source is not disposed until the run
+ *   drains, so `readResource` is still live at this emit point. Note: a caller
+ *   who closes the MCP source early (outside `chat()`'s managed lifecycle)
+ *   degrades fail-soft — `readResource` may reject, the widget is absent, but
+ *   the tool result still flows to the model.
+ *   `@tanstack/ai` never imports `@tanstack/ai-mcp`; this travels structurally
+ *   on the tool.
+ */
+interface McpToolAppMeta {
+  uiResourceUri?: string
+  serverId?: string
+  /** Server-native (unprefixed) MCP tool name — used as the renderer's toolName. */
+  serverToolName?: string
+  readResource?: (uri: string) => Promise<McpResourceReadResult>
+}
+
+function readMcpAppMeta(tool: AnyTool): McpToolAppMeta | undefined {
+  const meta = (tool.metadata as { mcp?: McpToolAppMeta } | undefined)?.mcp
+  return meta
+}
+
+/**
+ * Eagerly read a tool's linked `ui://` resource (MCP Apps) and emit a
+ * `ui-resource` CUSTOM event so the client can render the widget. The model
+ * still receives the normal text tool-result; the widget rides alongside and
+ * never enters model input.
+ *
+ * Fail-soft: any read error logs a warning and emits nothing — it never throws,
+ * so the normal tool-result still flows and a broken widget cannot break the run.
+ */
+async function emitUiResourceIfLinked<TContext>(
+  tool: AnyTool,
+  context: ToolExecutionContext<TContext>,
+): Promise<void> {
+  const mcp = readMcpAppMeta(tool)
+  const uiUri = mcp?.uiResourceUri
+  if (!uiUri || !mcp.readResource) return
+
+  // The try covers ONLY the fallible read — keep `emitCustomEvent` out of it so
+  // an exception from the emit path can't be mislabeled as a read failure.
+  let matched: McpResourceReadResult['contents'][number] | undefined
+  try {
+    const res = await mcp.readResource(uiUri)
+    // Emit ONLY the content whose uri matches the requested `uiUri`. A source
+    // can return unrelated contents; falling back to `contents[0]` would risk
+    // rendering a widget that doesn't correspond to the linked resource. This
+    // is a display widget — a mismatched resource is worse than none, so if no
+    // content matches we fail-soft (warn + return) rather than emit.
+    matched = res.contents.find((c) => c.uri === uiUri)
+  } catch (err) {
+    // fail-soft — the text tool-result already flows; a broken widget must
+    // not break the run.
+    console.warn(`[mcp-apps] failed to read ui resource ${uiUri}:`, err)
+    return
+  }
+  if (!matched) {
+    console.warn(
+      `[mcp-apps] ui resource ${uiUri} returned no content matching that uri; not emitting`,
+    )
+    return
+  }
+  // NOTE: `toolCallId` is intentionally NOT set here — it is stamped onto
+  // every emitted event by the `executeToolCalls` context wrapper, so the
+  // UIResourceEvent.value.toolCallId / UIResourcePart.toolCallId contract is
+  // still satisfied downstream.
+  context.emitCustomEvent('ui-resource', {
+    resource: {
+      uri: matched.uri,
+      mimeType: matched.mimeType ?? 'text/html',
+      text: matched.text,
+      blob: matched.blob,
+    },
+    serverId: mcp.serverId,
+    toolName: mcp.serverToolName ?? tool.name,
+    meta: undefined,
+  })
+}
+
 /**
  * Optional middleware hooks for tool execution.
  * When provided, these callbacks are invoked before/after each tool execution.
@@ -456,7 +543,7 @@ async function applyBeforeToolCallDecision(
  * Execute a server-side tool with event polling, output validation, and middleware hooks.
  * Yields CustomEvent chunks during execution and pushes the result to the results array.
  */
-async function* executeServerTool<TContext = unknown>(
+export async function* executeServerTool<TContext = unknown>(
   toolCall: ToolCall,
   tool: AnyTool,
   toolName: string,
@@ -475,7 +562,14 @@ async function* executeServerTool<TContext = unknown>(
     let result = yield* executeWithEventPolling(executionPromise, pendingEvents)
     const duration = Date.now() - startTime
 
-    // Flush remaining events
+    // MCP Apps: if this tool links a ui:// resource, eagerly read it and queue
+    // a `ui-resource` CUSTOM event. The MCP source stays live until the run
+    // drains (MCPManager's `connection:'close'` policy disposes on completion),
+    // so `readResource` is callable here. Fail-soft: a read error warns and
+    // emits nothing — the text result still flows.
+    await emitUiResourceIfLinked(tool, context)
+
+    // Flush remaining events (including any queued ui-resource event)
     let pendingEvent: CustomEvent | undefined
     while ((pendingEvent = pendingEvents.shift()) !== undefined) {
       yield pendingEvent

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/client.ts

@@ -114,6 +114,7 @@ export type {
   ToolCallPart,
   ToolResultPart,
   UIMessage,
+  UIResourcePart,
   VideoPart,
   InferSchemaType,
 } from './types'

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

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)