@aspalagin/openclaw-max 0.7.2

package/dist/src/format.js

@@ -0,0 +1,31 @@
+/**
+ * Конвертер форматирования 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) {
+    return text.replace(/<u>([\s\S]*?)<\/u>/gi, '++$1++');
+}
+/**
+ * Конвертирует OpenClaw/стандартный markdown в MAX markdown, не затрагивая
+ * содержимое inline-кода, fenced-блоков и URL.
+ */
+export function toMaxMarkdown(text) {
+    if (!text)
+        return text;
+    // split с захватывающей группой: нечётные индексы — код/URL (не трогаем)
+    return text
+        .split(CODE_OR_URL)
+        .map((segment, index) => (index % 2 === 0 ? convertSegment(segment) : segment))
+        .join('');
+}

package/dist/src/inbound-attachments.js

@@ -0,0 +1,125 @@
+/**
+ * Inbound attachments: downloads media (image, sticker, video, audio, file)
+ * into the gateway media store and describes the rest as text for the agent.
+ */
+import { sanitizeMaxFileName } from './media-temp.js';
+import { getMaxRuntime } from './runtime.js';
+import { rememberStickerCode } from './sticker-cache.js';
+/** Process attachments: download media, build descriptions for non-downloadable types. */
+export async function collectInboundAttachments(params) {
+    const { attachments, messageId, chatId, api, account, log } = params;
+    const core = getMaxRuntime();
+    const attachmentDescriptions = [];
+    const mediaInputs = [];
+    for (const att of attachments) {
+        const attType = att.type ?? 'unknown';
+        const payload = att.payload;
+        // 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 ?? '') : '';
+            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.url ?? '');
+            // 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.filename ?? payload?.filename ?? '';
+                    attachmentDescriptions.push(`[File${filename ? `: ${filename}` : ''}]`);
+                }
+                else {
+                    attachmentDescriptions.push(`[${attType}]`);
+                }
+            }
+        }
+        else if (attType === 'share') {
+            const url = (payload?.url ?? att.url ?? '');
+            attachmentDescriptions.push(`[Share${url ? `: ${url}` : ''}]`);
+        }
+        else if (attType === 'location') {
+            const lat = att.latitude ?? payload?.latitude ?? '';
+            const lon = att.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) {
+    const value = att.transcription;
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}

package/dist/src/inbound.js

@@ -0,0 +1,362 @@
+/**
+ * Inbound pipeline: DM/group gates, agent routing and context, then the
+ * reply dispatch (finalizeInboundContext → dispatchReplyWithBufferedBlockDispatcher).
+ */
+import { toInboundMediaFacts } from 'openclaw/plugin-sdk/channel-inbound';
+import { createReplyPrefixOptions } from 'openclaw/plugin-sdk/channel-outbound';
+import { deliverMaxReply, withoutMaxButtons } from './deliver.js';
+import { collectInboundAttachments } from './inbound-attachments.js';
+import { materializeMaxPresentation } from './presentation.js';
+import { getMaxRuntime } from './runtime.js';
+import { readMaxChannelButtons, sendMaxMessage } from './send.js';
+import { createMaxDraftStream } from './stream-draft.js';
+/**
+ * Process incoming MAX message through OpenClaw pipeline (also the target of
+ * synthesized /start and button-press messages).
+ */
+export async function processIncomingMessage(message, userLocale, opts) {
+    const { account, config, log, statusSink } = opts;
+    const core = getMaxRuntime();
+    const senderId = message.sender?.user_id;
+    const senderName = formatSenderName(message.sender);
+    const senderUsername = message.sender?.username ?? undefined;
+    // Determine chat type and IDs
+    const chatId = message.recipient.chat_id;
+    const chatType = message.recipient.chat_type; // "dialog", "chat", "channel"
+    const isGroup = chatType === 'chat' || chatType === 'channel';
+    const rawText = message.body.text ?? '';
+    const messageId = message.body.mid;
+    const isCallbackCommand = message.__maxCallback === true;
+    const attachments = message.body.attachments ?? [];
+    log?.debug?.(`[${account.accountId}] Processing message: mid=${messageId} chatId=${message.recipient.chat_id} chatType=${message.recipient.chat_type} senderId=${message.sender?.user_id} text="${rawText.slice(0, 50)}" attachments=${attachments.length}`);
+    // Skip truly empty messages (no text and no attachment that yields media or
+    // a description; inline keyboards yield neither). Attachments are
+    // downloaded only after the DM/group gates below, so ignored group chatter
+    // costs no traffic or disk.
+    if (!rawText.trim() && !attachments.some((att) => att.type !== 'inline_keyboard'))
+        return;
+    // Check for reply context
+    const replyToId = message.link?.type === 'reply' ? message.link.message?.body?.mid : undefined;
+    // Check for bot mention in group chats
+    let wasMentioned;
+    if (isGroup && (opts.botUsername || opts.botUserId)) {
+        // body.markup marks mentions as user_mention elements; the @botname regex
+        // stays as a fallback for clients/messages that send no markup.
+        wasMentioned = isBotMentionedInMarkup(message.body?.markup, opts.botUserId, opts.botUsername);
+        if (!wasMentioned && opts.botUsername) {
+            const mentionPattern = new RegExp(`@${escapeRegExp(opts.botUsername)}\\b`, 'i');
+            wasMentioned = mentionPattern.test(rawText);
+        }
+        // Reply to bot's message also counts as mention (like Telegram behavior)
+        if (!wasMentioned && message.link?.type === 'reply') {
+            const replySender = message.link.sender;
+            if (replySender?.is_bot && replySender?.user_id === opts.botUserId) {
+                wasMentioned = true;
+                log?.debug?.(`[${account.accountId}] Reply to bot message treated as mention`);
+            }
+        }
+    }
+    // Pressing a button on the bot's own keyboard is addressed to the bot, like a
+    // reply to its message — don't drop it at the group mention gate.
+    if (isGroup && isCallbackCommand) {
+        wasMentioned = true;
+    }
+    // DM security: check pairing/allowlist
+    if (!isGroup) {
+        const dmPolicy = account.config.dmPolicy ?? 'pairing';
+        if (dmPolicy === 'disabled') {
+            log?.debug?.(`[${account.accountId}] Blocked DM from ${senderId} (dmPolicy=disabled)`);
+            return;
+        }
+        if (dmPolicy !== 'open') {
+            const configAllowFrom = (account.config.allowFrom ?? []).map(String);
+            const storeAllowFrom = await core.channel.pairing
+                .readAllowFromStore({ channel: 'max', accountId: account.accountId })
+                .catch(() => []);
+            const effectiveAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+            const senderStr = String(senderId);
+            const allowed = effectiveAllowFrom.includes(senderStr) || effectiveAllowFrom.includes('*');
+            if (!allowed) {
+                if (dmPolicy === 'pairing') {
+                    const { code, created } = await core.channel.pairing.upsertPairingRequest({
+                        channel: 'max',
+                        id: senderStr,
+                        accountId: account.accountId,
+                        meta: { name: senderName },
+                    });
+                    if (created) {
+                        log?.info(`[${account.accountId}] Pairing request from ${senderStr}`);
+                        try {
+                            const pairingReply = core.channel.pairing.buildPairingReply({
+                                channel: 'max',
+                                idLine: `Your MAX user id: ${senderStr}`,
+                                code,
+                            });
+                            await sendMaxMessage(String(chatId ?? senderId), pairingReply, {
+                                token: account.token,
+                            });
+                            statusSink?.({ lastOutboundAt: Date.now() });
+                        }
+                        catch (err) {
+                            log?.error(`[${account.accountId}] Pairing reply failed: ${String(err)}`);
+                        }
+                    }
+                }
+                return;
+            }
+        }
+    }
+    // Group policy
+    if (isGroup) {
+        const defaultGroupPolicy = config.channels?.defaults?.groupPolicy;
+        const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? 'allowlist';
+        if (groupPolicy === 'disabled') {
+            log?.debug?.(`[${account.accountId}] Blocked group message (groupPolicy=disabled)`);
+            return;
+        }
+        // For allowlist policy, check if chat is in the groups config
+        if (groupPolicy === 'allowlist') {
+            const groups = account.config.groups ?? {};
+            const chatIdStr = String(chatId);
+            const hasWildcard = '*' in groups;
+            const chatAllowed = chatIdStr in groups || hasWildcard;
+            if (!chatAllowed) {
+                log?.debug?.(`[${account.accountId}] Blocked group message (not in allowlist, chat=${chatIdStr})`);
+                return;
+            }
+        }
+        // Require mention in groups
+        const groupCfg = account.config.groups?.[String(chatId)] ?? account.config.groups?.['*'];
+        const requireMention = groupCfg?.requireMention ?? true;
+        if (requireMention && !wasMentioned) {
+            log?.debug?.(`[${account.accountId}] Skipping group message (not mentioned)`);
+            return;
+        }
+    }
+    // Process attachments: download media, build descriptions for non-downloadable types
+    const { descriptions: attachmentDescriptions, mediaInputs } = await collectInboundAttachments({
+        attachments,
+        messageId,
+        chatId,
+        api: opts.api,
+        account,
+        log,
+    });
+    const attachmentText = attachmentDescriptions.join(' ');
+    const hasMedia = mediaInputs.length > 0;
+    const effectiveText = rawText.trim() || attachmentText;
+    // Nothing usable came out of the attachments (e.g. a failed sticker download)
+    if (!effectiveText && !hasMedia)
+        return;
+    // Resolve agent route
+    // chatIdStr stays the delivery address (MAX addresses replies by chat_id).
+    const chatIdStr = String(chatId ?? senderId);
+    // DM routing keys off the sender's user_id, not the dialog's chat_id: in MAX
+    // the two differ, and bindings/allowFrom are expressed in user_id terms, so a
+    // chat_id peer never matches. Groups keep chat_id — it is the group's own id.
+    const routePeerId = isGroup ? chatIdStr : String(senderId ?? chatId);
+    const route = core.channel.routing.resolveAgentRoute({
+        cfg: config,
+        channel: 'max',
+        accountId: account.accountId,
+        peer: {
+            kind: isGroup ? 'group' : 'direct',
+            id: routePeerId,
+        },
+    });
+    // Build context
+    const fromLabel = isGroup ? `chat:${chatIdStr}` : senderName || `user:${senderId}`;
+    const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+        agentId: route.agentId,
+    });
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
+    const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+        storePath,
+        sessionKey: route.sessionKey,
+    });
+    // Combine text and attachment descriptions for the agent
+    const bodyForAgent = attachmentText
+        ? rawText.trim()
+            ? `${rawText.trim()}\n${attachmentText}`
+            : attachmentText
+        : rawText;
+    const body = core.channel.reply.formatAgentEnvelope({
+        channel: 'MAX',
+        from: fromLabel,
+        timestamp: message.timestamp,
+        previousTimestamp,
+        envelope: envelopeOptions,
+        body: bodyForAgent,
+    });
+    // Detect text-slash commands (user types /status, /models, /reasoning etc.)
+    const rawTextTrimmed = (rawText || '').trim();
+    const isTextSlashCommand = rawTextTrimmed.startsWith('/');
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+        Body: body,
+        BodyForAgent: bodyForAgent,
+        RawBody: rawText,
+        CommandBody: rawText || attachmentText,
+        From: `max:${senderId}`,
+        To: `max:${chatIdStr}`,
+        SessionKey: route.sessionKey,
+        AccountId: route.accountId,
+        ChatType: isGroup ? 'group' : 'direct',
+        ConversationLabel: fromLabel,
+        SenderName: senderName || undefined,
+        SenderId: senderId != null ? String(senderId) : undefined,
+        SenderUsername: senderUsername,
+        WasMentioned: isGroup ? wasMentioned : undefined,
+        Provider: 'max',
+        Surface: 'max',
+        MessageSid: messageId,
+        MessageSidFull: messageId,
+        ReplyToId: replyToId,
+        ReplyToIdFull: replyToId,
+        OriginatingChannel: 'max',
+        OriginatingTo: `max:${chatIdStr}`,
+        // Media attachments (downloaded to local paths) as ordered media facts
+        media: hasMedia ? toInboundMediaFacts(mediaInputs) : undefined,
+        // Text-slash command detection: treat /status, /models etc. as text commands
+        // so OpenClaw routes them through handleCommands instead of silently dropping
+        ...(isTextSlashCommand
+            ? {
+                CommandSource: 'text',
+                CommandTurn: {
+                    kind: 'text-slash',
+                    source: 'text',
+                    authorized: undefined, // let allowFrom resolve authorization
+                    body: rawTextTrimmed,
+                },
+            }
+            : {}),
+    });
+    // Record session meta
+    void core.channel.session
+        .recordSessionMetaFromInbound({
+        storePath,
+        sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+        ctx: ctxPayload,
+    })
+        .catch((err) => {
+        log?.error(`[${account.accountId}] Failed updating session meta: ${String(err)}`);
+    });
+    // Dispatch through the standard reply pipeline
+    const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+        cfg: config,
+        agentId: route.agentId,
+        channel: 'max',
+        accountId: route.accountId,
+    });
+    // Send typing indicator while agent processes
+    if (chatId != null) {
+        opts.api.sendAction(chatId, 'typing_on').catch((err) => {
+            log?.debug?.(`[${account.accountId}] typing_on failed: ${String(err)}`);
+        });
+    }
+    // Streaming modes: "partial" = edit single message, "block" = each block as separate message
+    const streamMode = account.config.streamMode ?? 'off';
+    const useEditStreaming = streamMode === 'partial';
+    const useBlockStreaming = streamMode === 'block';
+    const replyMid = isCallbackCommand ? undefined : messageId.replace(/_edited_\d+$/, '');
+    const callbackId = isCallbackCommand ? messageId : undefined;
+    // Draft stream for edit-streaming (like Telegram's partial reply approach)
+    const draft = createMaxDraftStream({
+        account,
+        chatId: chatIdStr,
+        replyToId: replyMid,
+        log,
+        statusSink,
+    });
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx: ctxPayload,
+        cfg: config,
+        dispatcherOptions: {
+            ...prefixOptions,
+            deliver: async (rawPayload) => {
+                // This funnel consumes ReplyPayload directly, so it must apply the same
+                // presentation fallback/render policy as core's outbound path.
+                const payload = await materializeMaxPresentation(rawPayload);
+                if (useEditStreaming && draft.messageId && payload.text) {
+                    await draft.finalize(payload.text, readMaxChannelButtons(payload.channelData));
+                    // Handle media if present (buttons already sit on the draft)
+                    if (payload.mediaUrls?.length || payload.mediaUrl) {
+                        await deliverMaxReply({
+                            payload: {
+                                ...payload,
+                                text: undefined,
+                                channelData: withoutMaxButtons(payload.channelData),
+                            },
+                            account,
+                            chatId: chatIdStr,
+                            replyToId: replyMid,
+                            callbackId,
+                            config,
+                            log,
+                            statusSink,
+                        });
+                    }
+                    return;
+                }
+                // Non-streaming path or no draft yet
+                await deliverMaxReply({
+                    payload,
+                    account,
+                    chatId: chatIdStr,
+                    replyToId: replyMid,
+                    callbackId,
+                    config,
+                    log,
+                    statusSink,
+                });
+            },
+            onError: (err, info) => {
+                log?.error(`[${account.accountId}] MAX ${info.kind} reply failed: ${String(err)}`);
+            },
+        },
+        replyOptions: {
+            onModelSelected,
+            ...(useEditStreaming
+                ? {
+                    onPartialReply: (payload) => {
+                        if (payload.text)
+                            draft.update(payload.text);
+                    },
+                }
+                : {}),
+            ...(useBlockStreaming ? { disableBlockStreaming: false } : {}),
+        },
+    });
+    // Cleanup draft stream
+    await draft.clear();
+}
+/**
+ * Whether body.markup has a user_mention of this bot: by user_id (users
+ * without a username) or by user_link `@username` (case-insensitive).
+ * @internal exported for testing.
+ */
+export function isBotMentionedInMarkup(markup, botUserId, botUsername) {
+    if (!Array.isArray(markup))
+        return false;
+    const username = botUsername?.replace(/^@/, '').toLowerCase();
+    return markup.some((element) => {
+        if (element?.type !== 'user_mention')
+            return false;
+        if (botUserId != null && element.user_id === botUserId)
+            return true;
+        const link = typeof element.user_link === 'string'
+            ? element.user_link.replace(/^@/, '').toLowerCase()
+            : '';
+        return Boolean(username && link === username);
+    });
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function formatSenderName(user) {
+    if (!user)
+        return 'Unknown';
+    const parts = [user.first_name];
+    if (user.last_name)
+        parts.push(user.last_name);
+    return parts.join(' ') || user.username || `user_${user.user_id}`;
+}

package/dist/src/media-temp.js

@@ -0,0 +1,92 @@
+/**
+ * Remote media → temporary local file, for MAX uploads that need a path.
+ * One place for the download, the file name policy and the cleanup.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { getMaxRuntime } from './runtime.js';
+/** Upper bound for a sanitized file name (bytes of UTF-8 stay well under 255). */
+export const MAX_TEMP_FILE_NAME_LENGTH = 120;
+const EXTENSION_BY_CONTENT_TYPE = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/heic': 'heic',
+    'image/tiff': 'tiff',
+    'image/bmp': 'bmp',
+    'video/mp4': 'mp4',
+    'video/quicktime': 'mov',
+    'video/x-matroska': 'mkv',
+    'video/webm': 'webm',
+    'audio/mpeg': 'mp3',
+    'audio/ogg': 'ogg',
+    'audio/mp4': 'm4a',
+    'audio/wav': 'wav',
+    'audio/aac': 'aac',
+    'audio/flac': 'flac',
+    'audio/opus': 'opus',
+    'application/pdf': 'pdf',
+    'text/plain': 'txt',
+};
+/**
+ * A remote file name reduced to one safe path segment: no directories, no
+ * `..`, no control or path-reserved characters, bounded length, extension
+ * kept. Falls back to `file` (plus an extension from contentType if known).
+ */
+export function sanitizeMaxFileName(name, contentType) {
+    let base = (name ?? '').normalize('NFC');
+    // Last path segment only (both separators; URL-encoded ones too).
+    base =
+        base
+            .replace(/%2f|%5c/gi, '/')
+            .split(/[/\\]/)
+            .pop() ?? '';
+    base = base
+        .replace(/[\u0000-\u001f\u007f-\u009f<>:"|?*]/g, '_')
+        .replace(/\s+/g, ' ')
+        .replace(/\.{2,}/g, '.')
+        .replace(/^[.\s]+|[.\s]+$/g, '');
+    const dot = base.lastIndexOf('.');
+    let stem = dot > 0 ? base.slice(0, dot) : base;
+    let ext = dot > 0 ? base.slice(dot + 1).toLowerCase() : '';
+    if (!/^[a-z0-9]{1,10}$/.test(ext)) {
+        if (ext)
+            stem = base;
+        ext = '';
+    }
+    if (!ext && contentType)
+        ext = EXTENSION_BY_CONTENT_TYPE[contentType.split(';')[0].trim().toLowerCase()] ?? '';
+    if (!stem)
+        stem = 'file';
+    const room = MAX_TEMP_FILE_NAME_LENGTH - (ext ? ext.length + 1 : 0);
+    stem = Array.from(stem).slice(0, room).join('').trim() || 'file';
+    return ext ? `${stem}.${ext}` : stem;
+}
+/**
+ * Download `url` through the runtime media fetcher (size-capped), write it to
+ * a private temp directory under a sanitized name, run `use`, then remove the
+ * directory whatever happens.
+ */
+export async function withRemoteMediaTempFile(url, maxBytes, use) {
+    const loaded = await getMaxRuntime().channel.media.fetchRemoteMedia({ url, maxBytes });
+    const fileName = sanitizeMaxFileName(loaded.fileName ?? fileNameFromUrl(url), loaded.contentType);
+    const dir = await mkdtemp(join(tmpdir(), 'max-media-'));
+    try {
+        const path = join(dir, fileName);
+        await writeFile(path, loaded.buffer, { mode: 0o600 });
+        return await use({ path, contentType: loaded.contentType, fileName });
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+function fileNameFromUrl(url) {
+    try {
+        return decodeURIComponent(new URL(url).pathname.split('/').pop() ?? '') || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}