@aspalagin/openclaw-max 0.7.2 → 0.8.0

package/dist/src/send.js

@@ -1,11 +1,15 @@
 /**
  * Outbound message sending for MAX.
  */
+import { buildOutboundMediaLoadOptions, } from 'openclaw/plugin-sdk/media-runtime';
 import { retryAsync } from 'openclaw/plugin-sdk/runtime-env';
+import { isBlockedHostnameOrIp, resolvePinnedHostnameWithPolicy, } from 'openclaw/plugin-sdk/ssrf-runtime';
+import { loadWebMediaRaw } from 'openclaw/plugin-sdk/web-media';
 import { resolveMaxAccount } from './accounts.js';
 import { MaxApi, MaxApiError, MaxRequestTimeoutError, } from './api.js';
 import { toMaxMarkdown } from './format.js';
-import { withRemoteMediaTempFile } from './media-temp.js';
+import { downloadMaxRemoteMedia, sanitizeMaxFileName } from './media-temp.js';
+import { getMaxLogger } from './runtime.js';
 /**
  * Resolve a token from options or config.
  */
@@ -166,10 +170,20 @@ function formatOutboundText(text, format) {
     return text;
 }
 /**
- * NewMessageBody: text (MAX markdown dialect) with its format when `text` is
- * given (attachment-only bodies carry neither), notify, attachments and the
- * reply link.
+ * Notification and link-preview options of one send. An explicit value of the
+ * call beats the account default: core's `silent` flag first, then
+ * channelData.max (`notify`, `silent`, `disableLinkPreview`). Unset fields stay
+ * unset, so MAX applies its own defaults (notify on, previews on).
  */
+export function resolveMaxSendFlags(defaults, explicit = {}) {
+    const fromData = readMaxChannelSendOptions(explicit.channelData);
+    const notify = typeof explicit.silent === 'boolean' ? !explicit.silent : (fromData.notify ?? defaults.notify);
+    const disableLinkPreview = fromData.disableLinkPreview ?? defaults.disableLinkPreview;
+    return {
+        ...(notify !== undefined ? { notify } : {}),
+        ...(disableLinkPreview !== undefined ? { disableLinkPreview } : {}),
+    };
+}
 function buildMaxBody(opts, text, attachments) {
     const body = text === undefined
         ? { notify: opts.notify }
@@ -203,12 +217,17 @@ function buildSendParams(target, opts) {
  * the body (after the target, so a bad target fails before any upload), send —
  * the per-chat limiter lives in MaxApi.sendMessage — through the caller's retry
  * policy, and report the sent mid. typing_on is not sent here: the inbound
- * pipeline sends it once per handled message.
+ * pipeline keeps it up for the agent turn.
  */
 async function sendWithBody(params) {
     const { api, to, opts, retry } = params;
     const target = await resolveMaxTarget(api, to);
-    const body = typeof params.body === 'function' ? await params.body() : params.body;
+    let body = typeof params.body === 'function' ? await params.body() : params.body;
+    // MAX channels publish only with notifications (POST /messages: notify must
+    // be true or absent for a channel), so a silent send into a channel notifies.
+    if (body.notify === false && 'chat_id' in target && (await isMaxChannel(api, target.chat_id))) {
+        body = { ...body, notify: undefined };
+    }
     const sendTo = (to) => {
         const sendParams = buildSendParams(to, opts);
         const send = () => api.sendMessage(body, sendParams);
@@ -232,6 +251,32 @@ async function sendWithBody(params) {
         raw: result,
     };
 }
+/** Chat id → is a channel. A chat never changes its type, so this is never invalidated. */
+const channelChats = new Map();
+/**
+ * Whether chat_id names a MAX channel (GET /chats/{chatId}, cached). A chat
+ * the bot does not know is not a channel (the send falls back to user_id);
+ * after any other lookup failure assume a channel: a notified post is better
+ * than a send MAX rejects.
+ */
+async function isMaxChannel(api, chatId) {
+    const cached = channelChats.get(chatId);
+    if (cached !== undefined)
+        return cached;
+    let isChannel;
+    try {
+        isChannel = (await api.getChat(chatId)).type === 'channel';
+    }
+    catch (err) {
+        if (!isChatNotFound(err))
+            return true;
+        isChannel = false;
+    }
+    if (channelChats.size >= 1000)
+        channelChats.clear();
+    channelChats.set(chatId, isChannel);
+    return isChannel;
+}
 /** MAX answer for a chat_id that names no chat of the bot (e.g. a user id). */
 export function isChatNotFound(err) {
     if (!(err instanceof MaxApiError))
@@ -254,7 +299,7 @@ async function retryOnceOnTimeout(send) {
     catch (err) {
         if (!(err instanceof MaxRequestTimeoutError))
             throw err;
-        console.error(`[MAX] send timed out after ${err.elapsedMs}ms (phase=${err.phase}); retrying once`);
+        getMaxLogger().error(`[MAX] send timed out after ${err.elapsedMs}ms (phase=${err.phase}); retrying once`);
         return send();
     }
 }
@@ -269,17 +314,46 @@ function retryWhileAttachmentNotReady(send) {
     });
 }
 /**
- * Send a text message to a MAX chat or user.
+ * MAX refused a formatted text request as a whole (400) for a reason other
+ * than the target, an unready attachment or a dialog-only restriction, so the
+ * likely cause is the markup. MAX documents no dedicated code for bad markup:
+ * the known unrelated refusals are excluded instead. A 400 means nothing was
+ * created, so one plain-text resend cannot duplicate the message.
+ */
+export function isMaxFormatRejection(err) {
+    if (!(err instanceof MaxApiError) || err.status !== 400)
+        return false;
+    return !isChatNotFound(err) && !isAttachmentNotReady(err) && !isPinUnavailableForDialog(err);
+}
+/**
+ * Run a formatted text request; when MAX refuses the markup, repeat it once
+ * without `format` (the text goes as written). The second failure propagates.
+ */
+async function withPlainTextFallback(text, opts, attempt) {
+    try {
+        return await attempt(opts);
+    }
+    catch (err) {
+        if (!opts.format || !text.trim() || !isMaxFormatRejection(err))
+            throw err;
+        const code = err instanceof MaxApiError ? (err.code ?? err.status) : '';
+        getMaxLogger().warn(`[MAX] ${opts.format} refused (${code}); resending as plain text`);
+        return attempt({ ...opts, format: undefined });
+    }
+}
+/**
+ * Send a text message to a MAX chat or user. A markup refusal is retried
+ * once as plain text.
  */
 export async function sendMaxMessage(to, text, opts = {}) {
     const api = new MaxApi({ token: resolveToken(opts) });
-    return sendWithBody({
+    return withPlainTextFallback(text, opts, (sendOpts) => sendWithBody({
         api,
         to,
-        opts,
-        body: buildMaxTextBody(text, opts),
+        opts: sendOpts,
+        body: buildMaxTextBody(text, sendOpts),
         retry: retryOnceOnTimeout,
-    });
+    }));
 }
 /**
  * Answer a MAX callback. Unlike /messages, /answers is scoped by callback_id
@@ -288,25 +362,29 @@ export async function sendMaxMessage(to, text, opts = {}) {
 export async function answerMaxCallback(callbackId, text, opts = {}) {
     const token = resolveToken(opts);
     const api = new MaxApi({ token });
-    const body = buildMaxTextBody(text, opts);
-    await api.answerCallback(callbackId, {
-        ...(text || opts.buttons?.length ? { message: body } : {}),
-        ...(opts.notification ? { notification: opts.notification } : {}),
+    await withPlainTextFallback(text, opts, async (answerOpts) => {
+        await api.answerCallback(callbackId, {
+            ...(text || opts.buttons?.length ? { message: buildMaxTextBody(text, answerOpts) } : {}),
+            ...(opts.notification ? { notification: opts.notification } : {}),
+        });
     });
 }
 /**
  * Edit an existing MAX message. PUT /messages keeps the current attachments
  * when `attachments` is absent/null and deletes them all on an empty list, so
  * the keyboard is sent only when `buttons` are given (it then replaces the
- * message attachments, e.g. adds buttons to a text-only stream draft).
+ * message attachments, e.g. adds buttons to a text-only stream draft). A
+ * markup refusal is retried once as plain text.
  */
 export async function editMaxMessage(messageId, text, opts = {}) {
     const token = resolveToken(opts);
     const api = new MaxApi({ token });
-    await api.editMessage(messageId, {
-        text: formatOutboundText(text, opts.format),
-        format: opts.format ?? undefined,
-        ...(opts.buttons?.length ? { attachments: [buildInlineKeyboard(opts.buttons)] } : {}),
+    await withPlainTextFallback(text, opts, async (editOpts) => {
+        await api.editMessage(messageId, {
+            text: formatOutboundText(text, editOpts.format),
+            format: editOpts.format ?? undefined,
+            ...(opts.buttons?.length ? { attachments: [buildInlineKeyboard(opts.buttons)] } : {}),
+        });
     });
 }
 /**
@@ -395,8 +473,13 @@ function isAttachmentNotReady(err) {
 /** Images and videos per message (docs «Медиафайлы»: up to 12 in total). */
 export const MAX_VISUAL_MEDIA_PER_MESSAGE = 12;
 const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+/** Readable label of a source for errors and logs (never the content). */
+export function describeMaxMediaSource(source) {
+    return typeof source === 'string' ? source : `${source.fileName} (inline)`;
+}
+/** Any case: core's local-file loader would fetch such a URL itself, past the proxy. */
 function isRemoteUrl(source) {
-    return source.startsWith('https://') || source.startsWith('http://');
+    return /^https?:\/\//i.test(source);
 }
 /** https link whose path looks like an image: MAX can fetch it itself (image.payload.url). */
 function isImageLink(source) {
@@ -409,7 +492,29 @@ function isImageLink(source) {
         return false;
     }
 }
+/**
+ * An image link handed to MAX by URL must point to a public host: not a
+ * private, loopback, link-local or metadata address, also after DNS
+ * resolution. Anything else is downloaded through the guarded fetcher (which
+ * refuses such hosts as well) and uploaded.
+ */
+async function isPublicImageLink(source) {
+    if (typeof source !== 'string' || !isImageLink(source))
+        return false;
+    try {
+        const { hostname } = new URL(source);
+        if (isBlockedHostnameOrIp(hostname))
+            return false;
+        await resolvePinnedHostnameWithPolicy(hostname);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function mediaKind(source) {
+    if (typeof source !== 'string')
+        return detectMaxMediaType(source.fileName);
     if (!isRemoteUrl(source))
         return detectMaxMediaType(source);
     try {
@@ -419,33 +524,122 @@ function mediaKind(source) {
         return 'file';
     }
 }
-/** Upload a local path, or a remote URL through a temporary file. */
-async function uploadMaxAttachment(api, source, opts) {
-    if (isRemoteUrl(source)) {
-        return withRemoteMediaTempFile(source, opts.mediaMaxBytes ?? DEFAULT_MEDIA_MAX_BYTES, async ({ path, contentType }) => {
-            const type = detectMaxMediaType(path);
-            const uploaded = await api.uploadMedia(type, path, contentType);
-            return { type, payload: { token: uploaded.token } };
-        });
+/**
+ * A local media file through core's guarded loader (loadWebMediaRaw): only
+ * under the allowed roots, through the host reader when core passed one,
+ * capped at the media size limit. A path outside the roots fails with
+ * LocalMediaAccessError ("Local media path is not under an allowed
+ * directory") before any byte is read.
+ */
+async function loadLocalMaxMedia(source, opts) {
+    const loaded = await loadWebMediaRaw(source, buildOutboundMediaLoadOptions({
+        maxBytes: opts.mediaMaxBytes ?? DEFAULT_MEDIA_MAX_BYTES,
+        mediaAccess: opts.localMedia?.mediaAccess,
+        mediaLocalRoots: opts.localMedia?.mediaLocalRoots,
+        mediaReadFile: opts.localMedia?.mediaReadFile,
+        optimizeImages: false,
+    }));
+    return {
+        buffer: loaded.buffer,
+        contentType: loaded.contentType,
+        fileName: sanitizeMaxFileName(loaded.fileName, loaded.contentType),
+    };
+}
+/**
+ * Inline content within the media size limit, as an upload-ready file. The
+ * caller decodes it; the limit is checked again here for every path in.
+ */
+function loadInlineMaxMedia(source, opts) {
+    const maxBytes = opts.mediaMaxBytes ?? DEFAULT_MEDIA_MAX_BYTES;
+    if (source.buffer.byteLength > maxBytes) {
+        throw new Error(`Inline media ${source.fileName} is ${source.buffer.byteLength} bytes, over the ${maxBytes}-byte limit (mediaMaxMb)`);
     }
-    const type = detectMaxMediaType(source);
-    const uploaded = await api.uploadMedia(type, source);
-    return { type, payload: { token: uploaded.token } };
+    return {
+        buffer: source.buffer,
+        contentType: source.contentType,
+        fileName: sanitizeMaxFileName(source.fileName, source.contentType),
+    };
+}
+/**
+ * Load a local path (guarded loader), a remote URL (SSRF-guarded download)
+ * or inline content (size-checked).
+ */
+async function loadMaxMediaSource(api, source, opts) {
+    return typeof source !== 'string'
+        ? loadInlineMaxMedia(source, opts)
+        : isRemoteUrl(source)
+            ? await downloadMaxRemoteMedia(source, opts.mediaMaxBytes ?? DEFAULT_MEDIA_MAX_BYTES, api.mediaProxyUrl())
+            : await loadLocalMaxMedia(source, opts);
+}
+/**
+ * Upload type by file name; a voice send also takes audio known only by its
+ * MIME type (.oga, audio/webm) as audio.
+ */
+function maxUploadType(media, asVoice) {
+    const type = detectMaxMediaType(media.fileName);
+    if (asVoice && media.contentType?.toLowerCase().startsWith('audio/'))
+        return 'audio';
+    return type;
 }
 /**
- * One message with the given media. https image links go as image.payload.url
- * (no download/upload round trip); if MAX refuses the message, those links are
- * uploaded and the message is sent once more. MAX processes video/file uploads
- * asynchronously — sendMessage may answer attachment.not.ready for a few
- * seconds; retry the send (not the upload).
+ * Upload loaded media. MAX may refuse an audio upload (a format it does not
+ * take as audio): nothing was sent yet, so the same bytes go as a file.
+ */
+async function uploadMaxAttachment(api, media, type) {
+    try {
+        const uploaded = await api.uploadMedia(type, media.buffer, media.contentType, media.fileName);
+        return { type, payload: { token: uploaded.token } };
+    }
+    catch (err) {
+        if (type !== 'audio' || !(err instanceof MaxApiError))
+            throw err;
+        getMaxLogger().warn(`[MAX] audio upload of ${media.fileName} refused (${err.code ?? err.status}); sending as a file`);
+        return uploadMaxAttachment(api, media, 'file');
+    }
+}
+/**
+ * MAX refused a message with an audio attachment (400, also an audio still
+ * not processed after the attachment.not.ready retries): nothing was created,
+ * so one resend with the audio as a file cannot duplicate.
+ */
+function isMaxAudioRefusal(err) {
+    return err instanceof MaxApiError && err.status === 400 && !isChatNotFound(err);
+}
+/**
+ * One message with the given media. Image links to public https hosts go as
+ * image.payload.url (no download/upload round trip); if MAX refuses the
+ * message, those links are uploaded and the message is sent once more. MAX
+ * processes video/file uploads asynchronously — sendMessage may answer
+ * attachment.not.ready for a few seconds; retry the send (not the upload).
+ * Audio goes as MAX's audio attachment (shown as a voice message); if MAX
+ * refuses it, the audio is sent once more as a file, so the reply is not lost.
  */
 async function sendMaxAttachmentsMessage(api, to, caption, sources, opts) {
+    const links = await Promise.all(sources.map(isPublicImageLink));
+    // Loaded once per message: a resend reuses the bytes instead of a new read.
+    const loaded = new Map();
+    const asVoice = opts.asVoice === true && sources.length === 1;
+    let audioAsFile = false;
+    let hasAudio = false;
     const build = async (allowLinks) => {
         const attachments = [];
-        for (const source of sources) {
-            attachments.push(allowLinks && isImageLink(source)
-                ? { type: 'image', payload: { url: source } }
-                : await uploadMaxAttachment(api, source, opts));
+        hasAudio = false;
+        for (const [index, source] of sources.entries()) {
+            if (allowLinks && links[index]) {
+                attachments.push({ type: 'image', payload: { url: source } });
+                continue;
+            }
+            let media = loaded.get(index);
+            if (!media) {
+                media = loadMaxMediaSource(api, source, opts);
+                loaded.set(index, media);
+            }
+            const loadedMedia = await media;
+            const type = maxUploadType(loadedMedia, asVoice);
+            const attachment = await uploadMaxAttachment(api, loadedMedia, type === 'audio' && audioAsFile ? 'file' : type);
+            if (attachment.type === 'audio')
+                hasAudio = true;
+            attachments.push(attachment);
         }
         if (opts.buttons?.length) {
             attachments.push(buildInlineKeyboard(opts.buttons));
@@ -459,15 +653,25 @@ async function sendMaxAttachmentsMessage(api, to, caption, sources, opts) {
         body: () => build(allowLinks),
         retry: retryWhileAttachmentNotReady,
     });
-    if (!sources.some(isImageLink))
-        return send(false);
+    if (!links.some(Boolean)) {
+        try {
+            return await send(false);
+        }
+        catch (err) {
+            if (!hasAudio || !isMaxAudioRefusal(err))
+                throw err;
+            getMaxLogger().warn(`[MAX] message with audio refused (${err.code ?? 400}); sending the audio as a file`);
+            audioAsFile = true;
+            return send(false);
+        }
+    }
     try {
         return await send(true);
     }
     catch (err) {
         if (!(err instanceof MaxApiError))
             throw err;
-        console.warn(`[MAX] image by URL refused (${err.code ?? err.status}); uploading instead`);
+        getMaxLogger().warn(`[MAX] image by URL refused (${err.code ?? err.status}); uploading instead`);
         return send(false);
     }
 }
@@ -475,7 +679,7 @@ async function sendMaxAttachmentsMessage(api, to, caption, sources, opts) {
  * Send a media message to MAX (with upload).
  * @param to Chat ID or user ID
  * @param caption Text caption
- * @param mediaPath Local file path or URL (https image links are sent by URL)
+ * @param mediaPath Local file path (under the allowed roots), URL (public https image links are sent by URL) or inline content
  * @param opts Send options
  */
 export async function sendMaxMediaMessage(to, caption, mediaPath, opts = {}) {

package/dist/src/stream-draft.js

@@ -1,9 +1,11 @@
 /**
  * Edit streaming (streamMode "partial"): the first partial reply is sent as a
  * message, later partials edit it (throttled), and the final answer replaces
- * the draft together with its inline keyboard.
+ * the draft together with its inline keyboard. The draft holds one MAX
+ * message: a longer final answer is split by the reply delivery, which puts
+ * the first chunk into the draft and sends the rest as new messages.
  */
-import { editMaxMessage, sendMaxMessage } from './send.js';
+import { deleteMaxMessage, editMaxMessage, resolveMaxSendFlags, sendMaxMessage, } from './send.js';
 const DRAFT_THROTTLE_MS = 1200;
 const DRAFT_MAX_CHARS = 4000;
 const DRAFT_MIN_CHARS = 30; // Don't send until we have enough text
@@ -15,6 +17,18 @@ export function createMaxDraftStream(params) {
     let draftLastEditAt = 0;
     let draftTimer = null;
     let draftStopped = false;
+    let draftFinalized = false;
+    // Sends and edits run one at a time: a deferred update or the final never
+    // races the first send (which would leave a second, orphaned draft).
+    let inflight = Promise.resolve();
+    const stop = async () => {
+        if (draftTimer) {
+            clearTimeout(draftTimer);
+            draftTimer = null;
+        }
+        draftStopped = true;
+        await inflight;
+    };
     const draftUpdate = async (text) => {
         if (draftStopped || !text)
             return;
@@ -43,60 +57,88 @@ export function createMaxDraftStream(params) {
         }
         draftLastText = trimmed;
         draftLastEditAt = now;
-        try {
-            if (!draftMid) {
-                // First chunk — send new message
-                const res = await sendMaxMessage(chatId, trimmed, {
-                    token: account.token,
-                    replyToMessageId: params.replyToId,
-                    format: 'markdown',
-                });
-                draftMid = res.messageId || null;
-                statusSink?.({ lastOutboundAt: Date.now() });
+        const run = inflight.then(async () => {
+            // Stopped meanwhile (the final answer took over).
+            if (draftStopped)
+                return;
+            try {
+                if (!draftMid) {
+                    // First chunk — send new message
+                    // The draft is the message the user is notified about: account defaults apply.
+                    const res = await sendMaxMessage(chatId, trimmed, {
+                        token: account.token,
+                        replyToMessageId: params.replyToId,
+                        format: 'markdown',
+                        ...resolveMaxSendFlags(account.config),
+                    });
+                    draftMid = res.messageId || null;
+                    statusSink?.({ lastOutboundAt: Date.now() });
+                }
+                else {
+                    // Edit existing message
+                    await editMaxMessage(draftMid, trimmed, {
+                        token: account.token,
+                        format: 'markdown',
+                    });
+                }
             }
-            else {
-                // Edit existing message
-                await editMaxMessage(draftMid, trimmed, {
-                    token: account.token,
-                    format: 'markdown',
-                });
+            catch (err) {
+                draftStopped = true;
+                log?.debug?.(`[${account.accountId}] MAX draft stream failed: ${String(err)}`);
             }
-        }
-        catch (err) {
-            draftStopped = true;
-            log?.debug?.(`[${account.accountId}] MAX draft stream failed: ${String(err)}`);
-        }
+        });
+        inflight = run;
+        await run;
     };
     return {
         get messageId() {
             return draftMid;
         },
+        get finalized() {
+            return draftFinalized;
+        },
         update: draftUpdate,
         finalize: async (finalText, buttons) => {
             // Final delivery replaces the draft message with final text. The
             // keyboard (presentation buttons) goes onto the same edit, otherwise
             // the final answer would lose its buttons.
-            if (draftMid && (finalText !== draftLastText || buttons?.length)) {
-                try {
-                    await editMaxMessage(draftMid, finalText, {
-                        token: account.token,
-                        format: 'markdown',
-                        buttons,
-                    });
-                    draftLastText = finalText;
-                }
-                catch {
-                    /* best effort */
-                }
+            await stop();
+            if (!draftMid)
+                return false;
+            if (finalText === draftLastText && !buttons?.length) {
+                draftFinalized = true;
+                return true;
+            }
+            try {
+                await editMaxMessage(draftMid, finalText, {
+                    token: account.token,
+                    format: 'markdown',
+                    buttons,
+                });
+                draftLastText = finalText;
+                draftFinalized = true;
+                return true;
+            }
+            catch (err) {
+                log?.warn(`[${account.accountId}] MAX draft final edit failed: ${String(err)}`);
+                return false;
             }
-            draftStopped = true;
         },
-        clear: async () => {
-            if (draftTimer) {
-                clearTimeout(draftTimer);
-                draftTimer = null;
+        discard: async () => {
+            await stop();
+            if (!draftMid)
+                return true;
+            try {
+                await deleteMaxMessage(draftMid, { token: account.token });
+                draftMid = null;
+                return true;
+            }
+            catch (err) {
+                log?.warn(`[${account.accountId}] MAX draft delete failed: ${String(err)}`);
+                return false;
             }
-            draftStopped = true;
         },
+        clear: stop,
+        settle: stop,
     };
 }

package/dist/src/turn-adoption.js

@@ -0,0 +1,24 @@
+/**
+ * Hand-off between a journaled webhook update and core's own restart recovery.
+ *
+ * Core records a recovery claim when it adopts an agent turn and resumes that
+ * turn after a crash by itself. The journal row of the update must therefore
+ * be completed at adoption, not only when the dispatch returns: replaying it
+ * after a crash mid-turn would run the turn twice (SDK durable ingress rule:
+ * "mark the event complete at dispatch adoption"). The webhook queue and the
+ * polling loop run each journaled dispatch with its completion callback (for
+ * polling: remembering the dedupe key); the reply dispatch passes
+ * it on as the public `turnAdoptionLifecycle` reply option. Without `admission`
+ * or `ownerKey` core groups queued follow-ups exactly as without a lifecycle.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const adoption = new AsyncLocalStorage();
+/** Run a dispatch whose agent turn, once adopted by core, calls `onAdopted`. */
+export function runWithMaxTurnAdoption(onAdopted, dispatch) {
+    return adoption.run(onAdopted, dispatch);
+}
+/** Reply options fragment carrying the current update's adoption callback, if any. */
+export function maxTurnAdoptionReplyOptions() {
+    const onAdopted = adoption.getStore();
+    return onAdopted ? { turnAdoptionLifecycle: { onAdopted } } : {};
+}

package/dist/src/typing.js

@@ -0,0 +1,55 @@
+/**
+ * MAX typing indicator ("typing_on") on the SDK typing lifecycle.
+ *
+ * MAX shows the indicator for a few seconds and has no explicit stop action,
+ * so a long turn needs periodic refreshes. The shared SDK keepalive owns the
+ * refresh loop, the failure circuit breaker and the safety TTL; core stops it
+ * when the run completes, fails or is aborted.
+ */
+import { createTypingCallbacks } from 'openclaw/plugin-sdk/channel-outbound';
+import { resolveMaxAccount } from './accounts.js';
+import { MaxApi } from './api.js';
+import { resolveMaxTarget } from './send.js';
+/** Refresh period: shorter than the indicator lifetime on MAX clients. */
+export const MAX_TYPING_KEEPALIVE_MS = 4_000;
+/** Deadline for one typing request; a slow one is dropped, not retried. */
+const MAX_TYPING_TIMEOUT_MS = 5_000;
+/**
+ * One typing_on request. Best effort: a single attempt with a short deadline,
+ * since a retried indicator could land after the reply it announced. The
+ * actions endpoint is not a message send, so the per-chat send limiter does
+ * not apply; the keepalive period keeps it far below 2 requests per second.
+ */
+export async function sendMaxTypingAction(api, chatId, signal) {
+    await api.sendAction(chatId, 'typing_on', {
+        retryAttempts: 0,
+        timeoutMs: MAX_TYPING_TIMEOUT_MS,
+        ...(signal ? { signal } : {}),
+    });
+}
+/** Typing callbacks for one inbound turn in `chatId`; failures are only logged. */
+export function createMaxTypingCallbacks(params) {
+    return createTypingCallbacks({
+        start: () => sendMaxTypingAction(params.api, params.chatId),
+        onStartError: params.onError,
+        keepaliveIntervalMs: MAX_TYPING_KEEPALIVE_MS,
+    });
+}
+/**
+ * heartbeat.sendTyping / sendTypingGuarded: core wraps them in the same
+ * keepalive lifecycle (heartbeat runs; gateway runs and task progress use the
+ * guarded variant with a cancellation signal and a send-authorization check). Only chat targets can show typing (the actions endpoint takes
+ * a chat id); user:<id> targets and accounts without a token are skipped.
+ */
+export async function sendMaxHeartbeatTyping(params) {
+    const account = resolveMaxAccount({ cfg: params.cfg, accountId: params.accountId });
+    if (!account.token)
+        return;
+    const api = new MaxApi({ token: account.token });
+    const target = await resolveMaxTarget(api, params.to);
+    if (!('chat_id' in target) || params.signal?.aborted)
+        return;
+    // Recheck right before the physical send: the owner may have ended meanwhile.
+    params.assertPlatformSendAuthorized?.();
+    await sendMaxTypingAction(api, target.chat_id, params.signal);
+}