@aspalagin/openclaw-max 0.7.2 → 0.8.0

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "@aspalagin/openclaw-max",
-  "version": "0.7.2",
-  "description": "MAX messenger channel plugin for OpenClaw",
+  "version": "0.8.0",
+  "description": "MAX messenger (max.ru) channel for OpenClaw: private and group chats over webhook or long polling; media, voice messages with transcription and voice replies; inline keyboards and command menus; message edits and pins; several bot accounts",
   "keywords": [
     "openclaw",
     "openclaw-plugin",
+    "openclaw-channel",
     "max",
+    "max.ru",
     "max-messenger",
+    "max-bot-api",
     "messenger",
+    "chatbot",
+    "bot",
+    "webhook",
+    "long-polling",
+    "voice-messages",
     "ai-agent"
   ],
   "license": "MIT",
+  "author": {
+    "name": "Arseniy Palagin",
+    "url": "https://github.com/aspalagin"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -25,7 +37,7 @@
     "url": "https://github.com/aspalagin/openclaw-max/issues"
   },
   "scripts": {
-    "build": "rm -rf dist-ts dist/src && tsc --noEmit false --noEmitOnError false --outDir dist-ts && mkdir -p dist/src && cp dist-ts/index.js dist-ts/setup-entry.js dist/ && cp dist-ts/src/*.js dist/src/ && rm -f dist/src/*.test.js dist/src/test-setup.js",
+    "build": "rm -rf dist-ts dist/src && tsc --noEmit false --noEmitOnError false --outDir dist-ts && mkdir -p dist/src && cp dist-ts/index.js dist-ts/setup-entry.js dist-ts/secret-contract-api.js dist/ && cp dist-ts/src/*.js dist/src/ && rm -f dist/src/*.test.js dist/src/test-setup.js",
     "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
@@ -44,9 +56,10 @@
     "!src/**/*.test.ts",
     "!src/test-setup.ts",
     "!src/__fixtures__/",
-    "scripts/",
+    "assets/icon.png",
     "openclaw.plugin.json",
     "README.md",
+    "README_EN.md",
     "SKILL.md",
     "LICENSE"
   ],
@@ -61,7 +74,14 @@
       "selectionLabel": "MAX (max.ru)",
       "docsPath": "/channels/max",
       "docsLabel": "max",
-      "blurb": "MAX messenger channel (max.ru Bot API)."
+      "blurb": "MAX messenger channel (max.ru Bot API).",
+      "configuredState": {
+        "env": {
+          "anyOf": [
+            "MAX_BOT_TOKEN"
+          ]
+        }
+      }
     },
     "compat": {
       "pluginApi": ">=2026.9.6",

package/src/access-policy.ts

@@ -0,0 +1,154 @@
+/**
+ * Chat admission rules shared by the inbound gate and message-tool action
+ * scoping: the DM policy with allowFrom and the pairing store, the group
+ * policy with its allowlist, the group sender allowlist.
+ */
+
+import { isSenderIdAllowed, resolveGroupAllowFromSources } from 'openclaw/plugin-sdk/allow-from';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+import { DEFAULT_ACCOUNT_ID } from 'openclaw/plugin-sdk/core';
+
+import { maxAccountConfigPath, type ResolvedMaxAccount } from './accounts.js';
+import { getMaxRuntime } from './runtime.js';
+
+export type MaxAdmission = { admitted: true } | { admitted: false; reason: string };
+
+/** Effective group policy: account, then channels.defaults, then allowlist. */
+export function resolveMaxGroupPolicy(account: ResolvedMaxAccount, config: OpenClawConfig): string {
+  return account.config.groupPolicy ?? config.channels?.defaults?.groupPolicy ?? 'allowlist';
+}
+
+/** Whether a group chat passes the group policy (disabled / allowlist with "*" / open) and is enabled. */
+export function admitMaxGroupChat(
+  account: ResolvedMaxAccount,
+  config: OpenClawConfig,
+  chatId: number | string | undefined,
+): MaxAdmission {
+  const groupPolicy = resolveMaxGroupPolicy(account, config);
+  if (groupPolicy === 'disabled') return { admitted: false, reason: 'groupPolicy=disabled' };
+  if (groupPolicy === 'allowlist') {
+    const groups = account.config.groups ?? {};
+    if (!(String(chatId) in groups) && !('*' in groups)) {
+      return { admitted: false, reason: 'chat is not in the groups allowlist' };
+    }
+  }
+  // groups.<id>.enabled=false (else the "*" entry's) turns the group off under any policy.
+  const groupCfg = account.config.groups?.[String(chatId)] ?? account.config.groups?.['*'];
+  if (groupCfg?.enabled === false) return { admitted: false, reason: 'group enabled=false' };
+  return { admitted: true };
+}
+
+/**
+ * Sender allowlist of a group: its own groups.<id>.allowFrom (else the "*"
+ * entry's), else the account's groupAllowFrom — the first non-empty one, as
+ * core resolves group sender lists. `max:` prefixes are stripped.
+ */
+export function resolveMaxGroupSenderAllowFrom(
+  account: ResolvedMaxAccount,
+  chatId: number | string | undefined,
+): string[] {
+  const groupCfg = account.config.groups?.[String(chatId)] ?? account.config.groups?.['*'];
+  const groupAllowFrom = Array.isArray(groupCfg?.allowFrom)
+    ? (groupCfg.allowFrom as Array<string | number>)
+    : undefined;
+  return resolveGroupAllowFromSources({
+    groupAllowFrom,
+    allowFrom: account.config.groupAllowFrom,
+  }).map((entry) => entry.replace(/^max:/i, ''));
+}
+
+/**
+ * Whether a sender may trigger the bot in a group the group policy admits:
+ * anyone when no sender list is set (unlike core's WhatsApp/Telegram, no
+ * fallback to the DM allowFrom — MAX never applied it to groups), "*" for
+ * anyone, else only the listed user ids. DM pairing approvals don't count.
+ */
+export function admitMaxGroupSender(
+  account: ResolvedMaxAccount,
+  chatId: number | string | undefined,
+  senderId: number | string | undefined,
+): MaxAdmission {
+  const entries = resolveMaxGroupSenderAllowFrom(account, chatId);
+  const allow = {
+    entries,
+    hasWildcard: entries.includes('*'),
+    hasEntries: entries.length > 0,
+  };
+  if (isSenderIdAllowed(allow, senderId != null ? String(senderId) : undefined, true)) {
+    return { admitted: true };
+  }
+  return { admitted: false, reason: 'sender is not in the group allowFrom/groupAllowFrom' };
+}
+
+/** Group policy, then the group's sender allowlist. */
+export function admitMaxGroupMessage(
+  account: ResolvedMaxAccount,
+  config: OpenClawConfig,
+  chatId: number | string | undefined,
+  senderId: number | string | undefined,
+): MaxAdmission {
+  const chat = admitMaxGroupChat(account, config, chatId);
+  return chat.admitted ? admitMaxGroupSender(account, chatId, senderId) : chat;
+}
+
+/** allowFrom from the config plus the approved pairing store, as strings. */
+export async function readMaxDmAllowFrom(account: ResolvedMaxAccount): Promise<string[]> {
+  const configAllowFrom = (account.config.allowFrom ?? []).map(String);
+  const storeAllowFrom = await getMaxRuntime()
+    .channel.pairing.readAllowFromStore({ channel: 'max', accountId: account.accountId })
+    .catch(() => []);
+  return [...configAllowFrom, ...storeAllowFrom];
+}
+
+/** Whether a DM peer passes the DM policy (disabled / open / allowFrom + pairing store). */
+export async function admitMaxDmUser(
+  account: ResolvedMaxAccount,
+  userId: number | string | undefined,
+): Promise<MaxAdmission> {
+  const dmPolicy = account.config.dmPolicy ?? 'pairing';
+  if (dmPolicy === 'disabled') return { admitted: false, reason: 'dmPolicy=disabled' };
+  if (dmPolicy === 'open') return { admitted: true };
+  const allowFrom = await readMaxDmAllowFrom(account);
+  if (allowFrom.includes('*') || (userId != null && allowFrom.includes(String(userId)))) {
+    return { admitted: true };
+  }
+  return {
+    admitted: false,
+    reason: `user is not in allowFrom or the pairing store (dmPolicy=${dmPolicy})`,
+  };
+}
+
+/**
+ * Start-up warning for a named account that sets no DM or group policy of its
+ * own and inherits an open one (channels.max, or channels.defaults for
+ * groups): the second bot is then open too. Names the account, the policy
+ * and where to set its own; no secrets or user ids. undefined when nothing
+ * open is inherited.
+ */
+export function describeMaxInheritedOpenAccess(
+  cfg: OpenClawConfig | undefined,
+  account: ResolvedMaxAccount,
+): string | undefined {
+  if (!cfg || account.accountId === DEFAULT_ACCOUNT_ID) return undefined;
+  const channel = cfg.channels?.max as Record<string, unknown> | undefined;
+  const accounts = channel?.accounts as Record<string, Record<string, unknown>> | undefined;
+  const own = accounts?.[account.accountId] ?? {};
+  const inherited: string[] = [];
+  const fix: string[] = [];
+  if (!Object.hasOwn(own, 'dmPolicy') && account.config.dmPolicy === 'open') {
+    inherited.push('dmPolicy="open" from channels.max (anyone can message this bot)');
+    fix.push('dmPolicy (e.g. "pairing")');
+  }
+  if (!Object.hasOwn(own, 'groupPolicy') && resolveMaxGroupPolicy(account, cfg) === 'open') {
+    const from = channel?.groupPolicy === 'open' ? 'channels.max' : 'channels.defaults';
+    inherited.push(`groupPolicy="open" from ${from} (any group can add and ping this bot)`);
+    fix.push('groupPolicy (e.g. "allowlist" with groups)');
+  }
+  if (inherited.length === 0) return undefined;
+  const path = maxAccountConfigPath(account.accountId);
+  return (
+    `MAX account "${account.accountId}" has no access policy of its own and inherits ` +
+    `${inherited.join(' and ')}; set ${fix.map((key) => `${path}.${key}`).join(' / ')} ` +
+    'to give this bot its own access rules.'
+  );
+}

package/src/accounts.ts

@@ -4,8 +4,19 @@
 
 import { lstatSync, readFileSync } from 'node:fs';
 
+import { mergeAccountConfig } from 'openclaw/plugin-sdk/account-core';
 import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from 'openclaw/plugin-sdk/core';
+import { resolveSecretInputString } from 'openclaw/plugin-sdk/secret-input';
+import { canResolveEnvSecretRefInReadOnlyPath } from 'openclaw/plugin-sdk/secret-ref-readonly';
+
+import {
+  bindMaxNetwork,
+  type MaxNetwork,
+  MaxNetworkConfigError,
+  resolveMaxNetwork,
+} from './network.js';
+import type { MaxSecretField } from './secret-contract.js';
 
 export interface MaxAccountConfig {
   enabled?: boolean;
@@ -14,9 +25,20 @@ export interface MaxAccountConfig {
   name?: string;
   dmPolicy?: string;
   allowFrom?: Array<string | number>;
-  groups?: Record<string, { requireMention?: boolean; [key: string]: unknown }>;
+  groups?: Record<
+    string,
+    {
+      requireMention?: boolean;
+      enabled?: boolean;
+      systemPrompt?: string;
+      skills?: string[];
+      [key: string]: unknown;
+    }
+  >;
   groupPolicy?: string;
   groupAllowFrom?: Array<string | number>;
+  /** Where core mention patterns apply in groups (core channel mention policy) */
+  mentionPatterns?: { mode?: 'allow' | 'deny'; allowIn?: string[]; denyIn?: string[] };
   /** Update transport; default: "webhook" when webhookUrl is set, otherwise "polling" */
   transport?: 'polling' | 'webhook';
   webhookUrl?: string;
@@ -24,10 +46,39 @@ export interface MaxAccountConfig {
   /** File holding the webhook secret (like tokenFile) */
   webhookSecretFile?: string;
   webhookPath?: string;
+  /** Webhook queue: durable journal (default) or memory, size and overflow policy */
+  webhookQueue?: {
+    mode?: 'durable' | 'memory';
+    maxPending?: number;
+    overflow?: 'reject' | 'drop';
+  };
+  /** Updates the bot would answer are skipped past this age (default 60; 0 = no limit) */
+  maxEventAgeMinutes?: number;
+  /** Debug logs carry a text preview of inbound messages (default false) */
+  logMessagePreview?: boolean;
   mediaMaxMb?: number;
   streamMode?: 'off' | 'partial' | 'block';
   /** Send mark_seen read receipts on inbound messages (default true) */
   markSeen?: boolean;
+  /** Chats message-tool actions may act in (default "admitted"; see action-scope.ts) */
+  actionScope?: 'admitted' | 'current' | 'off';
+  /** Default MAX `notify` of sent messages (default true); channels always notify */
+  notify?: boolean;
+  /** Default: send messages without link previews (MAX `disable_link_preview`) */
+  disableLinkPreview?: boolean;
+  /** Most media attachments downloaded per inbound message (default 12) */
+  mediaMaxCount?: number;
+  /** MAX Bot API base URL (default https://platform-api2.max.ru); see network.ts */
+  apiBaseUrl?: string;
+  /** HTTP(S) proxy for all MAX traffic of the account; may carry credentials */
+  httpProxy?: string;
+  /** Core streaming settings (streaming.mode, streaming.progress) */
+  streaming?: Record<string, unknown>;
+  /**
+   * Message-tool actions; false turns one off (createActionGate). The schema
+   * also accepts legacy policy strings, which leave the action on.
+   */
+  actions?: Record<string, boolean | undefined>;
 }
 
 export interface ResolvedMaxAccount {
@@ -36,9 +87,47 @@ export interface ResolvedMaxAccount {
   enabled: boolean;
   token: string;
   tokenSource: 'config' | 'env' | 'file' | 'none';
+  /**
+   * available — a token was found; configured_unavailable — botToken is a
+   * SecretRef the gateway did not resolve; missing — no token anywhere.
+   */
+  tokenStatus?: 'available' | 'configured_unavailable' | 'missing';
+  /**
+   * Options set to a SecretRef that did not resolve: config path and ref, never
+   * a value. The account does not start; it never falls back to a
+   * lower-precedence source (token file, MAX_BOT_TOKEN, no proxy, generated
+   * webhook secret).
+   */
+  secretErrors?: Partial<Record<MaxSecretField, string>>;
+  /** Set when no token was found: what to configure, or which token file option failed. */
+  stateReason?: string;
+  /**
+   * Account settings; a named account inherits every channel-level value it
+   * does not set itself, except MAX_ACCOUNT_OWN_KEYS.
+   */
   config: MaxAccountConfig;
 }
 
+/**
+ * Channel-level keys a named account never inherits: they belong to one bot
+ * (token, token file, display name) or to one webhook subscription (transport,
+ * URL, secret, secret file, HTTP path — a shared path would route two bots to
+ * one handler). Top-level-only keys (commands, defaultAccount) are not account
+ * settings at all.
+ */
+export const MAX_ACCOUNT_OWN_KEYS = [
+  'botToken',
+  'tokenFile',
+  'name',
+  'transport',
+  'webhookUrl',
+  'webhookSecret',
+  'webhookSecretFile',
+  'webhookPath',
+  'commands',
+  'defaultAccount',
+] as const;
+
 /**
  * Get the MAX channel section from config.
  */
@@ -63,6 +152,46 @@ function readTokenFile(tokenFile?: string): string {
   }
 }
 
+/** Thrown at account start for an option whose SecretRef did not resolve. */
+export class MaxSecretConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MaxSecretConfigError';
+  }
+}
+
+type SecretOption = { value?: string; error?: string };
+
+/**
+ * A secret-capable option: a plain string, or a SecretRef the gateway has
+ * already replaced by its value in the runtime snapshot. A ref still present
+ * is unresolved — except an env ref the read-only SDK check allows (CLI and
+ * status paths without a gateway snapshot, as core channels do).
+ */
+function readSecretOption(cfg: OpenClawConfig, value: unknown, path: string): SecretOption {
+  const resolved = resolveSecretInputString({
+    value,
+    path,
+    defaults: cfg.secrets?.defaults,
+    mode: 'inspect',
+  });
+  if (resolved.status === 'available') return { value: resolved.value };
+  if (resolved.status === 'missing') return {};
+  const { ref } = resolved;
+  if (
+    ref.source === 'env' &&
+    canResolveEnvSecretRefInReadOnlyPath({ cfg, provider: ref.provider, id: ref.id })
+  ) {
+    const fromEnv = process.env[ref.id]?.trim();
+    if (fromEnv) return { value: fromEnv };
+  }
+  return {
+    error:
+      `MAX ${path} is a SecretRef (${ref.source}:${ref.provider}:${ref.id}) that did not ` +
+      'resolve; check the secret and secrets.providers (openclaw secrets audit)',
+  };
+}
+
 /**
  * List all MAX account IDs from config.
  */
@@ -101,12 +230,71 @@ export function resolveDefaultMaxAccountId(_cfg: OpenClawConfig): string {
   return DEFAULT_ACCOUNT_ID;
 }
 
+/** Config path of an account's own settings, for error messages. */
+export function maxAccountConfigPath(accountId: string): string {
+  return accountId === DEFAULT_ACCOUNT_ID ? 'channels.max' : `channels.max.accounts.${accountId}`;
+}
+
+/**
+ * The account's validated network settings (API base URL, proxy). Throws
+ * MaxNetworkConfigError with the config path; never echoes proxy credentials.
+ */
+export function resolveMaxAccountNetwork(account: ResolvedMaxAccount): MaxNetwork {
+  const proxyError = account.secretErrors?.httpProxy;
+  if (proxyError) throw new MaxNetworkConfigError(proxyError);
+  return resolveMaxNetwork(account.config, maxAccountConfigPath(account.accountId));
+}
+
+function resolveAccountNetwork(
+  accountId: string,
+  config: MaxAccountConfig,
+  proxyError: string | undefined,
+): MaxNetwork | { error: MaxNetworkConfigError } {
+  // An unresolved proxy ref must not mean "connect directly".
+  if (proxyError) return { error: new MaxNetworkConfigError(proxyError) };
+  try {
+    return resolveMaxNetwork(config, maxAccountConfigPath(accountId));
+  } catch (err) {
+    if (err instanceof MaxNetworkConfigError) return { error: err };
+    throw err;
+  }
+}
+
+/** A token was found, or botToken is a SecretRef that did not resolve. */
+export function isMaxAccountConfigured(account: ResolvedMaxAccount): boolean {
+  return Boolean(account.token?.trim()) || account.tokenStatus === 'configured_unavailable';
+}
+
 /**
  * Resolve a single MAX account from config.
  */
 export function resolveMaxAccount(params: {
   cfg: OpenClawConfig;
   accountId?: string | null;
+}): ResolvedMaxAccount {
+  const account = readMaxAccount(params);
+  // Every MaxApi built for this token (any send/action/lifecycle path) uses
+  // the account's API base URL and proxy — or fails with their config error.
+  bindMaxNetwork(
+    account.token,
+    resolveAccountNetwork(account.accountId, account.config, account.secretErrors?.httpProxy),
+  );
+  return account;
+}
+
+/** Why an account has no token: the options to set or the unreadable token file (no path of the file itself). */
+function missingTokenReason(accountId: string, tokenFile: string | undefined): string {
+  const path = maxAccountConfigPath(accountId);
+  if (tokenFile?.trim()) return `${path}.tokenFile is missing, empty or not a regular file`;
+  return accountId === DEFAULT_ACCOUNT_ID
+    ? `no bot token: set ${path}.botToken, ${path}.tokenFile or MAX_BOT_TOKEN`
+    : `no bot token: set ${path}.botToken or ${path}.tokenFile`;
+}
+
+/** Account resolution without side effects (resolveMaxAccount also binds its network). */
+export function readMaxAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
 }): ResolvedMaxAccount {
   const { cfg, accountId: rawId } = params;
   const accountId = rawId ? normalizeAccountId(rawId) : DEFAULT_ACCOUNT_ID;
@@ -116,6 +304,7 @@ export function resolveMaxAccount(params: {
   let accountConfig: MaxAccountConfig;
   let token = '';
   let tokenSource: ResolvedMaxAccount['tokenSource'] = 'none';
+  const secretErrors: NonNullable<ResolvedMaxAccount['secretErrors']> = {};
 
   if (accountId === DEFAULT_ACCOUNT_ID) {
     // Default account: top-level config
@@ -134,53 +323,94 @@ export function resolveMaxAccount(params: {
       webhookSecret: section.webhookSecret as string | undefined,
       webhookSecretFile: section.webhookSecretFile as string | undefined,
       webhookPath: section.webhookPath as string | undefined,
+      webhookQueue: section.webhookQueue as MaxAccountConfig['webhookQueue'],
+      maxEventAgeMinutes: section.maxEventAgeMinutes as number | undefined,
+      logMessagePreview: section.logMessagePreview as boolean | undefined,
       mediaMaxMb: section.mediaMaxMb as number | undefined,
       streamMode: section.streamMode as MaxAccountConfig['streamMode'],
       markSeen: section.markSeen as boolean | undefined,
+      actionScope: section.actionScope as MaxAccountConfig['actionScope'],
+      notify: section.notify as boolean | undefined,
+      disableLinkPreview: section.disableLinkPreview as boolean | undefined,
+      mediaMaxCount: section.mediaMaxCount as number | undefined,
+      apiBaseUrl: section.apiBaseUrl as string | undefined,
+      httpProxy: section.httpProxy as string | undefined,
+      streaming: section.streaming as MaxAccountConfig['streaming'],
+      mentionPatterns: section.mentionPatterns as MaxAccountConfig['mentionPatterns'],
+      actions: section.actions as MaxAccountConfig['actions'],
     };
 
-    if (accountConfig.botToken?.trim()) {
-      token = accountConfig.botToken.trim();
+    const botToken = readSecretOption(cfg, section.botToken, 'channels.max.botToken');
+    if (botToken.value) {
+      token = botToken.value;
       tokenSource = 'config';
+    } else if (botToken.error) {
+      tokenSource = 'config';
+      secretErrors.botToken = botToken.error;
     } else if (accountConfig.tokenFile?.trim()) {
       token = readTokenFile(accountConfig.tokenFile);
       tokenSource = token ? 'file' : 'none';
     }
-    if (!token && process.env.MAX_BOT_TOKEN?.trim()) {
+    if (!token && !botToken.error && process.env.MAX_BOT_TOKEN?.trim()) {
       token = process.env.MAX_BOT_TOKEN.trim();
       tokenSource = 'env';
     }
   } else {
-    // Named account
+    // Named account: the account's own values over the channel-level ones
+    // (SDK mergeAccountConfig, as core channels do), minus the per-bot keys.
+    // A channel switched off switches off every account.
     const raw = accounts?.[accountId] ?? {};
     accountConfig = {
-      enabled: raw.enabled !== false,
-      botToken: raw.botToken as string | undefined,
-      tokenFile: raw.tokenFile as string | undefined,
-      name: raw.name as string | undefined,
-      dmPolicy: raw.dmPolicy as string | undefined,
-      allowFrom: raw.allowFrom as Array<string | number> | undefined,
-      groups: raw.groups as MaxAccountConfig['groups'],
-      groupPolicy: raw.groupPolicy as string | undefined,
-      groupAllowFrom: raw.groupAllowFrom as Array<string | number> | undefined,
-      transport: raw.transport as MaxAccountConfig['transport'],
-      webhookUrl: raw.webhookUrl as string | undefined,
-      webhookSecret: raw.webhookSecret as string | undefined,
-      webhookSecretFile: raw.webhookSecretFile as string | undefined,
-      webhookPath: raw.webhookPath as string | undefined,
-      mediaMaxMb: raw.mediaMaxMb as number | undefined,
-      streamMode: raw.streamMode as MaxAccountConfig['streamMode'],
-      markSeen: raw.markSeen as boolean | undefined,
-    };
+      ...mergeAccountConfig<Record<string, unknown>>({
+        channelConfig: section,
+        accountConfig: raw,
+        omitKeys: [...MAX_ACCOUNT_OWN_KEYS],
+      }),
+      enabled: section.enabled !== false && raw.enabled !== false,
+    } as MaxAccountConfig;
 
-    if (accountConfig.botToken?.trim()) {
-      token = accountConfig.botToken.trim();
+    const botToken = readSecretOption(
+      cfg,
+      raw.botToken,
+      `${maxAccountConfigPath(accountId)}.botToken`,
+    );
+    if (botToken.value) {
+      token = botToken.value;
+      tokenSource = 'config';
+    } else if (botToken.error) {
       tokenSource = 'config';
+      secretErrors.botToken = botToken.error;
     } else if (accountConfig.tokenFile?.trim()) {
       token = readTokenFile(accountConfig.tokenFile);
       tokenSource = token ? 'file' : 'none';
     }
   }
+  // From here on a SecretRef option holds its value, or is absent.
+  const setResolved = (key: MaxSecretField, value: string | undefined) => {
+    if (!(key in accountConfig)) return;
+    if (value === undefined) delete accountConfig[key];
+    else accountConfig[key] = value;
+  };
+  setResolved('botToken', tokenSource === 'config' && token ? token : undefined);
+
+  // The webhook secret is per-bot; a named account's proxy may be inherited.
+  const webhookSecret = readSecretOption(
+    cfg,
+    accountConfig.webhookSecret,
+    `${maxAccountConfigPath(accountId)}.webhookSecret`,
+  );
+  setResolved('webhookSecret', webhookSecret.value);
+  if (webhookSecret.error) secretErrors.webhookSecret = webhookSecret.error;
+  const ownProxy =
+    accountId === DEFAULT_ACCOUNT_ID || Object.hasOwn(accounts?.[accountId] ?? {}, 'httpProxy');
+  const httpProxy = readSecretOption(
+    cfg,
+    accountConfig.httpProxy,
+    `${ownProxy ? maxAccountConfigPath(accountId) : 'channels.max'}.httpProxy`,
+  );
+  // "" still turns an inherited proxy off.
+  setResolved('httpProxy', httpProxy.value ?? (accountConfig.httpProxy === '' ? '' : undefined));
+  if (httpProxy.error) secretErrors.httpProxy = httpProxy.error;
 
   return {
     accountId,
@@ -188,6 +418,11 @@ export function resolveMaxAccount(params: {
     enabled: accountConfig.enabled ?? true,
     token,
     tokenSource,
+    tokenStatus: token ? 'available' : secretErrors.botToken ? 'configured_unavailable' : 'missing',
+    ...(Object.keys(secretErrors).length > 0 ? { secretErrors } : {}),
+    ...(token || secretErrors.botToken
+      ? {}
+      : { stateReason: missingTokenReason(accountId, accountConfig.tokenFile) }),
     config: accountConfig,
   };
 }