@aspalagin/openclaw-max 0.7.3 → 0.8.1

package/dist/src/deliver.js

@@ -1,77 +1,163 @@
 /**
  * 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 { readMaxDeliveryPin } from './presentation.js';
+import { createChannelPartialDeliveryError } from 'openclaw/plugin-sdk/channel-inbound';
+import { PlatformMessageNotDispatchedError } from 'openclaw/plugin-sdk/error-runtime';
+import { LocalMediaAccessError } from 'openclaw/plugin-sdk/web-media';
+import { MaxApiError } from './api.js';
+import { readMaxDeliveryPin, resolveMaxTextChunkLimit } from './presentation.js';
 import { getMaxRuntime } from './runtime.js';
-import { answerMaxCallback, pinMaxMessage, readMaxChannelButtons, readMaxChannelSendOptions, sendMaxMediaGroup, sendMaxMessage, } from './send.js';
+import { answerMaxCallback, pinMaxMessage, readMaxChannelButtons, resolveMaxSendFlags, sendMaxMediaGroup, sendMaxMessage, } from './send.js';
+/**
+ * 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, visible) {
+    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, log, what, err) {
+    const body = err?.body;
+    log?.error(`[${account.accountId}] MAX ${what} failed: ${String(err)}${body ? ` body=${JSON.stringify(body)}` : ''}`);
+}
 export async function deliverMaxReply(params) {
     const { payload, account, chatId, config, log, statusSink } = params;
     const core = getMaxRuntime();
     const buttons = readMaxChannelButtons(payload.channelData);
-    const sendOptions = readMaxChannelSendOptions(payload.channelData);
-    if (params.callbackId && (payload.text || buttons?.length)) {
+    // 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 = { messageIds: draftMid ? [draftMid] : [], texts: [] };
+    let failure;
+    // 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 ?? '', {
                 token: account.token,
                 format: 'markdown',
                 buttons,
             });
+            visible.callbackAnswered = true;
+            if (payload.text)
+                visible.texts.push(payload.text);
             statusSink?.({ lastOutboundAt: Date.now() });
         }
         catch (err) {
-            const body = err?.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;
     let firstChatType;
-    const noteDelivered = (messageId, chatType) => {
+    const noteDelivered = (messageId, chatType, text) => {
+        if (messageId && !visible.messageIds.includes(messageId))
+            visible.messageIds.push(messageId);
+        if (text)
+            visible.texts.push(text);
         if (!firstMessageId && messageId) {
             firstMessageId = messageId;
             firstChatType = chatType;
         }
     };
-    if (payload.text) {
-        const chunkLimit = 4000; // MAX message limit
+    const sendTextMessage = async (text, messageButtons) => {
+        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 (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) {
-                const body = err?.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) {
-            const body = err?.body;
-            log?.error(`[${account.accountId}] MAX send failed: ${String(err)}${body ? ` body=${JSON.stringify(body)}` : ''}`);
+            logSendFailure(account, log, 'send', err);
+            failure = { err };
         }
     }
     // Media URLs — upload and send
@@ -80,22 +166,41 @@ export async function deliverMaxReply(params) {
         : payload.mediaUrl
             ? [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) => log?.error(`[${account.accountId}] MAX media send failed (${failed.length} item(s)): ${String(err)}`),
+            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, {
@@ -112,15 +217,6 @@ export async function deliverMaxReply(params) {
             log?.[pin.required ? 'error' : 'warn'](`[${account.accountId}] MAX pin of ${firstMessageId} failed: ${String(err)}`);
         }
     }
-}
-/** channelData with `max.buttons` removed (other max options kept). */
-export function withoutMaxButtons(channelData) {
-    if (!channelData || typeof channelData !== 'object' || Array.isArray(channelData))
-        return channelData;
-    const maxData = channelData.max;
-    if (!maxData || typeof maxData !== 'object' || Array.isArray(maxData))
-        return channelData;
-    const rest = { ...maxData };
-    delete rest.buttons;
-    return { ...channelData, max: rest };
+    if (failure)
+        throw toMaxDeliveryError(failure.err, visible);
 }

package/dist/src/dispatch.js

@@ -4,7 +4,7 @@
  * events to the chat registry.
  */
 import { processCallback } from './callbacks.js';
-import { processIncomingMessage } from './inbound.js';
+import { describeMaxLogText, processIncomingMessage } from './inbound.js';
 /** mark_seen vanished from current MAX docs; keep behind config (default on). */
 function shouldMarkSeen(account) {
     return account.config.markSeen !== false;
@@ -18,8 +18,8 @@ function sendReadReceipt(chatId, opts) {
             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). */
 export async function dispatchUpdate(update, opts) {
@@ -59,22 +59,23 @@ export async function dispatchUpdate(update, opts) {
             break;
         }
         case 'message_edited': {
-            if (!update.message)
+            // 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}`);
+            log?.debug?.(`[${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
             if (!editedMessage.body.text?.trim() && originalMid) {
@@ -91,7 +92,7 @@ export async function dispatchUpdate(update, opts) {
                             if (fetchedMsg.body.attachments?.length) {
                                 editedMessage.body.attachments = fetchedMsg.body.attachments;
                             }
-                            log?.debug?.(`[${account.accountId}] Fetched edited text: "${fetchedMsg.body.text.slice(0, 50)}"`);
+                            log?.debug?.(`[${account.accountId}] Fetched edited text: ${describeMaxLogText(account, fetchedMsg.body.text)}`);
                         }
                     }
                 }

package/dist/src/gateway-drain.js

@@ -0,0 +1,40 @@
+/**
+ * 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) {
+    let current = err;
+    for (let depth = 0; depth <= MAX_CAUSE_DEPTH; depth += 1) {
+        if (typeof current !== 'object' || current === null)
+            return false;
+        if (current.name === DRAINING_ERROR_NAME)
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/** Pause before the retry after the `refusals`-th refusal in a row (1-based). */
+export function maxDrainRetryDelayMs(refusals) {
+    const index = Math.min(Math.max(refusals, 1), DRAIN_RETRY_DELAYS_MS.length) - 1;
+    return DRAIN_RETRY_DELAYS_MS[index];
+}
+/** Waits out the pause after a refusal; false when the channel stopped meanwhile (at once). */
+export async function waitForMaxDrainRetry(refusals, abortSignal) {
+    if (abortSignal.aborted)
+        return false;
+    await sleepWithAbort(maxDrainRetryDelayMs(refusals), abortSignal).catch(() => undefined);
+    return !abortSignal.aborted;
+}

package/dist/src/group-mention.js

@@ -0,0 +1,129 @@
+/**
+ * Group mention facts beyond the bot's native mention: core's configured
+ * mention patterns (messages.groupChat / agent groupChat mentionPatterns),
+ * also matched against the transcript of a captionless voice message — MAX's
+ * own transcript, else a core preflight transcription.
+ */
+import { resolveAgentConfig } from 'openclaw/plugin-sdk/agent-scope-runtime';
+import { buildMentionRegexes, matchesMentionPatterns, toInboundMediaFacts, } from 'openclaw/plugin-sdk/channel-inbound';
+import { createChannelPreflightAudio, formatAudioTranscriptForAgent, } from 'openclaw/plugin-sdk/media-understanding-runtime';
+import { admitMaxGroupSender } from './access-policy.js';
+import { collectInboundAttachments, readAudioTranscription, } from './inbound-attachments.js';
+const maxPreflightAudio = createChannelPreflightAudio({
+    channel: 'max',
+    isAudio: (media) => media.kind === 'audio',
+});
+/**
+ * Only explicitly configured patterns count: without them core derives
+ * patterns from the agent's identity name and emoji, which would start waking
+ * the bot in MAX groups that so far needed a real mention.
+ */
+function hasConfiguredMentionPatterns(cfg, agentId) {
+    const agentGroupChat = resolveAgentConfig(cfg, agentId)?.groupChat;
+    if (agentGroupChat && Object.hasOwn(agentGroupChat, 'mentionPatterns'))
+        return true;
+    const groupChat = cfg.messages?.groupChat;
+    return Boolean(groupChat && Object.hasOwn(groupChat, 'mentionPatterns'));
+}
+/** Core mention regexes for this group, after the channel's mentionPatterns policy. */
+export function resolveMaxMentionRegexes(params) {
+    const { cfg, agentId, account, chatId } = params;
+    if (!hasConfiguredMentionPatterns(cfg, agentId))
+        return [];
+    return buildMentionRegexes(cfg, agentId, {
+        provider: 'max',
+        conversationId: chatId,
+        ...(account.config.mentionPatterns ? { providerPolicy: account.config.mentionPatterns } : {}),
+    });
+}
+/**
+ * Transcribe the first audio of the message with core media understanding
+ * (tools.media.audio). Returns the transcript and the index of the input core
+ * transcribed; undefined when there is no audio, STT is off or it fails.
+ */
+export async function transcribeMaxVoiceForMention(params) {
+    const ctx = {
+        Provider: 'max',
+        Surface: 'max',
+        OriginatingChannel: 'max',
+        OriginatingTo: `max:${params.chatId}`,
+        AccountId: params.accountId,
+        ChatType: 'group',
+        media: toInboundMediaFacts(params.mediaInputs),
+    };
+    const transcript = await maxPreflightAudio.resolve({ request: { ctx, cfg: params.cfg } });
+    if (!transcript)
+        return undefined;
+    // Core marks the fact it transcribed on the request context.
+    const media = (ctx.media ?? []);
+    const marked = media.findIndex((fact, index) => fact?.transcribed === true && params.mediaInputs[index]?.transcribed !== true);
+    const index = marked >= 0 ? marked : params.mediaInputs.findIndex((input) => input.kind === 'audio');
+    return { transcript, index };
+}
+/**
+ * Mention check for a captionless voice message in a mention-gated group
+ * whose chat already passed the group policy. MAX's own transcript is matched
+ * as is; otherwise, for senders the group admits, the audio is downloaded
+ * (mediaMaxMb, mediaMaxCount) and transcribed once by core. The transcript
+ * then goes to the agent as core formats it, and the audio fact is marked
+ * transcribed so the reply pipeline does not transcribe it again. No match,
+ * no audio or any failure: undefined ("not mentioned").
+ */
+export async function resolveMaxVoiceMention(params) {
+    const { attachments, mentionRegexes, account, log } = params;
+    const audio = attachments.find((att) => att.type === 'audio');
+    if (!audio || mentionRegexes.length === 0)
+        return undefined;
+    const platformTranscript = readAudioTranscription(audio);
+    if (platformTranscript) {
+        return matchesMentionPatterns(platformTranscript, mentionRegexes) ? {} : undefined;
+    }
+    // The inbound gate admitted the sender already; the shared rule again, so
+    // no caller transcribes for a sender outside the group's allowlist.
+    if (!admitMaxGroupSender(account, params.chatId, params.senderId).admitted) {
+        return undefined;
+    }
+    try {
+        const collected = await collectInboundAttachments({
+            attachments,
+            messageId: params.messageId,
+            chatId: params.chatId,
+            api: params.api,
+            account,
+            log,
+        });
+        if (!collected.mediaInputs.some((input) => input.kind === 'audio' && !input.transcribed)) {
+            return undefined;
+        }
+        const result = await transcribeMaxVoiceForMention({
+            cfg: params.cfg,
+            accountId: account.accountId,
+            chatId: params.chatIdStr,
+            mediaInputs: collected.mediaInputs,
+        });
+        if (!result || !matchesMentionPatterns(result.transcript, mentionRegexes))
+            return undefined;
+        const mediaInputs = collected.mediaInputs.map((input, index) => index === result.index ? { ...input, transcribed: true } : input);
+        return {
+            attachments: {
+                ...collected,
+                mediaInputs,
+                descriptions: [...collected.descriptions, formatAudioTranscriptForAgent(result.transcript)],
+            },
+            transcript: result.transcript,
+        };
+    }
+    catch (err) {
+        log?.debug?.(`[${account.accountId}] Voice mention check failed: ${String(err)}`);
+        return undefined;
+    }
+}
+/** Core's deferred transcript echo (tools.media.audio.echoTranscript), after the gate. */
+export async function echoMaxVoiceTranscript(params) {
+    await maxPreflightAudio.send({
+        transcript: params.transcript,
+        cfg: params.cfg,
+        accountId: params.accountId,
+        originatingTo: `max:${params.chatId}`,
+    });
+}