feat(ai): extend addToolResult to support error results

This commit extends the `addToolResult` method on the `AbstractChat`
class to optionally take an `output-error` result. This allows clients
to report both successful and failed tool calls using the same
mechanism.

    addToolResult({ state: "output-error", errorText: "Failed" });

For backwards compatibility the existing method interface is still
supported and will default to a state of `output-available`.

Co-Authored-By: Lars Grammel <[email protected]>

Author: aron

packages/ai/src/ui/chat.test.ts

@@ -1742,6 +1742,149 @@ describe('Chat', () => {
       `);
     });
 
+    it('should send message when a tool error result is submitted', async () => {
+      server.urls['http://localhost:3000/api/chat'].response = [
+        {
+          type: 'stream-chunks',
+          chunks: [
+            formatChunk({ type: 'start' }),
+            formatChunk({ type: 'start-step' }),
+            formatChunk({
+              type: 'tool-input-available',
+              toolCallId: 'tool-call-0',
+              toolName: 'test-tool',
+              input: { testArg: 'test-value' },
+            }),
+            formatChunk({ type: 'finish-step' }),
+            formatChunk({ type: 'finish' }),
+          ],
+        },
+        {
+          type: 'stream-chunks',
+          chunks: [
+            formatChunk({ type: 'start' }),
+            formatChunk({ type: 'start-step' }),
+            formatChunk({ type: 'finish-step' }),
+            formatChunk({ type: 'finish' }),
+          ],
+        },
+      ];
+
+      let callCount = 0;
+      const onFinishPromise = createResolvablePromise<void>();
+
+      const chat = new TestChat({
+        id: '123',
+        generateId: mockId(),
+        transport: new DefaultChatTransport({
+          api: 'http://localhost:3000/api/chat',
+        }),
+        sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+        onFinish: () => {
+          callCount++;
+          if (callCount === 2) {
+            onFinishPromise.resolve();
+          }
+        },
+      });
+
+      await chat.sendMessage({
+        text: 'Hello, world!',
+      });
+
+      // user submits the tool result
+      await chat.addToolResult({
+        state: 'output-error',
+        tool: 'test-tool',
+        toolCallId: 'tool-call-0',
+        errorText: 'test-error',
+      });
+
+      // UI should show the tool result
+      expect(chat.messages).toMatchInlineSnapshot(`
+        [
+          {
+            "id": "id-0",
+            "metadata": undefined,
+            "parts": [
+              {
+                "text": "Hello, world!",
+                "type": "text",
+              },
+            ],
+            "role": "user",
+          },
+          {
+            "id": "id-1",
+            "metadata": undefined,
+            "parts": [
+              {
+                "type": "step-start",
+              },
+              {
+                "errorText": "test-error",
+                "input": {
+                  "testArg": "test-value",
+                },
+                "output": undefined,
+                "preliminary": undefined,
+                "providerExecuted": undefined,
+                "rawInput": undefined,
+                "state": "output-error",
+                "toolCallId": "tool-call-0",
+                "type": "tool-test-tool",
+              },
+            ],
+            "role": "assistant",
+          },
+        ]
+      `);
+
+      await onFinishPromise.promise;
+
+      // 2nd call should happen after the stream is finished
+      expect(server.calls.length).toBe(2);
+
+      // check details of the 2nd call
+      expect(await server.calls[1].requestBodyJson).toMatchInlineSnapshot(`
+        {
+          "id": "123",
+          "messageId": "id-1",
+          "messages": [
+            {
+              "id": "id-0",
+              "parts": [
+                {
+                  "text": "Hello, world!",
+                  "type": "text",
+                },
+              ],
+              "role": "user",
+            },
+            {
+              "id": "id-1",
+              "parts": [
+                {
+                  "type": "step-start",
+                },
+                {
+                  "errorText": "test-error",
+                  "input": {
+                    "testArg": "test-value",
+                  },
+                  "state": "output-error",
+                  "toolCallId": "tool-call-0",
+                  "type": "tool-test-tool",
+                },
+              ],
+              "role": "assistant",
+            },
+          ],
+          "trigger": "submit-message",
+        }
+      `);
+    });
+
     it('should send message when a dynamic tool result is submitted', async () => {
       server.urls['http://localhost:3000/api/chat'].response = [
         {
@@ -1795,6 +1938,7 @@ describe('Chat', () => {
 
       // user submits the tool result
       await chat.addToolResult({
+        state: 'output-available',
         tool: 'test-tool',
         toolCallId: 'tool-call-0',
         output: 'test-result',

packages/ai/src/ui/chat.ts

@@ -18,6 +18,7 @@ import {
 import {
   InferUIMessageToolCall,
   isToolOrDynamicToolUIPart,
+  ToolUIPart,
   type DataUIPart,
   type FileUIPart,
   type InferUIMessageData,
@@ -414,14 +415,26 @@ export abstract class AbstractChat<UI_MESSAGE extends UIMessage> {
   };
 
   addToolResult = async <TOOL extends keyof InferUIMessageTools<UI_MESSAGE>>({
+    state = 'output-available',
     tool,
     toolCallId,
     output,
-  }: {
-    tool: TOOL;
-    toolCallId: string;
-    output: InferUIMessageTools<UI_MESSAGE>[TOOL]['output'];
-  }) =>
+    errorText,
+  }:
+    | {
+        state?: 'output-available';
+        tool: TOOL;
+        toolCallId: string;
+        output: InferUIMessageTools<UI_MESSAGE>[TOOL]['output'];
+        errorText?: never;
+      }
+    | {
+        state: 'output-error';
+        tool: TOOL;
+        toolCallId: string;
+        output?: never;
+        errorText: string;
+      }) =>
     this.jobExecutor.run(async () => {
       const messages = this.state.messages;
       const lastMessage = messages[messages.length - 1];
@@ -430,7 +443,7 @@ export abstract class AbstractChat<UI_MESSAGE extends UIMessage> {
         ...lastMessage,
         parts: lastMessage.parts.map(part =>
           isToolOrDynamicToolUIPart(part) && part.toolCallId === toolCallId
-            ? { ...part, state: 'output-available', output }
+            ? { ...part, state, output, errorText }
             : part,
         ),
       });
@@ -440,12 +453,12 @@ export abstract class AbstractChat<UI_MESSAGE extends UIMessage> {
         this.activeResponse.state.message.parts =
           this.activeResponse.state.message.parts.map(part =>
             isToolOrDynamicToolUIPart(part) && part.toolCallId === toolCallId
-              ? {
+              ? ({
                   ...part,
-                  state: 'output-available',
+                  state,
                   output,
-                  errorText: undefined,
-                }
+                  errorText,
+                } as ToolUIPart<InferUIMessageTools<UI_MESSAGE>>)
               : part,
           );
       }