@aspalagin/openclaw-max 0.7.2

package/dist/src/channel-policy.js

@@ -0,0 +1,130 @@
+/**
+ * Access policy of the MAX channel: DM pairing/allowlist, group
+ * requireMention and tool policy, security warnings, pairing approval.
+ */
+import { resolveToolsBySender } from 'openclaw/plugin-sdk/channel-policy';
+import { PAIRING_APPROVED_MESSAGE } from 'openclaw/plugin-sdk/channel-status';
+import { DEFAULT_ACCOUNT_ID, formatPairingApproveHint } from 'openclaw/plugin-sdk/core';
+import { resolveMaxAccount } from './accounts.js';
+import { sendMaxMessage } from './send.js';
+// ── MAX group policy helpers ──
+// These mirror resolveChannelGroupRequireMention/resolveChannelGroupToolsPolicy
+// (internal SDK functions not exported) but for the "max" channel.
+function resolveMaxGroupConfig(cfg, groupId, accountId) {
+    const maxSection = cfg.channels?.max;
+    if (!maxSection)
+        return { groupConfig: undefined, defaultConfig: undefined };
+    // Resolve groups map: account-level takes priority over channel-level
+    let groups;
+    if (accountId && accountId !== DEFAULT_ACCOUNT_ID) {
+        const accounts = maxSection.accounts;
+        groups = accounts?.[accountId]?.groups;
+    }
+    if (!groups) {
+        groups = maxSection.groups;
+    }
+    const normalizedId = groupId?.trim();
+    const groupConfig = normalizedId && groups
+        ? groups[normalizedId]
+        : undefined;
+    const defaultConfig = groups?.['*'];
+    return { groupConfig, defaultConfig };
+}
+function resolveMaxGroupRequireMention(params) {
+    const { groupConfig, defaultConfig } = resolveMaxGroupConfig(params.cfg, params.groupId, params.accountId);
+    const configMention = typeof groupConfig?.requireMention === 'boolean'
+        ? groupConfig.requireMention
+        : typeof defaultConfig?.requireMention === 'boolean'
+            ? defaultConfig.requireMention
+            : undefined;
+    if (typeof configMention === 'boolean')
+        return configMention;
+    return true; // default: require mention
+}
+function resolveMaxGroupToolPolicy(params) {
+    const { groupConfig, defaultConfig } = resolveMaxGroupConfig(params.cfg, params.groupId, params.accountId);
+    // Group-level sender-specific policy
+    const groupSenderPolicy = resolveToolsBySender({
+        toolsBySender: groupConfig?.toolsBySender,
+        senderId: params.senderId,
+        senderName: params.senderName,
+        senderUsername: params.senderUsername,
+        senderE164: params.senderE164,
+    });
+    if (groupSenderPolicy)
+        return groupSenderPolicy;
+    if (groupConfig?.tools)
+        return groupConfig.tools;
+    // Default config fallback
+    const defaultSenderPolicy = resolveToolsBySender({
+        toolsBySender: defaultConfig?.toolsBySender,
+        senderId: params.senderId,
+        senderName: params.senderName,
+        senderUsername: params.senderUsername,
+        senderE164: params.senderE164,
+    });
+    if (defaultSenderPolicy)
+        return defaultSenderPolicy;
+    if (defaultConfig?.tools)
+        return defaultConfig.tools;
+    return undefined;
+}
+/** DM policy (default pairing) and warnings for open group policy. */
+export const maxSecurityAdapter = {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+        const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+        const maxSection = cfg.channels?.max;
+        const useAccountPath = Boolean(maxSection?.accounts?.[resolvedAccountId]);
+        const basePath = useAccountPath
+            ? `channels.max.accounts.${resolvedAccountId}.`
+            : 'channels.max.';
+        return {
+            policy: account.config.dmPolicy ?? 'pairing',
+            allowFrom: account.config.allowFrom ?? [],
+            policyPath: `${basePath}dmPolicy`,
+            allowFromPath: basePath,
+            approveHint: formatPairingApproveHint('max'),
+            normalizeEntry: (raw) => raw.replace(/^max:/i, ''),
+        };
+    },
+    collectWarnings: ({ account, cfg }) => {
+        const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+        const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? 'allowlist';
+        if (groupPolicy !== 'open') {
+            return [];
+        }
+        const groupAllowlistConfigured = account.config.groups && Object.keys(account.config.groups).length > 0;
+        if (groupAllowlistConfigured) {
+            return [
+                `- MAX groups: groupPolicy="open" allows any member in allowed groups to trigger (mention-gated). Set channels.max.groupPolicy="allowlist" + channels.max.groupAllowFrom to restrict senders.`,
+            ];
+        }
+        return [
+            `- MAX groups: groupPolicy="open" with no channels.max.groups allowlist; any group can add + ping (mention-gated). Set channels.max.groupPolicy="allowlist" + channels.max.groupAllowFrom or configure channels.max.groups.`,
+        ];
+    },
+};
+/** Group requireMention (default true) and tool policy from channels.max.groups. */
+export const maxGroupsAdapter = {
+    resolveRequireMention: ({ cfg, groupId, accountId }) => resolveMaxGroupRequireMention({ cfg, groupId, accountId }),
+    resolveToolPolicy: ({ cfg, groupId, accountId, senderId, senderName, senderUsername, senderE164, }) => resolveMaxGroupToolPolicy({
+        cfg,
+        groupId,
+        accountId,
+        senderId,
+        senderName,
+        senderUsername,
+        senderE164,
+    }),
+};
+/** Pairing ids are MAX user ids; approval is announced to the user in MAX. */
+export const maxPairingAdapter = {
+    idLabel: 'maxUserId',
+    normalizeAllowEntry: (entry) => entry.replace(/^max:/i, ''),
+    notifyApproval: async ({ cfg, id }) => {
+        const account = resolveMaxAccount({ cfg });
+        if (!account.token)
+            throw new Error('MAX bot token not configured');
+        await sendMaxMessage(id, PAIRING_APPROVED_MESSAGE, { token: account.token });
+    },
+};

package/dist/src/channel.js

@@ -0,0 +1,76 @@
+/**
+ * MAX channel plugin for OpenClaw.
+ *
+ * Implements the ChannelPlugin interface to integrate MAX messenger. The
+ * adapters live next to this file by role: channel-config (accounts, setup),
+ * channel-policy (DM/group access, pairing), channel-directory (targets,
+ * directory), channel-outbound (delivery), channel-lifecycle (start/stop,
+ * status, health), channel-agent-prompt; message tool actions in actions.ts.
+ */
+import { buildChannelConfigSchema } from 'openclaw/plugin-sdk/core';
+import { maxMessageActions } from './actions.js';
+import { maxAgentPromptAdapter } from './channel-agent-prompt.js';
+import { maxConfigAdapter, maxSetupAdapter } from './channel-config.js';
+import { maxDirectoryAdapter, maxMessagingAdapter } from './channel-directory.js';
+import { maxGatewayAdapter, maxStatusAdapter } from './channel-lifecycle.js';
+import { maxOutboundAdapter } from './channel-outbound.js';
+import { maxGroupsAdapter, maxPairingAdapter, maxSecurityAdapter } from './channel-policy.js';
+import { MaxConfigSchema } from './config-schema.js';
+import { buildMaxModelBrowseChannelData, buildMaxModelsAddProviderChannelData, buildMaxModelsListChannelData, buildMaxModelsMenuChannelData, buildMaxModelsProviderChannelData, } from './model-buttons.js';
+import { maxSetupWizard } from './onboarding.js';
+// ── Meta ──
+const maxMeta = {
+    id: 'max',
+    label: 'MAX',
+    selectionLabel: 'MAX Messenger',
+    docsPath: '/channels/max',
+    blurb: 'MAX messenger bot via platform-api2.max.ru. Supports DMs, groups, inline keyboards.',
+    order: 50,
+    aliases: ['max-messenger'],
+};
+// ── Channel Plugin ──
+export const maxPlugin = {
+    id: 'max',
+    meta: maxMeta,
+    setupWizard: maxSetupWizard,
+    configSchema: buildChannelConfigSchema(MaxConfigSchema),
+    capabilities: {
+        chatTypes: ['direct', 'group', 'channel'],
+        reactions: false,
+        threads: false,
+        media: true,
+        nativeCommands: true,
+        blockStreaming: false,
+        edit: true,
+        // DELETE /messages backs the "delete" action; replies use link.type=reply.
+        unsend: true,
+        reply: true,
+        polls: false,
+    },
+    reload: { configPrefixes: ['channels.max'] },
+    commands: {
+        nativeCommandsAutoEnabled: true,
+        nativeSkillsAutoEnabled: true,
+        buildModelsMenuChannelData: buildMaxModelsMenuChannelData,
+        buildModelsProviderChannelData: buildMaxModelsProviderChannelData,
+        buildModelsAddProviderChannelData: buildMaxModelsAddProviderChannelData,
+        buildModelsListChannelData: buildMaxModelsListChannelData,
+        buildModelBrowseChannelData: buildMaxModelBrowseChannelData,
+    },
+    agentPrompt: maxAgentPromptAdapter,
+    config: maxConfigAdapter,
+    security: maxSecurityAdapter,
+    groups: maxGroupsAdapter,
+    pairing: maxPairingAdapter,
+    threading: {
+        resolveReplyToMode: () => 'first',
+    },
+    messaging: maxMessagingAdapter,
+    directory: maxDirectoryAdapter,
+    outbound: maxOutboundAdapter,
+    setup: maxSetupAdapter,
+    status: maxStatusAdapter,
+    gateway: maxGatewayAdapter,
+    // Message actions (send, edit, delete)
+    actions: maxMessageActions,
+};

package/dist/src/config-schema.js

@@ -0,0 +1,133 @@
+/**
+ * MAX channel config Zod schema
+ */
+import { MarkdownConfigSchema, ToolPolicySchema } from 'openclaw/plugin-sdk/channel-config-schema';
+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.
+export const DmPolicySchema = z.enum(['pairing', 'allowlist', 'open', 'disabled']);
+export const GroupPolicySchema = z.enum(['open', 'disabled', 'allowlist']);
+// These schemas were removed from the public plugin-sdk surface in OpenClaw 2026.3.x.
+// Inlined here to stay compatible with both old and new runtimes.
+const BlockStreamingCoalesceSchema = z
+    .object({
+    minChars: z.number().int().optional(),
+    maxChars: z.number().int().optional(),
+    idleMs: z.number().int().optional(),
+})
+    .strict();
+const DmConfigSchema = z
+    .object({
+    historyLimit: z.number().int().min(0).optional(),
+})
+    .strict();
+function requireOpenAllowFrom(params) {
+    if (params.policy !== 'open')
+        return;
+    const normalized = (params.allowFrom ?? []).map(String);
+    if (normalized.includes('*'))
+        return;
+    params.ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: params.path,
+        message: params.message,
+    });
+}
+/**
+ * Per-group config for MAX chats
+ */
+export const MaxGroupSchema = z
+    .object({
+    requireMention: z.boolean().optional(),
+    tools: ToolPolicySchema.optional(),
+    skills: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    systemPrompt: z.string().optional(),
+})
+    .strict();
+/**
+ * MAX account config (base schema for both top-level and accounts.*)
+ */
+export const MaxAccountSchemaBase = z
+    .object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+    markdown: MarkdownConfigSchema.optional(),
+    botToken: z.string().optional(),
+    tokenFile: z.string().optional(),
+    dmPolicy: DmPolicySchema.optional().default('pairing'),
+    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'),
+    groups: z.record(z.string(), MaxGroupSchema.optional()).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(),
+    /** File holding the webhook secret (regular file, not a symlink) */
+    webhookSecretFile: z.string().optional(),
+    webhookPath: z.string().optional(),
+    historyLimit: z.number().int().min(0).optional(),
+    dmHistoryLimit: z.number().int().min(0).optional(),
+    dms: z.record(z.string(), DmConfigSchema.optional()).optional(),
+    textChunkLimit: z.number().int().positive().optional(),
+    blockStreaming: z.boolean().optional(),
+    streamMode: z.enum(['off', 'partial', 'block']).optional(),
+    blockStreamingCoalesce: BlockStreamingCoalesceSchema.optional(),
+    responsePrefix: z.string().optional(),
+    mediaMaxMb: z.number().positive().optional(),
+    markSeen: z.boolean().optional(),
+    actions: z
+        .record(z.string(), z.union([z.boolean(), z.enum(['pairing', 'allowlist', 'open'])]).optional())
+        .optional(),
+})
+    .strict();
+function requireWebhookUrl(params) {
+    if (params.transport !== 'webhook' || params.webhookUrl?.trim())
+        return;
+    params.ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['webhookUrl'],
+        message: 'channels.max.transport="webhook" requires channels.max.webhookUrl',
+    });
+}
+/**
+ * Individual account schema (with open-policy validation)
+ */
+export const MaxAccountSchema = MaxAccountSchemaBase.superRefine((value, ctx) => {
+    requireOpenAllowFrom({
+        policy: value.dmPolicy,
+        allowFrom: value.allowFrom,
+        ctx,
+        path: ['allowFrom'],
+        message: 'channels.max.dmPolicy="open" requires channels.max.allowFrom to include "*"',
+    });
+    requireWebhookUrl({ transport: value.transport, webhookUrl: value.webhookUrl, ctx });
+});
+/** Bot command registered via PATCH /me/commands (name ≤64 chars without slash, description ≤128) */
+const MaxBotCommandSchema = z
+    .object({
+    name: z.string().min(1).max(64),
+    description: z.string().max(128).optional(),
+})
+    .strict();
+/**
+ * Top-level MAX config schema (supports accounts.* sub-configs)
+ */
+export const MaxConfigSchema = MaxAccountSchemaBase.extend({
+    accounts: z.record(z.string(), MaxAccountSchema.optional()).optional(),
+    commands: z.array(MaxBotCommandSchema).max(32).optional(),
+}).superRefine((value, ctx) => {
+    requireOpenAllowFrom({
+        policy: value.dmPolicy,
+        allowFrom: value.allowFrom,
+        ctx,
+        path: ['allowFrom'],
+        message: 'channels.max.dmPolicy="open" requires channels.max.allowFrom to include "*"',
+    });
+    requireWebhookUrl({ transport: value.transport, webhookUrl: value.webhookUrl, ctx });
+});

package/dist/src/deliver.js

@@ -0,0 +1,126 @@
+/**
+ * Reply delivery for the inbound pipeline: callback answers, markdown chunks
+ * with the keyboard on the last one, media albums and delivery.pin.
+ */
+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) {
+    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) {
+            const body = err?.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;
+    let firstChatType;
+    const noteDelivered = (messageId, chatType) => {
+        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) {
+                const body = err?.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) {
+            const body = err?.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) {
+    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 };
+}

package/dist/src/dispatch.js

@@ -0,0 +1,186 @@
+/**
+ * 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 { processCallback } from './callbacks.js';
+import { processIncomingMessage } from './inbound.js';
+/** mark_seen vanished from current MAX docs; keep behind config (default on). */
+function shouldMarkSeen(account) {
+    return account.config.markSeen !== false;
+}
+function sendReadReceipt(chatId, opts) {
+    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, opts) {
+    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.message_id ?? '?'}`);
+            break;
+        }
+        default:
+            log?.debug?.(`[${account.accountId}] Unhandled update type: ${update.update_type}`);
+    }
+}
+async function processBotStarted(user, chatId, payload, opts) {
+    // 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 = {
+        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);
+}