@tanstack/ai-client 0.34.0 → 0.36.0

package/src/chat-client.ts

@@ -1,14 +1,15 @@
 import {
   EventType,
   StreamProcessor,
+  cloneAndDeepFreezeJson,
   convertSchemaToJsonSchema,
   generateMessageId,
   isStandardSchema,
   mergeMetadata,
   normalizeToUIMessage,
-  parseWithStandardSchema,
   restoreInboundChunk,
   tanstackMetadata,
+  validateWithStandardSchema,
 } from '@tanstack/ai/client'
 import {
   ByokBlockedError,
@@ -88,6 +89,20 @@ interface InternalQueuedMessage extends QueuedMessage {
   body?: Record<string, any>
 }
 
+const STREAM_PROCESSING_BUDGET_MS = 8
+
+type SchedulerWithYield = {
+  yield?: () => Promise<void>
+}
+
+function yieldToHost(): Promise<void> {
+  const { scheduler } = globalThis as typeof globalThis & {
+    scheduler?: SchedulerWithYield
+  }
+  if (scheduler?.yield) return scheduler.yield()
+  return new Promise((resolve) => setTimeout(resolve, 0))
+}
+
 function assertUniqueInterruptDefinitions(
   interrupts:
     | ReadonlyArray<InterruptDefinition<any, any, any, any>>
@@ -330,6 +345,7 @@ const REJOIN_CONNECT_DEADLINE_MS = 2000
 const REJOIN_REBUILD_TRIGGERS = new Set<string>([
   'TEXT_MESSAGE_START',
   'TEXT_MESSAGE_CONTENT',
+  'REASONING_MESSAGE_CONTENT',
   'TOOL_CALL_START',
   'MESSAGES_SNAPSHOT',
   // Drop the hydrated card before this chunk creates it again. A subagent
@@ -337,6 +353,20 @@ const REJOIN_REBUILD_TRIGGERS = new Set<string>([
   'SUBAGENT_STARTED',
 ])
 
+function rebuildsAssistantMessage(chunk: StreamChunk): boolean {
+  if (chunk.type === 'REASONING_ENCRYPTED_VALUE') {
+    return (
+      chunk.subtype === 'message' &&
+      typeof chunk.encryptedValue === 'string' &&
+      chunk.encryptedValue.length > 0
+    )
+  }
+  if (chunk.type === 'STEP_FINISHED') {
+    return 'signature' in chunk && Boolean(chunk.signature)
+  }
+  return REJOIN_REBUILD_TRIGGERS.has(chunk.type)
+}
+
 type SubagentCard = Extract<UIMessage['parts'][number], { type: 'subagent' }>
 
 /** Every subagent card in the messages, nested cards included. */
@@ -506,6 +536,8 @@ export class ChatClient<
   private readonly activeRunIds = new Set<string>()
   /** Latched by `dispose()`; stops any late async callback starting new work. */
   private disposed = false
+  /** The error a failed mount hydration set, cleared by the next successful one. */
+  private hydrationError: Error | undefined
   /** Whether a view is currently watching. See `attach` / `detach`. */
   private tailing = false
   /** Constructor inputs `attach()` needs on every re-attach, not just the first. */
@@ -1124,7 +1156,10 @@ export class ChatClient<
       const generation = this.historyGeneration
       try {
         result = await hydrate(this.threadId, hydrateOptions)
-      } catch {
+      } catch (cause) {
+        // Same staleness guard as the success path below: a failure from an
+        // older attempt must not touch the state of a newer one.
+        if (generation === this.historyGeneration) this.failHydration(cause)
         return
       }
       if (generation !== this.historyGeneration) return
@@ -1140,13 +1175,25 @@ export class ChatClient<
       if (this.disposed || !this.tailing) return
       // A send may have started while the fetch was in flight — don't stomp it.
       if (this.isLoading || this.abortController) return
+      // A retry after a failed load succeeded: drop that failure, but not an
+      // error something else set since.
+      if (this.hydrationError && this.error === this.hydrationError) {
+        this.setError(undefined)
+        this.setStatus('ready')
+      }
+      this.hydrationError = undefined
       this.applyHydrationPage(result.page)
       if (result.messages.length > 0) {
         const windowMessages = normalizeMessagesDates(result.messages)
         this.processor.setMessages(windowMessages)
         this.rememberServerMessageIds(windowMessages)
       }
-      if (result.interrupts && result.interrupts.pending.length > 0) {
+      if (
+        result.interrupts &&
+        result.interrupts.pending.length > 0 &&
+        (!result.activeRun?.runId ||
+          result.activeRun.runId === result.interrupts.runId)
+      ) {
         // Pending interrupt = the thread is paused awaiting a human decision, so
         // there is nothing to tail (no chunks stream until it resolves). Restore
         // the approval/wait from the SERVER — identical to reconstructing it from
@@ -1156,7 +1203,9 @@ export class ChatClient<
         // on the server, so a racing hydrate reports both an `activeRun` cursor
         // AND the pending interrupt. Tailing that "active" run would drop the
         // approval card (and hang on a stream that never comes), so the interrupt
-        // always wins.
+        // wins over that same run. A DIFFERENT active run is the continuation
+        // that answered this interrupt: the server commits the answer only when
+        // that run finishes, so join it (see the `else` branch below).
         this.applyResumeSnapshot({
           resumeState: {
             threadId: this.threadId,
@@ -1170,6 +1219,36 @@ export class ChatClient<
     })()
   }
 
+  /**
+   * Surface a mount-hydration failure (`persistence: true`) on the observable
+   * fields, mirroring `GenerationClient.failHydration`, so "this thread failed
+   * to load" is distinguishable from "this thread has no messages" and the app
+   * can show an error / offer a retry. A genuine miss — the server having no
+   * record for a fresh thread — resolves normally and never reaches here; only a
+   * thrown transport / authorize-gate error does.
+   *
+   * Skipped when the view unmounted (`!tailing`) or a `sendMessage` took
+   * ownership while the hydrate GET was in flight, so a live run's state always
+   * wins over a stale mount-time failure — same guard as the success path above.
+   */
+  private failHydration(cause: unknown): void {
+    if (this.disposed || !this.tailing) return
+    if (this.isLoading || this.abortController) return
+    const error = cause instanceof Error ? cause : new Error(String(cause))
+    // Mirror the send path: a BYOK key that is missing / locked must still
+    // trigger the key-request flow on thread load, not just be reported.
+    if (error instanceof ByokMissingError) {
+      this.byok?.request(error.provider, 'missing')
+    }
+    if (error instanceof ByokBlockedError && error.reason === 'locked') {
+      this.byok?.request(error.provider, 'locked')
+    }
+    this.hydrationError = error
+    this.setStatus('error')
+    this.setError(error)
+    this.callbacksRef.current.onError(error)
+  }
+
   mountDevtools(): void {
     this.ensureThreadId()
     if (this.devtoolsMounted) {
@@ -1857,13 +1936,23 @@ export class ChatClient<
   }
 
   /**
-   * Consume chunks from the connection subscription.
+   * Consume chunks from the connection subscription. Chunks are processed in
+   * order; the loop yields to the host after each processing budget.
    */
   private async consumeSubscription(signal: AbortSignal): Promise<void> {
     const stream = this.connection.subscribe(signal)
+    let chunkProcessingTime = 0
     for await (const chunk of stream) {
       if (signal.aborted) break
-      await this.processIncomingChunk(chunk)
+      const startedAt = performance.now()
+      this.processIncomingChunk(chunk)
+      chunkProcessingTime += performance.now() - startedAt
+      if (chunkProcessingTime < STREAM_PROCESSING_BUDGET_MS) continue
+      chunkProcessingTime = 0
+      // Skip the yield when the page is hidden. Browsers clamp timers there,
+      // and that wait paces stream pull.
+      if (typeof document !== 'undefined' && document.hidden) continue
+      await yieldToHost()
     }
   }
 
@@ -1886,7 +1975,7 @@ export class ChatClient<
    * give up after {@link REJOIN_CONNECT_DEADLINE_MS} if no chunk arrives and
    * clear the dead pointer so it does not retry on the next load.
    *
-   * Replay chunks are processed WITHOUT the per-chunk yield the live path uses,
+   * Replay chunks are processed WITHOUT the time-slice yield the live path uses,
    * so the buffered prefix snaps in and only the genuinely-live tail streams at
    * network speed — a reload looks like the run continued, not like it re-typed.
    */
@@ -1923,11 +2012,11 @@ export class ChatClient<
             attached = true
             clearTimeout(connectTimer)
           }
-          if (!rebuilt && REJOIN_REBUILD_TRIGGERS.has(chunk.type)) {
+          if (!rebuilt && rebuildsAssistantMessage(chunk)) {
             rebuilt = true
             this.dropTrailingInFlightAssistant()
           }
-          await this.processIncomingChunk(chunk, { defer: false })
+          this.processIncomingChunk(chunk)
         }
         // Same contract as `streamResponse`: client tools may finish (and
         // queue a resume) while `isLoading` is still true. Wait for them
@@ -1996,10 +2085,7 @@ export class ChatClient<
     }
   }
 
-  private async processIncomingChunk(
-    chunk: StreamChunk,
-    options?: { defer?: boolean },
-  ): Promise<void> {
+  private processIncomingChunk(chunk: StreamChunk): void {
     chunk = restoreInboundChunk(chunk)
     if (
       chunk.type === 'RUN_ERROR' &&
@@ -2042,15 +2128,6 @@ export class ChatClient<
     this.syncSubagentHandles()
     this.updateRunLifecycle(chunk)
     this.observeInterruptState(chunk)
-    // Live path: yield a macrotask so the UI can paint. Skip when the page is
-    // hidden. Browsers clamp setTimeout there, and that wait paces stream pull.
-    // Replay passes defer: false so a backlog applies in one batch.
-    if (
-      options?.defer !== false &&
-      (typeof document === 'undefined' || !document.hidden)
-    ) {
-      await new Promise((resolve) => setTimeout(resolve, 0))
-    }
     this.resolveJoinedRun(chunk)
   }
 
@@ -2813,12 +2890,22 @@ export class ChatClient<
     continuationGeneration: number,
     context?: ChatClientRunEventContext,
   ): Promise<void> {
-    if (clientTool && result.state !== 'output-error') {
+    if (result.state !== 'output-error') {
       try {
-        result = {
-          ...result,
-          output: this.validateClientToolOutput(clientTool, result.output),
+        let output =
+          clientTool?.outputSchema && isStandardSchema(clientTool.outputSchema)
+            ? await this.validateClientToolOutput(clientTool, result.output)
+            : result.output
+        // Only an interrupt resume needs JSON output. The legacy continuation
+        // keeps the raw value.
+        if (
+          this.interruptManager
+            .getDescriptors()
+            .some((interrupt) => interrupt.toolCallId === result.toolCallId)
+        ) {
+          output = cloneAndDeepFreezeJson(output)
         }
+        result = { ...result, output }
       } catch (error: any) {
         result = {
           ...result,
@@ -2850,12 +2937,16 @@ export class ChatClient<
     )
     this.devtoolsBridge.emitSnapshot()
 
-    const resolvedViaInterrupt = this.interruptManager.resolveClientToolOutput(
-      result.toolCallId,
+    const resolvedViaInterrupt =
       result.state === 'output-error'
-        ? { error: result.errorText || 'Tool execution failed' }
-        : result.output,
-    )
+        ? this.interruptManager.resolveClientToolError(
+            result.toolCallId,
+            result.errorText || 'Tool execution failed',
+          )
+        : this.interruptManager.resolveClientToolOutput(
+            result.toolCallId,
+            result.output,
+          )
     if (resolvedViaInterrupt) {
       // Interrupt manager stages/submits the resume batch (deferred until the
       // parent stream settles when still loading). Skip legacy continuation.
@@ -2875,15 +2966,20 @@ export class ChatClient<
     await this.checkForContinuation()
   }
 
-  private validateClientToolOutput(
+  private async validateClientToolOutput(
     clientTool: AnyClientTool,
-    output: any,
-  ): any {
-    if (clientTool.outputSchema && isStandardSchema(clientTool.outputSchema)) {
-      return parseWithStandardSchema(clientTool.outputSchema, output)
+    output: unknown,
+  ): Promise<unknown> {
+    const validation = await validateWithStandardSchema<unknown>(
+      clientTool.outputSchema,
+      output,
+    )
+    if (!validation.success) {
+      throw new Error(
+        validation.issues.map((issue) => issue.message).join(', '),
+      )
     }
-
-    return output
+    return validation.data
   }
 
   /**

package/src/index.ts

@@ -14,9 +14,16 @@ export type {
 } from './interrupt-manager'
 export { createMcpAppBridge } from './mcp-app-bridge'
 export type { McpAppBridge, CreateMcpAppBridgeOptions } from './mcp-app-bridge'
-export { registerWebMCPTools } from './web-mcp-tools'
+export {
+  getWebMCPTools,
+  registerWebMCPTools,
+  subscribeWebMCPTools,
+} from './web-mcp-tools'
 export type {
+  GetWebMCPToolsOptions,
   RegisterWebMCPToolsOptions,
+  SubscribeWebMCPToolsOptions,
+  WebMCPPageTool,
   WebMCPToolAnnotations,
   WebMCPToolOptions,
   WebMCPToolOptionsByName,

package/src/interrupt-manager.ts

@@ -11,6 +11,7 @@ import {
   isStandardSchema,
   normalizeApprovalSchema,
   readInterruptBinding,
+  withTanstackMetadata,
   wrapGenericInterruptContinuation,
 } from '@tanstack/ai/client'
 import type {
@@ -124,11 +125,13 @@ function resolutionWithContinuation(
   const continuation = genericInterruptContinuationFromDescriptor(
     item.descriptor,
   )
-  if (!continuation) return resolution
-  return {
-    ...resolution,
-    metadata: wrapGenericInterruptContinuation(continuation),
+  if (continuation) {
+    return {
+      ...resolution,
+      metadata: wrapGenericInterruptContinuation(continuation),
+    }
   }
+  return resolution
 }
 
 function isRootResolvableInterrupt<
@@ -684,6 +687,25 @@ export class InterruptManager<
   }
 
   resolveClientToolOutput(toolCallId: string, output: unknown): boolean {
+    return this.resolveClientToolResult(toolCallId, {
+      state: 'output-available',
+      output,
+    })
+  }
+
+  resolveClientToolError(toolCallId: string, errorText: string): boolean {
+    return this.resolveClientToolResult(toolCallId, {
+      state: 'output-error',
+      errorText,
+    })
+  }
+
+  private resolveClientToolResult(
+    toolCallId: string,
+    result:
+      | { state: 'output-available'; output: unknown }
+      | { state: 'output-error'; errorText: string },
+  ): boolean {
     const item = this.items.find(
       (candidate) =>
         (candidate.kind === 'client-tool-execution' &&
@@ -695,10 +717,56 @@ export class InterruptManager<
           isLegacyClientToolMetadata(candidate.descriptor.metadata)),
     )
     if (!item) return false
-    this.resolveItem(item.descriptor.id, output)
+    if (item.kind !== 'client-tool-execution') {
+      this.resolveItem(
+        item.descriptor.id,
+        result.state === 'output-error'
+          ? { error: result.errorText }
+          : result.output,
+      )
+      return true
+    }
+    if (result.state === 'output-available') {
+      this.resolveItem(item.descriptor.id, result.output)
+      return true
+    }
+    this.stageClientToolError(item, result.errorText)
     return true
   }
 
+  private stageClientToolError(
+    item: RuntimeInterrupt,
+    errorText: string,
+  ): void {
+    this.assertItemMutable()
+    this.invalidateRetry()
+    if (!item.canResolve) {
+      item.status = 'error'
+      item.error = this.itemError(
+        item.descriptor.id,
+        'invalid-response-schema',
+        'The interrupt response schema is invalid and cannot be resolved.',
+      )
+      this.publish()
+      return
+    }
+    item.validationGeneration++
+    item.resolution = cloneAndDeepFreezeJson(
+      withTanstackMetadata(
+        resolutionWithContinuation(item, {
+          interruptId: item.descriptor.id,
+          status: 'resolved',
+          payload: { error: errorText },
+        }),
+        { state: 'output-error' },
+      ),
+    )
+    item.status = 'staged'
+    item.error = undefined
+    this.publish()
+    this.maybeSubmit()
+  }
+
   resolveToolApprovalDecision(interruptId: string, approved: boolean): boolean {
     const item = this.items.find(
       (candidate) =>
@@ -1279,11 +1347,28 @@ export class InterruptManager<
         : preserveInput(validation)
     }
     if (item.kind === 'client-tool-execution') {
-      return validateWithSchema(
+      const validation = validateWithSchema(
         item.tool?.outputSchema,
         payload,
         'invalid-tool-output',
       )
+      const canonicalize = (result: ValidationResult): ValidationResult => {
+        if (!('valid' in result)) return result
+        try {
+          return {
+            valid: true,
+            payload: cloneAndDeepFreezeJson(result.payload),
+          }
+        } catch (error) {
+          return {
+            code: 'invalid-tool-output',
+            message: error instanceof Error ? error.message : String(error),
+          }
+        }
+      }
+      return isPromiseLike(validation)
+        ? Promise.resolve(validation).then(canonicalize)
+        : canonicalize(validation)
     }
     return this.validateApprovalCandidate(item, payload)
   }

package/src/types.ts

@@ -24,6 +24,7 @@ import type {
   StructuredOutputPart,
   SubagentHandleData,
   SubagentStatus,
+  ToolResultOutcome,
   UIResourcePart,
   VideoPart,
 } from '@tanstack/ai/client'
@@ -618,6 +619,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

package/src/web-mcp-tools.ts

@@ -209,3 +209,184 @@ export async function registerWebMCPTools<
     throw error
   }
 }
+
+/** A tool that a page registered with WebMCP, as `getTools()` returns it. */
+export interface WebMCPPageTool {
+  name: string
+  title?: string
+  description: string
+  /** A JSON Schema object for the tool input. */
+  inputSchema?: object
+  /** The origin of the document that registered the tool. */
+  origin: string
+  annotations?: WebMCPToolAnnotations
+}
+
+interface WebMCPToolReader {
+  getTools: () => Promise<Array<WebMCPPageTool>>
+  executeTool: (
+    tool: WebMCPPageTool,
+    input: unknown,
+    options: { signal?: AbortSignal },
+  ) => Promise<string>
+  addEventListener: EventTarget['addEventListener']
+  removeEventListener: EventTarget['removeEventListener']
+}
+
+/** Options for {@link getWebMCPTools}. */
+export interface GetWebMCPToolsOptions {
+  /** Return `false` to skip a tool. */
+  filter?: (tool: WebMCPPageTool) => boolean
+}
+
+/** Options for {@link subscribeWebMCPTools}. */
+export interface SubscribeWebMCPToolsOptions extends GetWebMCPToolsOptions {
+  /** Stops the subscription when it aborts. */
+  signal: AbortSignal
+  /** Receives a failure from the WebMCP `getTools()` call. */
+  onError?: (error: unknown) => void
+}
+
+function isWebMCPToolReader(value: unknown): value is WebMCPToolReader {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'getTools' in value &&
+    typeof value.getTools === 'function' &&
+    'executeTool' in value &&
+    typeof value.executeTool === 'function' &&
+    'addEventListener' in value &&
+    typeof value.addEventListener === 'function' &&
+    'removeEventListener' in value &&
+    typeof value.removeEventListener === 'function'
+  )
+}
+
+function getWebMCPToolReader() {
+  if (
+    typeof document === 'undefined' ||
+    (typeof isSecureContext !== 'undefined' && !isSecureContext) ||
+    !('modelContext' in document) ||
+    !isWebMCPToolReader(document.modelContext)
+  ) {
+    return undefined
+  }
+  return document.modelContext
+}
+
+function parseToolResult(result: string): unknown {
+  try {
+    return JSON.parse(result)
+  } catch {
+    return result
+  }
+}
+
+async function readWebMCPTools(
+  reader: WebMCPToolReader,
+  options: GetWebMCPToolsOptions | undefined,
+): Promise<Array<AnyClientTool>> {
+  const pageTools = await reader.getTools()
+  const names = new Set<string>()
+  return pageTools
+    .filter((tool) => options?.filter?.(tool) ?? true)
+    .map((tool) => {
+      if (names.has(tool.name)) {
+        throw new Error(
+          `Duplicate WebMCP tool name "${tool.name}". Use a filter or register tools with unique names.`,
+        )
+      }
+      names.add(tool.name)
+      return {
+        __toolSide: 'client' as const,
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema ?? { type: 'object' },
+        async execute(input: unknown, context?: { abortSignal?: AbortSignal }) {
+          const result = await reader.executeTool(
+            tool,
+            input,
+            context?.abortSignal ? { signal: context.abortSignal } : {},
+          )
+          return parseToolResult(result)
+        },
+      }
+    })
+}
+
+/**
+ * Reads the WebMCP tools on the page and returns them as client tools.
+ *
+ * Pass the result to a chat as `tools`. Each tool runs through the WebMCP
+ * `executeTool()` call. Unsupported browsers and server environments return
+ * an empty array.
+ *
+ * @param options - A filter that skips tools.
+ *
+ * @example
+ * ```ts
+ * const tools = await getWebMCPTools({
+ *   filter: (tool) => tool.origin === location.origin,
+ * })
+ * ```
+ */
+export async function getWebMCPTools(
+  options?: GetWebMCPToolsOptions,
+): Promise<Array<AnyClientTool>> {
+  const reader = getWebMCPToolReader()
+  return reader ? readWebMCPTools(reader, options) : []
+}
+
+/**
+ * Calls `listener` with the page WebMCP tools now and after each
+ * `toolchange` event, until `options.signal` aborts.
+ *
+ * Unsupported browsers and server environments call `listener` once with an
+ * empty array. When a read fails, `options.onError` gets the error and the
+ * listener keeps the last list.
+ *
+ * @param listener - Receives the current client tools.
+ * @param options - The subscription signal, a filter, and an error callback.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController()
+ * subscribeWebMCPTools((tools) => client.updateOptions({ tools }), {
+ *   signal: controller.signal,
+ * })
+ * ```
+ */
+export function subscribeWebMCPTools(
+  listener: (tools: Array<AnyClientTool>) => void,
+  options: SubscribeWebMCPToolsOptions,
+): void {
+  if (options.signal.aborted) return
+  const reader = getWebMCPToolReader()
+  if (!reader) {
+    listener([])
+    return
+  }
+
+  let latestRead = 0
+  const refresh = () => {
+    const read = ++latestRead
+    const isCurrent = () => read === latestRead && !options.signal.aborted
+    readWebMCPTools(reader, options).then(
+      (tools) => {
+        if (isCurrent()) listener(tools)
+      },
+      (error: unknown) => {
+        if (isCurrent()) options.onError?.(error)
+      },
+    )
+  }
+
+  // Remove the listener by hand: Zone.js breaks the `signal` listener option.
+  reader.addEventListener('toolchange', refresh)
+  options.signal.addEventListener(
+    'abort',
+    () => reader.removeEventListener('toolchange', refresh),
+    { once: true },
+  )
+  refresh()
+}