fix(gateway): never return an empty chat.history transcript (#92383)

Hidetsugu55 · web-flow · commit 50a4bb00e557 · 2026-06-19T04:17:02.000Z
Summary: - The PR changes gateway chat-history byte-budget fallback behavior to return a small metadata-free unavailable sentinel instead of an empty transcript, with focused budget tests. - PR surface: Source +20, Tests +73. Total +93 across 2 files. - Reproducibility: yes. Source inspection shows current main reaches `messages: []` when the full history, las ... d copied oversized placeholder all exceed `maxBytes`; I did not run tests because this review is read-only. Automerge notes: - PR branch already contained follow-up commit before automerge: test: access __openclaw via bracket notation for no-underscore-dangle Validation: - ClawSweeper review passed for head f2fa246. - Required merge gates passed before the squash merge. Prepared head SHA: f2fa246 Review: #92383 (comment) Co-authored-by: Hidetsugu55 <183473679+Hidetsugu55@users.noreply.github.com>
diff --git a/src/gateway/server-methods/chat-history-budget.test.ts b/src/gateway/server-methods/chat-history-budget.test.ts
@@ -0,0 +1,73 @@
+// Covers the chat.history final byte-budget fallback, including the sentinel
+// that prevents an empty (blank) transcript from being returned to the dashboard.
+import { describe, expect, it } from "vitest";
+import { enforceChatHistoryFinalBudget } from "./chat.js";
+
+type DisplayMessage = {
+  role?: string;
+  content?: Array<{ type?: string; text?: string }>;
+};
+
+function firstText(messages: unknown[]): string {
+  const msg = messages[0] as DisplayMessage | undefined;
+  return msg?.content?.[0]?.text ?? "";
+}
+
+describe("enforceChatHistoryFinalBudget", () => {
+  it("passes through history that already fits the budget", () => {
+    const messages = [
+      { role: "user", content: [{ type: "text", text: "hello" }] },
+      { role: "assistant", content: [{ type: "text", text: "hi" }] },
+    ];
+    const result = enforceChatHistoryFinalBudget({ messages, maxBytes: 1_000_000 });
+    expect(result.messages).toEqual(messages);
+    expect(result.placeholderCount).toBe(0);
+  });
+
+  it("returns the empty array unchanged for empty input", () => {
+    const result = enforceChatHistoryFinalBudget({ messages: [], maxBytes: 10 });
+    expect(result.messages).toEqual([]);
+    expect(result.placeholderCount).toBe(0);
+  });
+
+  it("keeps just the last message when the full set is over budget but the last fits", () => {
+    const big = { role: "user", content: [{ type: "text", text: "x".repeat(4000) }] };
+    const last = { role: "assistant", content: [{ type: "text", text: "ok" }] };
+    const result = enforceChatHistoryFinalBudget({ messages: [big, last], maxBytes: 2_000 });
+    expect(result.messages).toEqual([last]);
+    expect(result.placeholderCount).toBe(0);
+  });
+
+  it("falls back to a small placeholder when even the last message is too large", () => {
+    const last = {
+      role: "assistant",
+      timestamp: 1,
+      content: [{ type: "text", text: "y".repeat(4000) }],
+      __openclaw: { id: "abc", seq: 7 },
+    };
+    const result = enforceChatHistoryFinalBudget({ messages: [last], maxBytes: 2_000 });
+    expect(result.messages).toHaveLength(1);
+    expect(firstText(result.messages)).toContain("chat.history omitted: message too large");
+    expect(result.placeholderCount).toBe(1);
+  });
+
+  it("returns a metadata-free sentinel (never an empty transcript) when even the placeholder is over budget", () => {
+    // A pathological message whose oversized-placeholder copy is itself too
+    // large because it carries very large transcript metadata.
+    const hugeId = "z".repeat(4000);
+    const message = {
+      role: "user",
+      timestamp: 1,
+      content: [{ type: "text", text: "hi" }],
+      __openclaw: { id: hugeId, seq: 1 },
+    };
+    const result = enforceChatHistoryFinalBudget({ messages: [message], maxBytes: 1_000 });
+
+    // The critical guarantee: the dashboard never receives an empty history.
+    expect(result.messages).toHaveLength(1);
+    expect(firstText(result.messages)).toContain("chat.history unavailable");
+    // The sentinel does not carry the oversized source metadata.
+    expect((result.messages[0] as Record<string, unknown>)["__openclaw"]).toBeUndefined();
+    expect(result.placeholderCount).toBe(1);
+  });
+});
diff --git a/src/gateway/server-methods/chat.ts b/src/gateway/server-methods/chat.ts
@@ -537,6 +537,22 @@ export { sanitizeChatSendMessageInput } from "../chat-input-sanitize.js";
 
 export const CHAT_HISTORY_MAX_SINGLE_MESSAGE_BYTES = 128 * 1024;
 const CHAT_HISTORY_OVERSIZED_PLACEHOLDER = "[chat.history omitted: message too large]";
+const CHAT_HISTORY_UNAVAILABLE_SENTINEL =
+  "[chat.history unavailable: transcript too large to display; the full history is preserved on disk]";
+
+/**
+ * A minimal, metadata-free notice returned when even a single oversized
+ * placeholder cannot fit the chat-history byte budget. Returning this instead
+ * of an empty array guarantees the dashboard never renders a blank transcript,
+ * which otherwise reads to the operator as total history loss.
+ */
+function buildChatHistoryUnavailableSentinel(): Record<string, unknown> {
+  return {
+    role: "assistant",
+    timestamp: Date.now(),
+    content: [{ type: "text", text: CHAT_HISTORY_UNAVAILABLE_SENTINEL }],
+  };
+}
 const CHAT_STARTUP_OPTIONAL_MODEL_CATALOG_TIMEOUT_MS = 25;
 const MANAGED_OUTGOING_IMAGE_PATH_PREFIX = "/api/chat/media/outgoing/";
 let chatHistoryPlaceholderEmitCount = 0;
@@ -1653,7 +1669,11 @@ export function enforceChatHistoryFinalBudget(params: { messages: unknown[]; max
   if (jsonUtf8Bytes([placeholder]) <= maxBytes) {
     return { messages: [placeholder], placeholderCount: 1 };
   }
-  return { messages: [], placeholderCount: 0 };
+  // The oversized placeholder still does not fit (e.g. the source message
+  // carried very large metadata). Never return an empty history — that renders
+  // as a blank transcript and reads as data loss even though the on-disk
+  // transcript is intact. Fall back to a small metadata-free sentinel.
+  return { messages: [buildChatHistoryUnavailableSentinel()], placeholderCount: 1 };
 }
 
 function resolveTranscriptPath(params: {
