@aspalagin/openclaw-max 0.7.3 → 0.8.1

package/src/config-schema.ts

@@ -2,13 +2,24 @@
  * MAX channel config Zod schema
  */
 
-import { MarkdownConfigSchema, ToolPolicySchema } from 'openclaw/plugin-sdk/channel-config-schema';
+import {
+  ChannelPreviewStreamingConfigSchema,
+  MarkdownConfigSchema,
+  MentionPatternsPolicySchema,
+  ToolPolicySchema,
+} from 'openclaw/plugin-sdk/channel-config-schema';
+import { buildOptionalSecretInputSchema } from 'openclaw/plugin-sdk/secret-input';
 import { z } from 'zod';
 
-// Defaulted policy fields are built with this package's own zod: wrapping the
-// SDK's enum instances in `.optional().default()` breaks as soon as the plugin
-// and the gateway resolve different zod copies (4.4 vs 4.6 → "expected
-// nonoptional"). Values mirror the SDK's DmPolicySchema/GroupPolicySchema.
+// Policy fields are built with this package's own zod: wrapping the SDK's enum
+// instances in `.optional().default()` broke as soon as the plugin and the
+// gateway resolved different zod copies (4.4 vs 4.6 → "expected nonoptional").
+// Values mirror the SDK's DmPolicySchema/GroupPolicySchema.
+//
+// No field carries a schema default: the gateway writes JSON-schema defaults
+// into the runtime config, also under accounts.<id>, and a default there would
+// hide the channel-level value a named account inherits. The effective
+// defaults (pairing, allowlist, …) are applied where the values are read.
 export const DmPolicySchema = z.enum(['pairing', 'allowlist', 'open', 'disabled']);
 export const GroupPolicySchema = z.enum(['open', 'disabled', 'allowlist']);
 
@@ -52,46 +63,134 @@ export const MaxGroupSchema = z
   .object({
     requireMention: z.boolean().optional(),
     tools: ToolPolicySchema.optional(),
+    /** Skills a group turn may load (core skillFilter; [] = none). */
     skills: z.array(z.string()).optional(),
+    /** false: the group is ignored under any groupPolicy. */
     enabled: z.boolean().optional(),
     allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    /** Extra system prompt of group turns (core GroupSystemPrompt). */
     systemPrompt: z.string().optional(),
+    /** Skip transcribing a captionless voice message to find a mention pattern. */
+    disableAudioPreflight: z.boolean().optional(),
   })
   .strict();
 
 /**
- * MAX account config (base schema for both top-level and accounts.*)
+ * MAX account config (base schema for both top-level and accounts.*).
+ * accounts.<id> inherits every channel-level value it does not set, except
+ * the per-bot keys (token, name, webhook; MAX_ACCOUNT_OWN_KEYS in accounts.ts).
  */
 export const MaxAccountSchemaBase = z
   .object({
     name: z.string().optional(),
     enabled: z.boolean().optional(),
+    /** No effect in MAX: neither the plugin nor core reads it for this channel. */
     markdown: MarkdownConfigSchema.optional(),
-    botToken: z.string().optional(),
+    /** Plain token or a core SecretRef { source, provider, id } (also webhookSecret, httpProxy) */
+    botToken: buildOptionalSecretInputSchema(),
     tokenFile: z.string().optional(),
-    dmPolicy: DmPolicySchema.optional().default('pairing'),
+    /** Default "pairing" (applied where read); named accounts inherit the channel value. */
+    dmPolicy: DmPolicySchema.optional(),
     allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
     groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
-    groupPolicy: GroupPolicySchema.optional().default('allowlist'),
+    /** Default "allowlist" (applied where read); named accounts inherit the channel value. */
+    groupPolicy: GroupPolicySchema.optional(),
     groups: z.record(z.string(), MaxGroupSchema.optional()).optional(),
+    /**
+     * Where core mention patterns (messages.groupChat / agent groupChat
+     * mentionPatterns) apply in MAX groups: mode allow|deny, allowIn, denyIn.
+     */
+    mentionPatterns: MentionPatternsPolicySchema.optional(),
     /** Update transport; default: "webhook" when webhookUrl is set, otherwise "polling" */
     transport: z.enum(['polling', 'webhook']).optional(),
     webhookUrl: z.string().optional(),
     /** MAX secret: 5–256 of [A-Za-z0-9_-]; checked at start */
-    webhookSecret: z.string().optional(),
+    webhookSecret: buildOptionalSecretInputSchema(),
     /** File holding the webhook secret (regular file, not a symlink) */
     webhookSecretFile: z.string().optional(),
     webhookPath: z.string().optional(),
+    /**
+     * Webhook queue: "durable" (default) journals every accepted update before
+     * MAX gets its 200, so a restart or crash does not lose it; "memory" keeps
+     * the 0.7 in-memory queue. maxPending (default 5000) bounds accepted but
+     * unhandled updates; when full, overflow "reject" (default) answers 503
+     * so MAX redelivers later, "drop" acknowledges and drops.
+     */
+    webhookQueue: z
+      .object({
+        mode: z.enum(['durable', 'memory']).optional(),
+        maxPending: z.number().int().positive().optional(),
+        overflow: z.enum(['reject', 'drop']).optional(),
+      })
+      .strict()
+      .optional(),
+    /**
+     * Messages, edits, button presses and bot_started older than this many
+     * minutes (by MAX event time) are skipped instead of answered: after a
+     * long outage the bot does not reply to hours-old messages. Default 60;
+     * 0 answers any age.
+     */
+    maxEventAgeMinutes: z.number().int().min(0).optional(),
+    /**
+     * Debug logs of inbound messages carry a text preview (50 characters).
+     * Off by default: logs hold message type, length and ids, never text.
+     */
+    logMessagePreview: z.boolean().optional(),
+    /**
+     * Read by core, not the plugin: the embedded agent runtime keeps this many
+     * recent turns of a group session (historyLimit) or DM session
+     * (dmHistoryLimit, dms.<peer>.historyLimit) in the prompt.
+     */
     historyLimit: z.number().int().min(0).optional(),
     dmHistoryLimit: z.number().int().min(0).optional(),
     dms: z.record(z.string(), DmConfigSchema.optional()).optional(),
+    /** Characters per outgoing message (core resolution), at most MAX's 4000. */
     textChunkLimit: z.number().int().positive().optional(),
+    /** No effect in MAX: use streamMode / streaming.mode "block". */
     blockStreaming: z.boolean().optional(),
     streamMode: z.enum(['off', 'partial', 'block']).optional(),
+    /**
+     * Core streaming settings; streaming.mode wins over streamMode. "progress"
+     * shows one turn-status message (streaming.progress: label, toolProgress,
+     * maxLines, …) that is deleted once the answer landed. Default off.
+     */
+    streaming: ChannelPreviewStreamingConfigSchema.optional(),
+    /** No effect in MAX: core reads streaming.block.coalesce instead. */
     blockStreamingCoalesce: BlockStreamingCoalesceSchema.optional(),
+    /** Prefix of agent replies, applied by core ("auto" = agent name). */
     responsePrefix: z.string().optional(),
     mediaMaxMb: z.number().positive().optional(),
+    /** Most media attachments downloaded per inbound message (default 12); the rest is noted. */
+    mediaMaxCount: z.number().int().positive().optional(),
     markSeen: z.boolean().optional(),
+    /**
+     * Chats message-tool actions may act in: "admitted" (default) — the current
+     * chat, owner requests and chats admitted by the DM/group policy;
+     * "current" — non-owner turns only in their own chat; "off" — no check.
+     */
+    actionScope: z.enum(['admitted', 'current', 'off']).optional(),
+    /**
+     * Send defaults; an explicit value of the call (core `silent`,
+     * channelData.max) wins. notify=false sends without push notifications
+     * (channels always notify).
+     */
+    notify: z.boolean().optional(),
+    disableLinkPreview: z.boolean().optional(),
+    /**
+     * MAX Bot API base URL (default https://platform-api2.max.ru), e.g. a test
+     * stand; https only, http just for loopback hosts. Checked at start.
+     */
+    apiBaseUrl: z.string().optional(),
+    /**
+     * HTTP(S) proxy for all MAX traffic of the account (API, uploads, media
+     * downloads), e.g. http://user:pass@host:3128; "" turns an inherited one
+     * off. Sensitive: credentials are never logged. Accepts a SecretRef.
+     */
+    httpProxy: buildOptionalSecretInputSchema(),
+    /**
+     * Message-tool actions: false turns one off (hidden from the tool and
+     * refused). Other values, including the legacy policy strings, leave it on.
+     */
     actions: z
       .record(
         z.string(),
@@ -142,6 +241,8 @@ const MaxBotCommandSchema = z
 export const MaxConfigSchema = MaxAccountSchemaBase.extend({
   accounts: z.record(z.string(), MaxAccountSchema.optional()).optional(),
   commands: z.array(MaxBotCommandSchema).max(32).optional(),
+  /** Accepted as in the manifest; the channel-level options are always the "default" account. */
+  defaultAccount: z.string().optional(),
 }).superRefine((value, ctx) => {
   requireOpenAllowFrom({
     policy: value.dmPolicy,

package/src/deliver.ts

@@ -1,22 +1,82 @@
 /**
  * Reply delivery for the inbound pipeline: callback answers, markdown chunks
- * with the keyboard on the last one, media albums and delivery.pin.
+ * with the keyboard on the last one (the first chunk may fill the stream
+ * draft), media albums and delivery.pin. Failures are rejected per the SDK
+ * delivery contract instead of being swallowed.
  */
 
 import type { ChannelLogSink } from 'openclaw/plugin-sdk/channel-contract';
+import { createChannelPartialDeliveryError } from 'openclaw/plugin-sdk/channel-inbound';
 import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+import { PlatformMessageNotDispatchedError } from 'openclaw/plugin-sdk/error-runtime';
+import { LocalMediaAccessError } from 'openclaw/plugin-sdk/web-media';
 
 import type { ResolvedMaxAccount } from './accounts.js';
-import { readMaxDeliveryPin } from './presentation.js';
+import { MaxApiError } from './api.js';
+import { readMaxDeliveryPin, resolveMaxTextChunkLimit } from './presentation.js';
 import { getMaxRuntime } from './runtime.js';
 import {
   answerMaxCallback,
+  type MaxLocalMediaAccess,
   pinMaxMessage,
   readMaxChannelButtons,
-  readMaxChannelSendOptions,
+  resolveMaxSendFlags,
   sendMaxMediaGroup,
   sendMaxMessage,
 } from './send.js';
+import type { MaxDraftStream } from './stream-draft.js';
+
+/** What already reached the chat when a later send failed. */
+interface MaxVisibleDelivery {
+  messageIds: string[];
+  /** Text chunks the recipient can see, in order. */
+  texts: string[];
+  /** A button press was answered (POST /answers: visible, but no message id). */
+  callbackAnswered?: boolean;
+}
+
+/**
+ * Delivery failure per the SDK contract: once anything became visible (a
+ * chunk, an album, the stream draft) the error keeps that subset
+ * (createChannelPartialDeliveryError); a send MAX refused outright (4xx)
+ * proves nothing was dispatched (PlatformMessageNotDispatchedError, retryable
+ * only for 429), as does a local file refused by the media access policy;
+ * anything else (5xx, timeout, network) may have been applied and is
+ * rethrown as is.
+ * @internal exported for testing.
+ */
+export function toMaxDeliveryError(err: unknown, visible: MaxVisibleDelivery): unknown {
+  if (visible.messageIds.length > 0 || visible.callbackAnswered) {
+    const content = visible.texts.join('\n\n');
+    return createChannelPartialDeliveryError(err, {
+      visibleReplySent: true,
+      messageIds: [...visible.messageIds],
+      ...(content ? { content } : {}),
+    });
+  }
+  if (err instanceof MaxApiError && err.status >= 400 && err.status < 500) {
+    return new PlatformMessageNotDispatchedError(err.message, {
+      cause: err,
+      retryable: err.status === 429,
+    });
+  }
+  if (err instanceof LocalMediaAccessError) {
+    return new PlatformMessageNotDispatchedError(err.message, { cause: err, retryable: false });
+  }
+  return err;
+}
+
+function logSendFailure(
+  account: ResolvedMaxAccount,
+  log: ChannelLogSink | undefined,
+  what: string,
+  err: unknown,
+): void {
+  const body = (err as { body?: unknown })?.body;
+  log?.error(
+    `[${account.accountId}] MAX ${what} failed: ${String(err)}${body ? ` body=${JSON.stringify(body)}` : ''}`,
+  );
+}
 
 export async function deliverMaxReply(params: {
   payload: {
@@ -26,87 +86,138 @@ export async function deliverMaxReply(params: {
     replyToId?: string;
     channelData?: unknown;
     delivery?: unknown;
+    /** Voice reply (TTS, [[audio_as_voice]]): the audio goes as a MAX voice message. */
+    audioAsVoice?: boolean;
   };
   account: ResolvedMaxAccount;
   chatId: string;
   replyToId?: string;
   callbackId?: string;
+  /**
+   * Shared by the payloads of one turn: a press is answered by the first of
+   * them only (a second answer would replace the first in the same message).
+   */
+  callbackState?: { answered: boolean };
   config: OpenClawConfig;
   log?: ChannelLogSink;
   statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  /** Edit-streaming draft: the first text chunk replaces it instead of a new message. */
+  draft?: MaxDraftStream;
+  /** Allowed roots for local reply media (the agent's scoped media roots). */
+  localMedia?: MaxLocalMediaAccess;
+  /** Reply dispatcher kind of the payload: tool summaries go without link previews by default. */
+  kind?: 'tool' | 'block' | 'final';
 }): Promise<void> {
   const { payload, account, chatId, config, log, statusSink } = params;
   const core = getMaxRuntime();
   const buttons = readMaxChannelButtons(payload.channelData);
-  const sendOptions = readMaxChannelSendOptions(payload.channelData);
+  // channelData.max (notify, silent, disableLinkPreview) beats the account defaults.
+  const sendOptions = resolveMaxSendFlags(account.config, { channelData: payload.channelData });
+  // Tool summaries (verbose mode) quote paths and file names MAX would preview
+  // as links (`notes.md` reads as a domain); an explicit disableLinkPreview wins.
+  if (params.kind === 'tool' && sendOptions.disableLinkPreview === undefined) {
+    sendOptions.disableLinkPreview = true;
+  }
+  // A draft send still in flight settles first, so it is replaced, not orphaned.
+  if (params.draft) await params.draft.settle();
+  // Only the first text final replaces the draft: once it carries a final
+  // text, later final payloads of the turn go as new messages.
+  const draftMid =
+    payload.text && !params.draft?.finalized ? (params.draft?.messageId ?? undefined) : undefined;
+
+  // Everything the recipient can already see; a visible stream draft counts
+  // until it is replaced or deleted.
+  const visible: MaxVisibleDelivery = { messageIds: draftMid ? [draftMid] : [], texts: [] };
+  let failure: { err: unknown } | undefined;
 
-  if (params.callbackId && (payload.text || buttons?.length)) {
+  // A button press is answered with the text and keyboard (POST /answers);
+  // the reply's media still follows in the chat below.
+  const answersCallback = Boolean(
+    params.callbackId &&
+    !params.callbackState?.answered &&
+    // A finalized draft carries the answer: the pressed message stays as is.
+    !params.draft?.finalized &&
+    !draftMid &&
+    (payload.text || buttons?.length),
+  );
+  if (answersCallback) {
+    if (params.callbackState) params.callbackState.answered = true;
     try {
-      await answerMaxCallback(params.callbackId, payload.text ?? '', {
+      await answerMaxCallback(params.callbackId as string, payload.text ?? '', {
         token: account.token,
         format: 'markdown',
         buttons,
       });
+      visible.callbackAnswered = true;
+      if (payload.text) visible.texts.push(payload.text);
       statusSink?.({ lastOutboundAt: Date.now() });
     } catch (err: unknown) {
-      const body = (err as { body?: unknown })?.body;
-      log?.error(
-        `[${account.accountId}] MAX callback answer failed: ${String(err)}${body ? ` body=${JSON.stringify(body)}` : ''}`,
-      );
+      // Like a failed text chunk: the media still goes, then reject.
+      logSendFailure(account, log, 'callback answer', err);
+      failure = { err };
     }
-    return;
   }
 
   // delivery.pin: pin the first delivered message (first chunk).
   let firstMessageId: string | undefined;
   let firstChatType: string | undefined;
-  const noteDelivered = (messageId: string, chatType?: string) => {
+  const noteDelivered = (messageId: string, chatType?: string, text?: string) => {
+    if (messageId && !visible.messageIds.includes(messageId)) visible.messageIds.push(messageId);
+    if (text) visible.texts.push(text);
     if (!firstMessageId && messageId) {
       firstMessageId = messageId;
       firstChatType = chatType;
     }
   };
+  const sendTextMessage = async (text: string, messageButtons: typeof buttons) => {
+    const sent = await sendMaxMessage(chatId, text, {
+      token: account.token,
+      replyToMessageId: params.replyToId,
+      format: 'markdown',
+      buttons: messageButtons,
+      ...sendOptions,
+    });
+    noteDelivered(sent.messageId, sent.raw.message?.recipient?.chat_type, text);
+    statusSink?.({ lastOutboundAt: Date.now() });
+  };
 
-  if (payload.text) {
-    const chunkLimit = 4000; // MAX message limit
+  if (answersCallback) {
+    // The text went with the callback answer.
+  } else if (payload.text) {
+    const chunkLimit = resolveMaxTextChunkLimit(config, account.accountId);
     const chunkMode = core.channel.text.resolveChunkMode(config, 'max', account.accountId);
     const chunks = core.channel.text.chunkMarkdownTextWithMode(payload.text, chunkLimit, chunkMode);
 
     for (let index = 0; index < chunks.length; index += 1) {
       const chunk = chunks[index];
+      const chunkButtons = index === chunks.length - 1 ? buttons : undefined;
+      if (index === 0 && draftMid && params.draft) {
+        // The draft becomes the first chunk. If MAX refuses that edit, the
+        // stale partial draft is deleted and the answer goes as new messages.
+        if (await params.draft.finalize(chunk, chunkButtons)) {
+          noteDelivered(draftMid, undefined, chunk);
+          continue;
+        }
+        if (await params.draft.discard()) {
+          visible.messageIds.splice(visible.messageIds.indexOf(draftMid), 1);
+        }
+      }
       try {
-        const sent = await sendMaxMessage(chatId, chunk, {
-          token: account.token,
-          replyToMessageId: params.replyToId,
-          format: 'markdown',
-          buttons: index === chunks.length - 1 ? buttons : undefined,
-          ...sendOptions,
-        });
-        noteDelivered(sent.messageId, sent.raw.message?.recipient?.chat_type);
-        statusSink?.({ lastOutboundAt: Date.now() });
+        await sendTextMessage(chunk, chunkButtons);
       } catch (err: unknown) {
-        const body = (err as { body?: unknown })?.body;
-        log?.error(
-          `[${account.accountId}] MAX send failed: ${String(err)}${body ? ` body=${JSON.stringify(body)}` : ''}`,
-        );
+        // A later chunk after a gap would garble the answer: stop the text,
+        // still send the media (independent content), then reject.
+        logSendFailure(account, log, 'send', err);
+        failure = { err };
+        break;
       }
     }
   } else if (buttons?.length) {
     try {
-      const sent = await sendMaxMessage(chatId, '', {
-        token: account.token,
-        replyToMessageId: params.replyToId,
-        format: 'markdown',
-        buttons,
-        ...sendOptions,
-      });
-      noteDelivered(sent.messageId, sent.raw.message?.recipient?.chat_type);
-      statusSink?.({ lastOutboundAt: Date.now() });
+      await sendTextMessage('', buttons);
     } catch (err: unknown) {
-      const body = (err as { body?: unknown })?.body;
-      log?.error(
-        `[${account.accountId}] MAX send failed: ${String(err)}${body ? ` body=${JSON.stringify(body)}` : ''}`,
-      );
+      logSendFailure(account, log, 'send', err);
+      failure = { err };
     }
   }
 
@@ -117,24 +228,41 @@ export async function deliverMaxReply(params: {
       ? [payload.mediaUrl]
       : [];
 
-  // Images/videos go as albums (up to 12 per message); https image links are
-  // sent by URL, other remote media is downloaded and uploaded.
+  // Images/videos go as albums (up to 12 per message); public https image
+  // links are sent by URL, other remote media is downloaded (SSRF-guarded)
+  // and uploaded, local files are read only under the agent's media roots.
+  // Voice replies: the text (if any) went above as its own message(s), the
+  // audio follows without a caption; the text is never taken from the
+  // spoken text, so it reaches the chat once.
+  const asVoice = payload.audioAsVoice === true;
   if (mediaList.length) {
     const sent = await sendMaxMediaGroup(chatId, '', mediaList, {
       token: account.token,
       replyToMessageId: params.replyToId,
       mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+      localMedia: params.localMedia,
+      asVoice,
       ...sendOptions,
-      onError: (err, failed) =>
+      onError: (err, failed) => {
         log?.error(
           `[${account.accountId}] MAX media send failed (${failed.length} item(s)): ${String(err)}`,
-        ),
+        );
+        failure ??= { err };
+      },
     });
     for (const id of sent.messageIds) noteDelivered(id);
     if (sent.messageIds.length) statusSink?.({ lastOutboundAt: Date.now() });
+    // A voice-only reply (no visible text) leaves a partial stream draft of
+    // the same answer behind: once the audio is delivered the draft goes; a
+    // draft that already carries a final text stays.
+    const draft = params.draft;
+    if (asVoice && !payload.text && sent.messageIds.length && draft?.messageId) {
+      if (!draft.finalized) await draft.discard();
+    }
   }
 
-  const pin = readMaxDeliveryPin(payload.delivery);
+  // The message a callback answer changed has no id here to pin.
+  const pin = answersCallback ? undefined : readMaxDeliveryPin(payload.delivery);
   if (pin && firstMessageId) {
     try {
       const pinned = await pinMaxMessage(chatId, firstMessageId, {
@@ -154,15 +282,6 @@ export async function deliverMaxReply(params: {
       );
     }
   }
-}
 
-/** channelData with `max.buttons` removed (other max options kept). */
-export function withoutMaxButtons(channelData: unknown): unknown {
-  if (!channelData || typeof channelData !== 'object' || Array.isArray(channelData))
-    return channelData;
-  const maxData = (channelData as Record<string, unknown>).max;
-  if (!maxData || typeof maxData !== 'object' || Array.isArray(maxData)) return channelData;
-  const rest = { ...(maxData as Record<string, unknown>) };
-  delete rest.buttons;
-  return { ...(channelData as Record<string, unknown>), max: rest };
+  if (failure) throw toMaxDeliveryError(failure.err, visible);
 }

package/src/dispatch.ts

@@ -7,7 +7,7 @@
 import type { ResolvedMaxAccount } from './accounts.js';
 import type { MaxMessage, MaxUpdate, MaxUser } from './api.js';
 import { processCallback } from './callbacks.js';
-import { processIncomingMessage } from './inbound.js';
+import { describeMaxLogText, processIncomingMessage } from './inbound.js';
 import type { MaxMonitorOptions } from './monitor-types.js';
 
 /** mark_seen vanished from current MAX docs; keep behind config (default on). */
@@ -23,8 +23,8 @@ function sendReadReceipt(chatId: number | undefined, opts: MaxMonitorOptions): v
       log?.debug?.(`[${account.accountId}] mark_seen failed: ${String(err)}`);
     });
   }
-  // typing_on is sent once, by processIncomingMessage right before the agent
-  // run — only for messages that pass the group/DM gates.
+  // typing_on is kept up by processIncomingMessage for the agent turn — only
+  // for messages that pass the group/DM gates.
 }
 
 /** Route one update by update_type (shared by the polling loop and the webhook queue). */
@@ -67,22 +67,23 @@ export async function dispatchUpdate(update: MaxUpdate, opts: MaxMonitorOptions)
     }
 
     case 'message_edited': {
-      if (!update.message) break;
+      // An edit always carries the edited body; a forward-only message
+      // (body null) cannot be edited.
+      if (!update.message?.body) break;
       // Skip edits from the bot itself
       if (opts.botUserId && update.message.sender?.user_id === opts.botUserId) break;
       log?.debug?.(
-        `[${account.accountId}] Message edited: ${update.message?.body?.mid} text="${update.message?.body?.text ?? '<null>'}" hasBody=${!!update.message?.body}`,
+        `[${account.accountId}] Message edited: ${update.message?.body?.mid} ${describeMaxLogText(account, update.message?.body?.text)} hasBody=${!!update.message?.body}`,
       );
       statusSink?.({ lastInboundAt: Date.now() });
       // Mark as read (typing starts once the message reaches the agent)
       sendReadReceipt(update.message.recipient?.chat_id, opts);
       // Process edited message through the same pipeline as new messages.
       // Use a unique mid suffix to avoid OpenClaw dedup (same mid = skipped).
-      const editedMessage = { ...update.message };
-      const originalMid = editedMessage.body.mid;
-      editedMessage.body = {
-        ...editedMessage.body,
-        mid: `${originalMid}_edited_${update.timestamp}`,
+      const originalMid = update.message.body.mid;
+      const editedMessage = {
+        ...update.message,
+        body: { ...update.message.body, mid: `${originalMid}_edited_${update.timestamp}` },
       };
 
       // MAX message_edited may not include text — fetch it from API if missing
@@ -101,7 +102,7 @@ export async function dispatchUpdate(update: MaxUpdate, opts: MaxMonitorOptions)
                 editedMessage.body.attachments = fetchedMsg.body.attachments;
               }
               log?.debug?.(
-                `[${account.accountId}] Fetched edited text: "${fetchedMsg.body.text.slice(0, 50)}"`,
+                `[${account.accountId}] Fetched edited text: ${describeMaxLogText(account, fetchedMsg.body.text)}`,
               );
             }
           }

package/src/gateway-drain.ts

@@ -0,0 +1,45 @@
+/**
+ * Core's refusal of new turns while the gateway drains for a stop or restart.
+ *
+ * During a graceful stop core keeps the channels running (up to its drain
+ * budget, minutes) but refuses to start new work with `GatewayDrainingError`.
+ * Refused before core adopted the turn, the update was never handled: the
+ * webhook queue and the polling loop keep it and retry after a pause until the
+ * channel stops; its journal row then stays on disk for the next process. The
+ * plugin SDK exports nothing for this error, so it is recognized by name.
+ */
+
+import { sleepWithAbort } from 'openclaw/plugin-sdk/runtime-env';
+
+const DRAINING_ERROR_NAME = 'GatewayDrainingError';
+/** Causes followed below the error itself. */
+const MAX_CAUSE_DEPTH = 5;
+/** Pauses between retries of a refused update: 2 s, 5 s, 10 s, then every 30 s. */
+const DRAIN_RETRY_DELAYS_MS = [2_000, 5_000, 10_000, 30_000];
+
+/** True when `err` or one of its causes (up to 5 deep) is core's drain refusal. */
+export function isMaxGatewayDrainingError(err: unknown): boolean {
+  let current = err;
+  for (let depth = 0; depth <= MAX_CAUSE_DEPTH; depth += 1) {
+    if (typeof current !== 'object' || current === null) return false;
+    if ((current as { name?: unknown }).name === DRAINING_ERROR_NAME) return true;
+    current = (current as { cause?: unknown }).cause;
+  }
+  return false;
+}
+
+/** Pause before the retry after the `refusals`-th refusal in a row (1-based). */
+export function maxDrainRetryDelayMs(refusals: number): number {
+  const index = Math.min(Math.max(refusals, 1), DRAIN_RETRY_DELAYS_MS.length) - 1;
+  return DRAIN_RETRY_DELAYS_MS[index] as number;
+}
+
+/** Waits out the pause after a refusal; false when the channel stopped meanwhile (at once). */
+export async function waitForMaxDrainRetry(
+  refusals: number,
+  abortSignal: AbortSignal,
+): Promise<boolean> {
+  if (abortSignal.aborted) return false;
+  await sleepWithAbort(maxDrainRetryDelayMs(refusals), abortSignal).catch(() => undefined);
+  return !abortSignal.aborted;
+}