@tanstack/ai 0.36.0 → 0.38.0

package/dist/esm/utilities/tool-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.js","sources":["../../../src/utilities/tool-result.ts"],"sourcesContent":["import type { ContentPart } from '../types'\n\nconst CONTENT_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n])\n\n/**\n * Structural check for a single `ContentPart`. A text part must carry a string\n * `content`; every other modality must carry a `source` with `type` of\n * `'url' | 'data'` and a string `value`.\n */\nexport function isContentPart(value: unknown): value is ContentPart {\n  if (typeof value !== 'object' || value === null) return false\n  const part = value as Record<string, unknown>\n  if (typeof part.type !== 'string' || !CONTENT_PART_TYPES.has(part.type)) {\n    return false\n  }\n  if (part.type === 'text') {\n    return typeof part.content === 'string'\n  }\n  const source = part.source\n  if (typeof source !== 'object' || source === null) return false\n  const src = source as Record<string, unknown>\n  if (typeof src.value !== 'string') return false\n  // `data` sources require a mimeType (matches ContentPartDataSource); `url`\n  // sources don't. Requiring it here keeps the runtime guard consistent with\n  // the type and avoids emitting `data:undefined;base64,...` downstream.\n  if (src.type === 'data') return typeof src.mimeType === 'string'\n  return src.type === 'url'\n}\n\n/**\n * True iff `value` is a NON-EMPTY array whose every element is a valid\n * `ContentPart`. Empty arrays and mixed arrays return false so they continue\n * to be treated as ordinary (stringified) data — this keeps the auto-detection\n * footgun narrow.\n */\nexport function isContentPartArray(\n  value: unknown,\n): value is Array<ContentPart> {\n  return Array.isArray(value) && value.length > 0 && value.every(isContentPart)\n}\n\n/**\n * Normalize a tool's return value for transport:\n * - string            → unchanged\n * - ContentPart array → unchanged (multimodal, passed through to the adapter)\n * - anything else     → `JSON.stringify`\n */\nexport function normalizeToolResult(\n  result: unknown,\n): string | Array<ContentPart> {\n  if (typeof result === 'string') return result\n  if (isContentPartArray(result)) return result\n  return JSON.stringify(result)\n}\n"],"names":[],"mappings":"AAEA,MAAM,yCAAyB,IAAI;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAOM,SAAS,cAAc,OAAsC;AAClE,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAO;AACb,MAAI,OAAO,KAAK,SAAS,YAAY,CAAC,mBAAmB,IAAI,KAAK,IAAI,GAAG;AACvE,WAAO;AAAA,EACT;AACA,MAAI,KAAK,SAAS,QAAQ;AACxB,WAAO,OAAO,KAAK,YAAY;AAAA,EACjC;AACA,QAAM,SAAS,KAAK;AACpB,MAAI,OAAO,WAAW,YAAY,WAAW,KAAM,QAAO;AAC1D,QAAM,MAAM;AACZ,MAAI,OAAO,IAAI,UAAU,SAAU,QAAO;AAI1C,MAAI,IAAI,SAAS,OAAQ,QAAO,OAAO,IAAI,aAAa;AACxD,SAAO,IAAI,SAAS;AACtB;AAQO,SAAS,mBACd,OAC6B;AAC7B,SAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,SAAS,KAAK,MAAM,MAAM,aAAa;AAC9E;AAQO,SAAS,oBACd,QAC6B;AAC7B,MAAI,OAAO,WAAW,SAAU,QAAO;AACvC,MAAI,mBAAmB,MAAM,EAAG,QAAO;AACvC,SAAO,KAAK,UAAU,MAAM;AAC9B;"}

package/dist/esm/utilities/usage.d.ts

@@ -0,0 +1,31 @@
+import { ProviderUsageDetails, TokenUsage } from '../types.js';
+/**
+ * Input parameters for building base TokenUsage.
+ * Provider functions should extract these from their SDK's response.
+ */
+export interface BaseUsageInput {
+    /** Total input/prompt tokens */
+    promptTokens: number;
+    /** Total output/completion tokens */
+    completionTokens: number;
+    /** Total tokens (prompt + completion) */
+    totalTokens: number;
+}
+/**
+ * Builds the base TokenUsage object with core fields.
+ * Provider-specific functions should use this and then add their own details.
+ *
+ * @param input - The base token counts
+ * @returns A TokenUsage object with promptTokens, completionTokens, totalTokens
+ *
+ * @example
+ * ```typescript
+ * const base = buildBaseUsage({
+ *   promptTokens: 100,
+ *   completionTokens: 50,
+ *   totalTokens: 150
+ * });
+ * // Returns: { promptTokens: 100, completionTokens: 50, totalTokens: 150 }
+ * ```
+ */
+export declare function buildBaseUsage<TProviderDetails = ProviderUsageDetails>(input: BaseUsageInput): TokenUsage<TProviderDetails>;

package/dist/esm/utilities/usage.js

@@ -0,0 +1,11 @@
+function buildBaseUsage(input) {
+  return {
+    promptTokens: input.promptTokens,
+    completionTokens: input.completionTokens,
+    totalTokens: input.totalTokens
+  };
+}
+export {
+  buildBaseUsage
+};
+//# sourceMappingURL=usage.js.map

package/dist/esm/utilities/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sources":["../../../src/utilities/usage.ts"],"sourcesContent":["import type { ProviderUsageDetails, TokenUsage } from '../types'\n\n/**\n * Input parameters for building base TokenUsage.\n * Provider functions should extract these from their SDK's response.\n */\nexport interface BaseUsageInput {\n  /** Total input/prompt tokens */\n  promptTokens: number\n  /** Total output/completion tokens */\n  completionTokens: number\n  /** Total tokens (prompt + completion) */\n  totalTokens: number\n}\n\n/**\n * Builds the base TokenUsage object with core fields.\n * Provider-specific functions should use this and then add their own details.\n *\n * @param input - The base token counts\n * @returns A TokenUsage object with promptTokens, completionTokens, totalTokens\n *\n * @example\n * ```typescript\n * const base = buildBaseUsage({\n *   promptTokens: 100,\n *   completionTokens: 50,\n *   totalTokens: 150\n * });\n * // Returns: { promptTokens: 100, completionTokens: 50, totalTokens: 150 }\n * ```\n */\nexport function buildBaseUsage<TProviderDetails = ProviderUsageDetails>(\n  input: BaseUsageInput,\n): TokenUsage<TProviderDetails> {\n  return {\n    promptTokens: input.promptTokens,\n    completionTokens: input.completionTokens,\n    totalTokens: input.totalTokens,\n  }\n}\n"],"names":[],"mappings":"AAgCO,SAAS,eACd,OAC8B;AAC9B,SAAO;AAAA,IACL,cAAc,MAAM;AAAA,IACpB,kBAAkB,MAAM;AAAA,IACxB,aAAa,MAAM;AAAA,EAAA;AAEvB;"}

package/dist/esm/utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Detect image mime type from base64 data using magic bytes.
+ * Returns undefined if the format cannot be detected.
+ *
+ * This function analyzes the first few bytes of base64-encoded image data
+ * to determine the image format based on file signature (magic bytes).
+ *
+ * @param base64Data - The base64-encoded image data
+ * @returns The detected mime type, or undefined if unrecognized
+ *
+ * @example
+ * ```ts
+ * const mimeType = detectImageMimeType(imageBase64)
+ * // Returns 'image/jpeg', 'image/png', 'image/gif', 'image/webp', or undefined
+ * ```
+ */
+export declare function detectImageMimeType(base64Data: string): 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp' | undefined;

package/dist/esm/utils.js

@@ -0,0 +1,20 @@
+function detectImageMimeType(base64Data) {
+  const prefix = base64Data.substring(0, 20);
+  if (prefix.startsWith("/9j/")) {
+    return "image/jpeg";
+  }
+  if (prefix.startsWith("iVBORw0KGgo")) {
+    return "image/png";
+  }
+  if (prefix.startsWith("R0lGOD")) {
+    return "image/gif";
+  }
+  if (prefix.startsWith("UklGR")) {
+    return "image/webp";
+  }
+  return void 0;
+}
+export {
+  detectImageMimeType
+};
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["/**\n * Detect image mime type from base64 data using magic bytes.\n * Returns undefined if the format cannot be detected.\n *\n * This function analyzes the first few bytes of base64-encoded image data\n * to determine the image format based on file signature (magic bytes).\n *\n * @param base64Data - The base64-encoded image data\n * @returns The detected mime type, or undefined if unrecognized\n *\n * @example\n * ```ts\n * const mimeType = detectImageMimeType(imageBase64)\n * // Returns 'image/jpeg', 'image/png', 'image/gif', 'image/webp', or undefined\n * ```\n */\nexport function detectImageMimeType(\n  base64Data: string,\n): 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp' | undefined {\n  // Get first few bytes (base64 encoded)\n  const prefix = base64Data.substring(0, 20)\n\n  // JPEG: starts with /9j/ (FFD8FF in base64)\n  if (prefix.startsWith('/9j/')) {\n    return 'image/jpeg'\n  }\n  // PNG: starts with iVBORw0KGgo (89504E47 in base64)\n  if (prefix.startsWith('iVBORw0KGgo')) {\n    return 'image/png'\n  }\n  // GIF: starts with R0lGOD (474946 in base64)\n  if (prefix.startsWith('R0lGOD')) {\n    return 'image/gif'\n  }\n  // WebP: starts with UklGR (52494646 in base64, followed by WEBP)\n  if (prefix.startsWith('UklGR')) {\n    return 'image/webp'\n  }\n\n  return undefined\n}\n"],"names":[],"mappings":"AAgBO,SAAS,oBACd,YACqE;AAErE,QAAM,SAAS,WAAW,UAAU,GAAG,EAAE;AAGzC,MAAI,OAAO,WAAW,MAAM,GAAG;AAC7B,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,WAAW,aAAa,GAAG;AACpC,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,WAAW,QAAQ,GAAG;AAC/B,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,WAAW,OAAO,GAAG;AAC9B,WAAO;AAAA,EACT;AAEA,SAAO;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -76,8 +76,8 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.6.7",
-    "@tanstack/ai-utils": "0.3.0"
+    "@tanstack/ai-event-client": "0.6.8",
+    "@tanstack/ai-utils": "0.3.1"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.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/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/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/client.ts

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

package/src/types.ts

@@ -416,6 +416,23 @@ export interface StructuredOutputPart<TData = unknown> {
   errorMessage?: string
 }
 
+export interface UIResourcePart {
+  type: 'ui-resource'
+  /** The ui:// resource object in MCP-native shape — fed straight to the renderer. */
+  resource: { uri: string; mimeType: string; text?: string; blob?: string }
+  /** Pool prefix / config key — routes interactive calls to the right MCP server. */
+  serverId?: string
+  /** Links the widget to the originating tool call — correlates it with the
+   *  sibling ToolCallPart/ToolResultPart in the same message. */
+  toolCallId: string
+  /** Server-native (unprefixed) MCP tool name whose UI this resource renders.
+   *  Required by the renderer (`@mcp-ui/client`'s `AppRenderer` `toolName` prop). */
+  toolName: string
+  /** Reserved for future passthrough of the resource/tool `_meta.ui` (e.g. frame-size hints).
+   *  Currently always `undefined` — nothing populates this field yet. */
+  meta?: Record<string, unknown>
+}
+
 export type MessagePart<TData = unknown> =
   | TextPart
   | ImagePart
@@ -426,6 +443,7 @@ export type MessagePart<TData = unknown> =
   | ToolResultPart
   | ThinkingPart
   | StructuredOutputPart<TData>
+  | UIResourcePart
 
 /**
  * UIMessage - Domain-specific message format optimized for building chat UIs
@@ -1308,6 +1326,19 @@ export interface ToolInputAvailableEvent extends CustomEvent {
   }
 }
 
+/** Emitted when an MCP tool returns a ui:// resource (MCP Apps). Reconciled into
+ *  a UIResourcePart on the assistant UIMessage. Never enters model input. */
+export interface UIResourceEvent extends CustomEvent {
+  name: 'ui-resource'
+  value: {
+    resource: UIResourcePart['resource']
+    serverId?: string
+    toolCallId: string
+    toolName: string
+    meta?: Record<string, unknown>
+  }
+}
+
 /**
  * Public type for streams returned by `chat({ outputSchema, stream: true })`.
  *