feat #20295

Co-authored-by: wasim-builds <108329802+wasim-builds@users.noreply.github.com>

Author: ai-sdk-factory

.changeset/stable-tool-output-errors.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat(ai): add a stable UI message type and type guard for tool output errors

content/docs/04-ai-sdk-ui/03-chatbot-tool-usage.mdx

@@ -329,7 +329,7 @@ export default function Chat() {
 
 ### Error handling
 
-Sometimes an error may occur during client-side tool execution. Use the `addToolOutput` method with a `state` of `output-error` and `errorText` value instead of `output` record the error.
+Sometimes an error may occur during client-side tool execution. Use the `addToolOutput` method with a `state` of `output-error` and `errorText` value instead of `output` to record the error.
 
 ```tsx filename='app/page.tsx' highlight="19,36-41"
 'use client';
@@ -380,6 +380,21 @@ export default function Chat() {
 }
 ```
 
+When rendering messages, use `isToolOutputErrorUIPart` to identify failed
+static and dynamic tool parts without checking the tool state directly:
+
+```tsx
+import { isToolOutputErrorUIPart, type UIMessage } from 'ai';
+
+function ToolError({ part }: { part: UIMessage['parts'][number] }) {
+  if (!isToolOutputErrorUIPart(part)) {
+    return null;
+  }
+
+  return <div role="alert">{part.errorText}</div>;
+}
+```
+
 ## Tool Execution Approval
 
 Tool execution approval lets you require user confirmation before a server-side tool runs. Unlike [client-side tools](#example) that execute in the browser, tools with approval still execute on the server—but only after the user approves.

content/docs/07-reference/01-ai-sdk-core/31-ui-message.mdx

@@ -203,6 +203,34 @@ type ToolUIPart<TOOLS extends UITools = UITools> = ValueOf<{
 the tool part transitions from `approval-requested` to `approval-responded` and
 in later approval-bearing output states.
 
+### `ToolOutputErrorUIPart`
+
+A static or dynamic tool part whose execution failed. Use the
+`isToolOutputErrorUIPart` type guard when rendering messages so your code does
+not need to check the tool state discriminator directly.
+
+```tsx
+import { isToolOutputErrorUIPart, type UIMessage } from 'ai';
+
+function ToolError({ part }: { part: UIMessage['parts'][number] }) {
+  if (!isToolOutputErrorUIPart(part)) {
+    return null;
+  }
+
+  return <div role="alert">{part.errorText}</div>;
+}
+```
+
+The generic `ToolOutputErrorUIPart<TOOLS>` type preserves the input types of
+static tools and also includes dynamic tool errors:
+
+```typescript
+type ToolOutputErrorUIPart<TOOLS extends UITools = UITools> = Extract<
+  ToolUIPart<TOOLS> | DynamicToolUIPart,
+  { state: 'output-error' }
+>;
+```
+
 ### `CustomContentUIPart`
 
 A provider-specific custom content part of a message.

examples/ai-functions/src/types/tool-output-error-ui-part.ts

@@ -0,0 +1,28 @@
+import { isToolOutputErrorUIPart, type UIDataTypes, type UIMessage } from 'ai';
+
+type WeatherTools = {
+  weather: {
+    input: { city: string };
+    output: { temperature: number };
+  };
+};
+
+const message: UIMessage<unknown, UIDataTypes, WeatherTools> = {
+  id: 'message-1',
+  role: 'assistant',
+  parts: [
+    {
+      type: 'tool-weather',
+      toolCallId: 'call-1',
+      state: 'output-error',
+      input: { city: 'Berlin' },
+      errorText: 'Weather service unavailable',
+    },
+  ],
+};
+
+for (const part of message.parts) {
+  if (isToolOutputErrorUIPart(part)) {
+    console.log(`Tool failed: ${part.errorText}`);
+  }
+}

packages/ai/src/ui/index.ts

@@ -44,6 +44,7 @@ export {
   isReasoningUIPart,
   isStaticToolUIPart,
   isTextUIPart,
+  isToolOutputErrorUIPart,
   isToolUIPart,
   type CustomContentUIPart,
   type DataUIPart,
@@ -57,6 +58,7 @@ export {
   type SourceUrlUIPart,
   type StepStartUIPart,
   type TextUIPart,
+  type ToolOutputErrorUIPart,
   type ToolUIPart,
   type UIDataTypes,
   type UIMessage,

packages/ai/src/ui/ui-messages.test-d.ts

@@ -1,5 +1,11 @@
-import { describe, it } from 'vitest';
-import type { DynamicToolUIPart, ToolUIPart } from './ui-messages';
+import { describe, expectTypeOf, it } from 'vitest';
+import {
+  isToolOutputErrorUIPart,
+  type DynamicToolUIPart,
+  type ToolOutputErrorUIPart,
+  type ToolUIPart,
+  type UIMessagePart,
+} from './ui-messages';
 
 type TestTools = {
   weather: {
@@ -86,3 +92,50 @@ describe('UIMessagePart', () => {
     type _Responded = AssertAssignable<ToolUIPart<TestTools>, RespondedPart>;
   });
 });
+
+describe('ToolOutputErrorUIPart', () => {
+  it('represents static and dynamic tool output errors', () => {
+    type StaticPart = {
+      type: 'tool-weather';
+      state: 'output-error';
+      toolCallId: 'call-1';
+      input: { city: 'Tokyo' };
+      errorText: 'Weather service unavailable';
+    };
+    type _Static = AssertAssignable<
+      ToolOutputErrorUIPart<TestTools>,
+      StaticPart
+    >;
+
+    type DynamicPart = {
+      type: 'dynamic-tool';
+      toolName: 'weather';
+      state: 'output-error';
+      toolCallId: 'call-2';
+      input: { city: 'Tokyo' };
+      errorText: 'Weather service unavailable';
+    };
+    type _Dynamic = AssertAssignable<
+      ToolOutputErrorUIPart<TestTools>,
+      DynamicPart
+    >;
+  });
+
+  it('narrows tool output errors while preserving static tool input types', () => {
+    const part = null as unknown as UIMessagePart<
+      Record<string, never>,
+      TestTools
+    >;
+
+    if (isToolOutputErrorUIPart(part)) {
+      expectTypeOf(part).toEqualTypeOf<ToolOutputErrorUIPart<TestTools>>();
+      expectTypeOf(part.errorText).toEqualTypeOf<string>();
+
+      if (part.type === 'tool-weather') {
+        expectTypeOf(part.input).toEqualTypeOf<
+          TestTools['weather']['input'] | undefined
+        >();
+      }
+    }
+  });
+});

packages/ai/src/ui/ui-messages.test.ts

@@ -3,6 +3,7 @@ import {
   getStaticToolName,
   isCustomContentUIPart,
   isDataUIPart,
+  isToolOutputErrorUIPart,
 } from './ui-messages';
 
 describe('getStaticToolName', () => {
@@ -82,3 +83,51 @@ describe('isDataUIPart', () => {
     ).toBe(false);
   });
 });
+
+describe('isToolOutputErrorUIPart', () => {
+  it('should return true for a static tool output error part', () => {
+    expect(
+      isToolOutputErrorUIPart({
+        type: 'tool-weather',
+        toolCallId: 'tool1',
+        state: 'output-error',
+        input: { city: 'Berlin' },
+        errorText: 'Weather service unavailable',
+      }),
+    ).toBe(true);
+  });
+
+  it('should return true for a dynamic tool output error part', () => {
+    expect(
+      isToolOutputErrorUIPart({
+        type: 'dynamic-tool',
+        toolName: 'weather',
+        toolCallId: 'tool1',
+        state: 'output-error',
+        input: { city: 'Berlin' },
+        errorText: 'Weather service unavailable',
+      }),
+    ).toBe(true);
+  });
+
+  it('should return false for a successful tool output part', () => {
+    expect(
+      isToolOutputErrorUIPart({
+        type: 'tool-weather',
+        toolCallId: 'tool1',
+        state: 'output-available',
+        input: { city: 'Berlin' },
+        output: { temperature: 18 },
+      }),
+    ).toBe(false);
+  });
+
+  it('should return false for a non-tool part', () => {
+    expect(
+      isToolOutputErrorUIPart({
+        type: 'text',
+        text: 'Weather service unavailable',
+      }),
+    ).toBe(false);
+  });
+});

packages/ai/src/ui/ui-messages.ts

@@ -361,7 +361,7 @@ export type UIToolInvocation<TOOL extends UITool | Tool> = {
       };
     }
   | {
-      state: 'output-error'; // TODO AI SDK 6: change to 'error' state
+      state: 'output-error';
       input: asUITool<TOOL>['input'] | undefined;
       rawInput?: unknown; // TODO AI SDK 6: remove this field, input should be unknown
       output?: never;
@@ -489,7 +489,7 @@ export type DynamicToolUIPart = {
       };
     }
   | {
-      state: 'output-error'; // TODO AI SDK 6: change to 'error' state
+      state: 'output-error';
       input: unknown;
       output?: never;
       errorText: string;
@@ -523,6 +523,17 @@ export type DynamicToolUIPart = {
     }
 );
 
+/**
+ * A static or dynamic tool UI part whose execution failed.
+ *
+ * Use `isToolOutputErrorUIPart` to identify tool output errors without
+ * depending on the underlying tool state discriminator.
+ */
+export type ToolOutputErrorUIPart<TOOLS extends UITools = UITools> = Extract<
+  ToolUIPart<TOOLS> | DynamicToolUIPart,
+  { state: 'output-error' }
+>;
+
 /**
  * Type guard to check if a message part is a text part.
  */
@@ -603,6 +614,17 @@ export function isToolUIPart<TOOLS extends UITools>(
   return isStaticToolUIPart(part) || isDynamicToolUIPart(part);
 }
 
+/**
+ * Check if a message part is a tool output error part.
+ *
+ * This works for both static and dynamic tools.
+ */
+export function isToolOutputErrorUIPart<TOOLS extends UITools>(
+  part: UIMessagePart<UIDataTypes, TOOLS>,
+): part is ToolOutputErrorUIPart<TOOLS> {
+  return isToolUIPart(part) && part.state === 'output-error';
+}
+
 /**
  * Returns the name of the static tool.
  *