@aspalagin/openclaw-max 0.7.3 → 0.8.1

package/src/media-temp.ts

@@ -1,14 +1,28 @@
 /**
- * Remote media → temporary local file, for MAX uploads that need a path.
- * One place for the download, the file name policy and the cleanup.
+ * Remote media download for MAX uploads and the file name policy shared with
+ * inbound media. The download goes through the runtime media fetcher (core's
+ * SSRF-guarded reader); bytes stay in memory, no temporary file.
  */
 
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
+import { proxiedMediaFetchOptions, scrubProxyCredentials } from './network.js';
 import { getMaxRuntime } from './runtime.js';
 
+/**
+ * runtime.channel.media.fetchRemoteMedia, routed through the account proxy
+ * when one is set; errors never carry the proxy credentials.
+ */
+export async function fetchMaxRemoteMedia(url: string, maxBytes: number, proxyUrl?: string) {
+  try {
+    return await getMaxRuntime().channel.media.fetchRemoteMedia({
+      url,
+      maxBytes,
+      ...proxiedMediaFetchOptions(proxyUrl),
+    });
+  } catch (err) {
+    throw scrubProxyCredentials(err, proxyUrl);
+  }
+}
+
 /** Upper bound for a sanitized file name (bytes of UTF-8 stay well under 255). */
 export const MAX_TEMP_FILE_NAME_LENGTH = 120;
 
@@ -70,28 +84,26 @@ export function sanitizeMaxFileName(name: string | undefined, contentType?: stri
   return ext ? `${stem}.${ext}` : stem;
 }
 
-export type MaxTempMedia = { path: string; contentType?: string; fileName: string };
+/** Media bytes ready for a MAX upload. */
+export type MaxLoadedMedia = { buffer: Buffer; contentType?: string; fileName: string };
 
 /**
- * Download `url` through the runtime media fetcher (size-capped), write it to
- * a private temp directory under a sanitized name, run `use`, then remove the
- * directory whatever happens.
+ * Download `url` through the runtime media fetcher: core's readRemoteMediaBuffer
+ * (fetchWithSsrFGuard, strict mode: private, loopback and metadata hosts are
+ * refused), size-capped, through the account proxy when one is set. The file
+ * name is sanitized to one safe segment.
  */
-export async function withRemoteMediaTempFile<T>(
+export async function downloadMaxRemoteMedia(
   url: string,
   maxBytes: number,
-  use: (media: MaxTempMedia) => Promise<T>,
-): Promise<T> {
-  const loaded = await getMaxRuntime().channel.media.fetchRemoteMedia({ url, maxBytes });
-  const fileName = sanitizeMaxFileName(loaded.fileName ?? fileNameFromUrl(url), loaded.contentType);
-  const dir = await mkdtemp(join(tmpdir(), 'max-media-'));
-  try {
-    const path = join(dir, fileName);
-    await writeFile(path, loaded.buffer, { mode: 0o600 });
-    return await use({ path, contentType: loaded.contentType, fileName });
-  } finally {
-    await rm(dir, { recursive: true, force: true }).catch(() => {});
-  }
+  proxyUrl?: string,
+): Promise<MaxLoadedMedia> {
+  const loaded = await fetchMaxRemoteMedia(url, maxBytes, proxyUrl);
+  return {
+    buffer: Buffer.from(loaded.buffer),
+    contentType: loaded.contentType,
+    fileName: sanitizeMaxFileName(loaded.fileName ?? fileNameFromUrl(url), loaded.contentType),
+  };
 }
 
 function fileNameFromUrl(url: string): string | undefined {

package/src/network.ts

@@ -0,0 +1,233 @@
+/**
+ * Per-account network settings: MAX API base URL and an outbound HTTP(S) proxy.
+ *
+ * The settings are bound to the bot token when the account is resolved
+ * (resolveMaxAccount), and every MaxApi built for that token picks them up —
+ * whichever send/action/lifecycle path built it. A bad value is bound as an
+ * error, so requests fail with it instead of silently going out directly.
+ *
+ * Proxy credentials (http://user:pass@host:port) never reach logs or errors:
+ * use redactProxyUrl() for display and scrubProxyCredentials() on errors that
+ * crossed the proxy.
+ */
+
+import { createHash } from 'node:crypto';
+import { isIP } from 'node:net';
+
+/** Canonical MAX Bot API endpoint (platform-api.max.ru was shut down on 2026-07-19). */
+export const DEFAULT_MAX_API_BASE_URL = 'https://platform-api2.max.ru';
+
+export interface MaxNetwork {
+  /** Base URL without a trailing slash; request paths are appended to it. */
+  apiBaseUrl: string;
+  /** Proxy for MAX API, upload and media download traffic; undefined = direct. */
+  proxyUrl?: string;
+}
+
+/** A misconfigured apiBaseUrl/httpProxy; never retried, safe to log. */
+export class MaxNetworkConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MaxNetworkConfigError';
+  }
+}
+
+/** Loopback host: localhost names, 127.0.0.0/8, ::1 (URL.hostname form). */
+export function isLoopbackHost(hostname: string): boolean {
+  const host = hostname
+    .replace(/^\[|\]$/g, '')
+    .replace(/\.$/, '')
+    .toLowerCase();
+  if (host === 'localhost' || host.endsWith('.localhost')) return true;
+  if (isIP(host) === 4) return host.startsWith('127.');
+  if (isIP(host) === 6) return host === '::1' || host.startsWith('::ffff:127.');
+  return false;
+}
+
+/** Whether requests to `url` bypass the proxy (loopback targets never use it). */
+export function bypassesProxy(url: string): boolean {
+  try {
+    return isLoopbackHost(new URL(url).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Proxy URL for display: scheme, host and port; credentials become "***". */
+export function redactProxyUrl(proxyUrl: string): string {
+  try {
+    const url = new URL(proxyUrl);
+    const auth = url.username || url.password ? '***@' : '';
+    return `${url.protocol}//${auth}${url.host}`;
+  } catch {
+    return '<invalid URL>';
+  }
+}
+
+/** Secret fragments of a proxy URL, as they may appear in error text. */
+function proxySecrets(proxyUrl: string): string[] {
+  let url: URL;
+  try {
+    url = new URL(proxyUrl);
+  } catch {
+    return [proxyUrl];
+  }
+  if (!url.username && !url.password) return [];
+  const secrets = [proxyUrl, url.href];
+  for (const part of [url.password, url.username]) {
+    if (!part) continue;
+    secrets.push(part);
+    try {
+      secrets.push(decodeURIComponent(part));
+    } catch {
+      // keep the encoded form only
+    }
+  }
+  // longest first, so a URL is replaced whole before its parts
+  return [...new Set(secrets.filter((s) => s.length > 0))].sort((a, b) => b.length - a.length);
+}
+
+/**
+ * Remove proxy credentials from an error (message, and its cause chain) in
+ * place and return it. No-op when the proxy URL carries no credentials.
+ */
+export function scrubProxyCredentials<T>(err: T, proxyUrl: string | undefined): T {
+  if (!proxyUrl) return err;
+  const secrets = proxySecrets(proxyUrl);
+  if (secrets.length === 0) return err;
+  const scrub = (text: string): string =>
+    secrets.reduce((acc, secret) => acc.split(secret).join('***'), text);
+  let current: unknown = err;
+  for (let depth = 0; depth < 5 && current instanceof Error; depth++) {
+    if (secrets.some((s) => current instanceof Error && current.message.includes(s))) {
+      current.message = scrub(current.message);
+    }
+    if (
+      current.stack &&
+      secrets.some((s) => current instanceof Error && current.stack?.includes(s))
+    ) {
+      current.stack = scrub(current.stack);
+    }
+    current = (current as { cause?: unknown }).cause;
+  }
+  return err;
+}
+
+/**
+ * Validate and normalize the account's apiBaseUrl/httpProxy. `configPath` is
+ * the config prefix for messages ("channels.max" or "channels.max.accounts.x").
+ * Throws MaxNetworkConfigError; messages never echo proxy credentials.
+ */
+export function resolveMaxNetwork(
+  config: { apiBaseUrl?: unknown; httpProxy?: unknown },
+  configPath = 'channels.max',
+): MaxNetwork {
+  return {
+    apiBaseUrl: resolveApiBaseUrl(config.apiBaseUrl, `${configPath}.apiBaseUrl`),
+    proxyUrl: resolveProxyUrl(config.httpProxy, `${configPath}.httpProxy`),
+  };
+}
+
+function resolveApiBaseUrl(value: unknown, path: string): string {
+  if (value === undefined || value === null) return DEFAULT_MAX_API_BASE_URL;
+  if (typeof value !== 'string') throw new MaxNetworkConfigError(`${path} must be a string URL`);
+  const raw = value.trim();
+  if (!raw) return DEFAULT_MAX_API_BASE_URL;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new MaxNetworkConfigError(`${path} is not a valid URL (expected https://host[/path])`);
+  }
+  if (url.username || url.password) {
+    throw new MaxNetworkConfigError(`${path} must not contain credentials`);
+  }
+  if (url.search || url.hash) {
+    throw new MaxNetworkConfigError(`${path} must not contain a query or fragment: ${url.origin}`);
+  }
+  if (url.protocol === 'http:') {
+    // The bot token rides in the Authorization header of every call.
+    if (!isLoopbackHost(url.hostname)) {
+      throw new MaxNetworkConfigError(
+        `${path} must use https (http is allowed only for loopback hosts, the bot token would travel unencrypted): ${url.origin}`,
+      );
+    }
+  } else if (url.protocol !== 'https:') {
+    throw new MaxNetworkConfigError(`${path} must be an https URL: ${url.origin}`);
+  }
+  return `${url.origin}${url.pathname}`.replace(/\/+$/, '');
+}
+
+function resolveProxyUrl(value: unknown, path: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') throw new MaxNetworkConfigError(`${path} must be a string URL`);
+  const raw = value.trim();
+  // "" turns an inherited channel-level proxy off for one account.
+  if (!raw) return undefined;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new MaxNetworkConfigError(`${path} is not a valid URL (expected http://host:port)`);
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new MaxNetworkConfigError(
+      `${path} must be an http:// or https:// proxy URL (got ${url.protocol}//…)`,
+    );
+  }
+  if (!url.hostname) {
+    throw new MaxNetworkConfigError(`${path} has no host: ${redactProxyUrl(raw)}`);
+  }
+  return raw;
+}
+
+// ────────────────────── Token binding ──────────────────────
+
+type MaxNetworkBinding = MaxNetwork | { error: MaxNetworkConfigError };
+
+const bindings = new Map<string, MaxNetworkBinding>();
+
+/** Registry key: a token digest, not the token itself. */
+export function maxTokenKey(token: string): string {
+  return createHash('sha256').update(token).digest('hex').slice(0, 16);
+}
+
+/** Bind the account's network settings (or its config error) to its token. */
+export function bindMaxNetwork(token: string, binding: MaxNetworkBinding): void {
+  if (!token) return;
+  bindings.set(maxTokenKey(token), binding);
+}
+
+/**
+ * Network settings bound to a token; the default endpoint, direct, when the
+ * token was never resolved from config (e.g. a setup-wizard probe). Throws the
+ * bound config error.
+ */
+export function lookupMaxNetwork(token: string): MaxNetwork {
+  const binding = bindings.get(maxTokenKey(token));
+  if (!binding) return { apiBaseUrl: DEFAULT_MAX_API_BASE_URL };
+  if ('error' in binding) throw binding.error;
+  return binding;
+}
+
+export function resetMaxNetworkBindingsForTests(): void {
+  bindings.clear();
+}
+
+/**
+ * Options for runtime.channel.media.fetchRemoteMedia routing a download
+ * through the account proxy (core SSRF guard, explicit-proxy dispatcher; the
+ * proxy is operator-configured, so it may sit on a private address, and it
+ * resolves the target DNS after the guard's hostname checks — as core's
+ * Telegram channel does for its explicit proxy).
+ */
+export function proxiedMediaFetchOptions(proxyUrl: string | undefined): {
+  dispatcherPolicy?: { mode: 'explicit-proxy'; proxyUrl: string; allowPrivateProxy: true };
+  trustExplicitProxyDns?: true;
+} {
+  if (!proxyUrl) return {};
+  return {
+    dispatcherPolicy: { mode: 'explicit-proxy', proxyUrl, allowPrivateProxy: true },
+    trustExplicitProxyDns: true,
+  };
+}

package/src/onboarding.ts

@@ -8,7 +8,7 @@ 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 { listMaxAccountIds, resolveMaxAccount, resolveMaxAccountNetwork } from './accounts.js';
 import { MaxApi } from './api.js';
 
 const channel = 'max' as const;
@@ -150,7 +150,9 @@ export const maxSetupWizard: ChannelSetupWizard = {
 
         // Verify token by calling GET /me
         try {
-          const api = new MaxApi({ token: tokenValue, timeoutMs: 5000 });
+          // Probe over the account's apiBaseUrl/httpProxy: the new token is not bound yet.
+          const network = resolveMaxAccountNetwork(resolveMaxAccount({ cfg, accountId }));
+          const api = new MaxApi({ token: tokenValue, timeoutMs: 5000, network });
           const me = await api.getMe();
           console.log(
             `✓ Token verified! Bot: ${me.first_name}${me.username ? ` (@${me.username})` : ''} (ID: ${me.user_id})`,

package/src/polling.ts

@@ -7,14 +7,24 @@ import {
   channelReadyPatch,
   createTransportActivityStatusPatch,
 } from 'openclaw/plugin-sdk/gateway-runtime';
+import {
+  type BackoffPolicy,
+  computeBackoff,
+  sleepWithAbort,
+} from 'openclaw/plugin-sdk/runtime-env';
 
-import type { MaxSubscription } from './api.js';
+import { MaxApiError, type MaxSubscription, type MaxUpdate } from './api.js';
 import { dispatchUpdate } from './dispatch.js';
+import { isMaxGatewayDrainingError, waitForMaxDrainRetry } from './gateway-drain.js';
 import {
   MAX_SUBSCRIBED_UPDATE_TYPES,
   type MaxMonitorOptions,
   type MaxStatusPatch,
 } from './monitor-types.js';
+import { runWithMaxTurnAdoption } from './turn-adoption.js';
+import { type MaxUpdateJournal, openMaxUpdateJournal } from './update-journal.js';
+import { maxUpdateDedupeKey } from './webhook.js';
+import { resolveMaxEventMaxAgeMs, staleMaxUpdateAgeMs } from './webhook-queue.js';
 
 /**
  * Polling mode: MAX stops serving GET /updates while any webhook subscription
@@ -47,6 +57,196 @@ export async function clearMaxSubscriptionsForPolling(
   }
 }
 
+/** Pause after failed polls: 2 s doubling up to 60 s, plus up to 20% jitter; a good poll resets it. */
+const POLL_BACKOFF: BackoffPolicy = { initialMs: 2_000, maxMs: 60_000, factor: 2, jitter: 0.2 };
+
+/** A rejected token (401) does not heal in seconds: retry rarely instead of at the error pace. */
+export const POLL_AUTH_PAUSE_MS = 5 * 60_000;
+
+/** Ceiling for a server Retry-After, so one answer cannot silence the bot for hours. */
+const POLL_MAX_RETRY_AFTER_MS = 10 * 60_000;
+
+function isAuthRejected(err: unknown): boolean {
+  return err instanceof MaxApiError && err.status === 401;
+}
+
+/**
+ * Delay before the next poll after `failures` failed polls in a row: the
+ * exponential backoff, at least the server's Retry-After (bounded), and a
+ * long fixed pause for a rejected token.
+ * @internal exported for testing.
+ */
+export function resolvePollRetryDelayMs(err: unknown, failures: number): number {
+  if (isAuthRejected(err)) return POLL_AUTH_PAUSE_MS;
+  const backoffMs = computeBackoff(POLL_BACKOFF, failures);
+  const retryAfterMs = err instanceof MaxApiError ? err.retryAfterMs : undefined;
+  if (!retryAfterMs) return backoffMs;
+  return Math.max(backoffMs, Math.min(retryAfterMs, POLL_MAX_RETRY_AFTER_MS));
+}
+
+/**
+ * Dedupe keys of handled updates survive restarts in the account journal: a
+ * restart mid-batch re-fetches the whole batch (the marker is persisted only
+ * after it), and core's inbound dedupe lives in process memory. Undefined when
+ * the state directory is not writable (then replays are dispatched again).
+ */
+async function openPollingJournal(opts: MaxMonitorOptions): Promise<MaxUpdateJournal | undefined> {
+  const { account, log } = opts;
+  try {
+    return await openMaxUpdateJournal({
+      accountId: account.accountId,
+      warn: (message) => log?.warn(`[${account.accountId}] ${message}`),
+    });
+  } catch (err) {
+    const code = (err as { code?: unknown })?.code;
+    log?.warn(
+      `[${account.accountId}] MAX update journal unavailable (${typeof code === 'string' ? code : String(err)}); updates handled before a restart may be handled again`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * One polled update: skip a handled or stale one, dispatch, remember it.
+ * False when the channel stopped while the draining gateway refused it: not
+ * handled, not remembered.
+ */
+async function handlePolledUpdate(
+  update: MaxUpdate,
+  opts: MaxMonitorOptions,
+  journal: MaxUpdateJournal | undefined,
+  maxAgeMs: number,
+): Promise<boolean> {
+  const { account, log } = opts;
+  const key = maxUpdateDedupeKey(update);
+  if (key && journal?.hasCompleted(key)) {
+    log?.debug?.(
+      `[${account.accountId}] MAX polling: ${update.update_type} already handled, skipped`,
+    );
+    return true;
+  }
+  let remembered: Promise<void> | undefined;
+  const remember = (): Promise<void> =>
+    (remembered ??= key && journal ? journal.remember(key) : Promise.resolve());
+  const staleMs = staleMaxUpdateAgeMs(update, maxAgeMs, Date.now());
+  if (staleMs !== undefined) {
+    log?.warn(
+      `[${account.accountId}] MAX polling: ${update.update_type} from ${Math.round(staleMs / 60_000)} min ago skipped (older than maxEventAgeMinutes)`,
+    );
+  } else {
+    try {
+      const durable = Boolean(key && journal);
+      const adopted = () => remembered !== undefined;
+      if (!(await dispatchThroughDrain(remember, adopted, update, opts, durable))) return false;
+    } catch (err) {
+      log?.error(
+        `[${account.accountId}] Error dispatching update ${update.update_type}: ${String(err)}`,
+      );
+    }
+  }
+  await remember();
+  return true;
+}
+
+/**
+ * Dispatch; with `durable`, `done` also runs at core's turn adoption. Core then
+ * owns the turn and resumes it after a crash by itself: marking the update
+ * handled only when the dispatch returns would replay it after the restart and
+ * run the turn twice (see turn-adoption.ts).
+ */
+function dispatchWithAdoption(
+  done: () => Promise<void>,
+  update: MaxUpdate,
+  opts: MaxMonitorOptions,
+  durable: boolean,
+): Promise<void> {
+  const dispatch = () => dispatchUpdate(update, opts);
+  return durable ? runWithMaxTurnAdoption(done, dispatch) : dispatch();
+}
+
+/**
+ * dispatchWithAdoption, again after a pause while the draining gateway refuses
+ * a durable update before core adopted its turn: the turn never started (see
+ * gateway-drain.ts). False when the channel stopped first; other errors throw.
+ */
+async function dispatchThroughDrain(
+  done: () => Promise<void>,
+  adopted: () => boolean,
+  update: MaxUpdate,
+  opts: MaxMonitorOptions,
+  durable: boolean,
+): Promise<boolean> {
+  const { account, log } = opts;
+  let refusals = 0;
+  for (;;) {
+    try {
+      await dispatchWithAdoption(done, update, opts, durable);
+      if (refusals > 0) {
+        log?.info(
+          `[${account.accountId}] MAX polling: ${update.update_type} accepted after ${refusals} refusal(s) of the draining gateway`,
+        );
+      }
+      return true;
+    } catch (err) {
+      if (!durable || adopted() || !isMaxGatewayDrainingError(err)) throw err;
+      refusals += 1;
+      if (refusals === 1) {
+        log?.warn(
+          `[${account.accountId}] MAX polling: the gateway is draining and refused ${update.update_type}; retried until accepted or the channel stops (then after the restart)`,
+        );
+      }
+      if (!(await waitForMaxDrainRetry(refusals, opts.abortSignal))) return false;
+    }
+  }
+}
+
+/**
+ * Updates a webhook-mode run accepted but did not handle before the transport
+ * was switched to polling: handle them first, in order.
+ */
+async function drainWebhookLeftovers(
+  opts: MaxMonitorOptions,
+  journal: MaxUpdateJournal,
+  maxAgeMs: number,
+): Promise<void> {
+  const { account, log } = opts;
+  let pending;
+  try {
+    pending = await journal.readPending();
+  } catch (err) {
+    log?.error(`[${account.accountId}] MAX update journal read failed: ${String(err)}`);
+    return;
+  }
+  if (pending.entries.length + pending.unreadable === 0) return;
+  log?.warn(
+    `[${account.accountId}] MAX polling: ${pending.entries.length} webhook update(s) accepted before the restart handled first, ${pending.unreadable} unreadable dropped`,
+  );
+  for (const entry of pending.entries) {
+    if (opts.abortSignal.aborted) {
+      journal.release(entry);
+      continue;
+    }
+    let completed: Promise<void> | undefined;
+    const complete = (): Promise<void> => (completed ??= journal.complete(entry));
+    const staleMs = staleMaxUpdateAgeMs(entry.update, maxAgeMs, Date.now(), entry.receivedAt);
+    if (staleMs === undefined) {
+      try {
+        const adopted = () => completed !== undefined;
+        if (!(await dispatchThroughDrain(complete, adopted, entry.update, opts, true))) {
+          // Stopped while the draining gateway refused it: the next start takes it.
+          journal.release(entry);
+          continue;
+        }
+      } catch (err) {
+        log?.error(
+          `[${account.accountId}] Error dispatching update ${entry.update.update_type}: ${String(err)}`,
+        );
+      }
+    }
+    await complete();
+  }
+}
+
 export async function startMaxPollingLoop(opts: MaxMonitorOptions): Promise<void> {
   const { api, account, abortSignal, log, statusSink } = opts;
   let marker: number | null = opts.state?.marker ?? null;
@@ -55,6 +255,11 @@ export async function startMaxPollingLoop(opts: MaxMonitorOptions): Promise<void
     `[${account.accountId}] MAX long-polling started${marker != null ? ` (resuming from marker ${marker})` : ''}`,
   );
 
+  const maxAgeMs = resolveMaxEventMaxAgeMs(account.config.maxEventAgeMinutes);
+  const journal = await openPollingJournal(opts);
+  if (journal) await drainWebhookLeftovers(opts, journal, maxAgeMs);
+
+  let failures = 0;
   while (!abortSignal.aborted) {
     try {
       // The channel abort signal must reach the request: a 35s long poll that
@@ -66,6 +271,7 @@ export async function startMaxPollingLoop(opts: MaxMonitorOptions): Promise<void
         types: MAX_SUBSCRIBED_UPDATE_TYPES,
         signal: abortSignal,
       });
+      failures = 0;
 
       // A completed poll is the transport proof the gateway waits for: it moves
       // the account out of lifecycle "starting", clears a stale lastError, and
@@ -88,38 +294,38 @@ export async function startMaxPollingLoop(opts: MaxMonitorOptions): Promise<void
           batchCompleted = false;
           break;
         }
-        try {
-          await dispatchUpdate(update, opts);
-        } catch (err) {
-          log?.error(
-            `[${account.accountId}] Error dispatching update ${update.update_type}: ${String(err)}`,
-          );
+        if (!(await handlePolledUpdate(update, opts, journal, maxAgeMs))) {
+          batchCompleted = false;
+          break;
         }
       }
 
       // …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.
+      // the journal's dedupe keys skip the ones already handled.
       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)}`);
+      failures += 1;
+      const delayMs = resolvePollRetryDelayMs(err, failures);
+      const retryIn = `retrying in ${Math.round(delayMs / 1000)}s`;
+      log?.error(
+        isAuthRejected(err)
+          ? `[${account.accountId}] MAX rejected the bot token (401): check botToken/tokenFile; ${retryIn}`
+          : `[${account.accountId}] Polling error: ${String(err)}; ${retryIn}`,
+      );
       // 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);
+      // The account stop ends the pause at once (sleepWithAbort rejects).
+      await sleepWithAbort(delayMs, abortSignal).catch(() => undefined);
     }
   }
 
   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));
-}

package/src/presentation.ts

@@ -21,7 +21,7 @@
  */
 
 import type { ChannelOutboundAdapter } from 'openclaw/plugin-sdk/channel-contract';
-import type { ReplyPayload } from 'openclaw/plugin-sdk/core';
+import type { OpenClawConfig, ReplyPayload } from 'openclaw/plugin-sdk/core';
 import {
   type MessagePresentation,
   type MessagePresentationBlock,
@@ -33,6 +33,7 @@ import {
   resolveMessagePresentationButtonAction,
   resolveMessagePresentationOptionAction,
 } from 'openclaw/plugin-sdk/interactive-runtime';
+import { resolveTextChunkLimit } from 'openclaw/plugin-sdk/reply-chunking';
 
 import type { MaxSendButton } from './send.js';
 
@@ -47,6 +48,18 @@ export const MAX_KEYBOARD_ROWS = 30;
 export const MAX_KEYBOARD_BUTTONS = 210;
 export const MAX_LINK_URL_LENGTH = 2048;
 export const MAX_TEXT_LIMIT = 4000;
+
+/**
+ * Chunk size of outgoing text: channels.max.textChunkLimit (account first, as
+ * core resolves it) may lower it, never above MAX's 4000-character cap.
+ */
+export function resolveMaxTextChunkLimit(cfg: OpenClawConfig, accountId?: string | null): number {
+  const configured = resolveTextChunkLimit(cfg, 'max', accountId, {
+    fallbackLimit: MAX_TEXT_LIMIT,
+  });
+  return Math.min(configured, MAX_TEXT_LIMIT);
+}
+
 /** Buttons per row we render: within MAX's 7 (3 for link/open_app/request_*). */
 const BUTTONS_PER_ROW = 3;
 const SELECT_OPTIONS_PER_ROW = 2;