@aspalagin/openclaw-max 0.7.2

package/src/deliver.ts

@@ -0,0 +1,168 @@
+/**
+ * Reply delivery for the inbound pipeline: callback answers, markdown chunks
+ * with the keyboard on the last one, media albums and delivery.pin.
+ */
+
+import type { ChannelLogSink } from 'openclaw/plugin-sdk/channel-contract';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+
+import type { ResolvedMaxAccount } from './accounts.js';
+import { readMaxDeliveryPin } from './presentation.js';
+import { getMaxRuntime } from './runtime.js';
+import {
+  answerMaxCallback,
+  pinMaxMessage,
+  readMaxChannelButtons,
+  readMaxChannelSendOptions,
+  sendMaxMediaGroup,
+  sendMaxMessage,
+} from './send.js';
+
+export async function deliverMaxReply(params: {
+  payload: {
+    text?: string;
+    mediaUrls?: string[];
+    mediaUrl?: string;
+    replyToId?: string;
+    channelData?: unknown;
+    delivery?: unknown;
+  };
+  account: ResolvedMaxAccount;
+  chatId: string;
+  replyToId?: string;
+  callbackId?: string;
+  config: OpenClawConfig;
+  log?: ChannelLogSink;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+}): Promise<void> {
+  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)) {
+    try {
+      await answerMaxCallback(params.callbackId, payload.text ?? '', {
+        token: account.token,
+        format: 'markdown',
+        buttons,
+      });
+      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)}` : ''}`,
+      );
+    }
+    return;
+  }
+
+  // delivery.pin: pin the first delivered message (first chunk).
+  let firstMessageId: string | undefined;
+  let firstChatType: string | undefined;
+  const noteDelivered = (messageId: string, chatType?: string) => {
+    if (!firstMessageId && messageId) {
+      firstMessageId = messageId;
+      firstChatType = chatType;
+    }
+  };
+
+  if (payload.text) {
+    const chunkLimit = 4000; // MAX message limit
+    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];
+      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() });
+      } catch (err: unknown) {
+        const body = (err as { body?: unknown })?.body;
+        log?.error(
+          `[${account.accountId}] MAX send failed: ${String(err)}${body ? ` body=${JSON.stringify(body)}` : ''}`,
+        );
+      }
+    }
+  } 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() });
+    } catch (err: unknown) {
+      const body = (err as { body?: unknown })?.body;
+      log?.error(
+        `[${account.accountId}] MAX send failed: ${String(err)}${body ? ` body=${JSON.stringify(body)}` : ''}`,
+      );
+    }
+  }
+
+  // Media URLs — upload and send
+  const mediaList = payload.mediaUrls?.length
+    ? payload.mediaUrls
+    : 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.
+  if (mediaList.length) {
+    const sent = await sendMaxMediaGroup(chatId, '', mediaList, {
+      token: account.token,
+      replyToMessageId: params.replyToId,
+      mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+      ...sendOptions,
+      onError: (err, failed) =>
+        log?.error(
+          `[${account.accountId}] MAX media send failed (${failed.length} item(s)): ${String(err)}`,
+        ),
+    });
+    for (const id of sent.messageIds) noteDelivered(id);
+    if (sent.messageIds.length) statusSink?.({ lastOutboundAt: Date.now() });
+  }
+
+  const pin = readMaxDeliveryPin(payload.delivery);
+  if (pin && firstMessageId) {
+    try {
+      const pinned = await pinMaxMessage(chatId, firstMessageId, {
+        token: account.token,
+        pinNotify: pin.notify === true,
+        chatType: firstChatType,
+      });
+      if (!pinned.pinned) {
+        log?.debug?.(
+          `[${account.accountId}] MAX pin of ${firstMessageId} skipped: ${pinned.reason}`,
+        );
+      }
+    } catch (err) {
+      // Optional pins degrade; the delivered message stays.
+      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: 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 };
+}

package/src/dispatch.ts

@@ -0,0 +1,224 @@
+/**
+ * Update dispatch: routes each MAX update by update_type — messages and edits
+ * to the inbound pipeline, button presses to callbacks, bot/dialog lifecycle
+ * events to the chat registry.
+ */
+
+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 type { MaxMonitorOptions } from './monitor-types.js';
+
+/** mark_seen vanished from current MAX docs; keep behind config (default on). */
+function shouldMarkSeen(account: ResolvedMaxAccount): boolean {
+  return account.config.markSeen !== false;
+}
+
+function sendReadReceipt(chatId: number | undefined, opts: MaxMonitorOptions): void {
+  const { log, account } = opts;
+  if (!chatId) return;
+  if (shouldMarkSeen(account)) {
+    opts.api.sendAction(chatId, 'mark_seen').catch((err) => {
+      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.
+}
+
+/** Route one update by update_type (shared by the polling loop and the webhook queue). */
+export async function dispatchUpdate(update: MaxUpdate, opts: MaxMonitorOptions): Promise<void> {
+  const { log, account, statusSink } = opts;
+
+  switch (update.update_type) {
+    case 'message_created': {
+      if (!update.message) break;
+      // Skip messages from the bot itself
+      if (opts.botUserId && update.message.sender?.user_id === opts.botUserId) break;
+      statusSink?.({ lastInboundAt: Date.now() });
+      // Mark message as read (typing starts once the message reaches the agent)
+      sendReadReceipt(update.message.recipient?.chat_id, opts);
+      // Passive chat discovery: GET /chats is deprecated, register group chats
+      // the bot actually sees so directory.listGroups keeps working.
+      const recipient = update.message.recipient;
+      if (
+        opts.state &&
+        recipient?.chat_id != null &&
+        (recipient.chat_type === 'chat' || recipient.chat_type === 'channel') &&
+        !opts.state.hasActiveChat(recipient.chat_id)
+      ) {
+        // A message from this chat proves the bot is a member — (re)register it,
+        // clearing any stale removedAt from an earlier bot_removed/dialog_removed.
+        opts.state.upsertChat(recipient.chat_id, {
+          type: recipient.chat_type,
+          addedAt: Date.now(),
+        });
+      }
+      await processIncomingMessage(update.message, update.user_locale, opts);
+      break;
+    }
+
+    case 'message_callback': {
+      if (!update.callback) break;
+      statusSink?.({ lastInboundAt: Date.now() });
+      await processCallback(update.callback, update.message ?? null, update.user_locale, opts);
+      break;
+    }
+
+    case 'message_edited': {
+      if (!update.message) 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}`,
+      );
+      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}`,
+      };
+
+      // MAX message_edited may not include text — fetch it from API if missing
+      if (!editedMessage.body.text?.trim() && originalMid) {
+        try {
+          const chatId = editedMessage.recipient?.chat_id;
+          if (chatId) {
+            const fetched = await opts.api.getMessages(chatId, {
+              message_ids: [originalMid],
+              count: 1,
+            });
+            const fetchedMsg = fetched.messages?.[0];
+            if (fetchedMsg?.body?.text) {
+              editedMessage.body = { ...editedMessage.body, text: fetchedMsg.body.text };
+              if (fetchedMsg.body.attachments?.length) {
+                editedMessage.body.attachments = fetchedMsg.body.attachments;
+              }
+              log?.debug?.(
+                `[${account.accountId}] Fetched edited text: "${fetchedMsg.body.text.slice(0, 50)}"`,
+              );
+            }
+          }
+        } catch (err) {
+          log?.debug?.(
+            `[${account.accountId}] Failed to fetch edited message text: ${String(err)}`,
+          );
+        }
+      }
+
+      await processIncomingMessage(editedMessage, update.user_locale, opts);
+      break;
+    }
+
+    case 'bot_started': {
+      if (!update.user) break;
+      log?.info(
+        `[${account.accountId}] Bot started by user ${update.user.user_id}${update.payload ? ' (with deeplink payload)' : ''}`,
+      );
+      statusSink?.({ lastInboundAt: Date.now() });
+      if (opts.state && update.chat_id != null) {
+        opts.state.upsertChat(update.chat_id, {
+          type: 'dialog',
+          addedAt: Date.now(),
+          stopped: false,
+        });
+      }
+      await processBotStarted(update.user, update.chat_id, update.payload ?? undefined, opts);
+      break;
+    }
+
+    case 'bot_stopped': {
+      // User halted the bot in a dialog — stop proactive sends until they return
+      log?.info(
+        `[${account.accountId}] Bot stopped by user ${update.user?.user_id ?? '?'} (chat ${update.chat_id ?? '?'})`,
+      );
+      if (opts.state && update.chat_id != null) {
+        opts.state.upsertChat(update.chat_id, { type: 'dialog', stopped: true });
+      }
+      break;
+    }
+
+    case 'bot_added': {
+      log?.info(`[${account.accountId}] Bot added to chat ${update.chat_id}`);
+      if (opts.state && update.chat_id != null) {
+        opts.state.upsertChat(update.chat_id, {
+          type: update.is_channel ? 'channel' : 'chat',
+          addedAt: Date.now(),
+        });
+      }
+      break;
+    }
+
+    case 'bot_removed': {
+      log?.info(`[${account.accountId}] Bot removed from chat ${update.chat_id}`);
+      if (opts.state && update.chat_id != null) {
+        opts.state.upsertChat(update.chat_id, { removedAt: Date.now() });
+      }
+      break;
+    }
+
+    case 'dialog_removed': {
+      log?.info(
+        `[${account.accountId}] Dialog removed by user ${update.user_id ?? update.user?.user_id ?? '?'} (chat ${update.chat_id ?? '?'})`,
+      );
+      if (opts.state && update.chat_id != null) {
+        opts.state.upsertChat(update.chat_id, { removedAt: Date.now() });
+      }
+      break;
+    }
+
+    case 'dialog_cleared': {
+      // User wiped the dialog history on their side; keep our session but log it
+      log?.info(
+        `[${account.accountId}] Dialog cleared by user ${update.user_id ?? update.user?.user_id ?? '?'} (chat ${update.chat_id ?? '?'})`,
+      );
+      break;
+    }
+
+    case 'chat_title_changed': {
+      if (opts.state && update.chat_id != null && typeof update.title === 'string') {
+        opts.state.upsertChat(update.chat_id, { title: update.title });
+      }
+      break;
+    }
+
+    case 'message_removed': {
+      // Deliberate no-op: OpenClaw sessions have no per-message retraction.
+      log?.debug?.(
+        `[${account.accountId}] Message removed in chat ${update.chat_id ?? '?'}: ${(update as { message_id?: string }).message_id ?? '?'}`,
+      );
+      break;
+    }
+
+    default:
+      log?.debug?.(`[${account.accountId}] Unhandled update type: ${update.update_type}`);
+  }
+}
+
+async function processBotStarted(
+  user: MaxUser,
+  chatId: number | undefined,
+  payload: string | undefined,
+  opts: MaxMonitorOptions,
+): Promise<void> {
+  // Synthesize a /start message; deeplink payload (max.ru/<bot>?start=...) is
+  // forwarded as the command argument like other messengers do.
+  const startText = payload?.trim() ? `/start ${payload.trim()}` : '/start';
+  const syntheticMessage: MaxMessage = {
+    sender: user,
+    recipient: { chat_id: chatId ?? user.user_id, chat_type: 'dialog' },
+    timestamp: Date.now(),
+    body: {
+      mid: `bot_started_${user.user_id}_${Date.now()}`,
+      text: startText,
+    },
+  };
+
+  await processIncomingMessage(syntheticMessage, null, opts);
+}

package/src/format.ts

@@ -0,0 +1,33 @@
+/**
+ * Конвертер форматирования OpenClaw/стандартный markdown → MAX markdown.
+ *
+ * Отличия MAX markdown от стандартного:
+ * - Подчёркивание: MAX не поддерживает markdown-синтаксис подчёркивания, но
+ *   рендерит HTML-тег <u>…</u> → конвертируем в ++…++.
+ * - `**bold**` и `__bold__` MAX рендерит как жирный сам — НЕ трогаем.
+ * - Упоминание: [Имя](max://user/user_id) — синтаксис MAX, оставляем как есть.
+ * - bold, italic, strikethrough, code, ссылки — совпадают со стандартом.
+ *
+ * Конвертация выполняется только ВНЕ inline-кода, fenced-блоков и URL, чтобы
+ * не портить текст внутри `код` / ```блоков``` / ссылок.
+ */
+
+const CODE_OR_URL = /(```[\s\S]*?```|`[^`]*`|https?:\/\/\S+)/g;
+
+/** Заменяет только <u>…</u> → ++…++; markdown-подчёркивание MAX не поддерживает. */
+function convertSegment(text: string): string {
+  return text.replace(/<u>([\s\S]*?)<\/u>/gi, '++$1++');
+}
+
+/**
+ * Конвертирует OpenClaw/стандартный markdown в MAX markdown, не затрагивая
+ * содержимое inline-кода, fenced-блоков и URL.
+ */
+export function toMaxMarkdown(text: string): string {
+  if (!text) return text;
+  // split с захватывающей группой: нечётные индексы — код/URL (не трогаем)
+  return text
+    .split(CODE_OR_URL)
+    .map((segment, index) => (index % 2 === 0 ? convertSegment(segment) : segment))
+    .join('');
+}

package/src/inbound-attachments.ts

@@ -0,0 +1,152 @@
+/**
+ * Inbound attachments: downloads media (image, sticker, video, audio, file)
+ * into the gateway media store and describes the rest as text for the agent.
+ */
+
+import type { ChannelLogSink } from 'openclaw/plugin-sdk/channel-contract';
+import type { ChannelInboundMediaInput } from 'openclaw/plugin-sdk/channel-inbound';
+
+import type { ResolvedMaxAccount } from './accounts.js';
+import type { MaxApi, MaxAttachment } from './api.js';
+import { sanitizeMaxFileName } from './media-temp.js';
+import { getMaxRuntime } from './runtime.js';
+import { rememberStickerCode } from './sticker-cache.js';
+
+export interface MaxInboundAttachments {
+  /** Text descriptions ([Sticker: …], [Location: …], [Voice transcript: …], failed downloads). */
+  descriptions: string[];
+  /** One entry per downloaded attachment; array position is attachment identity. */
+  mediaInputs: ChannelInboundMediaInput[];
+}
+
+/** Process attachments: download media, build descriptions for non-downloadable types. */
+export async function collectInboundAttachments(params: {
+  attachments: MaxAttachment[];
+  messageId: string;
+  chatId: number | undefined;
+  api: MaxApi;
+  account: ResolvedMaxAccount;
+  log?: ChannelLogSink;
+}): Promise<MaxInboundAttachments> {
+  const { attachments, messageId, chatId, api, account, log } = params;
+  const core = getMaxRuntime();
+  const attachmentDescriptions: string[] = [];
+  const mediaInputs: ChannelInboundMediaInput[] = [];
+
+  for (const att of attachments) {
+    const attType = att.type ?? 'unknown';
+    const payload = att.payload as Record<string, unknown> | undefined;
+
+    // Media types with downloadable URL: image, sticker, video, audio, file
+    if (['image', 'sticker', 'video', 'audio', 'file'].includes(attType)) {
+      // For stickers, always capture the code for outbound use
+      const stickerCode = attType === 'sticker' ? ((payload?.code ?? '') as string) : '';
+      if (stickerCode) {
+        log?.debug?.(`[${account.accountId}] Sticker received: code=${stickerCode}`);
+        attachmentDescriptions.push(`[Sticker: code=${stickerCode}]`);
+        if (chatId != null) {
+          rememberStickerCode(chatId, stickerCode);
+        }
+      }
+
+      let url = (payload?.url ?? (att as Record<string, unknown>).url ?? '') as string;
+
+      // Inbound video attachments often carry only a token — resolve playback
+      // URLs via GET /videos/{videoToken} instead of degrading to "[video]".
+      if (!url && attType === 'video' && typeof payload?.token === 'string' && payload.token) {
+        try {
+          const info = await api.getVideoInfo(payload.token);
+          const urls = info?.urls ?? undefined;
+          url =
+            urls?.mp4_720 ??
+            urls?.mp4_480 ??
+            urls?.mp4_1080 ??
+            urls?.mp4_360 ??
+            urls?.mp4_240 ??
+            urls?.mp4_144 ??
+            '';
+          if (!url) {
+            log?.debug?.(
+              `[${account.accountId}] Video ${payload.token.slice(0, 12)}… has no playback URLs yet`,
+            );
+          }
+        } catch (err) {
+          log?.debug?.(`[${account.accountId}] getVideoInfo failed: ${String(err)}`);
+        }
+      }
+
+      // MAX may transcribe voice messages itself (AudioAttachment.transcription,
+      // a sibling of payload). The text goes to the agent and the audio fact is
+      // marked transcribed, so core media understanding does not run STT again.
+      const transcription = attType === 'audio' ? readAudioTranscription(att) : undefined;
+      if (transcription) {
+        attachmentDescriptions.push(`[Voice transcript: ${transcription}]`);
+      }
+
+      if (url && typeof url === 'string' && url.startsWith('http')) {
+        try {
+          const maxBytes = (account.config.mediaMaxMb ?? 20) * 1024 * 1024;
+          const fetched = await core.channel.media.fetchRemoteMedia({ url, maxBytes });
+          const inboundFileName = fetched.fileName
+            ? sanitizeMaxFileName(fetched.fileName, fetched.contentType)
+            : undefined;
+          const saved = await core.channel.media.saveMediaBuffer(
+            Buffer.from(fetched.buffer),
+            fetched.contentType,
+            'inbound',
+            maxBytes,
+            inboundFileName,
+          );
+          // Only the local copy goes to the agent: MAX download URLs are signed
+          // and short-lived, so they are not recorded as the media url.
+          mediaInputs.push({
+            path: saved.path,
+            contentType: saved.contentType,
+            fileName: inboundFileName,
+            messageId,
+            ...(transcription ? { transcribed: true } : {}),
+          });
+        } catch (err) {
+          log?.error?.(`[${account.accountId}] Failed to download ${attType}: ${String(err)}`);
+          // Fall back to text description (sticker code already added above)
+          if (attType !== 'sticker') {
+            attachmentDescriptions.push(`[${attType}: ${url}]`);
+          }
+        }
+      } else {
+        // No URL — text description
+        if (attType === 'sticker') {
+          const code = payload?.code ?? '';
+          attachmentDescriptions.push(`[Sticker${code ? `: ${code}` : ''}]`);
+        } else if (attType === 'file') {
+          const filename = (att as Record<string, unknown>).filename ?? payload?.filename ?? '';
+          attachmentDescriptions.push(`[File${filename ? `: ${filename}` : ''}]`);
+        } else {
+          attachmentDescriptions.push(`[${attType}]`);
+        }
+      }
+    } else if (attType === 'share') {
+      const url = (payload?.url ?? (att as Record<string, unknown>).url ?? '') as string;
+      attachmentDescriptions.push(`[Share${url ? `: ${url}` : ''}]`);
+    } else if (attType === 'location') {
+      const lat = (att as Record<string, unknown>).latitude ?? payload?.latitude ?? '';
+      const lon = (att as Record<string, unknown>).longitude ?? payload?.longitude ?? '';
+      attachmentDescriptions.push(`[Location: ${lat}, ${lon}]`);
+    } else if (attType === 'contact') {
+      const name = payload?.name ?? payload?.vcf_info ?? '';
+      attachmentDescriptions.push(`[Contact${name ? `: ${name}` : ''}]`);
+    } else if (attType !== 'inline_keyboard') {
+      attachmentDescriptions.push(`[${attType}]`);
+    }
+  }
+
+  return { descriptions: attachmentDescriptions, mediaInputs };
+}
+
+/** Non-empty MAX transcription of an audio attachment, if any. */
+function readAudioTranscription(att: MaxAttachment): string | undefined {
+  const value = att.transcription;
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}