@aspalagin/openclaw-max 0.7.2

package/dist/src/channel-agent-prompt.js

@@ -0,0 +1,38 @@
+/**
+ * Agent prompt hints of the MAX channel: stickers, location, contact, pin,
+ * button types and presentation for the message tool.
+ */
+/** message tool hints for MAX-specific actions. */
+export const maxAgentPromptAdapter = {
+    messageToolHints: () => {
+        // Compact sticker emoji map: top 50 emojis → sticker codes
+        // Codes are hex IDs derived from listmax.ru external_id: parseInt(extId).toString(16)
+        const emojiMap = '😂:109550b5 😊:109971b5 😍:10931eb5 🥰:10931eb5 😢:109330b5 😭:109330b5 😡:10941fb5 😱:109302b5 🤔:109308b5 👍:109368b5 👎:109323b5 ❤️:10931eb5 🔥:b4867ebb 💪:c1254bbb 🎉:10933cb5 😘:10931eb5 🤗:109b94b5 😎:10931db5 🙄:c14211bb 😴:10936eb5 😤:10941fb5 🤮:6b8bb 🤯:109302b5 😳:109302b5 🥳:10933cb5 💀:b4863ebb 🙈:b4850cbb 😏:11e4c60bb 😅:109550b5 🤣:109550b5 😋:109d2db5 😜:455b5 🤷:10d5cf5bb 😫:10936eb5 😩:10997db5 🥺:109356b5 😌:14aae3bb 😒:109323b5 🤪:455b5 😇:11e4dedbb 🙏:50cb5 💔:10997db5 👀:b48534bb ✨:11e43b2bb 😈:10941fb5 🤝:109368b5 🤦:502b5 😬:5dab4b5 🤩:5dabfb5 😶:2ae2b5';
+        // Also try to load full sticker-emoji-map.json for extended catalog
+        let extendedHint = '';
+        try {
+            const fs = require('fs');
+            const path = require('path');
+            const candidates = [
+                path.join(__dirname, '..', 'sticker-emoji-map.json'),
+                path.join(process.cwd(), 'projects', 'openclaw-max', 'sticker-emoji-map.json'),
+            ];
+            for (const p of candidates) {
+                if (fs.existsSync(p)) {
+                    extendedHint = ' Full emoji→sticker map available at: ' + p;
+                    break;
+                }
+            }
+        }
+        catch { }
+        return [
+            '- MAX stickers: use `message(action="sticker", target="CHAT_ID", stickerId="CODE")`. Pick a sticker code matching the mood from the emoji map below. Each entry is emoji:hexCode.',
+            `- Sticker emoji map: ${emojiMap}${extendedHint}`,
+            '- MAX location: use `message(action="sendAttachment", target="CHAT_ID", type="location", latitude="55.75", longitude="37.62")` to send a native map pin.',
+            '- MAX contact: use `message(action="sendAttachment", target="CHAT_ID", type="contact", contactName="Name", vcfPhone="+70001234567")` to send a native contact card.',
+            '- MAX pin: use `message(action="pin", target="CHAT_ID", messageId="MID")` to pin a message; `message(action="unpin", target="CHAT_ID")` to unpin.',
+            '- MAX buttons support types: callback (default), link, message (sends the button text as a user message — great for suggested replies), clipboard (copies payload), open_app (webApp = public name of the bot wired to the mini app), request_contact, request_geo_location. Pass via buttons=[[{"text":"...","type":"message"}]].',
+            '- MAX rich messages: prefer `presentation` (title/tone, text, context, divider, table/chart as monospace text, buttons and select as an inline keyboard); `pin=true` pins the sent message.',
+        ];
+    },
+};

package/dist/src/channel-config.js

@@ -0,0 +1,103 @@
+/**
+ * Account config and CLI setup adapters of the MAX channel: account listing
+ * and resolution, enable/delete, allowFrom formatting, `openclaw channels add`.
+ */
+import { applyAccountNameToChannelSection, DEFAULT_ACCOUNT_ID, deleteAccountFromConfigSection, migrateBaseNameToDefaultAccount, normalizeAccountId, setAccountEnabledInConfigSection, } from 'openclaw/plugin-sdk/core';
+import { listMaxAccountIds, resolveMaxAccount } from './accounts.js';
+/** Accounts under channels.max (top level = default account, plus channels.max.accounts). */
+export const maxConfigAdapter = {
+    listAccountIds: (cfg) => listMaxAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveMaxAccount({ cfg, accountId }),
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    setAccountEnabled: ({ cfg, accountId, enabled }) => setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: 'max',
+        accountId,
+        enabled,
+        allowTopLevel: true,
+    }),
+    deleteAccount: ({ cfg, accountId }) => deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: 'max',
+        accountId,
+        clearBaseFields: ['botToken', 'tokenFile', 'name'],
+    }),
+    isConfigured: (account) => Boolean(account.token?.trim()),
+    describeAccount: (account) => ({
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured: Boolean(account.token?.trim()),
+        tokenSource: account.tokenSource,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) => (resolveMaxAccount({ cfg, accountId }).config.allowFrom ?? []).map(String),
+    formatAllowFrom: ({ allowFrom }) => allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.replace(/^max:/i, '')),
+};
+/** Non-interactive setup: token / token file / MAX_BOT_TOKEN for the default account. */
+export const maxSetupAdapter = {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) => applyAccountNameToChannelSection({
+        cfg,
+        channelKey: 'max',
+        accountId,
+        name,
+    }),
+    validateInput: ({ accountId, input }) => {
+        if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+            return 'MAX_BOT_TOKEN can only be used for the default account.';
+        }
+        if (!input.useEnv && !input.token && !input.tokenFile) {
+            return 'MAX requires --token or --token-file (or --use-env with MAX_BOT_TOKEN).';
+        }
+        return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+        const namedConfig = applyAccountNameToChannelSection({
+            cfg,
+            channelKey: 'max',
+            accountId,
+            name: input.name,
+        });
+        const next = accountId !== DEFAULT_ACCOUNT_ID
+            ? migrateBaseNameToDefaultAccount({
+                cfg: namedConfig,
+                channelKey: 'max',
+            })
+            : namedConfig;
+        if (accountId === DEFAULT_ACCOUNT_ID) {
+            return {
+                ...next,
+                channels: {
+                    ...next.channels,
+                    max: {
+                        ...next.channels?.max,
+                        enabled: true,
+                        ...(input.useEnv ? {} : input.token ? { botToken: input.token } : {}),
+                    },
+                },
+            };
+        }
+        const maxSection = next.channels?.max ?? {};
+        return {
+            ...next,
+            channels: {
+                ...next.channels,
+                max: {
+                    ...maxSection,
+                    enabled: true,
+                    accounts: {
+                        ...maxSection.accounts,
+                        [accountId]: {
+                            ...maxSection.accounts?.[accountId],
+                            enabled: true,
+                            ...(input.token ? { botToken: input.token } : {}),
+                        },
+                    },
+                },
+            },
+        };
+    },
+};

package/dist/src/channel-directory.js

@@ -0,0 +1,84 @@
+/**
+ * Directory and addressing of the MAX channel: self, peers from allowFrom,
+ * groups from the passive chat registry, numeric target normalization.
+ */
+import { resolveMaxAccount } from './accounts.js';
+import { MaxApi } from './api.js';
+import { loadMaxAccountState } from './state.js';
+/** `user:<id>` addresses a user (DM); a bare number is a chat id. */
+const MAX_TARGET_PATTERN = /^(?:user:\d+|-?\d+)$/;
+function stripMaxPrefix(raw) {
+    const trimmed = raw.trim();
+    return trimmed.startsWith('max:') ? trimmed.slice(4) : trimmed;
+}
+/**
+ * Targets are numeric chat ids or `user:<id>`, with an optional max: prefix.
+ * The `user:` prefix must survive normalization: dropping it turns a user id
+ * into a chat_id and MAX answers dialog.not.found.
+ */
+export const maxMessagingAdapter = {
+    normalizeTarget: (raw) => {
+        const normalized = stripMaxPrefix(raw);
+        return MAX_TARGET_PATTERN.test(normalized) ? normalized : undefined;
+    },
+    targetResolver: {
+        looksLikeId: (raw) => MAX_TARGET_PATTERN.test(stripMaxPrefix(raw)),
+        hint: '<chatId|user:userId>',
+    },
+};
+/** MAX has no member/chat listing for bots: peers come from allowFrom, groups from the chat registry. */
+export const maxDirectoryAdapter = {
+    self: async ({ cfg, accountId }) => {
+        const account = resolveMaxAccount({ cfg, accountId });
+        if (!account.token)
+            return null;
+        try {
+            const api = new MaxApi({ token: account.token, timeoutMs: 3000 });
+            const me = await api.getMe();
+            return {
+                kind: 'user',
+                id: String(me.user_id),
+                name: me.first_name || undefined,
+                handle: me.username || undefined,
+            };
+        }
+        catch {
+            return null;
+        }
+    },
+    listPeers: async ({ cfg, accountId }) => {
+        const account = resolveMaxAccount({ cfg, accountId });
+        // MAX doesn't expose a full user list API. Return peers from allowFrom config.
+        const allowFrom = account.config.allowFrom ?? [];
+        return allowFrom.map((id) => ({
+            kind: 'user',
+            id: String(id),
+            name: undefined,
+        }));
+    },
+    listGroups: async ({ cfg, accountId }) => {
+        const account = resolveMaxAccount({ cfg, accountId });
+        if (!account.token)
+            return [];
+        const groups = new Map();
+        // Реестр чатов пополняется событиями bot_added, chat_title_changed и сообщениями групп.
+        try {
+            const state = await loadMaxAccountState(account.accountId);
+            for (const entry of Object.values(state.chats ?? {})) {
+                if (entry.removedAt)
+                    continue;
+                if (entry.type !== 'chat' && entry.type !== 'channel')
+                    continue;
+                groups.set(String(entry.chatId), {
+                    kind: entry.type === 'channel' ? 'channel' : 'group',
+                    id: String(entry.chatId),
+                    name: entry.title || undefined,
+                });
+            }
+        }
+        catch {
+            // При недоступности реестра вернуть пустой список.
+        }
+        return [...groups.values()];
+    },
+};

package/dist/src/channel-lifecycle.js

@@ -0,0 +1,219 @@
+/**
+ * Account lifecycle of the MAX channel: gateway start (probe, bot commands,
+ * monitor) and logout, status snapshots, probes and group audits (health).
+ */
+import { DEFAULT_ACCOUNT_ID } from 'openclaw/plugin-sdk/core';
+import { MaxApi } from './api.js';
+import { startMaxPolling } from './monitor.js';
+import { writeMaxConfig } from './runtime.js';
+/** Runtime snapshots, GET /me probe and a membership audit of configured groups. */
+export const maxStatusAdapter = {
+    defaultRuntime: {
+        accountId: DEFAULT_ACCOUNT_ID,
+        running: false,
+        lastStartAt: null,
+        lastStopAt: null,
+        lastError: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+        configured: snapshot.configured ?? false,
+        tokenSource: snapshot.tokenSource ?? 'none',
+        running: snapshot.running ?? false,
+        // lifecycle/connected must mirror the gateway runtime store: the health cache
+        // compares them with the live runtime and treats a missing value as stale.
+        ...(snapshot.lifecycle !== undefined ? { lifecycle: snapshot.lifecycle } : {}),
+        ...(typeof snapshot.connected === 'boolean' ? { connected: snapshot.connected } : {}),
+        lastStartAt: snapshot.lastStartAt ?? null,
+        lastStopAt: snapshot.lastStopAt ?? null,
+        lastError: snapshot.lastError ?? null,
+        probe: snapshot.probe,
+    }),
+    probeAccount: async ({ account, timeoutMs }) => {
+        if (!account.token)
+            return { ok: false, error: 'no token' };
+        const api = new MaxApi({ token: account.token, timeoutMs });
+        try {
+            const me = await api.getMe();
+            return { ok: true, bot: me };
+        }
+        catch (err) {
+            return { ok: false, error: String(err) };
+        }
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured: Boolean(account.token?.trim()),
+        tokenSource: account.tokenSource,
+        running: runtime?.running ?? false,
+        ...(runtime?.lifecycle !== undefined ? { lifecycle: runtime.lifecycle } : {}),
+        ...(typeof runtime?.connected === 'boolean' ? { connected: runtime.connected } : {}),
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        lastError: runtime?.lastError ?? null,
+        probe,
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+    auditAccount: async ({ account, timeoutMs }) => {
+        if (!account.token) {
+            return {
+                ok: false,
+                checkedGroups: 0,
+                unresolvedGroups: 0,
+                groups: [],
+                elapsedMs: 0,
+            };
+        }
+        const start = Date.now();
+        const groups = account.config.groups ?? {};
+        const groupIds = Object.keys(groups).filter((id) => id !== '*');
+        if (groupIds.length === 0) {
+            return {
+                ok: true,
+                checkedGroups: 0,
+                unresolvedGroups: 0,
+                groups: [],
+                elapsedMs: Date.now() - start,
+            };
+        }
+        const api = new MaxApi({ token: account.token, timeoutMs });
+        const results = [];
+        let unresolvedCount = 0;
+        for (const groupId of groupIds) {
+            try {
+                const chat = await api.getChat(Number(groupId));
+                const isMember = chat.type === 'chat' || chat.type === 'channel';
+                if (!isMember) {
+                    unresolvedCount++;
+                    results.push({
+                        id: groupId,
+                        ok: false,
+                        error: 'Bot is not a member of this chat',
+                    });
+                }
+                else {
+                    // Long polling delivers group updates only to admin bots — surface
+                    // a missing-admin state, the classic "bot is silent in the group" cause.
+                    let adminSuffix = '';
+                    try {
+                        const membership = await api.getMembership(Number(groupId));
+                        if (membership && membership.is_admin !== true) {
+                            adminSuffix = ' (⚠ bot is not admin — group updates are not delivered via polling)';
+                        }
+                    }
+                    catch {
+                        // membership endpoint unavailable — skip the admin hint
+                    }
+                    results.push({
+                        id: groupId,
+                        ok: true,
+                        title: `${chat.title ?? ''}${adminSuffix}` || undefined,
+                    });
+                }
+            }
+            catch (err) {
+                unresolvedCount++;
+                results.push({
+                    id: groupId,
+                    ok: false,
+                    error: String(err),
+                });
+            }
+        }
+        return {
+            ok: unresolvedCount === 0,
+            checkedGroups: groupIds.length,
+            unresolvedGroups: unresolvedCount,
+            groups: results,
+            elapsedMs: Date.now() - start,
+        };
+    },
+    collectStatusIssues: (accounts) => {
+        const issues = [];
+        for (const snapshot of accounts) {
+            if (!snapshot.configured) {
+                issues.push({
+                    channel: 'max',
+                    accountId: snapshot.accountId,
+                    kind: 'config',
+                    message: 'MAX bot token not configured',
+                    fix: 'Set channels.max.botToken or MAX_BOT_TOKEN env var',
+                });
+            }
+        }
+        return issues;
+    },
+};
+/** Starts one account: probe the bot, register commands, run the monitor until abort. */
+export const maxGatewayAdapter = {
+    startAccount: async (ctx) => {
+        const account = ctx.account;
+        const token = account.token.trim();
+        let botLabel = '';
+        let botUserId;
+        let botUsername;
+        try {
+            const probeApi = new MaxApi({ token, timeoutMs: 3000 });
+            const me = await probeApi.getMe();
+            if (me.username) {
+                botLabel = ` (@${me.username})`;
+                botUsername = me.username;
+            }
+            botUserId = me.user_id;
+        }
+        catch {
+            // probe failed, continue anyway
+        }
+        ctx.log?.info(`[${account.accountId}] Starting MAX provider${botLabel}`);
+        const api = new MaxApi({ token });
+        // Register bot commands if configured
+        const commands = ctx.cfg.channels?.max?.commands;
+        if (commands?.length) {
+            try {
+                await api.setMyCommands(commands);
+                ctx.log?.info(`[${account.accountId}] Registered ${commands.length} bot commands`);
+            }
+            catch (err) {
+                ctx.log?.error(`[${account.accountId}] Failed to register commands: ${String(err)}`);
+            }
+        }
+        return startMaxPolling({
+            api,
+            account,
+            config: ctx.cfg,
+            abortSignal: ctx.abortSignal,
+            botUserId,
+            botUsername,
+            log: ctx.log,
+            statusSink: (patch) => {
+                const current = ctx.getStatus();
+                ctx.setStatus({ ...current, ...patch });
+            },
+        });
+    },
+    logoutAccount: async ({ accountId, cfg }) => {
+        const nextCfg = { ...cfg };
+        const channels = { ...nextCfg.channels };
+        const maxSection = channels.max ? { ...channels.max } : undefined;
+        let cleared = false;
+        if (maxSection) {
+            if (accountId === DEFAULT_ACCOUNT_ID && maxSection.botToken) {
+                delete maxSection.botToken;
+                cleared = true;
+            }
+            const accounts = maxSection.accounts;
+            if (accounts && accountId in accounts) {
+                delete accounts[accountId];
+                cleared = true;
+            }
+            channels.max = maxSection;
+            nextCfg.channels = channels;
+            if (cleared) {
+                await writeMaxConfig(nextCfg);
+            }
+        }
+        return { cleared, loggedOut: cleared };
+    },
+};

package/dist/src/channel-outbound.js

@@ -0,0 +1,133 @@
+/**
+ * Outbound adapter of the MAX channel: sendText / sendPayload / sendMedia,
+ * presentation rendering and delivery pins for core's outbound path.
+ */
+import { resolveMaxAccount } from './accounts.js';
+import { materializeMaxPresentation, MAX_PRESENTATION_CAPABILITIES, MAX_TEXT_LIMIT, renderMaxPresentation, } from './presentation.js';
+import { getMaxRuntime, loadMaxConfig } from './runtime.js';
+import { pinMaxMessage, readMaxChannelButtons, sendMaxMediaGroup, sendMaxMediaMessage, sendMaxMessage, } from './send.js';
+/** Direct delivery with 4000-character markdown chunks. */
+export const maxOutboundAdapter = {
+    deliveryMode: 'direct',
+    chunker: (text, limit) => getMaxRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: 'markdown',
+    textChunkLimit: 4000,
+    // Presentation (docs/plugins/message-presentation.md): core adapts to these
+    // capabilities, renders through renderPresentation and pins through
+    // pinDeliveredMessage after the first delivered message.
+    presentationCapabilities: MAX_PRESENTATION_CAPABILITIES,
+    deliveryCapabilities: { pin: true },
+    renderPresentation: ({ payload, presentation }) => renderMaxPresentation(payload, presentation),
+    pinDeliveredMessage: async ({ cfg, target, messageId, pin, assertDirectAdapterHandoff }) => {
+        const account = resolveMaxAccount({ cfg, accountId: target.accountId });
+        if (!account.token)
+            throw new Error('MAX bot token not configured');
+        assertDirectAdapterHandoff?.();
+        // Dialogs cannot pin: pinMaxMessage resolves { pinned: false } without an
+        // API call or error, so core logs no failed pin for a DM delivery.
+        await pinMaxMessage(target.to, messageId, {
+            token: account.token,
+            pinNotify: pin.notify === true,
+            beforeRequest: assertDirectAdapterHandoff,
+        });
+    },
+    sendPayload: async ({ to, text, payload: rawPayload, mediaUrl, accountId, replyToId }) => {
+        const cfg = await loadMaxConfig();
+        const account = resolveMaxAccount({ cfg, accountId });
+        if (!account.token)
+            throw new Error('MAX bot token not configured');
+        // Core renders presentation before sendPayload; a payload that still
+        // carries one came through a path that did not, so apply the same policy.
+        const payload = rawPayload.presentation
+            ? await materializeMaxPresentation(rawPayload)
+            : rawPayload;
+        const effectiveText = payload === rawPayload ? text : (payload.text ?? '');
+        const buttons = readMaxChannelButtons(payload.channelData);
+        const mediaUrls = mediaUrl
+            ? [mediaUrl]
+            : payload.mediaUrls?.length
+                ? payload.mediaUrls
+                : payload.mediaUrl
+                    ? [payload.mediaUrl]
+                    : [];
+        if (mediaUrls.length) {
+            // Albums: up to 12 images/videos per message, caption on the first,
+            // buttons on the last; report the first message (delivery.pin).
+            const result = await sendMaxMediaGroup(to, effectiveText, mediaUrls, {
+                token: account.token,
+                replyToMessageId: replyToId ?? undefined,
+                format: 'markdown',
+                buttons,
+                mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+            });
+            return {
+                channel: 'max',
+                messageId: result.messageIds[0] ?? '',
+            };
+        }
+        // MAX caps a message at 4000 characters: split, keyboard on the last
+        // chunk, report the first one (delivery.pin pins the first chunk).
+        const chunks = effectiveText.length > MAX_TEXT_LIMIT
+            ? getMaxRuntime().channel.text.chunkMarkdownText(effectiveText, MAX_TEXT_LIMIT)
+            : [effectiveText];
+        let firstMessageId = '';
+        for (let index = 0; index < chunks.length; index += 1) {
+            const result = await sendMaxMessage(to, chunks[index], {
+                token: account.token,
+                replyToMessageId: index === 0 ? (replyToId ?? undefined) : undefined,
+                format: 'markdown',
+                buttons: index === chunks.length - 1 ? buttons : undefined,
+            });
+            if (index === 0)
+                firstMessageId = result.messageId;
+        }
+        return {
+            channel: 'max',
+            messageId: firstMessageId,
+        };
+    },
+    sendText: async ({ to, text, accountId, replyToId }) => {
+        const cfg = await loadMaxConfig();
+        const account = resolveMaxAccount({ cfg, accountId });
+        if (!account.token)
+            throw new Error('MAX bot token not configured');
+        const result = await sendMaxMessage(to, text, {
+            token: account.token,
+            replyToMessageId: replyToId ?? undefined,
+            format: 'markdown',
+        });
+        return {
+            channel: 'max',
+            messageId: result.messageId,
+        };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, replyToId }) => {
+        const cfg = await loadMaxConfig();
+        const account = resolveMaxAccount({ cfg, accountId });
+        if (!account.token)
+            throw new Error('MAX bot token not configured');
+        if (!mediaUrl) {
+            // No media, send as text
+            const result = await sendMaxMessage(to, text, {
+                token: account.token,
+                replyToMessageId: replyToId ?? undefined,
+                format: 'markdown',
+            });
+            return {
+                channel: 'max',
+                messageId: result.messageId,
+            };
+        }
+        // Upload and send media
+        const result = await sendMaxMediaMessage(to, text, mediaUrl, {
+            token: account.token,
+            replyToMessageId: replyToId ?? undefined,
+            format: 'markdown',
+            mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+        });
+        return {
+            channel: 'max',
+            messageId: result.messageId,
+        };
+    },
+};