@tanstack/ai 0.59.0 → 0.63.0

package/src/types.ts

@@ -100,6 +100,9 @@ export type ToolResultState =
   | 'complete' // Result is complete
   | 'error' // Error occurred
 
+/** Why a tool result ended without executing successfully. */
+export type ToolResultOutcome = 'cancelled' | 'denied'
+
 export type ToolOutputState = 'output-available' | 'output-error'
 
 /**
@@ -196,6 +199,13 @@ export interface ToolCall<TMetadata = unknown> extends Omit<
   metadata?: TMetadata
 }
 
+/** One source link from a provider-executed web search. */
+export interface ProviderExecutedToolSource {
+  url: string
+  title?: string
+  pageAge?: string
+}
+
 /**
  * Convention for tool-call `metadata` that marks a call as **provider-executed**
  * — run by the provider's own infrastructure (e.g. Anthropic `web_search` /
@@ -209,10 +219,12 @@ export interface ToolCall<TMetadata = unknown> extends Omit<
  *
  * 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.
+ * preserves those per-adapter fields. `sources` is the normalized list of
+ * links a web search used, shared across providers.
  */
 export interface ProviderExecutedToolMetadata {
   providerExecuted?: boolean
+  sources?: Array<ProviderExecutedToolSource>
   [key: string]: unknown
 }
 
@@ -239,8 +251,24 @@ export interface ContentPartUrlSource extends AGUIUrlSource {}
 /**
  * A provider-issued file handle (Files API). AG-UI `FileSource`: the handle
  * is opaque, do not fetch or parse it.
+ *
+ * The media is uploaded once via a `files` adapter (`openaiFiles()`,
+ * `anthropicFiles()`, `geminiFiles()`, `grokFiles()`, `falFiles()`) and
+ * referenced here by the returned handle instead of re-sending base64 or a
+ * public URL on each request. Only the provider that minted a handle can
+ * resolve it. Adapters that cannot consume file handles at all are rejected
+ * by the activity-layer preflight before mapping starts.
  */
-export interface ContentPartFileSource extends AGUIFileSource {}
+export interface ContentPartFileSource<
+  TProvider extends string = string,
+> extends AGUIFileSource {
+  /**
+   * The adapter name of the provider that issued the handle (`'openai'`,
+   * `'gemini'`, ...), the same id TanStack reports as the usage provider.
+   * When present, an adapter rejects a handle another provider issued.
+   */
+  provider?: TProvider
+}
 
 /**
  * Where a media part's bytes come from: inline data, a URL, or a provider
@@ -426,6 +454,8 @@ export interface ToolResultPart {
   toolCallId: string
   content: string | Array<ContentPart>
   state: ToolResultState
+  /** Set when the user or middleware cancelled or denied the tool call; state remains `error`. */
+  outcome?: ToolResultOutcome
   error?: string // Error message if state is "error"
   metadata?: Record<string, unknown>
   createdAt?: Date
@@ -544,6 +574,12 @@ export interface TanStackMessageMetadata {
   model?: string
   /** Parent chat run that produced this assistant message. */
   runId?: string
+  /**
+   * The chat run that produced this assistant message. `withPersistence` sets
+   * `id`. `reconstructChat` with `includeRuns: true` adds the finished run's
+   * timings, in epoch ms.
+   */
+  run?: { id: string; startedAt?: number; finishedAt?: number }
   /** Card data on a child wire message. See `uiMessagesToWire`. */
   subagent?: SubagentWireInfo
   /** Thinking signature for a `role: 'reasoning'` fan-out message. */
@@ -555,6 +591,8 @@ export interface TanStackMessageMetadata {
     createdAt?: string
     content?: Array<ContentPart>
   }
+  /** Outcome of a cancelled or denied tool result; when present, the UI state is `error`. */
+  toolResultOutcome?: ToolResultOutcome
   structuredOutput?: {
     status?: 'streaming' | 'complete' | 'error'
     partial?: unknown
@@ -663,6 +701,15 @@ export interface EmitCustomEventOptions {
   batch?: boolean
 }
 
+/**
+ * The user's answer to an `mcp_input` interrupt.
+ * `resolved` carries the `payload` from `resolveInterrupt`.
+ * `cancelled` means the user called `cancel()`.
+ */
+export type ToolInputResponse =
+  | { status: 'resolved'; payload: unknown }
+  | { status: 'cancelled' }
+
 /**
  * Context passed to tool execute functions, providing capabilities like
  * emitting custom events during execution.
@@ -677,6 +724,12 @@ export type ToolExecutionContext<TContext = unknown> =
      * e.g. MCP `callTool` — should forward this to cancel in-flight work.
      */
     abortSignal?: AbortSignal
+    /**
+     * The answer to the input request that this tool call raised in the
+     * previous run. It is set only when the run resumes an `mcp_input`
+     * interrupt for this tool call.
+     */
+    inputResponse?: ToolInputResponse
     /**
      * Emit a custom event during tool execution.
      * Events are streamed to the client in real-time as AG-UI CUSTOM events.
@@ -2305,7 +2358,7 @@ export interface VideoUrlResult {
 // ============================================================================
 
 /**
- * Options for world generation (live, prompt-steerable sessions).
+ * Options for world generation (live session or finished job).
  *
  * @experimental World generation is an experimental feature and may change.
  */
@@ -2317,8 +2370,10 @@ export interface WorldGenerationOptions<
   /** Natural-language description of the world or scene */
   prompt: string
   /**
-   * Provider mint options. Reactor resolution/seed/audio are browser
-   * `sendCommand` fields, not token-mint fields.
+   * Provider-specific options. Live adapters (Reactor) use mint fields here.
+   * Job adapters (World Labs) use image/video inputs, `wait`, and poll.
+   * Reactor resolution/seed/audio are browser `sendCommand` fields, not
+   * token-mint fields.
    */
   modelOptions?: TProviderOptions
   /**
@@ -2335,28 +2390,73 @@ export interface WorldGenerationOptions<
   abortSignal?: AbortSignal
 }
 
+/**
+ * Assets from a finished world job. Live session adapters omit this.
+ * URLs are often signed CDN links. They can expire and may need a proxy
+ * to fetch from a browser.
+ *
+ * @experimental World generation is an experimental feature and may change.
+ */
+export interface WorldGenerationAssets {
+  /** Auto-generated scene description */
+  caption?: string
+  /** Preview image URL */
+  thumbnailUrl?: string
+  splats?: {
+    /** Quality-key map of splat URLs (`100k`, `500k`, `full_res`, …) */
+    spzUrls?: Record<string, string>
+    metricScaleFactor?: number
+    groundPlaneOffset?: number
+  }
+  mesh?: {
+    colliderMeshUrl?: string
+    hqMeshUrl?: string
+    fullResMeshUrl?: string
+  }
+  imagery?: {
+    panoUrl?: string
+  }
+}
+
 /**
  * Result of world generation. JSON-serializable so a server route can return
- * it to a browser. The browser uses `token` + `model` to open the live
- * session (set the prompt, start streaming, steer mid-run).
+ * it to a browser.
+ *
+ * Live adapters (Reactor): `status: 'ready'` with `token` and token
+ * `expiresAt`. The browser uses `token` + `model` to open the session.
+ *
+ * Job adapters (World Labs): `status: 'ready'` with viewer `url` and
+ * `worldId`, or `status: 'waiting'` with `operationId` and no `url`.
+ * `expiresAt` on a job is operation expiry, not a session token.
  *
  * @experimental World generation is an experimental feature and may change.
  */
 export interface WorldGenerationResult {
   /** Unique identifier for this generation */
   id: string
-  /** Model used for generation (provider connect slug) */
+  /** Model used for generation (provider connect slug or model id) */
   model: string
-  /** Short-lived session token for the client connection */
-  token: string
-  /** Token expiry as milliseconds since epoch */
-  expiresAt: number
-  /** Prompt the client should send when it starts the session */
+  /** Short-lived session token for a live client connection */
+  token?: string
+  /**
+   * Expiry as milliseconds since epoch. Live adapters: session token.
+   * Job adapters: operation expiry when the provider sends it.
+   */
+  expiresAt?: number
+  /** Prompt used to generate the world, or the prompt the client should send */
   prompt: string
-  /** Session status after the server half finishes */
+  /** Status after the server half finishes */
   status: 'ready' | 'waiting'
   /** Provider session id, when the adapter created one */
   sessionId?: string
+  /** Viewer URL for a finished world job (not an asset download URL) */
+  url?: string
+  /** Provider world id for a finished or in-progress job */
+  worldId?: string
+  /** Provider operation id for a long-running world job */
+  operationId?: string
+  /** Assets when a world job has finished and the provider returned them */
+  assets?: WorldGenerationAssets
   /** Token usage / billing, when the adapter can report it */
   usage?: TokenUsage
 }

package/src/utilities/ag-ui-wire.ts

@@ -14,11 +14,13 @@ import type {
   StructuredOutputPart,
   SubagentPart,
   TanStackMessageMetadata,
+  ToolResultOutcome,
   UIMessage,
   UIResourcePart,
 } from '../types'
 import type { MetadataRecord } from './merge-metadata'
 import { tanstackMetadata } from './merge-metadata'
+import { isProviderExecutedToolCall } from './provider-executed'
 import { normalizeToolResult } from './tool-result'
 import { wireSubagentInfo, wireSubagentRunId } from './subagent-wire'
 import type { SubagentWireInfo } from './subagent-wire'
@@ -48,6 +50,7 @@ function rebuiltToolMetadata(
   id: string | undefined,
   content: string | null | Array<ContentPart>,
   anchorOwnsUiResources = false,
+  outcome?: ToolResultOutcome,
 ): MetadataRecord | undefined {
   const source: MetadataRecord = isRecord(metadata) ? metadata : {}
   const tanstack = isRecord(source.tanstack) ? { ...source.tanstack } : {}
@@ -60,7 +63,11 @@ function rebuiltToolMetadata(
   }
   const result = {
     ...source,
-    tanstack: { ...tanstack, toolResult },
+    tanstack: {
+      ...tanstack,
+      ...(outcome !== undefined && { toolResultOutcome: outcome }),
+      toolResult,
+    },
   }
   return Object.keys(result).length ? result : undefined
 }
@@ -171,9 +178,45 @@ export function uiMessagesToWire(
       continue
     }
 
-    // assistant: emit reasoning fan-outs first, then anchor, then tool fan-outs
+    // assistant: reasoning fan-outs, then anchor, then tool fan-outs.
+    //
+    // Provider-executed tools (Anthropic web_search / web_fetch) run inside one
+    // provider response, and the provider signs every thinking block against
+    // the blocks before it. Emitting all reasoning first and a single anchor
+    // with the joined text and every tool call turns
+    // "thinking, tool, thinking, text, tool" into
+    // "thinking, thinking, text, tool, tool", and the provider rejects the next
+    // turn ("thinking blocks in the latest assistant message cannot be
+    // modified"). Split the message into ordered segments at each thinking
+    // part that follows a provider-executed tool call, the same rule
+    // buildAssistantMessages applies, so the wire keeps the signed order.
+    // Segments after the first get derived anchor ids; strict AG-UI consumers
+    // still see plain anchors.
+    type Segment = {
+      thinking: Array<Extract<MessagePart, { type: 'thinking' }>>
+      parts: Array<MessagePart>
+    }
+    let current: Segment = { thinking: [], parts: [] }
+    const segments: Array<Segment> = [current]
     for (const part of parts) {
       if (part.type === 'thinking') {
+        if (
+          current.parts.some(
+            (p) => p.type === 'tool-call' && isProviderExecutedToolCall(p),
+          )
+        ) {
+          current = { thinking: [part], parts: [] }
+          segments.push(current)
+        } else {
+          current.thinking.push(part)
+        }
+      } else {
+        current.parts.push(part)
+      }
+    }
+
+    segments.forEach((segment, index) => {
+      for (const part of segment.thinking) {
         const reasoning: WireReasoningMessage = {
           role: 'reasoning',
           id: uniqueWireId(deriveReasoningId(uiMessage.id, part), usedWireIds),
@@ -184,22 +227,29 @@ export function uiMessagesToWire(
         }
         wire.push(reasoning)
       }
-    }
 
-    const text = collectText(parts)
-    const toolCalls = collectToolCalls(parts)
-    wire.push(
-      toAnchor(
-        uiMessage,
-        'assistant',
-        {
-          ...(text !== '' && { content: text }),
-          ...(toolCalls && { toolCalls }),
-        },
-        parts,
-        includeSnapshotStructuredOutput,
-      ),
-    )
+      const text = collectText(segment.parts)
+      const toolCalls = collectToolCalls(segment.parts)
+      const anchorMessage: UIMessage =
+        index === 0
+          ? uiMessage
+          : {
+              ...uiMessage,
+              id: uniqueWireId(`${uiMessage.id}-segment-${index}`, usedWireIds),
+            }
+      wire.push(
+        toAnchor(
+          anchorMessage,
+          'assistant',
+          {
+            ...(text !== '' && { content: text }),
+            ...(toolCalls && { toolCalls }),
+          },
+          segment.parts,
+          includeSnapshotStructuredOutput,
+        ),
+      )
+    })
 
     const explicitToolResults = new Set(
       parts.flatMap((part) =>
@@ -218,6 +268,7 @@ export function uiMessagesToWire(
           part.id,
           part.content,
           true,
+          part.outcome,
         )
         wire.push({
           role: 'tool',
@@ -262,6 +313,8 @@ export function uiMessagesToWire(
             undefined,
             undefined,
             result,
+            false,
+            part.approval?.approved === false ? 'denied' : undefined,
           ),
         })
       }
@@ -341,6 +394,8 @@ function messageMetadata(
     tanstack.model = previousTanstack.model
   if (previousTanstack?.runId !== undefined)
     tanstack.runId = previousTanstack.runId
+  if (previousTanstack?.run?.id !== undefined)
+    tanstack.run = { id: previousTanstack.run.id }
   if (previousTanstack?.signature !== undefined)
     tanstack.signature = previousTanstack.signature
   const createdAt = coerceCreatedAt(msg.createdAt)

package/src/utilities/content-source.ts

@@ -0,0 +1,138 @@
+import type { ContentPartFileSource, ContentPartSource } from '../types'
+
+/**
+ * Narrow a {@link ContentPartSource} to the provider-file-reference arm.
+ *
+ * Issuer adapters use this to route a file source to their native wire field;
+ * everyone else is protected by the core preflight (see
+ * {@link assertMessagesFileSourceSupport}) plus a defensive throw at their own
+ * mapping site.
+ */
+export function isFileSource(
+  source: ContentPartSource,
+): source is ContentPartFileSource {
+  return source.type === 'file'
+}
+
+/**
+ * Resolve the handle `providerName` should send for a file source.
+ *
+ * A file source carries one opaque handle (`value`) and, optionally, the
+ * provider that issued it. An adapter always knows which provider it talks
+ * to, so a source that names no provider is taken as-is.
+ *
+ * @throws when the source names a different issuing provider. A handle only
+ * resolves at the provider that minted it.
+ */
+export function fileReferenceFor(
+  source: ContentPartFileSource,
+  providerName: string,
+): string {
+  if (source.provider !== undefined && source.provider !== providerName) {
+    throw new Error(
+      `${providerName}: file source was issued by ${source.provider}. ` +
+        `A provider file handle only works with the provider that issued ` +
+        `it. Upload the file with ${providerName}Files(), or pass a data or ` +
+        `url source instead.`,
+    )
+  }
+  return source.value
+}
+
+/**
+ * Build the standard error a non-issuer adapter throws when it encounters a
+ * `{ type: 'file' }` source it can't consume — either because the provider has
+ * no file-reference input surface, or because the endpoint requires raw bytes
+ * (image edits, Veo) rather than a reference.
+ *
+ * @param detail Optional context appended to the message (e.g. a modality or
+ * endpoint name, or a pointer to the adapter that does support references).
+ * When provided it replaces the generic remediation tail, so a site-specific
+ * hint ("pass inline bytes") is never contradicted by generic advice.
+ */
+export function unsupportedFileSourceError(
+  providerName: string,
+  detail?: string,
+): Error {
+  return new Error(
+    `${providerName} does not support provider file-handle sources ` +
+      `({ type: 'file' })` +
+      (detail
+        ? ` ${detail}.`
+        : `. Pass a data or url source, or upload via the provider's files ` +
+          `adapter where supported.`),
+  )
+}
+
+/**
+ * The slice of an adapter the file-source preflight reads. Adapters that can
+ * consume `{ type: 'file' }` sources declare `supportsFileSources: true`;
+ * everything else — including adapters written before this arm existed —
+ * fails closed at the activity layer instead of falling through to a
+ * URL/data branch and silently mis-mapping the reference.
+ */
+export interface FileSourceCapable {
+  name: string
+  supportsFileSources?: boolean
+}
+
+/** True when a content-part-like value carries a `{ type: 'file' }` source. */
+function partHasFileSource(part: unknown): boolean {
+  if (typeof part !== 'object' || part === null) return false
+  const source = (part as { source?: unknown }).source
+  return (
+    typeof source === 'object' &&
+    source !== null &&
+    (source as { type?: unknown }).type === 'file'
+  )
+}
+
+/**
+ * True when `value` is a content part with a file source, or an array
+ * (possibly nested — fused embedding items) that contains one.
+ */
+function inputHasFileSource(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(inputHasFileSource)
+  return partHasFileSource(value)
+}
+
+/**
+ * Fail-closed preflight for media prompts and embedding inputs
+ * (`generateImage` / `generateVideo` / `embed`): throws when the input
+ * carries a `{ type: 'file' }` source and the adapter hasn't declared
+ * `supportsFileSources`. Runs in the activity dispatcher — the same layer
+ * that validates modality — so an adapter that predates the file arm can
+ * never receive one. Walks a single part, an array of parts, and nested
+ * arrays (fused embedding items).
+ */
+export function assertPromptFileSourceSupport(
+  adapter: FileSourceCapable,
+  prompt: unknown,
+): void {
+  if (adapter.supportsFileSources === true) return
+  if (inputHasFileSource(prompt)) {
+    throw unsupportedFileSourceError(adapter.name)
+  }
+}
+
+/**
+ * Fail-closed preflight for chat messages: throws when any message content
+ * part carries a `{ type: 'file' }` source and the adapter hasn't declared
+ * `supportsFileSources`. See {@link assertPromptFileSourceSupport}.
+ */
+export function assertMessagesFileSourceSupport(
+  adapter: FileSourceCapable,
+  messages: ReadonlyArray<unknown>,
+): void {
+  if (adapter.supportsFileSources === true) return
+  for (const message of messages) {
+    if (typeof message !== 'object' || message === null) continue
+    const content = (message as { content?: unknown }).content
+    if (!Array.isArray(content)) continue
+    for (const part of content) {
+      if (partHasFileSource(part)) {
+        throw unsupportedFileSourceError(adapter.name)
+      }
+    }
+  }
+}

package/src/utilities/provider-executed.ts

@@ -30,3 +30,16 @@ export function isProviderExecutedToolCall(
 ): boolean {
   return getProviderExecutedMetadata(toolCall) !== null
 }
+
+/**
+ * True when `id` is a `${parentId}-segment-${n}` message. The wire and the
+ * run loop split one provider turn into segments at thinking that follows a
+ * provider-executed tool call, to keep signed thinking order. Readers fold a
+ * segment back into its parent so the UI still shows one message.
+ */
+export function isAssistantSegmentOf(
+  id: string | undefined,
+  parentId: string,
+): boolean {
+  return id?.startsWith(`${parentId}-segment-`) === true
+}

package/src/utilities/tool-result.ts

@@ -1,4 +1,4 @@
-import type { ContentPart } from '../types'
+import type { ContentPart, ToolResultOutcome } from '../types'
 
 const CONTENT_PART_TYPES = new Set([
   'text',
@@ -8,10 +8,17 @@ const CONTENT_PART_TYPES = new Set([
   'document',
 ])
 
+export function isToolResultOutcome(
+  value: unknown,
+): value is ToolResultOutcome {
+  return value === 'cancelled' || value === 'denied'
+}
+
 /**
  * Structural check for a single `ContentPart`. A text part must carry a string
- * `content`; every other modality must carry a `source` with `type` of
- * `'url' | 'data'` and a string `value`.
+ * `content`. Every other part carries a source with a string `value`; a file
+ * source's `value` is a non-empty opaque handle, and its optional `provider`
+ * is a string.
  */
 export function isContentPart(value: unknown): value is ContentPart {
   if (typeof value !== 'object' || value === null) return false
@@ -26,6 +33,14 @@ export function isContentPart(value: unknown): value is ContentPart {
   if (typeof source !== 'object' || source === null) return false
   const src = source as Record<string, unknown>
   if (typeof src.value !== 'string') return false
+  // `file` sources carry an opaque handle in `value`; `provider`, when set,
+  // names the issuer.
+  if (src.type === 'file') {
+    return (
+      src.value.length > 0 &&
+      (src.provider === undefined || typeof src.provider === 'string')
+    )
+  }
   // `data` sources require a mimeType (matches ContentPartDataSource); `url`
   // sources don't. Requiring it here keeps the runtime guard consistent with
   // the type and avoids emitting `data:undefined;base64,...` downstream.
@@ -45,6 +60,33 @@ export function isContentPartArray(
   return Array.isArray(value) && value.length > 0 && value.every(isContentPart)
 }
 
+/**
+ * Error text for a failed tool result: `output.error` when it is a string,
+ * else the output itself when it is a string, else a generic message.
+ * `StreamProcessor` and `chat()` history share it, so a reload shows the
+ * same text as the live stream.
+ */
+export function toolResultErrorText(output: unknown): string {
+  if (
+    output &&
+    typeof output === 'object' &&
+    'error' in output &&
+    typeof output.error === 'string'
+  ) {
+    return output.error
+  }
+  return typeof output === 'string' ? output : 'Tool execution failed'
+}
+
+/** Parse tool result content as JSON. Plain text stays a string. */
+export function parseToolOutput(content: string): unknown {
+  try {
+    return JSON.parse(content)
+  } catch {
+    return content
+  }
+}
+
 /**
  * Normalize a tool's return value for transport:
  * - string            → unchanged