fix(gateway): expose idempotencyKey on chat.history __openclaw envelope (#79844)

Sanjays2402 · Sanjays2402 · commit d0de65b289a7 · 2026-05-09T18:14:45.000-07:00
When a user message is sent with an idempotencyKey, that key is persisted on
the transcript message but was only available as a top-level message field on
hydration. Clients consuming chat.history (and the SSE inline message stream)
expect identity-style metadata to live inside the __openclaw envelope alongside
seq, id, importedFrom, etc.

Hoist the persisted idempotencyKey into __openclaw at hydration time:
- parsedSessionEntryToMessage (chat.history reads + recent-tail reads)
- SessionHistorySseState.appendInlineMessage (live SSE inline append)
- broadcastSessionMessage in server-session-events (inline broadcast path)

The original top-level field is preserved for back-compat, so no existing
reader breaks.

Tests:
- session-utils.fs.test.ts: idempotencyKey surfaces on full + recent reads
- session-history-state.test.ts: idempotencyKey surfaces on inline append
diff --git a/src/gateway/server-session-events.ts b/src/gateway/server-session-events.ts
@@ -126,9 +126,16 @@ async function handleTranscriptUpdateBroadcast(
     sessionRow: loadGatewaySessionRow(sessionKey, { transcriptUsageMaxBytes: 64 * 1024 }),
     includeSession: true,
   });
+  const rawIdempotencyKey =
+    update.message && typeof update.message === "object" && !Array.isArray(update.message)
+      ? (update.message as Record<string, unknown>).idempotencyKey
+      : undefined;
   const rawMessage = attachOpenClawTranscriptMeta(update.message, {
     ...(typeof update.messageId === "string" ? { id: update.messageId } : {}),
     ...(typeof messageSeq === "number" ? { seq: messageSeq } : {}),
+    ...(typeof rawIdempotencyKey === "string" && rawIdempotencyKey.length > 0
+      ? { idempotencyKey: rawIdempotencyKey }
+      : {}),
   });
   const message = projectChatDisplayMessage(rawMessage);
   if (message) {
diff --git a/src/gateway/session-history-state.test.ts b/src/gateway/session-history-state.test.ts
@@ -329,4 +329,23 @@ describe("SessionHistorySseState", () => {
     ).toBeNull();
     expect(state.snapshot().messages).toHaveLength(1);
   });
+
+  test("surfaces idempotencyKey from the inline message in the __openclaw envelope", () => {
+    const state = SessionHistorySseState.fromRawSnapshot({
+      target: { sessionId: "sess-idempotency" },
+      rawMessages: [],
+    });
+    const appended = state.appendInlineMessage({
+      message: {
+        role: "user",
+        content: [{ type: "text", text: "hi from client" }],
+        idempotencyKey: "client-key-42",
+      },
+      messageId: "msg-42",
+    });
+    expect(appended).not.toBeNull();
+    const sent = appended?.message as { __openclaw?: { idempotencyKey?: unknown; id?: unknown } };
+    expect(sent.__openclaw?.idempotencyKey).toBe("client-key-42");
+    expect(sent.__openclaw?.id).toBe("msg-42");
+  });
 });
diff --git a/src/gateway/session-history-state.ts b/src/gateway/session-history-state.ts
@@ -229,9 +229,16 @@ export class SessionHistorySseState {
       return null;
     }
     this.rawTranscriptSeq += 1;
+    const idempotencyKey =
+      update.message && typeof update.message === "object" && !Array.isArray(update.message)
+        ? (update.message as Record<string, unknown>).idempotencyKey
+        : undefined;
     const nextMessage = attachOpenClawTranscriptMeta(update.message, {
       ...(typeof update.messageId === "string" ? { id: update.messageId } : {}),
       seq: this.rawTranscriptSeq,
+      ...(typeof idempotencyKey === "string" && idempotencyKey.length > 0
+        ? { idempotencyKey }
+        : {}),
     });
     const [sanitizedMessage] = toSessionHistoryMessages(
       projectChatDisplayMessages([nextMessage], { maxChars: this.maxChars }),
diff --git a/src/gateway/session-utils.fs.test.ts b/src/gateway/session-utils.fs.test.ts
@@ -612,6 +612,47 @@ describe("readSessionMessages", () => {
     ]);
   });
 
+  test("surfaces idempotencyKey in the __openclaw envelope when persisted on the message", () => {
+    const sessionId = "test-session-idempotency-key";
+    writeTranscript(tmpDir, sessionId, [
+      { type: "session", version: 1, id: sessionId },
+      {
+        message: {
+          role: "user",
+          content: "hello",
+          idempotencyKey: "client-key-abc",
+        },
+      },
+      {
+        message: {
+          role: "assistant",
+          content: "hi",
+          idempotencyKey: "server-key-xyz",
+        },
+      },
+      { message: { role: "user", content: "no key here" } },
+    ]);
+
+    const out = readSessionMessages(sessionId, storePath) as Array<{
+      role: string;
+      __openclaw?: { idempotencyKey?: unknown; seq?: unknown };
+    }>;
+    expect(out).toHaveLength(3);
+    expect(out[0]?.__openclaw?.idempotencyKey).toBe("client-key-abc");
+    expect(out[1]?.__openclaw?.idempotencyKey).toBe("server-key-xyz");
+    expect(out[2]?.__openclaw?.idempotencyKey).toBeUndefined();
+    // The original top-level field is preserved for back-compat readers.
+    expect((out[0] as { idempotencyKey?: unknown }).idempotencyKey).toBe("client-key-abc");
+
+    const recent = readRecentSessionMessages(sessionId, storePath, undefined, {
+      maxMessages: 2,
+      maxBytes: 4096,
+    }) as Array<{ __openclaw?: { idempotencyKey?: unknown } }>;
+    expect(recent).toHaveLength(2);
+    expect(recent[0]?.__openclaw?.idempotencyKey).toBe("server-key-xyz");
+    expect(recent[1]?.__openclaw?.idempotencyKey).toBeUndefined();
+  });
+
   test("bounds recent-message reads for large append-only transcripts", () => {
     const sessionId = "test-session-recent-large";
     const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
diff --git a/src/gateway/session-utils.fs.ts b/src/gateway/session-utils.fs.ts
@@ -711,15 +711,25 @@ export function readRecentSessionTranscriptLines(params: {
   return { lines, totalLines };
 }
 
+function extractIdempotencyKey(message: unknown): string | undefined {
+  if (!message || typeof message !== "object" || Array.isArray(message)) {
+    return undefined;
+  }
+  const value = (message as Record<string, unknown>).idempotencyKey;
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
 function parsedSessionEntryToMessage(parsed: unknown, seq: number): unknown {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     return null;
   }
   const entry = parsed as Record<string, unknown>;
   if (entry.message) {
+    const idempotencyKey = extractIdempotencyKey(entry.message);
     return attachOpenClawTranscriptMeta(entry.message, {
       ...(typeof entry.id === "string" ? { id: entry.id } : {}),
       seq,
+      ...(idempotencyKey ? { idempotencyKey } : {}),
     });
   }
 
