@aspalagin/openclaw-max 0.7.2

package/dist/src/api.js

@@ -0,0 +1,553 @@
+/**
+ * MAX Bot API client — thin wrapper around platform-api2.max.ru
+ *
+ * API docs: https://dev.max.ru/docs-api
+ * Auth: Authorization header with bot token
+ * Rate limit: 30 rps
+ *
+ * TLS: platform-api2.max.ru serves a certificate issued by the Russian Trusted
+ * (Минцифры) CA, which is not in the default Node trust store. Requests go
+ * through a dedicated undici dispatcher whose CA set = system roots + Russian
+ * Trusted Root/Sub CA. Trust is scoped to this client only, never process-wide.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import * as tls from 'node:tls';
+import { retryAsync } from 'openclaw/plugin-sdk/runtime-env';
+import { Agent, buildConnector, fetch as undiciFetch } from 'undici';
+import { RUSSIAN_TRUSTED_ROOT_CA, RUSSIAN_TRUSTED_SUB_CA } from './russian-trusted-ca.js';
+/**
+ * platform-api.max.ru is shut down on 2026-07-19; platform-api2.max.ru is the
+ * canonical endpoint since June 2026.
+ */
+const BASE_URL = 'https://platform-api2.max.ru';
+/**
+ * Default per-request deadline. Raised from 10s after an intermittent in-process
+ * stall aborted sends at exactly 10s ("This operation was aborted") while the
+ * same request from a fresh process completed in <300ms. The long poll sets its
+ * own (longer) timeout, so this only bounds one-shot calls like send/edit/get.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Round trips slower than this are logged, to fingerprint a stalling path. */
+const MAX_SLOW_REQUEST_MS = 5_000;
+/** New connections whose DNS+TCP+TLS exceeds this are logged. */
+const MAX_SLOW_CONNECT_MS = 2_000;
+let testFetchOverride;
+/**
+ * Test seam: route all MAX HTTP through the given fetch (e.g. a vi.fn or a
+ * passthrough to a mocked globalThis.fetch). Pass undefined to restore.
+ */
+export function setMaxFetchForTests(fetchImpl) {
+    testFetchOverride = fetchImpl;
+}
+let cachedDispatcher;
+function getMaxDispatcher() {
+    if (!cachedDispatcher) {
+        const tlsWithCaList = tls;
+        // getCACertificates("default") includes NODE_EXTRA_CA_CERTS additions when available
+        const systemCas = tlsWithCaList.getCACertificates?.('default') ?? tls.rootCertificates;
+        const ca = [...systemCas, RUSSIAN_TRUSTED_ROOT_CA, RUSSIAN_TRUSTED_SUB_CA];
+        // Wrap the TLS connector to time the DNS+TCP+TLS phase, scoped to this
+        // dispatcher only (never process-wide). Diagnosing the intermittent
+        // "This operation was aborted" needs to separate a connect stall from a
+        // response-wait stall; a slow or failed connect leaves a fingerprint here.
+        const connect = buildConnector({ ca });
+        const timedConnect = (options, callback) => {
+            const startedAt = Date.now();
+            connect(options, (...args) => {
+                const err = args[0];
+                const elapsedMs = Date.now() - startedAt;
+                if (err || elapsedMs > MAX_SLOW_CONNECT_MS) {
+                    console.error(`[MAX API] connect ${options.hostname} ${err ? 'failed' : 'slow'} dns+tcp+tls=${elapsedMs}ms` +
+                        (err ? ` (${err.name})` : ''));
+                }
+                callback(...args);
+            });
+        };
+        cachedDispatcher = new Agent({ connect: timedConnect });
+    }
+    return cachedDispatcher;
+}
+function maxFetch(url, init) {
+    if (testFetchOverride)
+        return testFetchOverride(url, init);
+    return undiciFetch(url, {
+        ...init,
+        dispatcher: getMaxDispatcher(),
+    });
+}
+function escapeMultipartHeaderValue(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/[\r\n]/g, '_');
+}
+function buildMultipartFileBody(fieldName, fileName, mimeType, fileBuffer) {
+    const boundary = `----openclaw-max-${randomBytes(12).toString('hex')}`;
+    const escapedField = escapeMultipartHeaderValue(fieldName);
+    const escapedFile = escapeMultipartHeaderValue(fileName);
+    const preamble = Buffer.from(`--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="${escapedField}"; filename="${escapedFile}"\r\n` +
+        `Content-Type: ${mimeType}\r\n\r\n`);
+    const closing = Buffer.from(`\r\n--${boundary}--\r\n`);
+    return {
+        body: Buffer.concat([preamble, fileBuffer, closing]),
+        contentType: `multipart/form-data; boundary=${boundary}`,
+    };
+}
+/** MAX docs (POST /messages): at most 2 messages per second into one dialog, chat or channel. */
+export const MAX_SENDS_PER_CHAT_PER_SECOND = 2;
+/**
+ * Sliding-window limiter for sends into one chat. Callers for the same key are
+ * served in order; a caller over the limit waits until the oldest send in the
+ * window is a full window old. Keys are independent, long polling and other
+ * requests never pass through it.
+ */
+export class MaxChatSendLimiter {
+    limit;
+    windowMs;
+    recent = new Map();
+    tails = new Map();
+    constructor(limit = MAX_SENDS_PER_CHAT_PER_SECOND, windowMs = 1000) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+    }
+    acquire(key) {
+        const take = async () => {
+            for (;;) {
+                const now = Date.now();
+                const times = (this.recent.get(key) ?? []).filter((t) => now - t < this.windowMs);
+                if (times.length < this.limit) {
+                    times.push(now);
+                    this.recent.set(key, times);
+                    return;
+                }
+                this.recent.set(key, times);
+                await new Promise((resolve) => setTimeout(resolve, times[0] + this.windowMs - now));
+            }
+        };
+        const slot = (this.tails.get(key) ?? Promise.resolve()).then(take);
+        this.tails.set(key, slot);
+        void slot.finally(() => {
+            if (this.tails.get(key) === slot)
+                this.tails.delete(key);
+        });
+        if (this.recent.size > 1000)
+            this.prune();
+        return slot;
+    }
+    prune() {
+        const now = Date.now();
+        for (const [key, times] of this.recent) {
+            if (!this.tails.has(key) && times.every((t) => now - t >= this.windowMs))
+                this.recent.delete(key);
+        }
+    }
+}
+let sharedSendLimiter = new MaxChatSendLimiter();
+/** @internal Fresh process-wide send limiter (test isolation). */
+export function resetMaxSendLimiterForTests() {
+    sharedSendLimiter = new MaxChatSendLimiter();
+}
+export class MaxApiError extends Error {
+    status;
+    body;
+    /** MAX error code from the response body, e.g. "attachment.not.ready" */
+    code;
+    /** Parsed Retry-After (ms), when the response carried one */
+    retryAfterMs;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'MaxApiError';
+        if (body && typeof body === 'object') {
+            const code = body.code;
+            if (typeof code === 'string')
+                this.code = code;
+        }
+    }
+}
+/**
+ * A request that hit the client-side deadline (our AbortController), as opposed
+ * to a caller-supplied stop signal. Carries the stalled phase so the send path
+ * can decide whether one retry on a fresh connection is safe.
+ */
+export class MaxRequestTimeoutError extends Error {
+    method;
+    path;
+    elapsedMs;
+    phase;
+    constructor(method, path, elapsedMs, phase) {
+        super(`MAX API ${method} ${path} timed out after ${elapsedMs}ms (phase=${phase})`);
+        this.method = method;
+        this.path = path;
+        this.elapsedMs = elapsedMs;
+        this.phase = phase;
+        this.name = 'MaxRequestTimeoutError';
+    }
+}
+/**
+ * Whether an error is safe to retry. `idempotent` gates the ambiguous cases:
+ * for non-idempotent calls (POST /messages, POST /answers) a 5xx or network
+ * failure may mean the request WAS applied server-side, so retrying would
+ * duplicate the message — only a definite 429 (never applied) is retried.
+ */
+function isRetryableError(err, idempotent) {
+    // A client-side timeout is safe to retry only for idempotent methods here; the
+    // send path handles its own single, duplicate-safe retry for POST /messages.
+    if (err instanceof MaxRequestTimeoutError)
+        return idempotent;
+    if (err instanceof MaxApiError) {
+        if (err.status === 429)
+            return true; // rate-limited: request was rejected, safe to retry
+        // 500 excluded everywhere: the request may have been applied.
+        if (err.status === 502 || err.status === 503 || err.status === 504)
+            return idempotent;
+        return false;
+    }
+    if (err instanceof Error && err.name === 'AbortError')
+        return false;
+    // undici network-level failure (fetch failed, ECONNRESET, socket hang up…):
+    // ambiguous — the request may have reached the server, so retry only if idempotent.
+    return idempotent && (err instanceof TypeError || err instanceof Error);
+}
+const IDEMPOTENT_METHODS = new Set(['GET', 'PUT', 'DELETE']);
+export class MaxApi {
+    token;
+    baseUrl;
+    timeoutMs;
+    retryAttempts;
+    sendLimiter;
+    /** Limiter key prefix: the same chat under two bots has two budgets. */
+    tokenKey;
+    constructor(opts) {
+        this.token = opts.token;
+        this.sendLimiter = opts.sendLimiter === undefined ? sharedSendLimiter : opts.sendLimiter;
+        this.tokenKey = createHash('sha256').update(opts.token).digest('hex').slice(0, 12);
+        this.baseUrl = opts.baseUrl ?? BASE_URL;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const envAttempts = Number(process.env.OPENCLAW_MAX_RETRY_ATTEMPTS);
+        this.retryAttempts =
+            opts.retryAttempts ?? (Number.isFinite(envAttempts) && envAttempts >= 0 ? envAttempts : 3);
+    }
+    // ── HTTP helpers ──
+    async requestOnce(method, path, params, body, timeoutMs, externalSignal) {
+        const url = new URL(path, this.baseUrl);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v != null)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const controller = new AbortController();
+        let timedOutByUs = false;
+        let gotResponse = false;
+        const startedAt = Date.now();
+        const timeout = setTimeout(() => {
+            timedOutByUs = true;
+            controller.abort();
+        }, timeoutMs ?? this.timeoutMs);
+        // A caller-supplied signal (the channel stop) must cancel the in-flight
+        // request, not just be polled between requests: a 35s long poll otherwise
+        // keeps running long after the gateway asked the channel to stop.
+        const signal = externalSignal
+            ? AbortSignal.any([controller.signal, externalSignal])
+            : controller.signal;
+        try {
+            const res = await maxFetch(url.toString(), {
+                method,
+                headers: {
+                    Authorization: this.token,
+                    ...(body ? { 'Content-Type': 'application/json' } : {}),
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal,
+            });
+            gotResponse = true;
+            const json = (await res.json().catch(() => null));
+            const elapsedMs = Date.now() - startedAt;
+            // The long poll blocks server-side for its `timeout` seconds by design, so
+            // it is excluded here; every other call reaching the server slowly is a
+            // fingerprint that points away from a connect hang.
+            if (elapsedMs > MAX_SLOW_REQUEST_MS && path !== '/updates') {
+                console.error(`[MAX API] ${method} ${path} slow: ${elapsedMs}ms (status ${res.status})`);
+            }
+            if (!res.ok) {
+                // Never log the request body: it may carry the webhook secret (POST
+                // /subscriptions) or private message text. Log only method+path+status.
+                console.error(`[MAX API] ${method} ${path} → ${res.status}`);
+                const error = new MaxApiError(`MAX API ${method} ${path} → ${res.status}`, res.status, json);
+                const retryAfter = res.headers?.get?.('retry-after');
+                if (retryAfter) {
+                    const seconds = Number(retryAfter);
+                    if (Number.isFinite(seconds) && seconds > 0)
+                        error.retryAfterMs = seconds * 1000;
+                }
+                throw error;
+            }
+            return json;
+        }
+        catch (err) {
+            const elapsedMs = Date.now() - startedAt;
+            const isAbort = err instanceof Error && err.name === 'AbortError';
+            if (timedOutByUs && isAbort) {
+                // Our own deadline fired (not the caller's stop signal). Convert the
+                // opaque "This operation was aborted" into a typed, loggable timeout
+                // that records whether a response had started.
+                const phase = gotResponse ? 'reading-body' : 'awaiting-response';
+                console.error(`[MAX API] ${method} ${path} timed out after ${elapsedMs}ms (phase=${phase})`);
+                throw new MaxRequestTimeoutError(method, path, elapsedMs, phase);
+            }
+            if (!isAbort && !(err instanceof MaxApiError)) {
+                // Network-level failure (DNS/TCP/TLS/reset): record timing so a connect
+                // stall is distinguishable from a response-wait stall in the log.
+                console.error(`[MAX API] ${method} ${path} failed after ${elapsedMs}ms: ${err.name}`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async request(method, path, params, body, timeoutMs, retryAttempts, externalSignal) {
+        const attempts = retryAttempts ?? this.retryAttempts;
+        if (attempts <= 1) {
+            return this.requestOnce(method, path, params, body, timeoutMs, externalSignal);
+        }
+        const idempotent = IDEMPOTENT_METHODS.has(method);
+        return retryAsync(() => this.requestOnce(method, path, params, body, timeoutMs, externalSignal), {
+            attempts,
+            minDelayMs: 500,
+            maxDelayMs: 5_000,
+            label: `MAX ${method} ${path}`,
+            shouldRetry: (err) => isRetryableError(err, idempotent),
+            retryAfterMs: (err) => (err instanceof MaxApiError ? err.retryAfterMs : undefined),
+        });
+    }
+    // ── Bot info ──
+    async getMe() {
+        return this.request('GET', '/me');
+    }
+    // ── Messages ──
+    async sendMessage(body, params) {
+        const chat = params.chat_id != null ? `c${params.chat_id}` : `u${params.user_id}`;
+        await this.sendLimiter?.acquire(`${this.tokenKey}:${chat}`);
+        return this.request('POST', '/messages', params, body);
+    }
+    async editMessage(messageId, body) {
+        return this.request('PUT', '/messages', { message_id: messageId }, body);
+    }
+    async deleteMessage(messageId) {
+        return this.request('DELETE', '/messages', { message_id: messageId });
+    }
+    /**
+     * List messages in a chat, newest first (GET /messages). `before`/`after` are
+     * Unix-time bounds in ms; they replace the deprecated `from`/`to`.
+     */
+    async getMessages(chatId, params) {
+        const qp = { chat_id: chatId };
+        if (params?.message_ids)
+            qp.message_ids = params.message_ids.join(',');
+        if (params?.before != null)
+            qp.before = params.before;
+        if (params?.after != null)
+            qp.after = params.after;
+        if (params?.count)
+            qp.count = params.count;
+        return this.request('GET', '/messages', qp);
+    }
+    /** Get a single message by its mid (GET /messages/{messageId}); 404 if gone or inaccessible. */
+    async getMessageById(messageId) {
+        return this.request('GET', `/messages/${encodeURIComponent(messageId)}`);
+    }
+    // ── Chats ──
+    /** Get chat info by numeric id (GET /chats/{chatId}). */
+    async getChat(chatId) {
+        return this.request('GET', `/chats/${chatId}`);
+    }
+    /** Bot's own membership in a chat — is_admin matters: long polling delivers group updates only to admin bots. */
+    async getMembership(chatId) {
+        return this.request('GET', `/chats/${chatId}/members/me`);
+    }
+    // ── Pinned messages ──
+    async getPinnedMessage(chatId) {
+        return this.request('GET', `/chats/${chatId}/pin`);
+    }
+    async pinMessage(chatId, messageId, notify) {
+        return this.request('PUT', `/chats/${chatId}/pin`, undefined, {
+            message_id: messageId,
+            ...(notify != null ? { notify } : {}),
+        });
+    }
+    async unpinMessage(chatId) {
+        return this.request('DELETE', `/chats/${chatId}/pin`);
+    }
+    // ── Chat actions ──
+    async sendAction(chatId, action) {
+        return this.request('POST', `/chats/${chatId}/actions`, undefined, { action });
+    }
+    // ── Callbacks ──
+    async answerCallback(callbackId, body) {
+        return this.request('POST', '/answers', { callback_id: callbackId }, body);
+    }
+    // ── Updates (long polling) ──
+    async getUpdates(params) {
+        const qp = {};
+        if (params?.limit)
+            qp.limit = params.limit;
+        if (params?.timeout != null)
+            qp.timeout = params.timeout;
+        if (params?.marker != null)
+            qp.marker = params.marker;
+        if (params?.types?.length)
+            qp.types = params.types.join(',');
+        // Long polling needs a longer timeout; the polling loop owns retries
+        const pollTimeout = ((params?.timeout ?? 30) + 5) * 1000;
+        return this.request('GET', '/updates', qp, undefined, pollTimeout, 0, params?.signal);
+    }
+    // ── Videos ──
+    /** Playback info for an inbound video attachment (GET /videos/{videoToken}). */
+    async getVideoInfo(videoToken) {
+        return this.request('GET', `/videos/${encodeURIComponent(videoToken)}`);
+    }
+    // ── Subscriptions (webhooks) ──
+    async getSubscriptions() {
+        return this.request('GET', '/subscriptions');
+    }
+    async subscribe(params) {
+        return this.request('POST', '/subscriptions', undefined, params);
+    }
+    async unsubscribe(subscriptionUrl) {
+        return this.request('DELETE', '/subscriptions', { url: subscriptionUrl });
+    }
+    // ── Commands ──
+    /**
+     * Replace the bot command list (PATCH /me/commands; PATCH /me answers 404).
+     * Limits: 32 commands, name ≤ 64 chars (no leading slash), description ≤ 128 chars.
+     */
+    async setMyCommands(commands) {
+        const normalized = commands
+            .map((cmd) => ({
+            name: cmd.name.replace(/^\//, '').slice(0, 64),
+            ...(cmd.description ? { description: cmd.description.slice(0, 128) } : {}),
+        }))
+            .filter((cmd) => cmd.name.length > 0)
+            .slice(0, 32);
+        return this.request('PATCH', '/me/commands', undefined, {
+            commands: normalized,
+        });
+    }
+    // ── Upload ──
+    async getUploadUrl(type) {
+        return this.request('POST', `/uploads`, { type });
+    }
+    /**
+     * Upload media file to MAX.
+     * MAX upload requires multipart/form-data with field "data".
+     * Response contains a token (in photos/videos/etc) to use in attachments.
+     *
+     * @param type Media type (image, video, audio, file)
+     * @param data File path (string) or buffer (Buffer/Uint8Array)
+     * @param contentType MIME type (optional, auto-detected for common types)
+     * @returns Upload result with token (for use in attachment payload)
+     */
+    async uploadMedia(type, data, contentType) {
+        // Step 1: Get upload URL and attachment token.
+        // MAX returns the attachment token together with the upload URL. The
+        // following upload host may answer with XML like `<retval>1</retval>` and
+        // does not repeat that token.
+        const uploadInfo = await this.getUploadUrl(type);
+        const uploadUrl = uploadInfo.url;
+        // Step 2: Load file if data is a path
+        let fileBuffer;
+        let mimeType = contentType;
+        let fileName = 'file';
+        if (typeof data === 'string') {
+            // File path — read from disk
+            const fs = await import('fs/promises');
+            const path = await import('path');
+            fileBuffer = await fs.readFile(data);
+            fileName = path.basename(data);
+            // Auto-detect MIME type if not provided
+            if (!mimeType) {
+                const ext = data.split('.').pop()?.toLowerCase();
+                const mimeMap = {
+                    jpg: 'image/jpeg',
+                    jpeg: 'image/jpeg',
+                    png: 'image/png',
+                    gif: 'image/gif',
+                    webp: 'image/webp',
+                    heic: 'image/heic',
+                    heif: 'image/heif',
+                    tif: 'image/tiff',
+                    tiff: 'image/tiff',
+                    bmp: 'image/bmp',
+                    mp4: 'video/mp4',
+                    mov: 'video/quicktime',
+                    avi: 'video/x-msvideo',
+                    mkv: 'video/x-matroska',
+                    webm: 'video/webm',
+                    mp3: 'audio/mpeg',
+                    wav: 'audio/wav',
+                    ogg: 'audio/ogg',
+                    m4a: 'audio/mp4',
+                    aac: 'audio/aac',
+                    flac: 'audio/flac',
+                    opus: 'audio/opus',
+                    pdf: 'application/pdf',
+                    txt: 'text/plain',
+                };
+                mimeType = ext ? mimeMap[ext] : 'application/octet-stream';
+            }
+        }
+        else {
+            // Already a buffer
+            fileBuffer = Buffer.from(data);
+            mimeType = mimeType ?? 'application/octet-stream';
+        }
+        // Step 3: POST file as multipart/form-data to upload URL. MAX upload hosts
+        // reject Node's native FormData in some cases with 412, while curl-style
+        // multipart with a known Content-Length is accepted.
+        const multipart = buildMultipartFileBody('data', fileName, mimeType, fileBuffer);
+        const uploadRes = await maxFetch(uploadUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': multipart.contentType,
+                'Content-Length': String(multipart.body.byteLength),
+            },
+            body: multipart.body,
+        });
+        if (!uploadRes.ok) {
+            throw new MaxApiError(`MAX media upload failed: ${uploadRes.status}`, uploadRes.status, await uploadRes.text().catch(() => null));
+        }
+        // Step 4: Parse response to extract token
+        // Image response: { photos: { "<id>": { token: "...", url: "..." } } }
+        // Video/audio/file may respond with a top-level token or a similar nested map
+        const result = (await uploadRes.json().catch(() => ({})));
+        // Try to find token from nested response structure
+        let token = typeof uploadInfo.token === 'string' ? uploadInfo.token : '';
+        let url;
+        let foundNested = false;
+        const nestedContainers = ['photos', 'videos', 'audios', 'files'];
+        for (const key of nestedContainers) {
+            const container = result[key];
+            if (container && typeof container === 'object' && !Array.isArray(container)) {
+                const first = Object.values(container)[0];
+                if (first?.token) {
+                    token = first.token;
+                    url = first.url;
+                    foundNested = true;
+                    break;
+                }
+            }
+        }
+        if (!foundNested && result.token && typeof result.token === 'string') {
+            token = result.token;
+            url = result.url ?? undefined;
+        }
+        if (!token) {
+            throw new MaxApiError('MAX media upload: no token in response', 200, result);
+        }
+        return { token, url };
+    }
+}

package/dist/src/callbacks.js

@@ -0,0 +1,111 @@
+/**
+ * Button presses (message_callback): presentation approvals and ask_user
+ * answers go to the gateway runtimes; other payloads re-enter the inbound
+ * pipeline as a synthesized message.
+ */
+import { resolveApprovalOverGateway } from 'openclaw/plugin-sdk/approval-gateway-runtime';
+import { questionGatewayRuntime } from 'openclaw/plugin-sdk/question-gateway-runtime';
+import { processIncomingMessage } from './inbound.js';
+import { decodeMaxPresentationCallback } from './presentation.js';
+/**
+ * Synthesize a regular message from a button press. The keyboard's message is
+ * a sibling of `callback` in the update; its recipient is the real chat
+ * (dialog chat_id ≠ user_id). Only when that message is gone (null) do we fall
+ * back to addressing the pressing user.
+ * callback_id is not a valid MAX message id, so replies to callback-originated
+ * commands must not use it as replyToMessageId.
+ * @internal - Exported for testing only
+ */
+export function buildCallbackMessage(callback, message, text = callback.payload ?? '') {
+    return {
+        __maxCallback: true,
+        sender: callback.user,
+        recipient: message ? message.recipient : { chat_id: callback.user.user_id },
+        timestamp: callback.timestamp,
+        body: {
+            mid: callback.callback_id,
+            text,
+        },
+    };
+}
+export async function processCallback(callback, message, userLocale, opts) {
+    const payload = callback.payload ?? '';
+    if (!payload.trim())
+        return;
+    // Presentation buttons carry private envelopes (see presentation.ts).
+    // Command buttons carry the command text itself and take the default path;
+    // plain channelData.max.buttons payloads keep arriving as message text.
+    const presentationCallback = decodeMaxPresentationCallback(payload);
+    if (presentationCallback?.kind === 'approval' || presentationCallback?.kind === 'question') {
+        await resolveMaxRuntimeControlCallback(presentationCallback, callback, opts);
+        return;
+    }
+    // Opaque callback data goes to the agent labelled, never as a slash command.
+    const text = presentationCallback?.kind === 'callback'
+        ? `callback_data: ${presentationCallback.value}`
+        : payload;
+    await processIncomingMessage(buildCallbackMessage(callback, message, text), userLocale, opts);
+}
+/**
+ * Approvals and ask_user answers are operator actions: only senders listed
+ * explicitly in the account's allowFrom may press them (a wildcard is enough
+ * for questions, never for approvals).
+ */
+function isMaxRuntimeControlSender(account, senderId, kind) {
+    const allowFrom = (account.config.allowFrom ?? []).map((entry) => String(entry).trim().replace(/^max:/i, ''));
+    if (allowFrom.includes(senderId))
+        return true;
+    return kind === 'question' && allowFrom.includes('*');
+}
+async function resolveMaxRuntimeControlCallback(action, callback, opts) {
+    const { account, config, log } = opts;
+    const senderId = String(callback.user.user_id);
+    let notification;
+    if (!isMaxRuntimeControlSender(account, senderId, action.kind)) {
+        log?.warn(`[${account.accountId}] MAX ${action.kind} button pressed by unauthorized sender ${senderId}`);
+        notification = 'You are not allowed to answer this.';
+    }
+    else {
+        try {
+            if (action.kind === 'approval') {
+                const result = await resolveApprovalOverGateway({
+                    cfg: config,
+                    approvalId: action.approvalId,
+                    approvalKind: action.approvalKind,
+                    decision: action.decision,
+                    channel: 'max',
+                    accountId: account.accountId,
+                    senderId,
+                });
+                notification = result.applied
+                    ? `Decision recorded: ${action.decision}.`
+                    : 'This approval was already resolved.';
+            }
+            else {
+                const result = await questionGatewayRuntime.resolveOption({
+                    cfg: config,
+                    questionId: action.questionId,
+                    optionValue: action.optionValue,
+                    senderId,
+                    authorize: () => isMaxRuntimeControlSender(account, senderId, 'question'),
+                });
+                notification =
+                    result.status === 'answered'
+                        ? 'Answer recorded.'
+                        : result.status === 'denied'
+                            ? 'You are not allowed to answer this.'
+                            : 'This question is no longer open.';
+            }
+        }
+        catch (err) {
+            log?.error(`[${account.accountId}] MAX ${action.kind} callback failed: ${String(err)}`);
+            notification = 'Could not apply this action.';
+        }
+    }
+    try {
+        await opts.api.answerCallback(callback.callback_id, { notification });
+    }
+    catch (err) {
+        log?.debug?.(`[${account.accountId}] MAX callback answer failed: ${String(err)}`);
+    }
+}