@aspalagin/openclaw-max 0.7.3 → 0.8.1

package/src/progress-draft.ts

@@ -0,0 +1,226 @@
+/**
+ * Turn status (streaming.mode "progress"): one MAX message that core's
+ * progress compositor keeps up to date while the agent works — status
+ * headline, plan, approvals and, with streaming.progress.toolProgress, a
+ * rolling tool log — and that is deleted once the final answer landed.
+ *
+ * Core owns what the status says (createChannelProgressDraftCompositor, the
+ * channels.max.streaming.progress settings) and when the preview may go away
+ * (createLivePreviewLifecycle: deleted after a delivered final, kept after
+ * an error final or a failed delivery). This module is the MAX transport:
+ * send once, then edit in place, at most one call per second
+ * (createDraftStreamLoop) — half of MAX's two edits per second per chat.
+ */
+
+import type { ChannelLogSink } from 'openclaw/plugin-sdk/channel-contract';
+import {
+  createChannelProgressDraftCompositor,
+  createDraftStreamLoop,
+  createLivePreviewLifecycle,
+} from 'openclaw/plugin-sdk/channel-outbound';
+
+import type { ResolvedMaxAccount } from './accounts.js';
+import { deleteMaxMessage, editMaxMessage, resolveMaxSendFlags, sendMaxMessage } from './send.js';
+
+/** One send or edit per second for the status message. */
+export const MAX_PROGRESS_THROTTLE_MS = 1000;
+/** MAX text limit; the compositor stays far below it (8 lines × 120 chars). */
+const MAX_PROGRESS_MAX_CHARS = 4000;
+
+type Compositor = ReturnType<typeof createChannelProgressDraftCompositor>;
+
+/** Progress callbacks of the reply dispatch (GetReplyOptions subset). */
+export interface MaxProgressReplyOptions {
+  suppressDefaultToolProgressMessages: true;
+  preserveProgressCallbackStartOrder: true;
+  onVerboseProgressVisibility: (isActive: () => boolean) => void;
+  onToolStart: (payload: Parameters<Compositor['pushToolEvent']>[0]) => Promise<boolean>;
+  onItemEvent: (payload: Parameters<Compositor['pushItemEvent']>[0]) => Promise<boolean>;
+  onPlanUpdate: (payload: {
+    phase?: string;
+    explanation?: string;
+    explanationFormat?: 'plain';
+    steps?: Parameters<Compositor['pushPlanProgress']>[0];
+  }) => Promise<boolean>;
+  onApprovalEvent: (payload: Parameters<Compositor['pushApprovalEvent']>[0]) => Promise<boolean>;
+  onAssistantMessageStart: () => boolean;
+}
+
+export interface MaxProgressDraft {
+  readonly replyOptions: MaxProgressReplyOptions;
+  /** Mid of the status message while it is shown. */
+  readonly messageId: string | undefined;
+  /**
+   * Deliver a final answer: status updates stop, `send` delivers it, and the
+   * status message is deleted once a non-error final landed. Errors of `send`
+   * propagate (the status then stays as the record of the failed turn).
+   */
+  deliverFinal(params: { isError: boolean; send: () => Promise<void> }): Promise<void>;
+  /**
+   * End of the turn: stop timers and updates; an unused status message (no
+   * final, e.g. NO_REPLY or an answer sent by the message tool) is deleted
+   * unless the turn failed.
+   */
+  close(params?: { failed?: boolean }): Promise<void>;
+}
+
+export function createMaxProgressDraft(params: {
+  account: ResolvedMaxAccount;
+  chatId: string;
+  replyToId?: string;
+  log?: ChannelLogSink;
+  statusSink?: (patch: { lastOutboundAt?: number }) => void;
+}): MaxProgressDraft {
+  const { account, chatId, log, statusSink } = params;
+  let messageId: string | undefined;
+  let stopped = false;
+  let verboseActive: () => boolean = () => false;
+
+  const sendOrEdit = async (text: string): Promise<boolean> => {
+    const body =
+      text.length > MAX_PROGRESS_MAX_CHARS ? text.slice(0, MAX_PROGRESS_MAX_CHARS) : text;
+    if (!messageId) {
+      // No status appears once the final answer is on its way.
+      if (lifecycle.finalStarted) return false;
+      // Plain text (tool names and paths carry markdown characters); no push
+      // notification for a temporary message — the final answer notifies.
+      const res = await sendMaxMessage(chatId, body, {
+        token: account.token,
+        replyToMessageId: params.replyToId,
+        ...resolveMaxSendFlags(account.config, { silent: true }),
+      });
+      messageId = res.messageId || undefined;
+      statusSink?.({ lastOutboundAt: Date.now() });
+      return Boolean(messageId);
+    }
+    await editMaxMessage(messageId, body, { token: account.token });
+    return true;
+  };
+
+  const stopOnError = (err: unknown) => {
+    // A failed status never fails the turn: stop updating and keep going.
+    stopped = true;
+    log?.debug?.(`[${account.accountId}] MAX progress status failed: ${String(err)}`);
+  };
+
+  const loop = createDraftStreamLoop<string>({
+    throttleMs: MAX_PROGRESS_THROTTLE_MS,
+    coalesceInFlight: true,
+    isStopped: () => stopped,
+    sendOrEditStreamMessage: sendOrEdit,
+    onBackgroundFlushError: stopOnError,
+  });
+
+  const stopUpdates = async () => {
+    stopped = true;
+    loop.stop();
+    await loop.waitForInFlight().catch(() => undefined);
+  };
+
+  const lifecycle = createLivePreviewLifecycle<void, string>({
+    draft: {
+      flush: () => loop.flush().catch(stopOnError),
+      id: () => messageId,
+      discardPending: stopUpdates,
+      clear: async () => {
+        if (!messageId) return true;
+        await deleteMaxMessage(messageId, { token: account.token });
+        messageId = undefined;
+        return true;
+      },
+    },
+    // Like Discord: an error final keeps the status as the record of the turn.
+    retainOnError: true,
+    cleanupUndelivered: true,
+    onFinalStarted: () => {
+      compositor.markFinalReplyStarted();
+      loop.resetPending();
+    },
+    onFinalDelivered: () => compositor.markFinalReplyDelivered(),
+    onCleanupFailure: (err) => {
+      log?.warn(`[${account.accountId}] MAX progress status delete failed: ${String(err)}`);
+    },
+  });
+
+  const compositor = createChannelProgressDraftCompositor({
+    preparedItems: true,
+    entry: account.config as Parameters<typeof createChannelProgressDraftCompositor>[0]['entry'],
+    mode: 'progress',
+    active: true,
+    seed: `${account.accountId}:${chatId}`,
+    update: async (text, options) => {
+      if (stopped) return false;
+      loop.update(text);
+      if (options.flush) await loop.flush().catch(stopOnError);
+      return !stopped;
+    },
+    // Every line was retracted: remove the message; new progress sends a new one.
+    deleteCurrent: async () => {
+      loop.resetPending();
+      await loop.waitForInFlight().catch(() => undefined);
+      const current = messageId;
+      if (!current) return;
+      messageId = undefined;
+      await deleteMaxMessage(current, { token: account.token }).catch((err: unknown) => {
+        log?.warn(`[${account.accountId}] MAX progress status delete failed: ${String(err)}`);
+      });
+    },
+  });
+
+  /** Progress may change until the final answer starts; verbose mode owns it otherwise. */
+  const canPush = () => !stopped && !lifecycle.finalStarted && !verboseActive();
+  const push = async (event: () => Promise<boolean>): Promise<boolean> => {
+    if (!canPush()) return false;
+    try {
+      return await event();
+    } catch (err) {
+      stopOnError(err);
+      return false;
+    }
+  };
+
+  return {
+    get messageId() {
+      return messageId;
+    },
+    replyOptions: {
+      suppressDefaultToolProgressMessages: true,
+      preserveProgressCallbackStartOrder: true,
+      onVerboseProgressVisibility: (isActive) => {
+        verboseActive = isActive;
+      },
+      onToolStart: (payload) => push(() => compositor.pushToolEvent(payload)),
+      onItemEvent: (payload) => push(() => compositor.pushItemEvent(payload)),
+      onPlanUpdate: (payload) =>
+        payload.phase === 'update'
+          ? push(() =>
+              compositor.pushPlanProgress(payload.steps, {
+                explanation: payload.explanation,
+                explanationFormat: payload.explanationFormat,
+              }),
+            )
+          : Promise.resolve(false),
+      onApprovalEvent: (payload) => push(() => compositor.pushApprovalEvent(payload)),
+      onAssistantMessageStart: () => {
+        compositor.beginAssistantMessage();
+        return false;
+      },
+    },
+    deliverFinal: async ({ isError, send }) => {
+      await lifecycle.deliver({
+        kind: 'final',
+        payload: undefined,
+        isError,
+        deliverNormally: async () => {
+          await send();
+          return { visibleReplySent: true };
+        },
+      });
+    },
+    close: async (options) => {
+      compositor.cancel();
+      await lifecycle.cleanup({ failed: options?.failed === true });
+      await stopUpdates();
+    },
+  };
+}

package/src/runtime.ts

@@ -13,6 +13,29 @@ export function getMaxRuntime(): PluginRuntime {
   return runtime;
 }
 
+/** The log levels plugin modules without an account log sink use. */
+export type MaxLogger = {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+let pluginLogger: { owner: PluginRuntime; logger: MaxLogger } | undefined;
+
+/**
+ * Logger for modules with no account log sink at hand (API client, send
+ * helpers): the plugin's child logger of the gateway runtime, or the console
+ * before the runtime is set (CLI, tests).
+ */
+export function getMaxLogger(): MaxLogger {
+  const logging = runtime?.logging;
+  if (!runtime || typeof logging?.getChildLogger !== 'function') return console;
+  if (pluginLogger?.owner !== runtime) {
+    pluginLogger = { owner: runtime, logger: logging.getChildLogger({ plugin: 'max' }) };
+  }
+  return pluginLogger.logger;
+}
+
 /**
  * Legacy runtime config API (OpenClaw < 2026.9.3).
  * Since 2026.9.3 `loadConfig`/`writeConfigFile` are removed from PluginRuntime;

package/src/secret-contract.ts

@@ -0,0 +1,183 @@
+/**
+ * SecretRef contract of the MAX channel. `secretTargetRegistryEntries` tells
+ * `openclaw secrets configure/apply/audit` which options may hold a SecretRef;
+ * `collectRuntimeConfigAssignments` tells the gateway which of them each
+ * account uses, so it resolves them into the runtime snapshot before the
+ * account starts and isolates an account whose ref does not resolve (owner
+ * `max:<accountId>`). Loaded from `secret-contract-api.js` before the plugin
+ * runtime: keep this module free of runtime imports.
+ */
+
+import {
+  collectSecretInputAssignment,
+  createChannelSecretTargetRegistryEntries,
+  getChannelRecord,
+  hasOwnProperty,
+  isEnabledFlag,
+  isRecord,
+  type ResolverContext,
+  type SecretDefaults,
+} from 'openclaw/plugin-sdk/channel-secret-basic-runtime';
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from 'openclaw/plugin-sdk/core';
+
+/** Options accepting a SecretRef, at the channel level and under accounts.<id>. */
+export const MAX_SECRET_FIELDS = ['botToken', 'webhookSecret', 'httpProxy'] as const;
+export type MaxSecretField = (typeof MAX_SECRET_FIELDS)[number];
+
+export const secretTargetRegistryEntries = createChannelSecretTargetRegistryEntries({
+  channelKey: 'max',
+  account: [...MAX_SECRET_FIELDS],
+  channel: [...MAX_SECRET_FIELDS],
+});
+
+interface MaxAccountEntry {
+  /** Config key under channels.max.accounts */
+  key: string;
+  accountId: string;
+  account: Record<string, unknown>;
+  enabled: boolean;
+}
+
+/** Webhook mode as resolveMaxTransport decides it (transport, else webhookUrl). */
+function usesWebhook(config: Record<string, unknown>): boolean {
+  if (config.transport === 'polling' || config.transport === 'webhook') {
+    return config.transport === 'webhook';
+  }
+  return typeof config.webhookUrl === 'string' && config.webhookUrl.trim().length > 0;
+}
+
+/**
+ * Whether an account reads the option at all: the token always, the webhook
+ * secret only in webhook mode, the proxy always. `config` holds the account's
+ * own transport/webhookUrl (both are per-bot keys, never inherited).
+ */
+function usesField(field: MaxSecretField, config: Record<string, unknown>): boolean {
+  return field === 'webhookSecret' ? usesWebhook(config) : true;
+}
+
+/** The default account exists as listMaxAccountIds decides it. */
+function hasDefaultAccount(
+  channel: Record<string, unknown>,
+  named: MaxAccountEntry[],
+  env: NodeJS.ProcessEnv,
+): boolean {
+  if (channel.botToken || channel.tokenFile || env.MAX_BOT_TOKEN) return true;
+  return named.length === 0 && channel.enabled !== false;
+}
+
+function listNamedAccounts(channel: Record<string, unknown>): MaxAccountEntry[] {
+  const accounts = channel.accounts;
+  if (!isRecord(accounts)) return [];
+  const entries: MaxAccountEntry[] = [];
+  for (const [key, account] of Object.entries(accounts)) {
+    if (!isRecord(account)) continue;
+    const accountId = normalizeAccountId(key);
+    if (accountId === DEFAULT_ACCOUNT_ID) continue;
+    entries.push({
+      key,
+      accountId,
+      account,
+      enabled: isEnabledFlag(channel) && isEnabledFlag(account),
+    });
+  }
+  return entries;
+}
+
+/**
+ * Register every SecretRef the enabled MAX accounts read. A channel-level
+ * value belongs to the default account and, for httpProxy only, to each named
+ * account that does not set its own; the other options are per-bot.
+ */
+export function collectRuntimeConfigAssignments(params: {
+  config: { channels?: Record<string, unknown> };
+  defaults?: SecretDefaults;
+  context: ResolverContext;
+}): void {
+  const channel = getChannelRecord(params.config, 'max');
+  if (!channel) return;
+  // The owner contract: every non-secret channel setting the accounts use.
+  const channelDefaults = Object.fromEntries(
+    Object.entries(channel).filter(([key]) => key !== 'accounts'),
+  );
+  const named = listNamedAccounts(channel);
+  const defaultActive =
+    isEnabledFlag(channel) && hasDefaultAccount(channel, named, params.context.env);
+
+  for (const field of MAX_SECRET_FIELDS) {
+    const consumers: Array<{ accountId: string; account: Record<string, unknown> }> = [];
+    if (defaultActive && usesField(field, channel)) {
+      consumers.push({ accountId: DEFAULT_ACCOUNT_ID, account: {} });
+    }
+    if (field === 'httpProxy') {
+      for (const entry of named) {
+        if (entry.enabled && !hasOwnProperty(entry.account, field)) consumers.push(entry);
+      }
+    }
+    const applyChannel = (value: unknown) => {
+      channel[field] = value;
+    };
+    const channelPath = `channels.max.${field}`;
+    if (consumers.length === 0) {
+      collectSecretInputAssignment({
+        value: channel[field],
+        path: channelPath,
+        expected: 'string',
+        defaults: params.defaults,
+        context: params.context,
+        active: false,
+        inactiveReason: `no enabled MAX account uses this channel-level ${field}.`,
+        apply: applyChannel,
+      });
+    }
+    const contract = { channel: channelDefaults, consumers: consumers.map((c) => c.accountId) };
+    for (const consumer of consumers) {
+      collectSecretInputAssignment({
+        value: channel[field],
+        path: channelPath,
+        expected: 'string',
+        defaults: params.defaults,
+        context: params.context,
+        owner: {
+          ownerKind: 'account',
+          ownerId: `max:${consumer.accountId}`,
+          requiredForGateway: false,
+          disposition: 'isolate',
+          contract,
+        },
+        apply: applyChannel,
+      });
+    }
+
+    for (const entry of named) {
+      if (!hasOwnProperty(entry.account, field)) continue;
+      collectSecretInputAssignment({
+        value: entry.account[field],
+        path: `channels.max.accounts.${entry.key}.${field}`,
+        expected: 'string',
+        defaults: params.defaults,
+        context: params.context,
+        active: entry.enabled && usesField(field, entry.account),
+        inactiveReason:
+          field === 'webhookSecret'
+            ? 'MAX account is disabled or does not use webhook mode.'
+            : 'MAX account is disabled.',
+        owner: {
+          ownerKind: 'account',
+          ownerId: `max:${entry.accountId}`,
+          requiredForGateway: false,
+          disposition: 'isolate',
+          contract: { channel: channelDefaults, account: entry.account },
+        },
+        apply: (value) => {
+          entry.account[field] = value;
+        },
+      });
+    }
+  }
+}
+
+/** Channel secrets adapter (ChannelPlugin.secrets) and secret-contract-api.js export. */
+export const maxChannelSecrets = {
+  secretTargetRegistryEntries,
+  collectRuntimeConfigAssignments,
+};