fix(gateway): broadcast agent-run error payloads

vincentkoc · vincentkoc · commit a230fcc4cc38 · 2026-05-22T20:36:00.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -37,6 +37,7 @@ Docs: https://docs.openclaw.ai
 
 - CLI/update: start managed Gateway update handoff helpers from a stable existing directory and tolerate deleted cwd/package roots during macOS LaunchAgent handoff. Fixes #83808. (#83875) Thanks @jason-allen-oneal.
 - Cron: honor `cron.retry.retryOn: ["network"]` for common network error codes such as `EAI_AGAIN`, `EHOSTUNREACH`, and `ENETUNREACH`.
+- Gateway chat: broadcast returned agent-run error payloads after an agent starts so ACP/WebChat clients receive terminal idle-timeout errors. Fixes #84945.
 - Agents/OpenAI: preserve structured provider error code, type, and redacted body metadata on boundary-aware transport failures.
 - CLI/agents: retry transient normal-close Gateway handshakes before falling back to embedded `openclaw agent` execution.
 - CLI/update: keep managed Gateway service stop/restart status lines out of `openclaw update --json` stdout so package-update automation can parse the JSON payload.
diff --git a/src/gateway/server-methods/chat.directive-tags.test.ts b/src/gateway/server-methods/chat.directive-tags.test.ts
@@ -31,6 +31,7 @@ const mockState = vi.hoisted(() => ({
     replyToId?: string;
     replyToCurrent?: boolean;
     isReasoning?: boolean;
+    isError?: boolean;
   } | null,
   dispatchedReplies: [] as Array<{
     kind: "tool" | "block" | "final";
@@ -45,6 +46,7 @@ const mockState = vi.hoisted(() => ({
       replyToId?: string;
       replyToCurrent?: boolean;
       isReasoning?: boolean;
+      isError?: boolean;
     };
   }>,
   dispatchError: null as Error | null,
@@ -151,6 +153,7 @@ vi.mock("../../auto-reply/dispatch.js", () => ({
           replyToId?: string;
           replyToCurrent?: boolean;
           isReasoning?: boolean;
+          isError?: boolean;
         }) => boolean;
         sendBlockReply: (payload: {
           text?: string;
@@ -162,6 +165,7 @@ vi.mock("../../auto-reply/dispatch.js", () => ({
           replyToId?: string;
           replyToCurrent?: boolean;
           isReasoning?: boolean;
+          isError?: boolean;
         }) => boolean;
         sendToolResult: (payload: {
           text?: string;
@@ -173,6 +177,7 @@ vi.mock("../../auto-reply/dispatch.js", () => ({
           replyToId?: string;
           replyToCurrent?: boolean;
           isReasoning?: boolean;
+          isError?: boolean;
         }) => boolean;
         markComplete: () => void;
         waitForIdle: () => Promise<void>;
@@ -965,6 +970,52 @@ describe("chat directive tag stripping for non-streaming final payloads", () =>
     expect(assistantEntries).toStrictEqual([]);
   });
 
+  it("broadcasts returned agent-run error payloads after an agent starts", async () => {
+    createTranscriptFixture("openclaw-chat-send-agent-returned-error-");
+    const errorMessage = "LLM idle timeout (120s): no response from model";
+    mockState.triggerAgentRunStart = true;
+    mockState.dispatchedReplies = [
+      {
+        kind: "final",
+        payload: {
+          text: errorMessage,
+          isError: true,
+        },
+      },
+    ];
+    const respond = vi.fn();
+    const context = createChatContext();
+
+    const broadcast = await runNonStreamingChatSend({
+      context,
+      respond,
+      idempotencyKey: "idem-agent-returned-error",
+      message: "please keep working",
+    });
+
+    expect(broadcast).toMatchObject({
+      runId: "idem-agent-returned-error",
+      sessionKey: "main",
+      state: "error",
+      errorMessage,
+    });
+    const dedupe = context.dedupe.get("chat:idem-agent-returned-error");
+    expect(dedupe?.ok).toBe(false);
+    expect(dedupe?.payload).toMatchObject({
+      runId: "idem-agent-returned-error",
+      status: "error",
+      summary: errorMessage,
+    });
+    expect(findUserUpdate()).toBeDefined();
+    const assistantUpdates = mockState.emittedTranscriptUpdates.filter(
+      (update) =>
+        typeof update.message === "object" &&
+        update.message !== null &&
+        (update.message as { role?: unknown }).role === "assistant",
+    );
+    expect(assistantUpdates).toStrictEqual([]);
+  });
+
   it("keeps visible text on non-agent TTS final media because no model transcript exists", async () => {
     const transcriptDir = createTranscriptFixture("openclaw-chat-send-command-tts-final-");
     const audioPath = path.join(transcriptDir, "tts.mp3");
diff --git a/src/gateway/server-methods/chat.ts b/src/gateway/server-methods/chat.ts
@@ -2691,6 +2691,13 @@ export const chatHandlers: GatewayRequestHandlers = {
         })();
         await userTranscriptUpdatePromise;
       };
+      const emitUserTranscriptUpdateAfterAgentRun = async () => {
+        await emitUserTranscriptUpdate().catch((transcriptErr) => {
+          context.logGateway.warn(
+            `webchat user transcript update failed after agent run: ${formatForLog(transcriptErr)}`,
+          );
+        });
+      };
       let transcriptMediaRewriteDone = false;
       const rewriteUserTranscriptMedia = async () => {
         if (transcriptMediaRewriteDone) {
@@ -2895,6 +2902,16 @@ export const chatHandlers: GatewayRequestHandlers = {
             "gateway.chat_send.post_dispatch",
             async () => {
               await rewriteUserTranscriptMedia();
+              const returnedAgentErrorPayloads = agentRunStarted
+                ? deliveredReplies
+                    .map((entry) => entry.payload)
+                    .filter((payload) => payload.isError)
+                : [];
+              const returnedAgentErrorMessage =
+                returnedAgentErrorPayloads
+                  .map((payload) => payload.text?.trim())
+                  .filter((text): text is string => Boolean(text))
+                  .join(" | ") || undefined;
               // WebChat persistence has two owners. Agent runs persist model-visible turns
               // through Pi's SessionManager; this dispatcher only owns live delivery payloads.
               // Do not blindly mirror agent-run final payloads into JSONL or chat.history can
@@ -3091,21 +3108,42 @@ export const chatHandlers: GatewayRequestHandlers = {
                     message,
                   });
                 }
-              } else if (!hasBeforeAgentRunGate) {
-                await emitUserTranscriptUpdate().catch((transcriptErr) => {
-                  context.logGateway.warn(
-                    `webchat user transcript update failed after agent run: ${formatForLog(transcriptErr)}`,
-                  );
+              } else if (returnedAgentErrorPayloads.length > 0) {
+                if (!hasBeforeAgentRunGate) {
+                  await emitUserTranscriptUpdateAfterAgentRun();
+                }
+                broadcastChatError({
+                  context,
+                  runId: clientRunId,
+                  sessionKey,
+                  errorMessage: returnedAgentErrorMessage,
                 });
+              } else if (!hasBeforeAgentRunGate) {
+                await emitUserTranscriptUpdateAfterAgentRun();
               }
               if (!context.chatAbortedRuns.has(clientRunId)) {
+                const returnedAgentError =
+                  returnedAgentErrorPayloads.length > 0
+                    ? errorShape(
+                        ErrorCodes.UNAVAILABLE,
+                        returnedAgentErrorMessage ?? "agent returned an error payload",
+                      )
+                    : undefined;
                 setGatewayDedupeEntry({
                   dedupe: context.dedupe,
                   key: `chat:${clientRunId}`,
                   entry: {
                     ts: Date.now(),
-                    ok: true,
-                    payload: { runId: clientRunId, status: "ok" as const },
+                    ok: returnedAgentErrorPayloads.length === 0,
+                    payload:
+                      returnedAgentErrorPayloads.length > 0
+                        ? {
+                            runId: clientRunId,
+                            status: "error" as const,
+                            summary: returnedAgentErrorMessage ?? "agent returned an error payload",
+                          }
+                        : { runId: clientRunId, status: "ok" as const },
+                    ...(returnedAgentError ? { error: returnedAgentError } : {}),
                   },
                 });
               }
