@aspalagin/openclaw-max 0.7.2

package/src/monitor-types.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared monitor contracts: options every transport and handler receives,
+ * the gateway status patch shape, and the update types this channel consumes.
+ */
+
+import type { ChannelAccountSnapshot, ChannelLogSink } from 'openclaw/plugin-sdk/channel-contract';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+
+import type { MaxAccountConfig, ResolvedMaxAccount } from './accounts.js';
+import type { MaxApi, MaxUpdateType } from './api.js';
+import type { MaxStateStore } from './state.js';
+import type { RegisterMaxWebhookRoute } from './webhook.js';
+
+/**
+ * Runtime status patches published to the gateway. Activity timestamps are not
+ * enough: the gateway leaves an account in `lifecycle: "starting"` until the
+ * transport reports `connected`, and its health policy can only detect a dead
+ * socket from `lastTransportActivityAt`.
+ */
+export type MaxStatusPatch = Partial<ChannelAccountSnapshot>;
+
+export interface MaxMonitorOptions {
+  api: MaxApi;
+  account: ResolvedMaxAccount;
+  config: OpenClawConfig;
+  abortSignal: AbortSignal;
+  botUserId?: number;
+  botUsername?: string;
+  log?: ChannelLogSink;
+  statusSink?: (patch: MaxStatusPatch) => void;
+  /** Persistent marker + chat registry (created by startMaxPolling when absent) */
+  state?: MaxStateStore;
+  /** Gateway route registration; defaults to plugin-sdk registerPluginHttpRoute (tests inject a mock) */
+  registerWebhookRoute?: RegisterMaxWebhookRoute;
+}
+
+/**
+ * Update types this channel consumes. Shared by long polling (types filter)
+ * and webhook subscriptions (update_types).
+ */
+export const MAX_SUBSCRIBED_UPDATE_TYPES: MaxUpdateType[] = [
+  'message_created',
+  'message_callback',
+  'message_edited',
+  'message_removed',
+  'bot_started',
+  'bot_stopped',
+  'bot_added',
+  'bot_removed',
+  'dialog_cleared',
+  'dialog_removed',
+  'chat_title_changed',
+];
+
+export type MaxTransport = 'polling' | 'webhook';
+
+/** Explicit `transport` wins; otherwise a configured webhookUrl selects webhook mode. */
+export function resolveMaxTransport(config: MaxAccountConfig): MaxTransport {
+  if (config.transport === 'polling' || config.transport === 'webhook') return config.transport;
+  return config.webhookUrl?.trim() ? 'webhook' : 'polling';
+}

package/src/monitor.ts

@@ -0,0 +1,49 @@
+/**
+ * MAX monitor — receives updates (long polling or webhook) and dispatches them
+ * to OpenClaw.
+ *
+ * Uses the same inbound pipeline as other channel plugins:
+ * finalizeInboundContext → dispatchReplyWithBufferedBlockDispatcher
+ *
+ * Roles: polling.ts / webhook-runner.ts (transports) → dispatch.ts (by
+ * update_type) → inbound.ts (gates, context, agent run; attachments in
+ * inbound-attachments.ts) / callbacks.ts (button presses) → deliver.ts and
+ * stream-draft.ts (replies).
+ */
+
+import { type MaxMonitorOptions, resolveMaxTransport } from './monitor-types.js';
+import { clearMaxSubscriptionsForPolling, startMaxPollingLoop } from './polling.js';
+import { MaxStateStore } from './state.js';
+import { startMaxWebhook } from './webhook-runner.js';
+
+export {
+  MAX_SUBSCRIBED_UPDATE_TYPES,
+  type MaxMonitorOptions,
+  type MaxStatusPatch,
+  type MaxTransport,
+  resolveMaxTransport,
+} from './monitor-types.js';
+
+export async function startMaxPolling(opts: MaxMonitorOptions): Promise<void> {
+  const { account, log } = opts;
+
+  // Persistent state: polling marker + chat registry + webhook secret
+  if (!opts.state) {
+    opts.state = new MaxStateStore(account.accountId, (err) => {
+      log?.error(`[${account.accountId}] MAX state persist failed: ${String(err)}`);
+    });
+  }
+  try {
+    await opts.state.load();
+  } catch (err) {
+    log?.error(`[${account.accountId}] MAX state load failed: ${String(err)}`);
+  }
+
+  if (resolveMaxTransport(account.config) === 'webhook') {
+    await startMaxWebhook(opts);
+  } else {
+    // An active subscription silently disables long polling on the MAX side.
+    await clearMaxSubscriptionsForPolling(opts);
+    await startMaxPollingLoop(opts);
+  }
+}

package/src/onboarding.ts

@@ -0,0 +1,215 @@
+/**
+ * MAX channel onboarding — setup wizard for `openclaw channel add max`
+ */
+
+import type { DmPolicy } from 'openclaw/plugin-sdk/config-contracts';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+import { DEFAULT_ACCOUNT_ID } from 'openclaw/plugin-sdk/core';
+import type { ChannelSetupDmPolicy, ChannelSetupWizard } from 'openclaw/plugin-sdk/setup';
+import { formatDocsLink } from 'openclaw/plugin-sdk/setup';
+
+import { listMaxAccountIds, resolveMaxAccount } from './accounts.js';
+import { MaxApi } from './api.js';
+
+const channel = 'max' as const;
+
+const ENV_MAX_BOT_TOKEN = 'MAX_BOT_TOKEN';
+
+function setMaxDmPolicy(cfg: OpenClawConfig, policy: DmPolicy): OpenClawConfig {
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      max: {
+        ...cfg.channels?.['max'],
+        dmPolicy: policy,
+      },
+    },
+  };
+}
+
+const dmPolicy: ChannelSetupDmPolicy = {
+  label: 'MAX',
+  channel,
+  policyKey: 'channels.max.dmPolicy',
+  allowFromKey: 'channels.max.allowFrom',
+  getCurrent: (cfg: OpenClawConfig) => cfg.channels?.['max']?.dmPolicy ?? 'pairing',
+  setPolicy: (cfg: OpenClawConfig, policy: DmPolicy) => setMaxDmPolicy(cfg, policy),
+};
+
+function applyAccountConfig(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  patch: Record<string, unknown>;
+}): OpenClawConfig {
+  const { cfg, accountId, patch } = params;
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        max: {
+          ...cfg.channels?.['max'],
+          enabled: true,
+          ...patch,
+        },
+      },
+    };
+  }
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      max: {
+        ...cfg.channels?.['max'],
+        enabled: true,
+        accounts: {
+          ...cfg.channels?.['max']?.accounts,
+          [accountId]: {
+            ...cfg.channels?.['max']?.accounts?.[accountId],
+            enabled: true,
+            ...patch,
+          },
+        },
+      },
+    },
+  };
+}
+
+export const maxSetupWizard: ChannelSetupWizard = {
+  channel,
+
+  status: {
+    configuredLabel: 'MAX (configured)',
+    unconfiguredLabel: 'MAX Messenger',
+    configuredHint: 'configured',
+    unconfiguredHint: 'needs bot token',
+    resolveConfigured: ({ cfg }) => {
+      return listMaxAccountIds(cfg).some(
+        (accountId) => resolveMaxAccount({ cfg, accountId }).tokenSource !== 'none',
+      );
+    },
+    resolveStatusLines: ({ configured }) => {
+      return [`MAX: ${configured ? 'configured' : 'needs bot token'}`];
+    },
+  },
+
+  introNote: {
+    title: 'MAX setup',
+    lines: [
+      'MAX messenger bot requires a bot token from https://platform-api.max.ru',
+      'Create your bot via MAX Business or MAX API portal.',
+      'The bot can receive messages via polling (default) or webhook.',
+      `Docs: ${formatDocsLink('/channels/max', 'channels/max')}`,
+    ],
+  },
+
+  envShortcut: {
+    prompt: 'Use MAX_BOT_TOKEN env var?',
+    preferredEnvVar: ENV_MAX_BOT_TOKEN,
+    isAvailable: ({ accountId }) => {
+      return accountId === DEFAULT_ACCOUNT_ID && Boolean(process.env[ENV_MAX_BOT_TOKEN]);
+    },
+    apply: ({ cfg, accountId }) => {
+      return applyAccountConfig({ cfg, accountId, patch: {} });
+    },
+  },
+
+  credentials: [
+    {
+      inputKey: 'botToken',
+      providerHint: 'MAX bot token',
+      credentialLabel: 'bot token',
+      preferredEnvVar: ENV_MAX_BOT_TOKEN,
+      envPrompt: 'Use MAX_BOT_TOKEN env var?',
+      keepPrompt: 'Keep current bot token?',
+      inputPrompt: 'MAX bot token',
+
+      inspect: ({ cfg, accountId }) => {
+        const account = resolveMaxAccount({ cfg, accountId });
+        const hasToken = Boolean(account.token);
+        const envValue =
+          accountId === DEFAULT_ACCOUNT_ID ? process.env[ENV_MAX_BOT_TOKEN] : undefined;
+
+        return {
+          accountConfigured: hasToken,
+          hasConfiguredValue: hasToken,
+          resolvedValue: account.token || undefined,
+          envValue,
+        };
+      },
+
+      allowEnv: ({ accountId }) => accountId === DEFAULT_ACCOUNT_ID,
+
+      applyUseEnv: ({ cfg, accountId }) => {
+        return applyAccountConfig({ cfg, accountId, patch: {} });
+      },
+
+      applySet: async ({ cfg, accountId, resolvedValue }) => {
+        const tokenValue = String(resolvedValue).trim();
+
+        // Verify token by calling GET /me
+        try {
+          const api = new MaxApi({ token: tokenValue, timeoutMs: 5000 });
+          const me = await api.getMe();
+          console.log(
+            `✓ Token verified! Bot: ${me.first_name}${me.username ? ` (@${me.username})` : ''} (ID: ${me.user_id})`,
+          );
+        } catch (err) {
+          const errorMsg = err instanceof Error ? err.message : String(err);
+          console.warn(`⚠ Token verification failed: ${errorMsg}`);
+          // Continue anyway - user will see the error when gateway starts
+        }
+
+        return applyAccountConfig({
+          cfg,
+          accountId,
+          patch: { botToken: tokenValue },
+        });
+      },
+    },
+  ],
+
+  textInputs: [
+    {
+      inputKey: 'tokenFile',
+      message: 'Token file path (optional)',
+      placeholder: '/path/to/max-token.txt',
+      required: false,
+
+      shouldPrompt: ({ credentialValues }) => {
+        // Only prompt if no token was set via credential
+        return !credentialValues.botToken;
+      },
+
+      applySet: ({ cfg, accountId, value }) => {
+        const path = value.trim();
+        if (!path) return cfg;
+
+        return applyAccountConfig({
+          cfg,
+          accountId,
+          patch: { tokenFile: path },
+        });
+      },
+    },
+  ],
+
+  finalize: ({ cfg }) => {
+    // Ensure the channel is enabled
+    return {
+      cfg: {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          max: {
+            ...cfg.channels?.['max'],
+            enabled: true,
+          },
+        },
+      },
+    };
+  },
+
+  dmPolicy,
+};

package/src/polling.ts

@@ -0,0 +1,125 @@
+/**
+ * Long-polling transport: GET /updates loop with a persisted marker, and the
+ * start-up cleanup of webhook subscriptions that would silence polling.
+ */
+
+import {
+  channelReadyPatch,
+  createTransportActivityStatusPatch,
+} from 'openclaw/plugin-sdk/gateway-runtime';
+
+import type { MaxSubscription } from './api.js';
+import { dispatchUpdate } from './dispatch.js';
+import {
+  MAX_SUBSCRIBED_UPDATE_TYPES,
+  type MaxMonitorOptions,
+  type MaxStatusPatch,
+} from './monitor-types.js';
+
+/**
+ * Polling mode: MAX stops serving GET /updates while any webhook subscription
+ * exists, so a leftover subscription (another deploy, a manual test) would
+ * leave the bot deaf without a single error. Remove it and say so.
+ * @internal exported for testing.
+ */
+export async function clearMaxSubscriptionsForPolling(
+  opts: Pick<MaxMonitorOptions, 'api' | 'account' | 'log'>,
+): Promise<void> {
+  const { api, account, log } = opts;
+  let subscriptions: MaxSubscription[];
+  try {
+    subscriptions = (await api.getSubscriptions()).subscriptions ?? [];
+  } catch (err) {
+    log?.warn(`[${account.accountId}] MAX subscriptions check failed: ${String(err)}`);
+    return;
+  }
+  for (const subscription of subscriptions) {
+    log?.warn(
+      `[${account.accountId}] MAX webhook subscription ${subscription.url} is active — long polling gets no updates while it exists; removing it`,
+    );
+    try {
+      await api.unsubscribe(subscription.url);
+    } catch (err) {
+      log?.error(
+        `[${account.accountId}] MAX unsubscribe ${subscription.url} failed: ${String(err)}`,
+      );
+    }
+  }
+}
+
+export async function startMaxPollingLoop(opts: MaxMonitorOptions): Promise<void> {
+  const { api, account, abortSignal, log, statusSink } = opts;
+  let marker: number | null = opts.state?.marker ?? null;
+
+  log?.info(
+    `[${account.accountId}] MAX long-polling started${marker != null ? ` (resuming from marker ${marker})` : ''}`,
+  );
+
+  while (!abortSignal.aborted) {
+    try {
+      // The channel abort signal must reach the request: a 35s long poll that
+      // only the request's own timeout can cancel outlives the gateway's 5s
+      // stop budget and logs "channel stop exceeded 5000ms after abort".
+      const resp = await api.getUpdates({
+        timeout: 30,
+        marker: marker ?? undefined,
+        types: MAX_SUBSCRIBED_UPDATE_TYPES,
+        signal: abortSignal,
+      });
+
+      // A completed poll is the transport proof the gateway waits for: it moves
+      // the account out of lifecycle "starting", clears a stale lastError, and
+      // refreshes the timestamp the health policy uses to spot a dead socket.
+      statusSink?.(
+        channelReadyPatch({
+          ...createTransportActivityStatusPatch(),
+          mode: 'polling',
+        }) as MaxStatusPatch,
+      );
+
+      // Advance the in-memory marker so the next poll in this process moves on…
+      if (resp.marker != null) {
+        marker = resp.marker;
+      }
+
+      let batchCompleted = true;
+      for (const update of resp.updates) {
+        if (abortSignal.aborted) {
+          batchCompleted = false;
+          break;
+        }
+        try {
+          await dispatchUpdate(update, opts);
+        } catch (err) {
+          log?.error(
+            `[${account.accountId}] Error dispatching update ${update.update_type}: ${String(err)}`,
+          );
+        }
+      }
+
+      // …but only PERSIST the marker after the whole batch is handled. A restart
+      // mid-batch then resumes from before the unprocessed updates (at-least-once);
+      // OpenClaw dedups replays by mid, so re-delivery is safe but loss is not.
+      if (batchCompleted && !abortSignal.aborted && resp.marker != null) {
+        opts.state?.setMarker(resp.marker);
+      }
+    } catch (err) {
+      if (abortSignal.aborted) break;
+      log?.error(`[${account.accountId}] Polling error: ${String(err)}`);
+      // Record the error but keep `connected` untouched: this loop owns its
+      // retries, and flipping to disconnected on a transient blip would hand
+      // the health monitor a restart trigger. A genuinely dead transport is
+      // caught by lastTransportActivityAt going stale instead.
+      statusSink?.({ lastError: String(err) } as MaxStatusPatch);
+      // Back off on error
+      await sleep(3000);
+    }
+  }
+
+  statusSink?.({ connected: false } as MaxStatusPatch);
+  log?.info(`[${account.accountId}] MAX long-polling stopped`);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}