fix(ai-client): preserve client tool errors through interrupt resume

.changeset/fix-client-tool-error-resume.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai': patch
+'@tanstack/ai-client': patch
+'@tanstack/ai-persistence': patch
+---
+
+Preserve failed client tool results across native interrupt resumes and await asynchronous client output validation

docs/tools/client-tools.md

@@ -58,7 +58,8 @@ sequenceDiagram
 4. **Client Execution**: The browser finds the registered `.client()`
    implementation by tool name and runs it with the parsed input
 5. **Result Return**: Client auto-submits the result via the resume batch
-6. **Server Update**: Result is validated and added to the conversation
+6. **Server Update**: Successful output is validated. Execution and output
+   validation failures are added as failed tool results.
 7. **LLM Continuation**: LLM receives the result and continues the conversation
 
 Native client-tool execution shares the atomic interrupt **batch** lifecycle

packages/ai-client/src/chat-client.ts

@@ -1,13 +1,14 @@
 import {
   StreamProcessor,
+  cloneAndDeepFreezeJson,
   convertSchemaToJsonSchema,
   generateMessageId,
   isStandardSchema,
   mergeMetadata,
   normalizeToUIMessage,
-  parseWithStandardSchema,
   restoreInboundChunk,
   tanstackMetadata,
+  validateWithStandardSchema,
 } from '@tanstack/ai/client'
 import {
   ByokBlockedError,
@@ -2609,11 +2610,15 @@ 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),
+          output:
+            clientTool?.outputSchema &&
+            isStandardSchema(clientTool.outputSchema)
+              ? await this.validateClientToolOutput(clientTool, result.output)
+              : cloneAndDeepFreezeJson(result.output),
         }
       } catch (error: any) {
         result = {
@@ -2646,12 +2651,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.
@@ -2671,15 +2680,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 cloneAndDeepFreezeJson(validation.data)
   }
 
   /**

packages/ai-client/src/interrupt-manager.ts

@@ -124,11 +124,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 +686,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,7 +716,14 @@ export class InterruptManager<
           isLegacyClientToolMetadata(candidate.descriptor.metadata)),
     )
     if (!item) return false
-    this.resolveItem(item.descriptor.id, output)
+    this.resolveItem(
+      item.descriptor.id,
+      item.kind === 'client-tool-execution'
+        ? result
+        : result.state === 'output-error'
+          ? { error: result.errorText }
+          : result.output,
+    )
     return true
   }
 
@@ -721,7 +749,9 @@ export class InterruptManager<
     const interrupt = cloneAndDeepFreezeJson(descriptor)
     const candidate = getDescriptorBinding(interrupt)
     const legacyResumable =
-      candidate === undefined && isLegacyInterruptMetadata(interrupt)
+      candidate === undefined &&
+      !hasReservedFirstPartyBindingMarker(interrupt) &&
+      isLegacyInterruptMetadata(interrupt)
 
     // No binding we understand, and nothing else identifying the descriptor as
     // ours, means this interrupt was not produced by this package's resume
@@ -866,6 +896,20 @@ export class InterruptManager<
           validationGeneration: 0,
         }
       }
+      return {
+        descriptor: interrupt,
+        binding: genericBinding(interrupt, hydration, candidate),
+        kind: 'generic',
+        status: 'error',
+        canResolve: false,
+        resumable: false,
+        error: this.itemError(
+          interrupt.id,
+          'stale',
+          'The client tool interrupt no longer matches the registered tool.',
+        ),
+        validationGeneration: 0,
+      }
     }
 
     if (
@@ -1279,11 +1323,60 @@ export class InterruptManager<
         : preserveInput(validation)
     }
     if (item.kind === 'client-tool-execution') {
-      return validateWithSchema(
+      if (!isUnknownObject(payload)) {
+        return {
+          code: 'invalid-tool-output',
+          message: 'Client tool results require a result state.',
+        }
+      }
+      if (
+        payload['state'] === 'output-error' &&
+        typeof payload['errorText'] === 'string' &&
+        Object.keys(payload).length === 2
+      ) {
+        return {
+          valid: true,
+          payload: cloneAndDeepFreezeJson({
+            state: 'output-error',
+            errorText: payload['errorText'],
+          }),
+        }
+      }
+      if (
+        payload['state'] !== 'output-available' ||
+        !Object.hasOwn(payload, 'output') ||
+        Object.keys(payload).length !== 2
+      ) {
+        return {
+          code: 'invalid-tool-output',
+          message: 'Client tool results require output or errorText.',
+        }
+      }
+      const validation = validateWithSchema(
         item.tool?.outputSchema,
-        payload,
+        payload['output'],
         'invalid-tool-output',
       )
+      const canonicalize = (result: ValidationResult): ValidationResult => {
+        if (!('valid' in result)) return result
+        try {
+          return {
+            valid: true,
+            payload: cloneAndDeepFreezeJson({
+              state: 'output-available',
+              output: 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)
   }

packages/ai-client/tests/chat-client-context.test.ts

@@ -5,6 +5,10 @@ import { ChatClient } from '../src/chat-client'
 import { createTextChunks, createToolCallChunks } from './test-utils'
 import type { ConnectConnectionAdapter } from '../src/connection-adapters'
 
+const asyncCountSchema = z
+  .object({ count: z.number() })
+  .refine(async ({ count }) => count > 0, 'expected positive count')
+
 function findToolCallPart(client: ChatClient, toolCallId: string) {
   for (const message of client.getMessages()) {
     if (message.role !== 'assistant') {
@@ -321,6 +325,48 @@ describe('ChatClient runtime context', () => {
     })
   })
 
+  it('awaits asynchronous outputSchema validation for executable client tools', async () => {
+    const firstChunks = createToolCallChunks([
+      {
+        id: 'tc-async-executable-output',
+        name: 'async_output_tool',
+        arguments: '{}',
+      },
+    ])
+    const secondChunks = createTextChunks('done', 'msg-async-output')
+    let callIndex = 0
+
+    const adapter: ConnectConnectionAdapter = {
+      async *connect(_messages, _data, abortSignal) {
+        const chunks = callIndex === 0 ? firstChunks : secondChunks
+        callIndex++
+        for (const chunk of chunks) {
+          if (abortSignal?.aborted) return
+          yield chunk
+        }
+      },
+    }
+
+    const tool = toolDefinition({
+      name: 'async_output_tool',
+      description: 'Returns asynchronously validated output',
+      outputSchema: asyncCountSchema,
+    }).client(() => ({ count: 1 }))
+
+    const client = new ChatClient({ connection: adapter, tools: [tool] })
+    await client.sendMessage('call async output tool')
+
+    expect(
+      findToolCallPart(client, 'tc-async-executable-output'),
+    ).toMatchObject({
+      state: 'input-complete',
+      output: { count: 1 },
+    })
+    expect(
+      findToolResultPart(client, 'tc-async-executable-output'),
+    ).toMatchObject({ state: 'complete' })
+  })
+
   it('renders a client tool that throws an empty-message error as terminal "error" (issue #718)', async () => {
     const firstChunks = createToolCallChunks([
       {
@@ -369,11 +415,11 @@ describe('ChatClient runtime context', () => {
     })
   })
 
-  it('validates manual client tool results against outputSchema', async () => {
+  it('awaits asynchronous outputSchema validation for manual client tool results', async () => {
     const tool = toolDefinition({
       name: 'manual_invalid_output_tool',
       description: 'Validates manual output',
-      outputSchema: z.object({ count: z.number() }),
+      outputSchema: asyncCountSchema,
     }).client(() => ({ count: 1 }))
 
     const client = new ChatClient({
@@ -403,13 +449,13 @@ describe('ChatClient runtime context', () => {
     await client.addToolResult({
       toolCallId: 'tc-manual-invalid-output',
       tool: 'manual_invalid_output_tool',
-      output: JSON.parse('{"count":"not-a-number"}'),
+      output: { count: 0 },
     })
 
     expect(findToolCallPart(client, 'tc-manual-invalid-output')).toMatchObject({
       state: 'error',
       output: {
-        error: expect.stringContaining('expected number'),
+        error: 'expected positive count',
       },
     })
     expect(