@aspalagin/openclaw-max 0.7.2 → 0.8.0

package/src/channel-lifecycle.ts

@@ -7,9 +7,16 @@ import type { ChannelPlugin } from 'openclaw/plugin-sdk/channel-core';
 import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
 import { DEFAULT_ACCOUNT_ID } from 'openclaw/plugin-sdk/core';
 
-import type { ResolvedMaxAccount } from './accounts.js';
+import { describeMaxInheritedOpenAccess } from './access-policy.js';
+import {
+  isMaxAccountConfigured,
+  MaxSecretConfigError,
+  type ResolvedMaxAccount,
+  resolveMaxAccountNetwork,
+} from './accounts.js';
 import { MaxApi } from './api.js';
 import { startMaxPolling } from './monitor.js';
+import { DEFAULT_MAX_API_BASE_URL, redactProxyUrl } from './network.js';
 import { writeMaxConfig } from './runtime.js';
 
 type MaxChannelPlugin = ChannelPlugin<ResolvedMaxAccount>;
@@ -32,6 +39,7 @@ export const maxStatusAdapter: NonNullable<MaxChannelPlugin['status']> = {
     // compares them with the live runtime and treats a missing value as stale.
     ...(snapshot.lifecycle !== undefined ? { lifecycle: snapshot.lifecycle } : {}),
     ...(typeof snapshot.connected === 'boolean' ? { connected: snapshot.connected } : {}),
+    ...(snapshot.mode ? { mode: snapshot.mode } : {}),
     lastStartAt: snapshot.lastStartAt ?? null,
     lastStopAt: snapshot.lastStopAt ?? null,
     lastError: snapshot.lastError ?? null,
@@ -53,11 +61,15 @@ export const maxStatusAdapter: NonNullable<MaxChannelPlugin['status']> = {
     accountId: account.accountId,
     name: account.name,
     enabled: account.enabled,
-    configured: Boolean(account.token?.trim()),
+    configured: isMaxAccountConfigured(account),
     tokenSource: account.tokenSource,
+    tokenStatus: account.tokenStatus,
+    ...(account.stateReason ? { stateReason: account.stateReason } : {}),
     running: runtime?.running ?? false,
     ...(runtime?.lifecycle !== undefined ? { lifecycle: runtime.lifecycle } : {}),
     ...(typeof runtime?.connected === 'boolean' ? { connected: runtime.connected } : {}),
+    // Transport the running task reported ("webhook" or "polling").
+    ...(runtime?.mode ? { mode: runtime.mode } : {}),
     lastStartAt: runtime?.lastStartAt ?? null,
     lastStopAt: runtime?.lastStopAt ?? null,
     lastError: runtime?.lastError ?? null,
@@ -163,7 +175,9 @@ export const maxStatusAdapter: NonNullable<MaxChannelPlugin['status']> = {
           channel: 'max',
           accountId: snapshot.accountId,
           kind: 'config' as const,
-          message: 'MAX bot token not configured',
+          message: snapshot.stateReason
+            ? `MAX bot token not configured: ${snapshot.stateReason}`
+            : 'MAX bot token not configured',
           fix: 'Set channels.max.botToken or MAX_BOT_TOKEN env var',
         });
       }
@@ -177,13 +191,26 @@ export const maxStatusAdapter: NonNullable<MaxChannelPlugin['status']> = {
 export const maxGatewayAdapter: NonNullable<MaxChannelPlugin['gateway']> = {
   startAccount: async (ctx) => {
     const account = ctx.account;
+    // Path and ref only; the gateway normally isolates such an account itself.
+    if (account.secretErrors?.botToken) {
+      throw new MaxSecretConfigError(account.secretErrors.botToken);
+    }
+    // A named account open only through channel-level (or default) policies.
+    const inheritedOpen = describeMaxInheritedOpenAccess(ctx.cfg, account);
+    if (inheritedOpen) ctx.log?.warn(`[${account.accountId}] ${inheritedOpen}`);
     const token = account.token.trim();
+    // A bad apiBaseUrl/httpProxy stops the account with a clear error rather
+    // than letting it connect directly or to the wrong host.
+    const network = resolveMaxAccountNetwork(account);
+    const route =
+      (network.apiBaseUrl !== DEFAULT_MAX_API_BASE_URL ? ` api=${network.apiBaseUrl}` : '') +
+      (network.proxyUrl ? ` proxy=${redactProxyUrl(network.proxyUrl)}` : '');
 
     let botLabel = '';
     let botUserId: number | undefined;
     let botUsername: string | undefined;
     try {
-      const probeApi = new MaxApi({ token, timeoutMs: 3000 });
+      const probeApi = new MaxApi({ token, timeoutMs: 3000, network });
       const me = await probeApi.getMe();
       if (me.username) {
         botLabel = ` (@${me.username})`;
@@ -194,9 +221,9 @@ export const maxGatewayAdapter: NonNullable<MaxChannelPlugin['gateway']> = {
       // probe failed, continue anyway
     }
 
-    ctx.log?.info(`[${account.accountId}] Starting MAX provider${botLabel}`);
+    ctx.log?.info(`[${account.accountId}] Starting MAX provider${botLabel}${route}`);
 
-    const api = new MaxApi({ token });
+    const api = new MaxApi({ token, network });
 
     // Register bot commands if configured
     const commands = ctx.cfg.channels?.max?.commands as

package/src/channel-outbound.ts

@@ -4,6 +4,8 @@
  */
 
 import type { ChannelPlugin } from 'openclaw/plugin-sdk/channel-core';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+import { getAgentScopedMediaLocalRoots } from 'openclaw/plugin-sdk/media-local-roots';
 
 import { type ResolvedMaxAccount, resolveMaxAccount } from './accounts.js';
 import {
@@ -11,11 +13,14 @@ import {
   MAX_PRESENTATION_CAPABILITIES,
   MAX_TEXT_LIMIT,
   renderMaxPresentation,
+  resolveMaxTextChunkLimit,
 } from './presentation.js';
 import { getMaxRuntime, loadMaxConfig } from './runtime.js';
 import {
+  type MaxLocalMediaAccess,
   pinMaxMessage,
   readMaxChannelButtons,
+  resolveMaxSendFlags,
   sendMaxMediaGroup,
   sendMaxMediaMessage,
   sendMaxMessage,
@@ -23,10 +28,31 @@ import {
 
 type MaxChannelPlugin = ChannelPlugin<ResolvedMaxAccount>;
 
-/** Direct delivery with 4000-character markdown chunks. */
+/**
+ * Local media access for an outbound send: the roots and host reader core
+ * passed with the delivery; without them the default media roots (no agent
+ * workspace is known here). Local files are read only through this policy.
+ */
+function resolveOutboundLocalMedia(
+  cfg: OpenClawConfig,
+  ctx: MaxLocalMediaAccess,
+): MaxLocalMediaAccess {
+  if (ctx.mediaAccess || ctx.mediaLocalRoots?.length || ctx.mediaReadFile) {
+    return {
+      mediaAccess: ctx.mediaAccess,
+      mediaLocalRoots: ctx.mediaLocalRoots,
+      mediaReadFile: ctx.mediaReadFile,
+    };
+  }
+  return { mediaLocalRoots: getAgentScopedMediaLocalRoots(cfg) };
+}
+
+/** Direct delivery with markdown chunks of at most 4000 characters. */
 export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
   deliveryMode: 'direct',
-  chunker: (text, limit) => getMaxRuntime().channel.text.chunkMarkdownText(text, limit),
+  // Core passes channels.max.textChunkLimit here; MAX rejects anything longer than 4000.
+  chunker: (text, limit) =>
+    getMaxRuntime().channel.text.chunkMarkdownText(text, Math.min(limit, MAX_TEXT_LIMIT)),
   chunkerMode: 'markdown',
   textChunkLimit: 4000,
 
@@ -49,7 +75,8 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
     });
   },
 
-  sendPayload: async ({ to, text, payload: rawPayload, mediaUrl, accountId, replyToId }) => {
+  sendPayload: async (ctx) => {
+    const { to, text, payload: rawPayload, mediaUrl, accountId, replyToId } = ctx;
     const cfg = await loadMaxConfig();
     const account = resolveMaxAccount({ cfg, accountId });
     if (!account.token) throw new Error('MAX bot token not configured');
@@ -61,6 +88,10 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
       : rawPayload;
     const effectiveText = payload === rawPayload ? text : (payload.text ?? '');
     const buttons = readMaxChannelButtons(payload.channelData);
+    const sendFlags = resolveMaxSendFlags(account.config, {
+      silent: ctx.silent,
+      channelData: payload.channelData,
+    });
     const mediaUrls = mediaUrl
       ? [mediaUrl]
       : payload.mediaUrls?.length
@@ -77,7 +108,10 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
         replyToMessageId: replyToId ?? undefined,
         format: 'markdown',
         buttons,
+        ...sendFlags,
         mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+        localMedia: resolveOutboundLocalMedia(cfg, ctx),
+        asVoice: ctx.audioAsVoice === true || payload.audioAsVoice === true,
       });
       return {
         channel: 'max',
@@ -87,9 +121,10 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
 
     // MAX caps a message at 4000 characters: split, keyboard on the last
     // chunk, report the first one (delivery.pin pins the first chunk).
+    const chunkLimit = resolveMaxTextChunkLimit(cfg, account.accountId);
     const chunks =
-      effectiveText.length > MAX_TEXT_LIMIT
-        ? getMaxRuntime().channel.text.chunkMarkdownText(effectiveText, MAX_TEXT_LIMIT)
+      effectiveText.length > chunkLimit
+        ? getMaxRuntime().channel.text.chunkMarkdownText(effectiveText, chunkLimit)
         : [effectiveText];
     let firstMessageId = '';
     for (let index = 0; index < chunks.length; index += 1) {
@@ -98,6 +133,7 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
         replyToMessageId: index === 0 ? (replyToId ?? undefined) : undefined,
         format: 'markdown',
         buttons: index === chunks.length - 1 ? buttons : undefined,
+        ...sendFlags,
       });
       if (index === 0) firstMessageId = result.messageId;
     }
@@ -108,7 +144,7 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
     };
   },
 
-  sendText: async ({ to, text, accountId, replyToId }) => {
+  sendText: async ({ to, text, accountId, replyToId, silent }) => {
     const cfg = await loadMaxConfig();
     const account = resolveMaxAccount({ cfg, accountId });
     if (!account.token) throw new Error('MAX bot token not configured');
@@ -117,6 +153,7 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
       token: account.token,
       replyToMessageId: replyToId ?? undefined,
       format: 'markdown',
+      ...resolveMaxSendFlags(account.config, { silent }),
     });
 
     return {
@@ -125,10 +162,12 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
     };
   },
 
-  sendMedia: async ({ to, text, mediaUrl, accountId, replyToId }) => {
+  sendMedia: async (ctx) => {
+    const { to, text, mediaUrl, accountId, replyToId } = ctx;
     const cfg = await loadMaxConfig();
     const account = resolveMaxAccount({ cfg, accountId });
     if (!account.token) throw new Error('MAX bot token not configured');
+    const sendFlags = resolveMaxSendFlags(account.config, { silent: ctx.silent });
 
     if (!mediaUrl) {
       // No media, send as text
@@ -136,6 +175,7 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
         token: account.token,
         replyToMessageId: replyToId ?? undefined,
         format: 'markdown',
+        ...sendFlags,
       });
       return {
         channel: 'max',
@@ -148,7 +188,10 @@ export const maxOutboundAdapter: NonNullable<MaxChannelPlugin['outbound']> = {
       token: account.token,
       replyToMessageId: replyToId ?? undefined,
       format: 'markdown',
+      ...sendFlags,
       mediaMaxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+      localMedia: resolveOutboundLocalMedia(cfg, ctx),
+      asVoice: ctx.audioAsVoice === true,
     });
 
     return {

package/src/channel.ts

@@ -29,6 +29,8 @@ import {
   buildMaxModelsProviderChannelData,
 } from './model-buttons.js';
 import { maxSetupWizard } from './onboarding.js';
+import { maxChannelSecrets } from './secret-contract.js';
+import { sendMaxHeartbeatTyping } from './typing.js';
 
 // ── Meta ──
 
@@ -64,6 +66,16 @@ export const maxPlugin: ChannelPlugin<ResolvedMaxAccount> = {
     unsend: true,
     reply: true,
     polls: false,
+    // TTS replies: core keeps its normal audio-file synthesis (MP3 unless the
+    // provider is set otherwise) and marks audio in these formats as voice.
+    // MAX documents MP3/WAV/M4A for audio and records its own voice messages
+    // as Ogg/Opus; no transcoding on either side.
+    tts: {
+      voice: {
+        synthesisTarget: 'audio-file',
+        audioFileFormats: ['mp3', 'm4a', 'wav', 'ogg', 'opus'],
+      },
+    },
   },
 
   reload: { configPrefixes: ['channels.max'] },
@@ -91,8 +103,12 @@ export const maxPlugin: ChannelPlugin<ResolvedMaxAccount> = {
   directory: maxDirectoryAdapter,
   outbound: maxOutboundAdapter,
   setup: maxSetupAdapter,
+  // botToken, webhookSecret, httpProxy accept SecretRefs (also exported as
+  // dist/secret-contract-api.js for the gateway's pre-runtime resolution).
+  secrets: maxChannelSecrets,
   status: maxStatusAdapter,
   gateway: maxGatewayAdapter,
+  heartbeat: { sendTyping: sendMaxHeartbeatTyping, sendTypingGuarded: sendMaxHeartbeatTyping },
 
   // Message actions (send, edit, delete)
   actions: maxMessageActions,

package/src/command-menu.ts

@@ -0,0 +1,277 @@
+/**
+ * Argument menus for core commands. A bare command whose core definition
+ * declares an argument menu (argsMenu: /think, /fast, /reasoning, /verbose,
+ * /usage, /tts, …) gets its choices as buttons; a press re-enters the inbound
+ * pipeline as that command's text, so it is applied exactly like typing it.
+ *
+ * Choices, titles and command text come from the core command registry;
+ * session state is only read through the runtime session API. Nothing here
+ * changes the session or the config: the chosen command does, in core.
+ */
+
+import {
+  buildCommandTextFromArgs,
+  type ChatCommandDefinition,
+  type CommandArgs,
+  findCommandByNativeName,
+  formatCommandArgMenuTitle,
+  formatFastModeCurrentStatus,
+  listChatCommands,
+  normalizeCommandBody,
+  parseCommandArgs,
+  resolveCommandArgChoices,
+  resolveCommandArgMenu,
+  resolveCommandAuthorization,
+  resolveEffectiveAgentRuntime,
+  resolveFastModeState,
+  resolveStoredModelOverride,
+} from 'openclaw/plugin-sdk/command-auth-native';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+
+import { MAX_CALLBACK_PAYLOAD_BYTES } from './presentation.js';
+import { getMaxRuntime } from './runtime.js';
+
+type MaxButton = { text: string; payload: string };
+
+type SessionEntry = NonNullable<
+  ReturnType<ReturnType<typeof getMaxRuntime>['agent']['session']['getSessionEntry']>
+>;
+
+/** Private envelope of a menu button: the command text of one choice. */
+const COMMAND_MENU_PREFIX = 'mxcmd1:';
+
+/** Session fields whose stored value is one of the command's choice values. */
+const SESSION_CHOICE_FIELDS: Record<string, keyof SessionEntry> = {
+  think: 'thinkingLevel',
+  verbose: 'verboseLevel',
+  reasoning: 'reasoningLevel',
+  elevated: 'elevatedLevel',
+  trace: 'traceLevel',
+  usage: 'responseUsage',
+  activation: 'groupActivation',
+};
+
+export type MaxCommandMenuDecision =
+  /** Not a menu case: the message goes to core as usual. */
+  | { kind: 'dispatch' }
+  /** Show (or, for a press, replace the pressed menu with) this menu. */
+  | { kind: 'menu'; text: string; buttons: MaxButton[][] }
+  /** Press by a sender without command rights. */
+  | { kind: 'denied' }
+  /** Press whose command or choice core no longer offers. */
+  | { kind: 'stale' };
+
+export function encodeMaxCommandMenuPayload(commandText: string): string | null {
+  const payload = `${COMMAND_MENU_PREFIX}${commandText}`;
+  return Buffer.byteLength(payload, 'utf8') <= MAX_CALLBACK_PAYLOAD_BYTES ? payload : null;
+}
+
+/** Command text of a menu button press; null for any other payload. */
+export function decodeMaxCommandMenuPayload(payload: string | undefined | null): string | null {
+  if (!payload?.startsWith(COMMAND_MENU_PREFIX)) return null;
+  const text = payload.slice(COMMAND_MENU_PREFIX.length).trim();
+  return text.startsWith('/') ? text : null;
+}
+
+/** A slash command whose core definition has an argument menu; null otherwise. */
+function parseMenuCommand(
+  text: string,
+  botUsername: string | undefined,
+): { command: ChatCommandDefinition; args?: CommandArgs } | null {
+  const normalized = normalizeCommandBody(text.trim(), botUsername ? { botUsername } : undefined);
+  const match = /^\/(\S+)(?:\s+([\s\S]*))?$/u.exec(normalized);
+  if (!match) return null;
+  const name = match[1].toLowerCase();
+  const command =
+    findCommandByNativeName(name, 'max') ??
+    listChatCommands().find(
+      (entry) => entry.key === name || entry.textAliases.includes(`/${name}`),
+    );
+  if (!command?.args?.length || !command.argsMenu) return null;
+  return { command, args: parseCommandArgs(command, match[2]?.trim() || undefined) };
+}
+
+type MenuModelContext = {
+  entry?: SessionEntry;
+  provider?: string;
+  model?: string;
+  agentRuntime?: string;
+};
+
+/** The session's model (dynamic choices such as /think levels depend on it). */
+function resolveMenuModelContext(params: {
+  cfg: OpenClawConfig;
+  agentId: string;
+  sessionKey: string;
+}): MenuModelContext {
+  const core = getMaxRuntime();
+  const { cfg, agentId, sessionKey } = params;
+  try {
+    const load = (key: string) => core.agent.session.getSessionEntry({ agentId, sessionKey: key });
+    const entry = load(sessionKey);
+    const defaults = core.modelConfig.resolveDefaultModelForAgent({ cfg, agentId });
+    // An automatic fallback override is temporary: menus follow the default.
+    const override =
+      entry?.modelOverrideSource === 'auto'
+        ? null
+        : resolveStoredModelOverride({
+            sessionEntry: entry,
+            loadSessionEntry: load,
+            sessionKey,
+            defaultProvider: defaults.provider,
+          });
+    const provider = override?.provider ?? defaults.provider;
+    const model = override?.model ?? defaults.model;
+    let agentRuntime: string | undefined;
+    try {
+      agentRuntime = resolveEffectiveAgentRuntime({
+        cfg,
+        provider,
+        modelId: model,
+        agentId,
+        sessionKey,
+        sessionEntry: entry,
+      });
+    } catch {
+      agentRuntime = undefined;
+    }
+    return { entry, provider, model, agentRuntime };
+  } catch {
+    return {};
+  }
+}
+
+/** Every argument value of a pressed command is still among core's choices. */
+function isPressStillOffered(
+  command: ChatCommandDefinition,
+  args: CommandArgs | undefined,
+  cfg: OpenClawConfig,
+  context: MenuModelContext,
+): boolean {
+  const values = args?.values ?? {};
+  for (const arg of command.args ?? []) {
+    const value = values[arg.name];
+    if (value == null || !arg.choices) continue;
+    const choices = resolveCommandArgChoices({
+      command,
+      arg,
+      cfg,
+      provider: context.provider,
+      model: context.model,
+      agentRuntime: context.agentRuntime,
+    });
+    if (choices.length > 0 && !choices.some((choice) => choice.value === String(value))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function resolveCurrentChoice(
+  command: ChatCommandDefinition,
+  context: MenuModelContext,
+  fastState: ReturnType<typeof resolveFastModeState> | undefined,
+): string | undefined {
+  if (fastState) {
+    if (fastState.source !== 'session') return 'default';
+    return fastState.mode === 'auto' ? 'auto' : fastState.mode ? 'on' : 'off';
+  }
+  const field = SESSION_CHOICE_FIELDS[command.key];
+  const stored = field ? context.entry?.[field] : undefined;
+  if (typeof stored === 'string' && stored) return stored;
+  // Nothing stored for this session: the "default" choice is what applies.
+  return 'default';
+}
+
+/**
+ * Decide what a slash command (typed, or pressed on a menu when `press`) does:
+ * open its argument menu, go to core unchanged, or — presses only — be refused
+ * for lack of command rights or as stale. `ctx` is the finalized inbound
+ * context of the message, so command rights are resolved exactly as core
+ * resolves them for the same text.
+ */
+export function resolveMaxCommandMenu(params: {
+  text: string;
+  press: boolean;
+  ctx: Parameters<typeof resolveCommandAuthorization>[0]['ctx'];
+  cfg: OpenClawConfig;
+  agentId: string;
+  sessionKey: string;
+  botUsername?: string;
+}): MaxCommandMenuDecision {
+  const { press, cfg, agentId, sessionKey } = params;
+  const pass: MaxCommandMenuDecision = press ? { kind: 'stale' } : { kind: 'dispatch' };
+  const parsed = parseMenuCommand(params.text, params.botUsername);
+  if (!parsed) return pass;
+  const { command, args } = parsed;
+
+  const core = getMaxRuntime();
+  if (
+    !core.channel.commands.shouldHandleTextCommands({ cfg, surface: 'max', commandSource: 'text' })
+  ) {
+    return pass;
+  }
+  // Core authorizes MAX text commands with CommandAuthorized unset (false).
+  const authorization = resolveCommandAuthorization({
+    ctx: params.ctx,
+    cfg,
+    commandAuthorized: params.ctx.CommandAuthorized === true,
+  });
+  if (!authorization.isAuthorizedSender) {
+    return press ? { kind: 'denied' } : { kind: 'dispatch' };
+  }
+
+  const context = resolveMenuModelContext({ cfg, agentId, sessionKey });
+  if (press && !isPressStillOffered(command, args, cfg, context)) return { kind: 'stale' };
+
+  const menu = resolveCommandArgMenu({
+    command,
+    args,
+    cfg,
+    provider: context.provider,
+    model: context.model,
+    agentRuntime: context.agentRuntime,
+    session: { agentId, sessionKey },
+  });
+  if (!menu) return { kind: 'dispatch' };
+
+  const fastState =
+    command.key === 'fast' && context.provider && context.model
+      ? resolveFastModeState({
+          cfg,
+          provider: context.provider,
+          model: context.model,
+          agentId,
+          sessionEntry:
+            context.entry?.fastMode !== undefined
+              ? { fastMode: context.entry.fastMode }
+              : undefined,
+        })
+      : undefined;
+  const current = resolveCurrentChoice(command, context, fastState);
+
+  let title = formatCommandArgMenuTitle({ command, menu });
+  if (fastState) {
+    title = `${formatFastModeCurrentStatus(fastState)}\n${title}`;
+  } else if (command.key === 'think' && current !== 'default') {
+    title = `Current thinking level: ${current}.\n${title}`;
+  }
+
+  const buttons: MaxButton[] = [];
+  for (const choice of menu.choices) {
+    const payload = encodeMaxCommandMenuPayload(
+      buildCommandTextFromArgs(command, {
+        values: { ...args?.values, [menu.arg.name]: choice.value },
+      }),
+    );
+    if (!payload) continue;
+    buttons.push({ text: choice.value === current ? `${choice.label} ✓` : choice.label, payload });
+  }
+  if (buttons.length === 0) return { kind: 'dispatch' };
+
+  const rows: MaxButton[][] = [];
+  for (let index = 0; index < buttons.length; index += 2) {
+    rows.push(buttons.slice(index, index + 2));
+  }
+  return { kind: 'menu', text: title, buttons: rows };
+}