@aspalagin/openclaw-max 0.7.3 → 0.8.1

package/src/send.ts

@@ -3,7 +3,16 @@
  */
 
 import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+import {
+  buildOutboundMediaLoadOptions,
+  type OutboundMediaAccess,
+} 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 {
@@ -18,7 +27,8 @@ import {
   type MaxStickerAttachment,
 } from './api.js';
 import { toMaxMarkdown } from './format.js';
-import { withRemoteMediaTempFile } from './media-temp.js';
+import { downloadMaxRemoteMedia, type MaxLoadedMedia, sanitizeMaxFileName } from './media-temp.js';
+import { getMaxLogger } from './runtime.js';
 
 export type MaxSendButton = {
   text: string;
@@ -231,6 +241,32 @@ type MaxBodyAttachments = NonNullable<MaxNewMessageBody['attachments']>;
  * given (attachment-only bodies carry neither), notify, attachments and the
  * reply link.
  */
+/** Account defaults for notifications and link previews (config `notify`, `disableLinkPreview`). */
+export interface MaxSendDefaults {
+  notify?: boolean;
+  disableLinkPreview?: boolean;
+}
+
+/**
+ * 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: MaxSendDefaults,
+  explicit: { silent?: boolean; channelData?: unknown } = {},
+): { notify?: boolean; disableLinkPreview?: boolean } {
+  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: MaxSendOptions,
   text: string | undefined,
@@ -280,7 +316,7 @@ export type MaxSendOutcome = { messageId: string; raw: MaxSendResult };
  * 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: {
   api: MaxApi;
@@ -291,7 +327,12 @@ async function sendWithBody(params: {
 }): Promise<MaxSendOutcome> {
   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: MaxSendTarget) => {
     const sendParams = buildSendParams(to, opts);
     const send = () => api.sendMessage(body, sendParams);
@@ -314,6 +355,30 @@ async function sendWithBody(params: {
   };
 }
 
+/** Chat id → is a channel. A chat never changes its type, so this is never invalidated. */
+const channelChats = new Map<number, boolean>();
+
+/**
+ * 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: MaxApi, chatId: number): Promise<boolean> {
+  const cached = channelChats.get(chatId);
+  if (cached !== undefined) return cached;
+  let isChannel: boolean;
+  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: unknown): boolean {
   if (!(err instanceof MaxApiError)) return false;
@@ -333,7 +398,7 @@ async function retryOnceOnTimeout(send: () => Promise<MaxSendResult>): Promise<M
     return await send();
   } catch (err) {
     if (!(err instanceof MaxRequestTimeoutError)) throw err;
-    console.error(
+    getMaxLogger().error(
       `[MAX] send timed out after ${err.elapsedMs}ms (phase=${err.phase}); retrying once`,
     );
     return send();
@@ -352,7 +417,39 @@ function retryWhileAttachmentNotReady(send: () => Promise<MaxSendResult>): Promi
 }
 
 /**
- * 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: unknown): boolean {
+  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<T>(
+  text: string,
+  opts: MaxSendOptions,
+  attempt: (opts: MaxSendOptions) => Promise<T>,
+): Promise<T> {
+  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: string,
@@ -360,13 +457,15 @@ export async function sendMaxMessage(
   opts: MaxSendOptions = {},
 ): Promise<MaxSendOutcome> {
   const api = new MaxApi({ token: resolveToken(opts) });
-  return sendWithBody({
-    api,
-    to,
-    opts,
-    body: buildMaxTextBody(text, opts),
-    retry: retryOnceOnTimeout,
-  });
+  return withPlainTextFallback(text, opts, (sendOpts) =>
+    sendWithBody({
+      api,
+      to,
+      opts: sendOpts,
+      body: buildMaxTextBody(text, sendOpts),
+      retry: retryOnceOnTimeout,
+    }),
+  );
 }
 
 /**
@@ -380,10 +479,11 @@ export async function answerMaxCallback(
 ): Promise<void> {
   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 } : {}),
+    });
   });
 }
 
@@ -391,7 +491,8 @@ export async function answerMaxCallback(
  * 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: string,
@@ -401,10 +502,12 @@ export async function editMaxMessage(
   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)] } : {}),
+    });
   });
 }
 
@@ -516,13 +619,57 @@ export const MAX_VISUAL_MEDIA_PER_MESSAGE = 12;
 
 const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
 
+/**
+ * Host media access for local files, as core hands it to message actions and
+ * the outbound adapter (ChannelMessageActionContext / ChannelOutboundContext).
+ */
+export interface MaxLocalMediaAccess {
+  mediaAccess?: OutboundMediaAccess;
+  mediaLocalRoots?: readonly string[];
+  mediaReadFile?: (filePath: string) => Promise<Buffer>;
+}
+
 export interface MaxMediaSendOptions extends MaxSendOptions {
-  /** Download cap for remote media that has to be uploaded (default 20 MB). */
+  /** Size cap for media that has to be uploaded (default 20 MB). */
   mediaMaxBytes?: number;
+  /**
+   * Allowed roots and host reader for local paths. A local path is read only
+   * through core's guarded loader under these roots (realpath containment, so
+   * `..` and symlinks cannot escape); without them the gateway's default
+   * media roots apply.
+   */
+  localMedia?: MaxLocalMediaAccess;
+  /**
+   * Voice delivery (reply `audioAsVoice`, message tool `asVoice`): a single
+   * audio source goes as MAX's audio attachment even when only its MIME type
+   * says audio. MAX has no separate voice type: its clients show that
+   * attachment as a voice message.
+   */
+  asVoice?: boolean;
+}
+
+/**
+ * Media handed over as content (message tool `buffer`), not as a path or URL:
+ * the name and type come from the call; the bytes never touch the filesystem.
+ */
+export interface MaxInlineMedia {
+  buffer: Buffer;
+  /** Sanitized file name (see sanitizeMaxFileName); its extension picks the MAX type. */
+  fileName: string;
+  contentType?: string;
+}
+
+/** A local path (guarded loader), a URL (guarded download) or inline content. */
+export type MaxMediaSource = string | MaxInlineMedia;
+
+/** Readable label of a source for errors and logs (never the content). */
+export function describeMaxMediaSource(source: MaxMediaSource): string {
+  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: string): boolean {
-  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). */
@@ -535,7 +682,26 @@ function isImageLink(source: string): boolean {
   }
 }
 
-function mediaKind(source: string): 'image' | 'video' | 'audio' | 'file' {
+/**
+ * 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: MaxMediaSource): Promise<boolean> {
+  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: MaxMediaSource): 'image' | 'video' | 'audio' | 'file' {
+  if (typeof source !== 'string') return detectMaxMediaType(source.fileName);
   if (!isRemoteUrl(source)) return detectMaxMediaType(source);
   try {
     return detectMaxMediaType(new URL(source).pathname);
@@ -544,50 +710,158 @@ function mediaKind(source: string): 'image' | 'video' | 'audio' | 'file' {
   }
 }
 
-/** Upload a local path, or a remote URL through a temporary file. */
-async function uploadMaxAttachment(
-  api: MaxApi,
+/**
+ * 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: string,
   opts: MaxMediaSendOptions,
+): Promise<MaxLoadedMedia> {
+  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: MaxInlineMedia, opts: MaxMediaSendOptions): MaxLoadedMedia {
+  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)`,
+    );
+  }
+  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: MaxApi,
+  source: MaxMediaSource,
+  opts: MaxMediaSendOptions,
+): Promise<MaxLoadedMedia> {
+  return typeof source !== 'string'
+    ? loadInlineMaxMedia(source, opts)
+    : isRemoteUrl(source)
+      ? await downloadMaxRemoteMedia(
+          source,
+          opts.mediaMaxBytes ?? DEFAULT_MEDIA_MAX_BYTES,
+          api.mediaProxyUrl(),
+        )
+      : await loadLocalMaxMedia(source, opts);
+}
+
+type MaxUploadType = ReturnType<typeof detectMaxMediaType>;
+
+/**
+ * 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: MaxLoadedMedia, asVoice: boolean): MaxUploadType {
+  const type = detectMaxMediaType(media.fileName);
+  if (asVoice && media.contentType?.toLowerCase().startsWith('audio/')) return 'audio';
+  return type;
+}
+
+/**
+ * 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: MaxApi,
+  media: MaxLoadedMedia,
+  type: MaxUploadType,
 ): Promise<MaxAttachment> {
-  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 } };
-      },
+  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');
   }
-  const type = detectMaxMediaType(source);
-  const uploaded = await api.uploadMedia(type, source);
-  return { type, payload: { token: uploaded.token } };
 }
 
 /**
- * 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).
+ * 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: unknown): boolean {
+  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: MaxApi,
   to: string,
   caption: string,
-  sources: string[],
+  sources: MaxMediaSource[],
   opts: MaxMediaSendOptions,
 ): Promise<MaxSendOutcome> {
+  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<number, Promise<MaxLoadedMedia>>();
+  const asVoice = opts.asVoice === true && sources.length === 1;
+  let audioAsFile = false;
+  let hasAudio = false;
   const build = async (allowLinks: boolean): Promise<MaxNewMessageBody> => {
     const attachments: MaxAttachment[] = [];
-    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 as string } });
+        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) as unknown as MaxAttachment);
@@ -603,12 +877,25 @@ async function sendMaxAttachmentsMessage(
       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 as MaxApiError).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);
   }
 }
@@ -617,13 +904,13 @@ async function sendMaxAttachmentsMessage(
  * 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: string,
   caption: string,
-  mediaPath: string,
+  mediaPath: MaxMediaSource,
   opts: MaxMediaSendOptions = {},
 ): Promise<MaxSendOutcome> {
   const token = resolveToken(opts);
@@ -636,9 +923,9 @@ export async function sendMaxMediaMessage(
  * (up to 12 per message, an album), audio and files one per message. Order is
  * kept.
  */
-export function groupMaxMedia(sources: string[]): string[][] {
-  const groups: string[][] = [];
-  let album: string[] = [];
+export function groupMaxMedia<T extends MaxMediaSource>(sources: T[]): T[][] {
+  const groups: T[][] = [];
+  let album: T[] = [];
   const flush = () => {
     if (album.length) groups.push(album);
     album = [];
@@ -666,8 +953,8 @@ export function groupMaxMedia(sources: string[]): string[][] {
 export async function sendMaxMediaGroup(
   to: string,
   caption: string,
-  sources: string[],
-  opts: MaxMediaSendOptions & { onError?: (err: unknown, sources: string[]) => void } = {},
+  sources: MaxMediaSource[],
+  opts: MaxMediaSendOptions & { onError?: (err: unknown, sources: MaxMediaSource[]) => void } = {},
 ): Promise<{ messageIds: string[] }> {
   const token = resolveToken(opts);
   const api = new MaxApi({ token });