@aspalagin/openclaw-max 0.7.3 → 0.8.1

package/src/actions.ts

@@ -2,22 +2,37 @@
  * MAX channel message actions adapter — implements message tool actions
  */
 
-import type { ChannelMessageActionAdapter } from 'openclaw/plugin-sdk/channel-contract';
+import { createActionGate } from 'openclaw/plugin-sdk/channel-actions';
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionContext,
+} from 'openclaw/plugin-sdk/channel-contract';
 import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
 import { normalizeMessagePresentation } from 'openclaw/plugin-sdk/interactive-runtime';
+import { getAgentScopedMediaLocalRoots } from 'openclaw/plugin-sdk/media-local-roots';
 import { readStringParam } from 'openclaw/plugin-sdk/param-readers';
 import { jsonResult } from 'openclaw/plugin-sdk/tool-results';
 
 import { listMaxAccountIds, resolveMaxAccount } from './accounts.js';
-import { materializeMaxPresentation, MAX_TEXT_LIMIT, readMaxDeliveryPin } from './presentation.js';
+import { assertMaxActionInScope } from './action-scope.js';
+import { sanitizeMaxFileName } from './media-temp.js';
+import {
+  materializeMaxPresentation,
+  readMaxDeliveryPin,
+  resolveMaxTextChunkLimit,
+} from './presentation.js';
 import { getMaxRuntime } from './runtime.js';
 import {
   deleteMaxMessage,
+  describeMaxMediaSource,
   editMaxMessage,
+  type MaxLocalMediaAccess,
   type MaxMediaSendOptions,
+  type MaxMediaSource,
   pinMaxMessage,
   readMaxChannelButtons,
   readMaxSendButtons,
+  resolveMaxSendFlags,
   sendMaxContact,
   sendMaxLocation,
   sendMaxMediaGroup,
@@ -30,6 +45,72 @@ import { getLastStickerCode } from './sticker-cache.js';
 
 const providerId = 'max';
 const mediaSourceKeys = ['media', 'filePath', 'path', 'fileUrl', 'url', 'buffer', 'image'] as const;
+/**
+ * Params that carry a media path or URL, per action: core normalizes them for
+ * the sandbox and scopes outbound media access to them. `buffer` is base64
+ * content for core, not a path, so it is not declared.
+ */
+const mediaSourceParams = mediaSourceKeys.filter((key) => key !== 'buffer');
+
+/** `data:<type>;base64,<data>` — a data URL in `buffer`. */
+const DATA_URL_RE = /^data:([^;,]*)(?:;[^,]*)?;base64,/i;
+
+/**
+ * Inline content from `buffer` (base64 or a base64 data URL) with `filename`
+ * and `contentType` (aliases fileName, mimeType) of the same object. The size
+ * limit is checked before decoding, so an oversized payload is refused
+ * without allocating it.
+ */
+function readInlineMedia(
+  source: Record<string, unknown>,
+  maxBytes: number,
+): MaxMediaSource | undefined {
+  const raw = typeof source.buffer === 'string' ? source.buffer : undefined;
+  if (!raw?.trim()) return undefined;
+  const dataUrl = DATA_URL_RE.exec(raw);
+  const base64 = (dataUrl ? raw.slice(dataUrl[0].length) : raw).replace(/\s+/g, '');
+  if (!/^[A-Za-z0-9+/_-]*={0,2}$/.test(base64)) {
+    throw new Error('buffer is not valid base64 content');
+  }
+  const decodedBytes = Math.floor((base64.replace(/=+$/, '').length * 3) / 4);
+  if (decodedBytes > maxBytes) {
+    throw new Error(
+      `buffer is ${decodedBytes} bytes, over the ${maxBytes}-byte media limit (mediaMaxMb)`,
+    );
+  }
+  const buffer = Buffer.from(
+    base64,
+    base64.includes('-') || base64.includes('_') ? 'base64url' : 'base64',
+  );
+  if (buffer.byteLength === 0) throw new Error('buffer is empty');
+  const pick = (...keys: string[]) =>
+    keys
+      .map((key) => source[key])
+      .find((value): value is string => typeof value === 'string' && value.trim() !== '')
+      ?.trim();
+  const contentType = pick('contentType', 'mimeType') ?? (dataUrl?.[1] || undefined);
+  return {
+    buffer,
+    fileName: sanitizeMaxFileName(pick('filename', 'fileName'), contentType),
+    contentType,
+  };
+}
+
+/**
+ * Local media access for an action: the roots and host reader core passed
+ * with the action; without them (direct plugin dispatch) the agent-scoped
+ * default roots. Local files are read only through this policy.
+ */
+function resolveActionLocalMedia(ctx: ChannelMessageActionContext): MaxLocalMediaAccess {
+  if (ctx.mediaAccess || ctx.mediaLocalRoots?.length || ctx.mediaReadFile) {
+    return {
+      mediaAccess: ctx.mediaAccess,
+      mediaLocalRoots: ctx.mediaLocalRoots,
+      mediaReadFile: ctx.mediaReadFile,
+    };
+  }
+  return { mediaLocalRoots: getAgentScopedMediaLocalRoots(ctx.cfg, ctx.agentId ?? undefined) };
+}
 
 function listEnabledAccounts(cfg: OpenClawConfig) {
   return listMaxAccountIds(cfg)
@@ -49,32 +130,29 @@ function readTargetParam(params: Record<string, unknown>, required = true): stri
 /**
  * Media sources in order: the direct media field first, then every
  * structured `attachments[]` item (one source per item). Duplicates dropped.
+ * A path or URL wins over `buffer` (core may fill both; the path goes through
+ * the guarded loader); `buffer` alone is sent as inline content.
  */
-function readMediaSources(params: Record<string, unknown>): string[] {
-  const sources: string[] = [];
-  const add = (value: string | undefined) => {
+function readMediaSources(params: Record<string, unknown>, maxBytes: number): MaxMediaSource[] {
+  const sources: MaxMediaSource[] = [];
+  const add = (value: MaxMediaSource | undefined) => {
     if (value && !sources.includes(value)) sources.push(value);
   };
-
-  for (const key of mediaSourceKeys) {
-    const value = readStringParam(params, key, { trim: false });
-    if (value) {
-      add(value);
-      break;
+  const readPath = (source: Record<string, unknown>): string | undefined => {
+    for (const key of mediaSourceParams) {
+      const value = readStringParam(source, key, { trim: false });
+      if (value) return value;
     }
-  }
+    return undefined;
+  };
+
+  add(readPath(params) ?? readInlineMedia(params, maxBytes));
 
   if (Array.isArray(params.attachments)) {
     for (const item of params.attachments) {
       if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
       const attachment = item as Record<string, unknown>;
-      for (const key of mediaSourceKeys) {
-        const value = typeof attachment[key] === 'string' ? attachment[key] : undefined;
-        if (value) {
-          add(value);
-          break;
-        }
-      }
+      add(readPath(attachment) ?? readInlineMedia(attachment, maxBytes));
     }
   }
 
@@ -89,7 +167,7 @@ function readMediaSources(params: Record<string, unknown>): string[] {
 async function sendMaxMediaSources(
   to: string,
   caption: string,
-  sources: string[],
+  sources: MaxMediaSource[],
   opts: MaxMediaSendOptions,
 ): Promise<{
   messageId: string;
@@ -113,7 +191,7 @@ async function sendMaxMediaSources(
     ...opts,
     onError: (err, failed) => {
       firstError ??= err;
-      errors.push(`${failed.join(', ')}: ${String(err)}`);
+      errors.push(`${failed.map(describeMaxMediaSource).join(', ')}: ${String(err)}`);
     },
   });
   if (messageIds.length === 0 && firstError !== undefined) throw firstError;
@@ -160,6 +238,13 @@ function readLocationParams(
   return { latitude: lat, longitude: lng };
 }
 
+/** Voice delivery of audio: core's `asVoice` (or its `audioAsVoice` alias), boolean or "true". */
+function readAsVoiceParam(params: Record<string, unknown>): boolean {
+  return [params.asVoice, params.audioAsVoice].some(
+    (value) => value === true || (typeof value === 'string' && value.trim() === 'true'),
+  );
+}
+
 /** Contact card fields: contactId (MAX user id) and vcfPhone/phone next to the given name. */
 function readContactParams(
   params: Record<string, unknown>,
@@ -174,20 +259,47 @@ function readContactParams(
   };
 }
 
+const MAX_MESSAGE_ACTIONS = [
+  'send',
+  'edit',
+  'delete',
+  'sticker',
+  'sendAttachment',
+  'pin',
+  'unpin',
+] as const;
+
 export const maxMessageActions: ChannelMessageActionAdapter = {
-  describeMessageTool: ({ cfg }) => {
+  describeMessageTool: ({ cfg, accountId }) => {
     const accounts = listEnabledAccounts(cfg);
     if (accounts.length === 0) {
       return null;
     }
+    // channels.max.actions.<action>: false hides the action from the tool.
+    const gate = createActionGate(resolveMaxAccount({ cfg, accountId }).config.actions);
     return {
-      actions: ['send', 'edit', 'delete', 'sticker', 'sendAttachment', 'pin', 'unpin'],
+      actions: MAX_MESSAGE_ACTIONS.filter((name) => gate(name)),
       // presentation → inline keyboard + MAX markdown (presentation.ts);
       // delivery-pin → PUT /chats/{chatId}/pin on the sent message.
       capabilities: ['presentation', 'delivery-pin'],
+      mediaSourceParams: { send: mediaSourceParams, sendAttachment: mediaSourceParams },
     };
   },
 
+  // A send with a presentation is delivered by core itself (outbound adapter
+  // sendPayload), never reaching handleAction: the action gate and scope are
+  // checked here first, then core delivers the payload unchanged. Any other
+  // send declines (null) and keeps the handleAction path, which checks them.
+  prepareSendPayload: async ({ ctx, to, payload, replyToId }) => {
+    if (!payload.presentation) return null;
+    const account = resolveMaxAccount({ cfg: ctx.cfg, accountId: ctx.accountId });
+    if (!createActionGate(account.config.actions)('send')) {
+      throw new Error('MAX action "send" is disabled by channels.max.actions');
+    }
+    await assertMaxActionInScope(ctx, account, { to, replyTo: replyToId });
+    return payload;
+  },
+
   extractToolSend: ({ args }: { args: Record<string, unknown> }) => {
     // Extract routing info for ALL actions (send, edit, delete, sticker)
     // Core uses extractToolSend for routing all message tool actions to plugin
@@ -209,13 +321,14 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
     if (!to) {
       return null;
     }
-    // Strip provider prefix (e.g. "max:188862440" → "188862440")
+    // Strip provider prefix (e.g. "max:123456789" → "123456789")
     if (to.startsWith('max:')) to = to.slice(4);
     const accountId = typeof args.accountId === 'string' ? args.accountId.trim() : undefined;
     return { to, accountId };
   },
 
-  handleAction: async ({ action, params, cfg, accountId }) => {
+  handleAction: async (ctx) => {
+    const { action, params, cfg, accountId } = ctx;
     const account = resolveMaxAccount({
       cfg,
       accountId,
@@ -223,8 +336,17 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
     if (!account.token) {
       throw new Error('MAX bot token not configured');
     }
+    if (!createActionGate(account.config.actions)(action)) {
+      throw new Error(`MAX action "${action}" is disabled by channels.max.actions`);
+    }
 
-    // Strip provider prefix from target (e.g. "max:188862440" → "188862440")
+    // Notification and link-preview options of sends: core's `silent` flag
+    // beats the account defaults (channels.max.notify / disableLinkPreview).
+    const sendFlags = resolveMaxSendFlags(account.config, {
+      silent: typeof params.silent === 'boolean' ? params.silent : undefined,
+    });
+
+    // Strip provider prefix from target (e.g. "max:123456789" → "123456789")
     const stripPrefix = (val: string | undefined): string | undefined => {
       if (!val) return val;
       return val.startsWith('max:') ? val.slice(4) : val;
@@ -232,6 +354,10 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
 
     if (action === 'send') {
       const to = stripPrefix(readTargetParam(params))!;
+      await assertMaxActionInScope(ctx, account, {
+        to,
+        replyTo: readStringParam(params, 'replyTo'),
+      });
       const presentation = normalizeMessagePresentation(params.presentation);
       const pin = readMaxDeliveryPin(params.delivery, params.pin);
       const content =
@@ -285,15 +411,17 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
         const rendered = await materializeMaxPresentation({ text: content, presentation });
         const renderedButtons = readMaxChannelButtons(rendered.channelData);
         const text = rendered.text ?? '';
+        const chunkLimit = resolveMaxTextChunkLimit(cfg, account.accountId);
         const chunks =
-          text.length > MAX_TEXT_LIMIT
-            ? getMaxRuntime().channel.text.chunkMarkdownText(text, MAX_TEXT_LIMIT)
+          text.length > chunkLimit
+            ? getMaxRuntime().channel.text.chunkMarkdownText(text, chunkLimit)
             : [text];
         let firstMessageId = '';
         let firstChatType: string | undefined;
         for (let index = 0; index < chunks.length; index += 1) {
           const sent = await sendMaxMessage(to, chunks[index], {
             token: account.token,
+            ...sendFlags,
             replyToMessageId:
               index === 0 ? (readStringParam(params, 'replyTo') ?? undefined) : undefined,
             format: 'markdown',
@@ -323,6 +451,7 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
         if (firstCode) {
           const result = await sendMaxSticker(to, firstCode, {
             token: account.token,
+            ...sendFlags,
             replyToMessageId: replyTo ?? undefined,
           });
           return withPin(result.messageId, result.raw.message?.recipient?.chat_type);
@@ -334,6 +463,7 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
       if (location) {
         const result = await sendMaxLocation(to, location, content || undefined, {
           token: account.token,
+          ...sendFlags,
           replyToMessageId: replyTo ?? undefined,
           format: 'markdown',
         });
@@ -345,28 +475,35 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
       if (contactName) {
         const result = await sendMaxContact(to, readContactParams(params, contactName), {
           token: account.token,
+          ...sendFlags,
           replyToMessageId: replyTo ?? undefined,
         });
         return withPin(result.messageId, result.raw.message?.recipient?.chat_type);
       }
 
       // Media: direct media fields and every structured attachments[] item.
-      const mediaSources = readMediaSources(params);
+      const mediaMaxBytes = (account.config.mediaMaxMb ?? 20) * 1024 * 1024;
+      const mediaSources = readMediaSources(params, mediaMaxBytes);
 
       if (mediaSources.length) {
-        // Local path or URL: https image links go by URL, other remote media
-        // is downloaded to a temp file and uploaded.
+        // Local paths only under the allowed roots (resolveActionLocalMedia);
+        // public https image links go by URL, other remote media is
+        // downloaded through the SSRF-guarded fetcher and uploaded.
         const result = await sendMaxMediaSources(to, content, mediaSources, {
           token: account.token,
+          ...sendFlags,
           replyToMessageId: replyTo ?? undefined,
           format: 'markdown',
-          mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+          mediaMaxBytes,
+          localMedia: resolveActionLocalMedia(ctx),
+          asVoice: readAsVoiceParam(params),
         });
         return withPin(result.messageId, result.chatType, mediaResultExtra(result));
       }
 
       const result = await sendMaxMessage(to, content, {
         token: account.token,
+        ...sendFlags,
         replyToMessageId: replyTo ?? undefined,
         format: 'markdown',
         buttons,
@@ -376,6 +513,7 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
 
     if (action === 'edit') {
       const messageId = readStringParam(params, 'messageId', { required: true });
+      await assertMaxActionInScope(ctx, account, { messageId });
       const text = readStringParam(params, 'message', {
         required: true,
         allowEmpty: true,
@@ -389,6 +527,7 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
 
     if (action === 'delete') {
       const messageId = readStringParam(params, 'messageId', { required: true });
+      await assertMaxActionInScope(ctx, account, { messageId });
       await deleteMaxMessage(messageId, {
         token: account.token,
       });
@@ -398,6 +537,7 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
     if (action === 'pin') {
       const to = stripPrefix(readTargetParam(params))!;
       const messageId = readStringParam(params, 'messageId', { required: true });
+      await assertMaxActionInScope(ctx, account, { to });
       const notifyParam = params.notify;
       const pinned = await pinMaxMessage(to, messageId, {
         token: account.token,
@@ -411,12 +551,17 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
 
     if (action === 'unpin') {
       const to = stripPrefix(readTargetParam(params))!;
+      await assertMaxActionInScope(ctx, account, { to });
       await unpinMaxMessage(to, { token: account.token });
       return jsonResult({ ok: true, to, pinned: false });
     }
 
     if (action === 'sticker') {
       const to = stripPrefix(readTargetParam(params))!;
+      await assertMaxActionInScope(ctx, account, {
+        to,
+        replyTo: readStringParam(params, 'replyTo'),
+      });
       // stickerId may come as string or string[] from message tool schema
       const rawStickerId = params.stickerId;
       let stickerCode: string | undefined = Array.isArray(rawStickerId)
@@ -433,6 +578,7 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
 
       const result = await sendMaxSticker(to, stickerCode, {
         token: account.token,
+        ...sendFlags,
         replyToMessageId: replyTo ?? undefined,
       });
       return jsonResult({ ok: true, to, messageId: result.messageId });
@@ -441,18 +587,23 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
     if (action === 'sendAttachment') {
       const to = stripPrefix(readTargetParam(params))!;
       const replyTo = readStringParam(params, 'replyTo');
+      await assertMaxActionInScope(ctx, account, { to, replyTo });
       const caption =
         readStringParam(params, 'message') ?? readStringParam(params, 'caption') ?? '';
       const attachType =
         readStringParam(params, 'type') ?? readStringParam(params, 'attachmentType') ?? '';
-      const mediaSources = readMediaSources(params);
+      const mediaMaxBytes = (account.config.mediaMaxMb ?? 20) * 1024 * 1024;
+      const mediaSources = readMediaSources(params, mediaMaxBytes);
 
       if (mediaSources.length) {
         const result = await sendMaxMediaSources(to, caption, mediaSources, {
           token: account.token,
+          ...sendFlags,
           replyToMessageId: replyTo ?? undefined,
           format: 'markdown',
-          mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+          mediaMaxBytes,
+          localMedia: resolveActionLocalMedia(ctx),
+          asVoice: readAsVoiceParam(params),
         });
         return jsonResult({
           ok: true,
@@ -473,6 +624,7 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
         if (location) {
           const result = await sendMaxLocation(to, location, caption || undefined, {
             token: account.token,
+            ...sendFlags,
             replyToMessageId: replyTo ?? undefined,
           });
           return jsonResult({ ok: true, to, messageId: result.messageId });
@@ -486,13 +638,14 @@ export const maxMessageActions: ChannelMessageActionAdapter = {
           readStringParam(params, 'contactName') ?? readStringParam(params, 'name') ?? 'Unknown';
         const result = await sendMaxContact(to, readContactParams(params, contactName), {
           token: account.token,
+          ...sendFlags,
           replyToMessageId: replyTo ?? undefined,
         });
         return jsonResult({ ok: true, to, messageId: result.messageId });
       }
 
       throw new Error(
-        "sendAttachment: unknown type. Use media/filePath for files, or type='location' / type='contact'",
+        "sendAttachment: unknown type. Use media/filePath (or base64 buffer with filename) for files, or type='location' / type='contact'",
       );
     }