@soimy/dingtalk 3.2.0 → 3.4.0

package/src/send-service.ts

@@ -9,20 +9,23 @@ import {
 import { stripTargetPrefix } from "./config";
 import { getLogger } from "./logger-context";
 import { getVoiceDurationMs, uploadMedia as uploadMediaUtil } from "./media-utils";
-import { detectMarkdownAndExtractTitle } from "./message-utils";
+import { convertMarkdownTablesToPlainText, detectMarkdownAndExtractTitle } from "./message-utils";
+import { DEFAULT_MESSAGE_CONTEXT_TTL_DAYS, upsertOutboundMessageContext } from "./message-context-store";
 import { resolveOriginalPeerId } from "./peer-id-registry";
 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,
+  QuotedRef,
   SendMessageOptions,
   SessionWebhookResponse,
 } from "./types";
@@ -30,6 +33,91 @@ 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 firstTrimmedString(...candidates: unknown[]): string | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return undefined;
+}
+
+function extractOutboundDeliveryMetadata(payload: unknown): {
+  messageId?: string;
+  processQueryKey?: string;
+  outTrackId?: string;
+  cardInstanceId?: string;
+} {
+  if (!payload || typeof payload !== "object") {
+    return {};
+  }
+  const data = payload as Record<string, unknown>;
+  const tracking =
+    data.tracking && typeof data.tracking === "object"
+      ? (data.tracking as Record<string, unknown>)
+      : undefined;
+  const messageId = firstTrimmedString(data.messageId, data.msgid, tracking?.messageId, tracking?.msgid);
+  const processQueryKey = firstTrimmedString(data.processQueryKey, tracking?.processQueryKey);
+  const outTrackId = firstTrimmedString(data.outTrackId, tracking?.outTrackId);
+  const cardInstanceId = firstTrimmedString(data.cardInstanceId, tracking?.cardInstanceId);
+  return { messageId, processQueryKey, outTrackId, cardInstanceId };
+}
+
+function persistOutboundMessageContext(params: {
+  storePath?: string;
+  accountId?: string;
+  conversationId: string;
+  text?: string;
+  messageType?: string;
+  createdAt?: number;
+  quotedRef?: QuotedRef;
+  log?: Logger;
+  delivery: {
+    messageId?: string;
+    processQueryKey?: string;
+    outTrackId?: string;
+    cardInstanceId?: string;
+    kind?: "session" | "proactive-text" | "proactive-card" | "proactive-media";
+  };
+}): void {
+  if (!params.storePath || !params.accountId) {
+    return;
+  }
+  params.log?.debug?.(
+    `[DingTalk][QuotedRef][Persist] direction=outbound scope=${params.conversationId} ` +
+    `messageType=${params.messageType || "(none)"} processQueryKey=${params.delivery.processQueryKey || "(none)"} ` +
+    `messageId=${params.delivery.messageId || "(none)"} quotedRef=${params.quotedRef ? JSON.stringify(params.quotedRef) : "(none)"}`,
+  );
+  upsertOutboundMessageContext({
+    storePath: params.storePath,
+    accountId: params.accountId,
+    conversationId: params.conversationId,
+    createdAt: params.createdAt ?? Date.now(),
+    text: params.text,
+    messageType: params.messageType,
+    ttlMs: DEFAULT_MESSAGE_CONTEXT_TTL_DAYS * 24 * 60 * 60 * 1000,
+    topic: null,
+    quotedRef: params.quotedRef,
+    delivery: params.delivery,
+  });
+}
+
+function buildPersistedOutboundText(text: string, options: SendMessageOptions): string {
+  if (text) {
+    return text;
+  }
+  if (options.mediaPath && options.mediaType) {
+    return `[media:${options.mediaType}] ${options.mediaPath}`;
+  }
+  return text;
+}
+
 function composeCardContentForAppend(previous: string | undefined, incoming: string): string {
   const prev = previous ?? "";
   if (!prev) {
@@ -50,6 +138,37 @@ function composeCardContentForAppend(previous: string | undefined, incoming: str
   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;
@@ -99,7 +218,7 @@ export async function sendProactiveTextOrMarkdown(
   target: string,
   text: string,
   options: SendMessageOptions = {},
-): Promise<AxiosResponse> {
+): Promise<ProactiveTextSendResult> {
   const log = options.log || getLogger();
 
   // Support group:/user: prefix and restore original case-sensitive conversationId.
@@ -115,13 +234,22 @@ export async function sendProactiveTextOrMarkdown(
 
   // In card mode, use card API to avoid oToMessages/batchSend permission requirement.
   const messageType = config.messageType || "markdown";
-  if (messageType === "card" && config.cardTemplateId) {
+  if (messageType === "card" && config.cardTemplateId && !options.forceMarkdown) {
     log?.debug?.(
       `[DingTalk] Using card API for proactive message to user ${resolvedTarget}${proactiveRiskTag}`,
     );
     const result = await sendProactiveCardText(config, resolvedTarget, text, log);
     if (result.ok) {
-      return {} as AxiosResponse; // Return empty response for compatibility
+      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"}`,
@@ -133,7 +261,8 @@ export async function sendProactiveTextOrMarkdown(
     ? "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 = config.convertMarkdownTables !== false ? convertMarkdownTablesToPlainText(text) : text;
+  const { useMarkdown, title } = detectMarkdownAndExtractTitle(normalizedText, options, "OpenClaw 提醒");
 
   log?.debug?.(
     `[DingTalk] Sending proactive message to ${isGroup ? "group" : "user"} ${resolvedTarget} with title "${title}"${proactiveRiskTag}`,
@@ -142,8 +271,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,
@@ -163,6 +292,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);
@@ -273,12 +403,27 @@ 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 delivery = extractOutboundDeliveryMetadata(result.data);
+    const messageId = delivery.messageId || delivery.processQueryKey || delivery.outTrackId;
+    persistOutboundMessageContext({
+      storePath: options.storePath,
+      accountId: options.accountId,
+      conversationId: options.conversationId || resolvedTarget,
+      text: `[media:${mediaType}] ${mediaPath}`,
+      messageType: "outbound-proactive-media",
+      quotedRef: options.quotedRef,
+      log,
+      delivery: {
+        ...delivery,
+        kind: "proactive-media",
+      },
+    });
     return { ok: true, data: result.data, messageId };
   } catch (err: any) {
     log?.error?.(`[DingTalk] Failed to send proactive media: ${err.message}`);
@@ -306,7 +451,38 @@ 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 fallbackDisplayText = `📎 媒体发送失败，兜底链接/路径：${mediaPath}`;
+    const fallbackPersistedText = `媒体发送失败，兜底链接/路径：${mediaPath}`;
+    const fallback = await sendProactiveTextOrMarkdown(
+      config,
+      target,
+      fallbackDisplayText,
+      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"}` };
+    }
+
+    const fallbackDelivery = extractOutboundDeliveryMetadata(fallback);
+    const fallbackMessageId =
+      fallbackDelivery.messageId || fallbackDelivery.processQueryKey || fallbackDelivery.outTrackId;
+    persistOutboundMessageContext({
+      storePath: options.storePath,
+      accountId: options.accountId,
+      conversationId: options.conversationId || normalizedTarget,
+      text: fallbackPersistedText,
+      messageType: "outbound-proactive-fallback",
+      quotedRef: options.quotedRef,
+      log,
+      delivery: {
+        ...fallbackDelivery,
+        kind: isTrackingResult(fallback as ProactiveTextSendResult) ? "proactive-card" : "proactive-text",
+      },
+    });
+    return { ok: true, data: fallback, messageId: fallbackMessageId };
   }
 }
 
@@ -342,52 +518,62 @@ 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 = config.convertMarkdownTables !== false ? convertMarkdownTablesToPlainText(text) : 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; card?: AICardInstance } = {},
-): 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();
 
-    if (messageType === "card" && options.card) {
+    if (messageType === "card" && options.card && !options.forceMarkdown) {
       const card = options.card;
       if (isCardInTerminalState(card.state)) {
         if (options.sessionWebhook) {
@@ -400,17 +586,19 @@ export async function sendMessage(
           if (!proactiveResult.ok) {
             return { ok: false, error: proactiveResult.error || "Card send failed" };
           }
-          return { ok: true };
+          return {
+            ok: true,
+            tracking: {
+              processQueryKey: proactiveResult.processQueryKey,
+              outTrackId: proactiveResult.outTrackId,
+              cardInstanceId: proactiveResult.cardInstanceId,
+            },
+          };
         }
-      } else {
+      } else if (options.cardUpdateMode === "append") {
         try {
-          const mode = options.cardUpdateMode || "replace";
-          const shouldFinalize = mode === "finalize" || options.cardFinalize === true;
-          const nextContent =
-            mode === "append"
-              ? composeCardContentForAppend(card.lastStreamedContent, text)
-              : text;
-          await streamAICard(card, nextContent, shouldFinalize, log);
+          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}`);
@@ -422,12 +610,46 @@ export async function sendMessage(
     }
 
     if (options.sessionWebhook) {
-      await sendBySession(config, options.sessionWebhook, text, options);
-      return { ok: true };
+      const data = await sendBySession(config, options.sessionWebhook, text, options);
+      const delivery = extractOutboundDeliveryMetadata(data);
+      const messageId = delivery.messageId || delivery.processQueryKey || delivery.outTrackId;
+      const persistedText = buildPersistedOutboundText(text, options);
+      persistOutboundMessageContext({
+        storePath: options.storePath,
+        accountId: options.accountId,
+        conversationId: options.conversationId || conversationId,
+        text: persistedText,
+        messageType: options.mediaPath && options.mediaType ? "outbound-media" : "outbound",
+        quotedRef: options.quotedRef,
+        log,
+        delivery: {
+          ...delivery,
+          kind: "session",
+        },
+      });
+      return { ok: true, data, messageId };
     }
 
     const result = await sendProactiveTextOrMarkdown(config, conversationId, text, options);
-    return { ok: true, data: result };
+    const delivery = extractOutboundDeliveryMetadata(result);
+    const messageId = delivery.messageId || delivery.processQueryKey || delivery.outTrackId;
+    persistOutboundMessageContext({
+      storePath: options.storePath,
+      accountId: options.accountId,
+      conversationId: options.conversationId || conversationId,
+      text,
+      messageType: "outbound-proactive",
+      quotedRef: options.quotedRef,
+      log,
+      delivery: {
+        ...delivery,
+        kind: isTrackingResult(result) ? "proactive-card" : "proactive-text",
+      },
+    });
+    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

@@ -4,6 +4,8 @@
 
 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.

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;
+}