@soimy/dingtalk 3.1.4 → 3.3.0

package/src/send-service.ts

@@ -2,26 +2,27 @@ import * as path from "node:path";
 import axios from "axios";
 import { getAccessToken } from "./auth";
 import {
-  deleteActiveCardByTarget,
-  getActiveCardIdByTarget,
-  getCardById,
   isCardInTerminalState,
+  sendProactiveCardText,
   streamAICard,
 } from "./card-service";
 import { stripTargetPrefix } from "./config";
 import { getLogger } from "./logger-context";
-import { uploadMedia as uploadMediaUtil } from "./media-utils";
-import { detectMarkdownAndExtractTitle } from "./message-utils";
+import { getVoiceDurationMs, uploadMedia as uploadMediaUtil } from "./media-utils";
+import { convertMarkdownTablesToPlainText, detectMarkdownAndExtractTitle } from "./message-utils";
 import { resolveOriginalPeerId } from "./peer-id-registry";
+import { appendOutboundToQuoteJournal, appendProactiveOutboundJournal } from "./quote-journal";
 import {
   deleteProactiveRiskObservation,
   getProactiveRiskObservation,
   recordProactiveRiskObservation,
 } from "./proactive-risk-registry";
-import { formatDingTalkErrorPayloadLog } from "./utils";
+import { formatDingTalkErrorPayloadLog, getProxyBypassOption } from "./utils";
 import type {
+  AICardInstance,
   AxiosResponse,
   DingTalkConfig,
+  DingTalkTrackingMetadata,
   Logger,
   ProactiveMessagePayload,
   SendMessageOptions,
@@ -31,6 +32,83 @@ import { AICardStatus } from "./types";
 
 export { detectMediaTypeFromExtension } from "./media-utils";
 
+type ProactiveTextSendResult = AxiosResponse | { tracking: DingTalkTrackingMetadata };
+
+function isTrackingResult(result: ProactiveTextSendResult): result is { tracking: DingTalkTrackingMetadata } {
+  return "tracking" in result;
+}
+
+function extractOutboundMessageId(payload: unknown): string | undefined {
+  if (!payload || typeof payload !== "object") {
+    return undefined;
+  }
+  const data = payload as Record<string, unknown>;
+  const tracking =
+    data.tracking && typeof data.tracking === "object"
+      ? (data.tracking as Record<string, unknown>)
+      : undefined;
+  const value =
+    data.processQueryKey ??
+    data.messageId ??
+    data.msgid ??
+    tracking?.processQueryKey ??
+    tracking?.messageId ??
+    tracking?.msgid ??
+    tracking?.outTrackId;
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function composeCardContentForAppend(previous: string | undefined, incoming: string): string {
+  const prev = previous ?? "";
+  if (!prev) {
+    return incoming;
+  }
+  if (!incoming) {
+    return prev;
+  }
+  if (incoming.startsWith(prev)) {
+    return incoming;
+  }
+  if (prev.endsWith(incoming)) {
+    return prev;
+  }
+  if (prev.endsWith("\n") || incoming.startsWith("\n")) {
+    return `${prev}${incoming}`;
+  }
+  return `${prev}${incoming}`;
+}
+
+const DINGTALK_TEXT_CHUNK_LIMIT = 3800;
+
+function splitMarkdownChunks(text: string, limit = DINGTALK_TEXT_CHUNK_LIMIT): string[] {
+  if (!text || text.length <= limit) {
+    return [text];
+  }
+  const chunks: string[] = [];
+  let buf = "";
+  const lines = text.split("\n");
+  let inCode = false;
+
+  for (const line of lines) {
+    const fenceCount = (line.match(/```/g) || []).length;
+    if (buf.length + line.length + 1 > limit && buf.length > 0) {
+      if (inCode) {
+        buf += "\n```";
+      }
+      chunks.push(buf);
+      buf = inCode ? "```\n" : "";
+    }
+    buf += (buf ? "\n" : "") + line;
+    if (fenceCount % 2 === 1) {
+      inCode = !inCode;
+    }
+  }
+  if (buf) {
+    chunks.push(buf);
+  }
+  return chunks;
+}
+
 function extractErrorCodeFromResponseData(data: unknown): string | null {
   if (!data || typeof data !== "object") {
     return null;
@@ -80,9 +158,8 @@ export async function sendProactiveTextOrMarkdown(
   target: string,
   text: string,
   options: SendMessageOptions = {},
-): Promise<AxiosResponse> {
+): Promise<ProactiveTextSendResult> {
   const log = options.log || getLogger();
-  const token = await getAccessToken(config, log);
 
   // Support group:/user: prefix and restore original case-sensitive conversationId.
   const { targetId, isExplicitUser } = stripTargetPrefix(target);
@@ -95,11 +172,37 @@ export async function sendProactiveTextOrMarkdown(
     ? ` proactiveRisk=${proactiveRisk.level}:${proactiveRisk.reason}`
     : "";
 
+  // In card mode, use card API to avoid oToMessages/batchSend permission requirement.
+  const messageType = config.messageType || "markdown";
+  if (messageType === "card" && config.cardTemplateId) {
+    log?.debug?.(
+      `[DingTalk] Using card API for proactive message to user ${resolvedTarget}${proactiveRiskTag}`,
+    );
+    const result = await sendProactiveCardText(config, resolvedTarget, text, log);
+    if (result.ok) {
+      if (options.accountId) {
+        deleteProactiveRiskObservation(options.accountId, resolvedTarget);
+      }
+      return {
+        tracking: {
+          processQueryKey: result.processQueryKey,
+          outTrackId: result.outTrackId,
+          cardInstanceId: result.cardInstanceId,
+        },
+      };
+    }
+    log?.warn?.(
+      `[DingTalk] Proactive card send failed, fallback to proactive template API: ${result.error || "unknown"}`,
+    );
+  }
+
+  const token = await getAccessToken(config, log);
   const url = isGroup
     ? "https://api.dingtalk.com/v1.0/robot/groupMessages/send"
     : "https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend";
 
-  const { useMarkdown, title } = detectMarkdownAndExtractTitle(text, options, "OpenClaw 提醒");
+  const normalizedText = convertMarkdownTablesToPlainText(text);
+  const { useMarkdown, title } = detectMarkdownAndExtractTitle(normalizedText, options, "OpenClaw 提醒");
 
   log?.debug?.(
     `[DingTalk] Sending proactive message to ${isGroup ? "group" : "user"} ${resolvedTarget} with title "${title}"${proactiveRiskTag}`,
@@ -108,8 +211,8 @@ export async function sendProactiveTextOrMarkdown(
   // DingTalk proactive API uses message templates (sampleMarkdown / sampleText).
   const msgKey = useMarkdown ? "sampleMarkdown" : "sampleText";
   const msgParam = useMarkdown
-    ? JSON.stringify({ title, text })
-    : JSON.stringify({ content: text });
+    ? JSON.stringify({ title, text: normalizedText })
+    : JSON.stringify({ content: normalizedText });
 
   const payload: ProactiveMessagePayload = {
     robotCode: config.robotCode || config.clientId,
@@ -129,6 +232,7 @@ export async function sendProactiveTextOrMarkdown(
       method: "POST",
       data: payload,
       headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+      ...getProxyBypassOption(config),
     });
     if (options.accountId) {
       deleteProactiveRiskObservation(options.accountId, resolvedTarget);
@@ -207,7 +311,8 @@ export async function sendProactiveMedia(
       msgParam = JSON.stringify({ photoURL: mediaId });
     } else if (mediaType === "voice") {
       msgKey = "sampleAudio";
-      msgParam = JSON.stringify({ mediaId, duration: "0" });
+      const durationMs = await getVoiceDurationMs(mediaPath, mediaType, log);
+      msgParam = JSON.stringify({ mediaId, duration: String(durationMs) });
     } else {
       // sampleVideo requires picMediaId; fallback to sampleFile for broader compatibility.
       const filename = path.basename(mediaPath);
@@ -238,12 +343,24 @@ export async function sendProactiveMedia(
       method: "POST",
       data: payload,
       headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+      ...getProxyBypassOption(config),
     });
     if (options.accountId) {
       deleteProactiveRiskObservation(options.accountId, resolvedTarget);
     }
 
-    const messageId = result.data?.processQueryKey || result.data?.messageId;
+    const messageId = extractOutboundMessageId(result.data);
+    if (options.storePath && options.accountId) {
+      await appendProactiveOutboundJournal({
+        storePath: options.storePath,
+        accountId: options.accountId,
+        conversationId: options.conversationId || resolvedTarget,
+        messageId,
+        text: `[media:${mediaType}] ${mediaPath}`,
+        messageType: "outbound-proactive-media",
+        log,
+      });
+    }
     return { ok: true, data: result.data, messageId };
   } catch (err: any) {
     log?.error?.(`[DingTalk] Failed to send proactive media: ${err.message}`);
@@ -271,7 +388,20 @@ export async function sendProactiveMedia(
       log?.error?.(`[DingTalk] Proactive media response${statusLabel}${proactiveRiskTag}`);
       log?.error?.(formatDingTalkErrorPayloadLog("send.proactiveMedia", err.response.data));
     }
-    return { ok: false, error: err.message };
+
+    // Fallback: ensure user still gets a usable link/path text.
+    const fallback = await sendProactiveTextOrMarkdown(
+      config,
+      target,
+      `📎 媒体发送失败，兜底链接/路径：${mediaPath}`,
+      options,
+    ).catch((fallbackErr: any) => ({ __fallbackError: fallbackErr }));
+
+    if ((fallback as any)?.__fallbackError) {
+      return { ok: false, error: `${err.message}; fallback failed: ${(fallback as any).__fallbackError?.message || "unknown"}` };
+    }
+
+    return { ok: true, data: fallback, messageId: (fallback as any)?.processQueryKey || (fallback as any)?.messageId };
   }
 }
 
@@ -293,7 +423,8 @@ export async function sendBySession(
       if (options.mediaType === "image") {
         body = { msgtype: "image", image: { media_id: mediaId } };
       } else if (options.mediaType === "voice") {
-        body = { msgtype: "voice", voice: { media_id: mediaId } };
+        const durationMs = await getVoiceDurationMs(options.mediaPath, options.mediaType, log);
+        body = { msgtype: "voice", voice: { media_id: mediaId, duration: String(durationMs) } };
       } else if (options.mediaType === "video") {
         body = { msgtype: "video", video: { media_id: mediaId } };
       } else if (options.mediaType === "file") {
@@ -306,82 +437,131 @@ export async function sendBySession(
           method: "POST",
           data: body,
           headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+          ...getProxyBypassOption(config),
         });
         return result.data;
       }
     } else {
+      const mediaHint = options.mediaUrl || options.mediaPath || options.filePath || "(媒体发送失败)";
+      text = `${text}\n\n📎 媒体发送失败，兜底链接/路径：${mediaHint}`.trim();
       log?.warn?.("[DingTalk] Media upload failed, falling back to text description");
     }
   }
 
   // Fallback to text/markdown reply payload.
-  const { useMarkdown, title } = detectMarkdownAndExtractTitle(text, options, "Clawdbot 消息");
+  const normalizedText = convertMarkdownTablesToPlainText(text);
+  const { useMarkdown, title } = detectMarkdownAndExtractTitle(normalizedText, options, "Clawdbot 消息");
+  const chunks = splitMarkdownChunks(normalizedText, DINGTALK_TEXT_CHUNK_LIMIT);
+
+  let lastResult: any = null;
+  for (const [idx, chunk] of chunks.entries()) {
+    let body: SessionWebhookResponse;
+    if (useMarkdown) {
+      let finalText = chunk;
+      if (options.atUserId && idx === chunks.length - 1) {
+        finalText = `${finalText} @${options.atUserId}`;
+      }
+      body = { msgtype: "markdown", markdown: { title: chunks.length > 1 ? `${title} (${idx + 1}/${chunks.length})` : title, text: finalText } };
+    } else {
+      body = { msgtype: "text", text: { content: chunk } };
+    }
 
-  let body: SessionWebhookResponse;
-  if (useMarkdown) {
-    let finalText = text;
-    if (options.atUserId) {
-      finalText = `${finalText} @${options.atUserId}`;
+    if (options.atUserId && idx === chunks.length - 1) {
+      body.at = { atUserIds: [options.atUserId], isAtAll: false };
     }
-    body = { msgtype: "markdown", markdown: { title, text: finalText } };
-  } else {
-    body = { msgtype: "text", text: { content: text } };
-  }
 
-  if (options.atUserId) {
-    body.at = { atUserIds: [options.atUserId], isAtAll: false };
+    const result = await axios({
+      url: sessionWebhook,
+      method: "POST",
+      data: body,
+      headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+      ...getProxyBypassOption(config),
+    });
+    lastResult = result.data;
   }
-
-  const result = await axios({
-    url: sessionWebhook,
-    method: "POST",
-    data: body,
-    headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
-  });
-  return result.data;
+  return lastResult;
 }
 
 export async function sendMessage(
   config: DingTalkConfig,
   conversationId: string,
   text: string,
-  options: SendMessageOptions & { sessionWebhook?: string; accountId?: string } = {},
-): Promise<{ ok: boolean; error?: string; data?: AxiosResponse }> {
+  options: SendMessageOptions & { sessionWebhook?: string; card?: AICardInstance; accountId?: string } = {},
+): Promise<{ ok: boolean; error?: string; data?: AxiosResponse; messageId?: string; tracking?: DingTalkTrackingMetadata }> {
   try {
     const messageType = config.messageType || "markdown";
     const log = options.log || getLogger();
 
-    // Card mode: stream into active card if exists; otherwise fallback to markdown/session send.
-    if (messageType === "card" && options.accountId) {
-      const targetKey = `${options.accountId}:${conversationId}`;
-      const activeCardId = getActiveCardIdByTarget(targetKey);
-      if (activeCardId) {
-        const activeCard = getCardById(activeCardId);
-        if (activeCard && !isCardInTerminalState(activeCard.state)) {
-          try {
-            await streamAICard(activeCard, text, false, log);
-            return { ok: true };
-          } catch (err: any) {
-            // Mark failed and continue to markdown fallback to avoid message loss.
-            log?.warn?.(
-              `[DingTalk] AI Card streaming failed, fallback to markdown: ${err.message}`,
-            );
-            activeCard.state = AICardStatus.FAILED;
-            activeCard.lastUpdated = Date.now();
+    if (messageType === "card" && options.card) {
+      const card = options.card;
+      if (isCardInTerminalState(card.state)) {
+        if (options.sessionWebhook) {
+          await sendBySession(config, options.sessionWebhook, text, options);
+          return { ok: true };
+        }
+
+        if (config.cardTemplateId) {
+          const proactiveResult = await sendProactiveCardText(config, conversationId, text, log);
+          if (!proactiveResult.ok) {
+            return { ok: false, error: proactiveResult.error || "Card send failed" };
           }
-        } else {
-          deleteActiveCardByTarget(targetKey);
+          return {
+            ok: true,
+            tracking: {
+              processQueryKey: proactiveResult.processQueryKey,
+              outTrackId: proactiveResult.outTrackId,
+              cardInstanceId: proactiveResult.cardInstanceId,
+            },
+          };
+        }
+      } else if (options.cardUpdateMode === "append") {
+        try {
+          const nextContent = composeCardContentForAppend(card.lastStreamedContent, text);
+          await streamAICard(card, nextContent, false, log);
+          return { ok: true };
+        } catch (err: any) {
+          log?.warn?.(`[DingTalk] AI Card streaming failed: ${err.message}`);
+          card.state = AICardStatus.FAILED;
+          card.lastUpdated = Date.now();
+          return { ok: false, error: err.message };
         }
       }
     }
 
     if (options.sessionWebhook) {
-      await sendBySession(config, options.sessionWebhook, text, options);
-      return { ok: true };
+      const data = await sendBySession(config, options.sessionWebhook, text, options);
+      const messageId = extractOutboundMessageId(data);
+      if (options.storePath && options.accountId) {
+        await appendOutboundToQuoteJournal({
+          storePath: options.storePath,
+          accountId: options.accountId,
+          conversationId: options.conversationId || conversationId,
+          messageId,
+          text,
+          messageType: "outbound",
+          log,
+        });
+      }
+      return { ok: true, data, messageId };
     }
 
     const result = await sendProactiveTextOrMarkdown(config, conversationId, text, options);
-    return { ok: true, data: result };
+    const messageId = extractOutboundMessageId(result);
+    if (options.storePath && options.accountId) {
+      await appendProactiveOutboundJournal({
+        storePath: options.storePath,
+        accountId: options.accountId,
+        conversationId: options.conversationId || conversationId,
+        messageId,
+        text,
+        messageType: "outbound-proactive",
+        log,
+      });
+    }
+    if (isTrackingResult(result)) {
+      return { ok: true, tracking: result.tracking };
+    }
+    return { ok: true, data: result, messageId };
   } catch (err: any) {
     options.log?.error?.(`[DingTalk] Send message failed: ${err.message}`);
     if (err?.response?.data !== undefined) {

package/src/session-command-service.ts

@@ -0,0 +1,147 @@
+export interface ParsedSessionCommand {
+  scope:
+    | "session-alias-show"
+    | "session-alias-set"
+    | "session-alias-clear"
+    | "session-alias-bind"
+    | "session-alias-unbind"
+    | "unknown";
+  peerId?: string;
+  sourceKind?: "direct" | "group";
+  sourceId?: string;
+}
+
+const SESSION_ALIAS_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+
+export function parseSessionCommand(text: string | undefined): ParsedSessionCommand {
+  const raw = String(text || "").trim();
+  if (!raw) {
+    return { scope: "unknown" };
+  }
+  const sessionAliasBindMatch = raw.match(/^\/session-alias\s+(bind|unbind)\s+(direct|group)\s+(\S+)(?:\s+(.+))?$/i);
+  if (sessionAliasBindMatch) {
+    const action = sessionAliasBindMatch[1]?.toLowerCase();
+    const sourceKind = sessionAliasBindMatch[2]?.toLowerCase() as "direct" | "group";
+    const sourceId = sessionAliasBindMatch[3]?.trim();
+    const rawPeerId = sessionAliasBindMatch[4]?.trim();
+    if (action === "bind") {
+      return sourceId && rawPeerId
+        ? { scope: "session-alias-bind", sourceKind, sourceId, peerId: rawPeerId }
+        : { scope: "unknown" };
+    }
+    if (action === "unbind") {
+      return sourceId
+        ? { scope: "session-alias-unbind", sourceKind, sourceId }
+        : { scope: "unknown" };
+    }
+  }
+  const sessionAliasMatch = raw.match(/^\/session-alias\s+(show|clear|set)(?:\s+(.+))?$/i);
+  if (!sessionAliasMatch) {
+    return { scope: "unknown" };
+  }
+  const action = sessionAliasMatch[1]?.toLowerCase();
+  const rawPeerId = sessionAliasMatch[2]?.trim();
+  if (action === "show") {
+    return { scope: "session-alias-show" };
+  }
+  if (action === "clear") {
+    return { scope: "session-alias-clear" };
+  }
+  if (action === "set") {
+    return rawPeerId ? { scope: "session-alias-set", peerId: rawPeerId } : { scope: "unknown" };
+  }
+  return { scope: "unknown" };
+}
+
+export function validateSessionAlias(peerId: string | undefined): string | null {
+  const value = String(peerId || "").trim();
+  if (!value) {
+    return "共享会话别名不能为空。";
+  }
+  if (!SESSION_ALIAS_PATTERN.test(value)) {
+    return "共享会话别名仅允许 [a-zA-Z0-9_-]{1,64}。";
+  }
+  return null;
+}
+
+export function formatSessionAliasReply(params: {
+  sourceKind: "direct" | "group";
+  sourceId: string;
+  peerId: string;
+  aliasSource: "default" | "override";
+}): string {
+  return [
+    "当前会话别名：",
+    "",
+    `- source: \`${params.sourceKind}\``,
+    `- sourceId: \`${params.sourceId}\``,
+    `- peerId: \`${params.peerId}\``,
+    `- mode: \`${params.aliasSource}\``,
+  ].join("\n");
+}
+
+export function formatSessionAliasSetReply(params: {
+  sourceKind: "direct" | "group";
+  sourceId: string;
+  peerId: string;
+}): string {
+  return [
+    "已更新当前会话共享会话别名。",
+    "",
+    `- source: \`${params.sourceKind}\``,
+    `- sourceId: \`${params.sourceId}\``,
+    `- peerId: \`${params.peerId}\``,
+    "",
+    "将其他私聊或群也设置为同一个 peerId 后，这些会话会共用同一条会话。",
+  ].join("\n");
+}
+
+export function formatSessionAliasValidationErrorReply(error: string): string {
+  return [
+    "共享会话别名不合法。",
+    "",
+    `- 原因：${error}`,
+    "- 允许规则：`[a-zA-Z0-9_-]{1,64}`",
+    "- 示例：`shared-dev`、`ops_shared`",
+  ].join("\n");
+}
+
+export function formatSessionAliasClearedReply(params: {
+  sourceKind: "direct" | "group";
+  sourceId: string;
+}): string {
+  return [
+    "已清除当前会话共享会话别名。",
+    "",
+    `- source: \`${params.sourceKind}\``,
+    `- sourceId: \`${params.sourceId}\``,
+    `- peerId: 恢复为当前${params.sourceKind === "direct" ? " senderId" : " conversationId"}`,
+  ].join("\n");
+}
+
+export function formatSessionAliasBoundReply(params: {
+  sourceKind: "direct" | "group";
+  sourceId: string;
+  peerId: string;
+}): string {
+  return [
+    "已绑定共享会话别名。",
+    "",
+    `- source: \`${params.sourceKind}\``,
+    `- sourceId: \`${params.sourceId}\``,
+    `- peerId: \`${params.peerId}\``,
+  ].join("\n");
+}
+
+export function formatSessionAliasUnboundReply(params: {
+  sourceKind: "direct" | "group";
+  sourceId: string;
+  existed: boolean;
+}): string {
+  return [
+    params.existed ? "已解除共享会话别名绑定。" : "未找到对应的共享会话别名绑定。",
+    "",
+    `- source: \`${params.sourceKind}\``,
+    `- sourceId: \`${params.sourceId}\``,
+  ].join("\n");
+}

package/src/session-lock.ts

@@ -0,0 +1,34 @@
+// Per-session mutex to serialize dispatchReply calls for the same session.
+// Prevents concurrent dispatch from producing empty replies when the runtime
+// cannot handle overlapping requests on the same session key.
+
+const locks = new Map<string, Promise<void>>();
+
+export const SESSION_LOCK_NAMESPACE_POLICY = "memory-only" as const;
+
+/**
+ * Acquire a per-session lock. Returns a release function that MUST be called
+ * (typically in a `finally` block) to unblock the next queued caller.
+ *
+ * Different session keys run in parallel; same key runs serially.
+ */
+export async function acquireSessionLock(sessionKey: string): Promise<() => void> {
+    let release!: () => void;
+    const gate = new Promise<void>((r) => {
+        release = r;
+    });
+    const prev = locks.get(sessionKey) ?? Promise.resolve();
+    locks.set(sessionKey, gate);
+    await prev;
+    return () => {
+        if (locks.get(sessionKey) === gate) {
+            locks.delete(sessionKey);
+        }
+        release();
+    };
+}
+
+/** Visible for testing only. */
+export function _getLocksMapForTest(): Map<string, Promise<void>> {
+    return locks;
+}

package/src/session-peer-store.ts

@@ -0,0 +1,77 @@
+import { readNamespaceJson, writeNamespaceJsonAtomic } from "./persistence-store";
+
+const SESSION_PEER_OVERRIDE_NAMESPACE = "session-peer-overrides";
+
+export type SessionPeerSourceKind = "direct" | "group";
+
+interface SessionPeerOverrideBucket {
+  peers: Record<string, string>;
+}
+
+function buildSourceKey(sourceKind: SessionPeerSourceKind, sourceId: string): string {
+  return `${sourceKind}:${sourceId}`;
+}
+
+function readBucket(storePath: string, accountId: string): SessionPeerOverrideBucket {
+  return readNamespaceJson<SessionPeerOverrideBucket>(SESSION_PEER_OVERRIDE_NAMESPACE, {
+    storePath,
+    scope: { accountId },
+    fallback: { peers: {} },
+  });
+}
+
+function writeBucket(storePath: string, accountId: string, bucket: SessionPeerOverrideBucket): void {
+  writeNamespaceJsonAtomic(SESSION_PEER_OVERRIDE_NAMESPACE, {
+    storePath,
+    scope: { accountId },
+    data: bucket,
+  });
+}
+
+export function getSessionPeerOverride(params: {
+  storePath: string;
+  accountId: string;
+  sourceKind: SessionPeerSourceKind;
+  sourceId: string;
+}): string | undefined {
+  const bucket = readBucket(params.storePath, params.accountId);
+  const sourceKey = buildSourceKey(params.sourceKind, params.sourceId);
+  const legacyKey = params.sourceKind === "group" ? params.sourceId : undefined;
+  const value = bucket.peers[sourceKey] ?? (legacyKey ? bucket.peers[legacyKey] : undefined);
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function setSessionPeerOverride(params: {
+  storePath: string;
+  accountId: string;
+  sourceKind: SessionPeerSourceKind;
+  sourceId: string;
+  peerId: string;
+}): void {
+  const bucket = readBucket(params.storePath, params.accountId);
+  const sourceKey = buildSourceKey(params.sourceKind, params.sourceId);
+  bucket.peers[sourceKey] = params.peerId.trim();
+  writeBucket(params.storePath, params.accountId, bucket);
+}
+
+export function clearSessionPeerOverride(params: {
+  storePath: string;
+  accountId: string;
+  sourceKind: SessionPeerSourceKind;
+  sourceId: string;
+}): boolean {
+  const bucket = readBucket(params.storePath, params.accountId);
+  const sourceKey = buildSourceKey(params.sourceKind, params.sourceId);
+  const legacyKey = params.sourceKind === "group" ? params.sourceId : undefined;
+  const existed = Object.prototype.hasOwnProperty.call(bucket.peers, sourceKey)
+    || (legacyKey ? Object.prototype.hasOwnProperty.call(bucket.peers, legacyKey) : false);
+  if (!existed) {
+    return false;
+  }
+  delete bucket.peers[sourceKey];
+  if (legacyKey) {
+    delete bucket.peers[legacyKey];
+  }
+  writeBucket(params.storePath, params.accountId, bucket);
+  return true;
+}