@aspalagin/openclaw-max 0.7.2

package/src/channel-outbound.ts

@@ -0,0 +1,159 @@
+/**
+ * Outbound adapter of the MAX channel: sendText / sendPayload / sendMedia,
+ * presentation rendering and delivery pins for core's outbound path.
+ */
+
+import type { ChannelPlugin } from 'openclaw/plugin-sdk/channel-core';
+
+import { type ResolvedMaxAccount, resolveMaxAccount } from './accounts.js';
+import {
+  materializeMaxPresentation,
+  MAX_PRESENTATION_CAPABILITIES,
+  MAX_TEXT_LIMIT,
+  renderMaxPresentation,
+} from './presentation.js';
+import { getMaxRuntime, loadMaxConfig } from './runtime.js';
+import {
+  pinMaxMessage,
+  readMaxChannelButtons,
+  sendMaxMediaGroup,
+  sendMaxMediaMessage,
+  sendMaxMessage,
+} from './send.js';
+
+type MaxChannelPlugin = ChannelPlugin<ResolvedMaxAccount>;
+
+/** Direct delivery with 4000-character markdown chunks. */
+export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
+  deliveryMode: 'direct',
+  chunker: (text, limit) => getMaxRuntime().channel.text.chunkMarkdownText(text, limit),
+  chunkerMode: 'markdown',
+  textChunkLimit: 4000,
+
+  // Presentation (docs/plugins/message-presentation.md): core adapts to these
+  // capabilities, renders through renderPresentation and pins through
+  // pinDeliveredMessage after the first delivered message.
+  presentationCapabilities: MAX_PRESENTATION_CAPABILITIES,
+  deliveryCapabilities: { pin: true },
+  renderPresentation: ({ payload, presentation }) => renderMaxPresentation(payload, presentation),
+  pinDeliveredMessage: async ({ cfg, target, messageId, pin, assertDirectAdapterHandoff }) => {
+    const account = resolveMaxAccount({ cfg, accountId: target.accountId });
+    if (!account.token) throw new Error('MAX bot token not configured');
+    assertDirectAdapterHandoff?.();
+    // Dialogs cannot pin: pinMaxMessage resolves { pinned: false } without an
+    // API call or error, so core logs no failed pin for a DM delivery.
+    await pinMaxMessage(target.to, messageId, {
+      token: account.token,
+      pinNotify: pin.notify === true,
+      beforeRequest: assertDirectAdapterHandoff,
+    });
+  },
+
+  sendPayload: async ({ to, text, payload: rawPayload, mediaUrl, accountId, replyToId }) => {
+    const cfg = await loadMaxConfig();
+    const account = resolveMaxAccount({ cfg, accountId });
+    if (!account.token) throw new Error('MAX bot token not configured');
+
+    // Core renders presentation before sendPayload; a payload that still
+    // carries one came through a path that did not, so apply the same policy.
+    const payload = rawPayload.presentation
+      ? await materializeMaxPresentation(rawPayload)
+      : rawPayload;
+    const effectiveText = payload === rawPayload ? text : (payload.text ?? '');
+    const buttons = readMaxChannelButtons(payload.channelData);
+    const mediaUrls = mediaUrl
+      ? [mediaUrl]
+      : payload.mediaUrls?.length
+        ? payload.mediaUrls
+        : payload.mediaUrl
+          ? [payload.mediaUrl]
+          : [];
+
+    if (mediaUrls.length) {
+      // Albums: up to 12 images/videos per message, caption on the first,
+      // buttons on the last; report the first message (delivery.pin).
+      const result = await sendMaxMediaGroup(to, effectiveText, mediaUrls, {
+        token: account.token,
+        replyToMessageId: replyToId ?? undefined,
+        format: 'markdown',
+        buttons,
+        mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+      });
+      return {
+        channel: 'max',
+        messageId: result.messageIds[0] ?? '',
+      };
+    }
+
+    // MAX caps a message at 4000 characters: split, keyboard on the last
+    // chunk, report the first one (delivery.pin pins the first chunk).
+    const chunks =
+      effectiveText.length > MAX_TEXT_LIMIT
+        ? getMaxRuntime().channel.text.chunkMarkdownText(effectiveText, MAX_TEXT_LIMIT)
+        : [effectiveText];
+    let firstMessageId = '';
+    for (let index = 0; index < chunks.length; index += 1) {
+      const result = await sendMaxMessage(to, chunks[index], {
+        token: account.token,
+        replyToMessageId: index === 0 ? (replyToId ?? undefined) : undefined,
+        format: 'markdown',
+        buttons: index === chunks.length - 1 ? buttons : undefined,
+      });
+      if (index === 0) firstMessageId = result.messageId;
+    }
+
+    return {
+      channel: 'max',
+      messageId: firstMessageId,
+    };
+  },
+
+  sendText: async ({ to, text, accountId, replyToId }) => {
+    const cfg = await loadMaxConfig();
+    const account = resolveMaxAccount({ cfg, accountId });
+    if (!account.token) throw new Error('MAX bot token not configured');
+
+    const result = await sendMaxMessage(to, text, {
+      token: account.token,
+      replyToMessageId: replyToId ?? undefined,
+      format: 'markdown',
+    });
+
+    return {
+      channel: 'max',
+      messageId: result.messageId,
+    };
+  },
+
+  sendMedia: async ({ to, text, mediaUrl, accountId, replyToId }) => {
+    const cfg = await loadMaxConfig();
+    const account = resolveMaxAccount({ cfg, accountId });
+    if (!account.token) throw new Error('MAX bot token not configured');
+
+    if (!mediaUrl) {
+      // No media, send as text
+      const result = await sendMaxMessage(to, text, {
+        token: account.token,
+        replyToMessageId: replyToId ?? undefined,
+        format: 'markdown',
+      });
+      return {
+        channel: 'max',
+        messageId: result.messageId,
+      };
+    }
+
+    // Upload and send media
+    const result = await sendMaxMediaMessage(to, text, mediaUrl, {
+      token: account.token,
+      replyToMessageId: replyToId ?? undefined,
+      format: 'markdown',
+      mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+    });
+
+    return {
+      channel: 'max',
+      messageId: result.messageId,
+    };
+  },
+};

package/src/channel-policy.ts

@@ -0,0 +1,185 @@
+/**
+ * Access policy of the MAX channel: DM pairing/allowlist, group
+ * requireMention and tool policy, security warnings, pairing approval.
+ */
+
+import type { ChannelPlugin } from 'openclaw/plugin-sdk/channel-core';
+import type { GroupToolPolicyConfig } from 'openclaw/plugin-sdk/channel-policy';
+import { resolveToolsBySender } from 'openclaw/plugin-sdk/channel-policy';
+import { PAIRING_APPROVED_MESSAGE } from 'openclaw/plugin-sdk/channel-status';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+import { DEFAULT_ACCOUNT_ID, formatPairingApproveHint } from 'openclaw/plugin-sdk/core';
+
+import { type ResolvedMaxAccount, resolveMaxAccount } from './accounts.js';
+import { sendMaxMessage } from './send.js';
+
+type MaxChannelPlugin = ChannelPlugin<ResolvedMaxAccount>;
+
+// ── MAX group policy helpers ──
+// These mirror resolveChannelGroupRequireMention/resolveChannelGroupToolsPolicy
+// (internal SDK functions not exported) but for the "max" channel.
+
+function resolveMaxGroupConfig(
+  cfg: OpenClawConfig,
+  groupId?: string | null,
+  accountId?: string | null,
+) {
+  const maxSection = (cfg.channels as Record<string, unknown>)?.max as
+    Record<string, unknown> | undefined;
+  if (!maxSection) return { groupConfig: undefined, defaultConfig: undefined };
+
+  // Resolve groups map: account-level takes priority over channel-level
+  let groups: Record<string, unknown> | undefined;
+  if (accountId && accountId !== DEFAULT_ACCOUNT_ID) {
+    const accounts = maxSection.accounts as Record<string, Record<string, unknown>> | undefined;
+    groups = accounts?.[accountId]?.groups as Record<string, unknown> | undefined;
+  }
+  if (!groups) {
+    groups = maxSection.groups as Record<string, unknown> | undefined;
+  }
+
+  const normalizedId = groupId?.trim();
+  const groupConfig =
+    normalizedId && groups
+      ? (groups[normalizedId] as Record<string, unknown> | undefined)
+      : undefined;
+  const defaultConfig = groups?.['*'] as Record<string, unknown> | undefined;
+
+  return { groupConfig, defaultConfig };
+}
+
+function resolveMaxGroupRequireMention(params: {
+  cfg: OpenClawConfig;
+  groupId?: string | null;
+  accountId?: string | null;
+}): boolean {
+  const { groupConfig, defaultConfig } = resolveMaxGroupConfig(
+    params.cfg,
+    params.groupId,
+    params.accountId,
+  );
+  const configMention =
+    typeof groupConfig?.requireMention === 'boolean'
+      ? groupConfig.requireMention
+      : typeof defaultConfig?.requireMention === 'boolean'
+        ? defaultConfig.requireMention
+        : undefined;
+  if (typeof configMention === 'boolean') return configMention;
+  return true; // default: require mention
+}
+
+function resolveMaxGroupToolPolicy(params: {
+  cfg: OpenClawConfig;
+  groupId?: string | null;
+  accountId?: string | null;
+  senderId?: string | null;
+  senderName?: string | null;
+  senderUsername?: string | null;
+  senderE164?: string | null;
+}): GroupToolPolicyConfig | undefined {
+  const { groupConfig, defaultConfig } = resolveMaxGroupConfig(
+    params.cfg,
+    params.groupId,
+    params.accountId,
+  );
+
+  // Group-level sender-specific policy
+  const groupSenderPolicy = resolveToolsBySender({
+    toolsBySender: groupConfig?.toolsBySender as Record<string, GroupToolPolicyConfig> | undefined,
+    senderId: params.senderId,
+    senderName: params.senderName,
+    senderUsername: params.senderUsername,
+    senderE164: params.senderE164,
+  });
+  if (groupSenderPolicy) return groupSenderPolicy;
+  if (groupConfig?.tools) return groupConfig.tools as GroupToolPolicyConfig;
+
+  // Default config fallback
+  const defaultSenderPolicy = resolveToolsBySender({
+    toolsBySender: defaultConfig?.toolsBySender as
+      Record<string, GroupToolPolicyConfig> | undefined,
+    senderId: params.senderId,
+    senderName: params.senderName,
+    senderUsername: params.senderUsername,
+    senderE164: params.senderE164,
+  });
+  if (defaultSenderPolicy) return defaultSenderPolicy;
+  if (defaultConfig?.tools) return defaultConfig.tools as GroupToolPolicyConfig;
+
+  return undefined;
+}
+
+/** DM policy (default pairing) and warnings for open group policy. */
+export const maxSecurityAdapter: NonNullable<MaxChannelPlugin['security']> = {
+  resolveDmPolicy: ({ cfg, accountId, account }) => {
+    const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+    const maxSection = (cfg.channels as Record<string, unknown>)?.max as
+      Record<string, unknown> | undefined;
+    const useAccountPath = Boolean(
+      (maxSection?.accounts as Record<string, unknown>)?.[resolvedAccountId],
+    );
+    const basePath = useAccountPath
+      ? `channels.max.accounts.${resolvedAccountId}.`
+      : 'channels.max.';
+    return {
+      policy: account.config.dmPolicy ?? 'pairing',
+      allowFrom: account.config.allowFrom ?? [],
+      policyPath: `${basePath}dmPolicy`,
+      allowFromPath: basePath,
+      approveHint: formatPairingApproveHint('max'),
+      normalizeEntry: (raw: string) => raw.replace(/^max:/i, ''),
+    };
+  },
+  collectWarnings: ({ account, cfg }) => {
+    const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+    const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? 'allowlist';
+    if (groupPolicy !== 'open') {
+      return [];
+    }
+    const groupAllowlistConfigured =
+      account.config.groups && Object.keys(account.config.groups).length > 0;
+    if (groupAllowlistConfigured) {
+      return [
+        `- MAX groups: groupPolicy="open" allows any member in allowed groups to trigger (mention-gated). Set channels.max.groupPolicy="allowlist" + channels.max.groupAllowFrom to restrict senders.`,
+      ];
+    }
+    return [
+      `- MAX groups: groupPolicy="open" with no channels.max.groups allowlist; any group can add + ping (mention-gated). Set channels.max.groupPolicy="allowlist" + channels.max.groupAllowFrom or configure channels.max.groups.`,
+    ];
+  },
+};
+
+/** Group requireMention (default true) and tool policy from channels.max.groups. */
+export const maxGroupsAdapter: NonNullable<MaxChannelPlugin['groups']> = {
+  resolveRequireMention: ({ cfg, groupId, accountId }) =>
+    resolveMaxGroupRequireMention({ cfg, groupId, accountId }),
+  resolveToolPolicy: ({
+    cfg,
+    groupId,
+    accountId,
+    senderId,
+    senderName,
+    senderUsername,
+    senderE164,
+  }) =>
+    resolveMaxGroupToolPolicy({
+      cfg,
+      groupId,
+      accountId,
+      senderId,
+      senderName,
+      senderUsername,
+      senderE164,
+    }),
+};
+
+/** Pairing ids are MAX user ids; approval is announced to the user in MAX. */
+export const maxPairingAdapter: NonNullable<MaxChannelPlugin['pairing']> = {
+  idLabel: 'maxUserId',
+  normalizeAllowEntry: (entry) => entry.replace(/^max:/i, ''),
+  notifyApproval: async ({ cfg, id }) => {
+    const account = resolveMaxAccount({ cfg });
+    if (!account.token) throw new Error('MAX bot token not configured');
+    await sendMaxMessage(id, PAIRING_APPROVED_MESSAGE, { token: account.token });
+  },
+};

package/src/channel.ts

@@ -0,0 +1,99 @@
+/**
+ * MAX channel plugin for OpenClaw.
+ *
+ * Implements the ChannelPlugin interface to integrate MAX messenger. The
+ * adapters live next to this file by role: channel-config (accounts, setup),
+ * channel-policy (DM/group access, pairing), channel-directory (targets,
+ * directory), channel-outbound (delivery), channel-lifecycle (start/stop,
+ * status, health), channel-agent-prompt; message tool actions in actions.ts.
+ */
+
+import type { ChannelMeta } from 'openclaw/plugin-sdk/channel-contract';
+import type { ChannelPlugin } from 'openclaw/plugin-sdk/channel-core';
+import { buildChannelConfigSchema } from 'openclaw/plugin-sdk/core';
+
+import type { ResolvedMaxAccount } from './accounts.js';
+import { maxMessageActions } from './actions.js';
+import { maxAgentPromptAdapter } from './channel-agent-prompt.js';
+import { maxConfigAdapter, maxSetupAdapter } from './channel-config.js';
+import { maxDirectoryAdapter, maxMessagingAdapter } from './channel-directory.js';
+import { maxGatewayAdapter, maxStatusAdapter } from './channel-lifecycle.js';
+import { maxOutboundAdapter } from './channel-outbound.js';
+import { maxGroupsAdapter, maxPairingAdapter, maxSecurityAdapter } from './channel-policy.js';
+import { MaxConfigSchema } from './config-schema.js';
+import {
+  buildMaxModelBrowseChannelData,
+  buildMaxModelsAddProviderChannelData,
+  buildMaxModelsListChannelData,
+  buildMaxModelsMenuChannelData,
+  buildMaxModelsProviderChannelData,
+} from './model-buttons.js';
+import { maxSetupWizard } from './onboarding.js';
+
+// ── Meta ──
+
+const maxMeta: ChannelMeta = {
+  id: 'max',
+  label: 'MAX',
+  selectionLabel: 'MAX Messenger',
+  docsPath: '/channels/max',
+  blurb: 'MAX messenger bot via platform-api2.max.ru. Supports DMs, groups, inline keyboards.',
+  order: 50,
+  aliases: ['max-messenger'],
+};
+
+// ── Channel Plugin ──
+
+export const maxPlugin: ChannelPlugin<ResolvedMaxAccount> = {
+  id: 'max',
+  meta: maxMeta,
+  setupWizard: maxSetupWizard,
+  configSchema: buildChannelConfigSchema(
+    MaxConfigSchema as unknown as Parameters<typeof buildChannelConfigSchema>[0],
+  ),
+
+  capabilities: {
+    chatTypes: ['direct', 'group', 'channel'],
+    reactions: false,
+    threads: false,
+    media: true,
+    nativeCommands: true,
+    blockStreaming: false,
+    edit: true,
+    // DELETE /messages backs the "delete" action; replies use link.type=reply.
+    unsend: true,
+    reply: true,
+    polls: false,
+  },
+
+  reload: { configPrefixes: ['channels.max'] },
+
+  commands: {
+    nativeCommandsAutoEnabled: true,
+    nativeSkillsAutoEnabled: true,
+    buildModelsMenuChannelData: buildMaxModelsMenuChannelData,
+    buildModelsProviderChannelData: buildMaxModelsProviderChannelData,
+    buildModelsAddProviderChannelData: buildMaxModelsAddProviderChannelData,
+    buildModelsListChannelData: buildMaxModelsListChannelData,
+    buildModelBrowseChannelData: buildMaxModelBrowseChannelData,
+  },
+
+  agentPrompt: maxAgentPromptAdapter,
+  config: maxConfigAdapter,
+  security: maxSecurityAdapter,
+  groups: maxGroupsAdapter,
+  pairing: maxPairingAdapter,
+
+  threading: {
+    resolveReplyToMode: () => 'first',
+  },
+  messaging: maxMessagingAdapter,
+  directory: maxDirectoryAdapter,
+  outbound: maxOutboundAdapter,
+  setup: maxSetupAdapter,
+  status: maxStatusAdapter,
+  gateway: maxGatewayAdapter,
+
+  // Message actions (send, edit, delete)
+  actions: maxMessageActions,
+};

package/src/config-schema.ts

@@ -0,0 +1,154 @@
+/**
+ * MAX channel config Zod schema
+ */
+
+import { MarkdownConfigSchema, ToolPolicySchema } from 'openclaw/plugin-sdk/channel-config-schema';
+import { z } from 'zod';
+
+// Defaulted policy fields are built with this package's own zod: wrapping the
+// SDK's enum instances in `.optional().default()` breaks as soon as the plugin
+// and the gateway resolve different zod copies (4.4 vs 4.6 → "expected
+// nonoptional"). Values mirror the SDK's DmPolicySchema/GroupPolicySchema.
+export const DmPolicySchema = z.enum(['pairing', 'allowlist', 'open', 'disabled']);
+export const GroupPolicySchema = z.enum(['open', 'disabled', 'allowlist']);
+
+// These schemas were removed from the public plugin-sdk surface in OpenClaw 2026.3.x.
+// Inlined here to stay compatible with both old and new runtimes.
+const BlockStreamingCoalesceSchema = z
+  .object({
+    minChars: z.number().int().optional(),
+    maxChars: z.number().int().optional(),
+    idleMs: z.number().int().optional(),
+  })
+  .strict();
+
+const DmConfigSchema = z
+  .object({
+    historyLimit: z.number().int().min(0).optional(),
+  })
+  .strict();
+
+function requireOpenAllowFrom(params: {
+  policy: string | undefined;
+  allowFrom: unknown[] | undefined;
+  ctx: z.RefinementCtx;
+  path: (string | number)[];
+  message: string;
+}): void {
+  if (params.policy !== 'open') return;
+  const normalized = (params.allowFrom ?? []).map(String);
+  if (normalized.includes('*')) return;
+  params.ctx.addIssue({
+    code: z.ZodIssueCode.custom,
+    path: params.path,
+    message: params.message,
+  });
+}
+
+/**
+ * Per-group config for MAX chats
+ */
+export const MaxGroupSchema = z
+  .object({
+    requireMention: z.boolean().optional(),
+    tools: ToolPolicySchema.optional(),
+    skills: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * MAX account config (base schema for both top-level and accounts.*)
+ */
+export const MaxAccountSchemaBase = z
+  .object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+    markdown: MarkdownConfigSchema.optional(),
+    botToken: z.string().optional(),
+    tokenFile: z.string().optional(),
+    dmPolicy: DmPolicySchema.optional().default('pairing'),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groupPolicy: GroupPolicySchema.optional().default('allowlist'),
+    groups: z.record(z.string(), MaxGroupSchema.optional()).optional(),
+    /** Update transport; default: "webhook" when webhookUrl is set, otherwise "polling" */
+    transport: z.enum(['polling', 'webhook']).optional(),
+    webhookUrl: z.string().optional(),
+    /** MAX secret: 5–256 of [A-Za-z0-9_-]; checked at start */
+    webhookSecret: z.string().optional(),
+    /** File holding the webhook secret (regular file, not a symlink) */
+    webhookSecretFile: z.string().optional(),
+    webhookPath: z.string().optional(),
+    historyLimit: z.number().int().min(0).optional(),
+    dmHistoryLimit: z.number().int().min(0).optional(),
+    dms: z.record(z.string(), DmConfigSchema.optional()).optional(),
+    textChunkLimit: z.number().int().positive().optional(),
+    blockStreaming: z.boolean().optional(),
+    streamMode: z.enum(['off', 'partial', 'block']).optional(),
+    blockStreamingCoalesce: BlockStreamingCoalesceSchema.optional(),
+    responsePrefix: z.string().optional(),
+    mediaMaxMb: z.number().positive().optional(),
+    markSeen: z.boolean().optional(),
+    actions: z
+      .record(
+        z.string(),
+        z.union([z.boolean(), z.enum(['pairing', 'allowlist', 'open'])]).optional(),
+      )
+      .optional(),
+  })
+  .strict();
+
+function requireWebhookUrl(params: {
+  transport: string | undefined;
+  webhookUrl: string | undefined;
+  ctx: z.RefinementCtx;
+}): void {
+  if (params.transport !== 'webhook' || params.webhookUrl?.trim()) return;
+  params.ctx.addIssue({
+    code: z.ZodIssueCode.custom,
+    path: ['webhookUrl'],
+    message: 'channels.max.transport="webhook" requires channels.max.webhookUrl',
+  });
+}
+
+/**
+ * Individual account schema (with open-policy validation)
+ */
+export const MaxAccountSchema = MaxAccountSchemaBase.superRefine((value, ctx) => {
+  requireOpenAllowFrom({
+    policy: value.dmPolicy,
+    allowFrom: value.allowFrom,
+    ctx,
+    path: ['allowFrom'],
+    message: 'channels.max.dmPolicy="open" requires channels.max.allowFrom to include "*"',
+  });
+  requireWebhookUrl({ transport: value.transport, webhookUrl: value.webhookUrl, ctx });
+});
+
+/** Bot command registered via PATCH /me/commands (name ≤64 chars without slash, description ≤128) */
+const MaxBotCommandSchema = z
+  .object({
+    name: z.string().min(1).max(64),
+    description: z.string().max(128).optional(),
+  })
+  .strict();
+
+/**
+ * Top-level MAX config schema (supports accounts.* sub-configs)
+ */
+export const MaxConfigSchema = MaxAccountSchemaBase.extend({
+  accounts: z.record(z.string(), MaxAccountSchema.optional()).optional(),
+  commands: z.array(MaxBotCommandSchema).max(32).optional(),
+}).superRefine((value, ctx) => {
+  requireOpenAllowFrom({
+    policy: value.dmPolicy,
+    allowFrom: value.allowFrom,
+    ctx,
+    path: ['allowFrom'],
+    message: 'channels.max.dmPolicy="open" requires channels.max.allowFrom to include "*"',
+  });
+  requireWebhookUrl({ transport: value.transport, webhookUrl: value.webhookUrl, ctx });
+});