@aspalagin/openclaw-max 0.7.2 → 0.8.0

package/src/stream-draft.ts

@@ -1,13 +1,21 @@
 /**
  * Edit streaming (streamMode "partial"): the first partial reply is sent as a
  * message, later partials edit it (throttled), and the final answer replaces
- * the draft together with its inline keyboard.
+ * the draft together with its inline keyboard. The draft holds one MAX
+ * message: a longer final answer is split by the reply delivery, which puts
+ * the first chunk into the draft and sends the rest as new messages.
  */
 
 import type { ChannelLogSink } from 'openclaw/plugin-sdk/channel-contract';
 
 import type { ResolvedMaxAccount } from './accounts.js';
-import { editMaxMessage, type MaxSendButton, sendMaxMessage } from './send.js';
+import {
+  deleteMaxMessage,
+  editMaxMessage,
+  type MaxSendButton,
+  resolveMaxSendFlags,
+  sendMaxMessage,
+} from './send.js';
 
 const DRAFT_THROTTLE_MS = 1200;
 const DRAFT_MAX_CHARS = 4000;
@@ -16,12 +24,28 @@ const DRAFT_MIN_CHARS = 30; // Don't send until we have enough text
 export interface MaxDraftStream {
   /** Mid of the draft message once the first partial was sent. */
   readonly messageId: string | null;
+  /** The draft carries a final text (finalize succeeded). */
+  readonly finalized: boolean;
   /** Show a partial reply (throttled; stops on errors or past 4000 chars). */
   update(text: string): Promise<void>;
-  /** Replace the draft with the final text; buttons go onto the same edit. */
-  finalize(text: string, buttons: MaxSendButton[][] | undefined): Promise<void>;
+  /**
+   * Replace the draft with the final text (at most one MAX message); buttons
+   * go onto the same edit. Resolves false when MAX refused the edit.
+   */
+  finalize(text: string, buttons: MaxSendButton[][] | undefined): Promise<boolean>;
+  /**
+   * Delete the draft and stop streaming (its final edit was refused, or the
+   * reply went as voice only); resolves false when that fails too.
+   */
+  discard(): Promise<boolean>;
   /** Cancel a pending update and stop streaming. */
   clear(): Promise<void>;
+  /**
+   * The final answer is coming: stop streaming and wait for a send or edit in
+   * flight, so `messageId` is settled (a draft still being sent is not left
+   * behind as a second message).
+   */
+  settle(): Promise<void>;
 }
 
 /** Draft stream for edit-streaming (like Telegram's partial reply approach). */
@@ -38,6 +62,19 @@ export function createMaxDraftStream(params: {
   let draftLastEditAt = 0;
   let draftTimer: ReturnType<typeof setTimeout> | null = null;
   let draftStopped = false;
+  let draftFinalized = false;
+  // Sends and edits run one at a time: a deferred update or the final never
+  // races the first send (which would leave a second, orphaned draft).
+  let inflight: Promise<void> = Promise.resolve();
+
+  const stop = async (): Promise<void> => {
+    if (draftTimer) {
+      clearTimeout(draftTimer);
+      draftTimer = null;
+    }
+    draftStopped = true;
+    await inflight;
+  };
 
   const draftUpdate = async (text: string) => {
     if (draftStopped || !text) return;
@@ -68,58 +105,82 @@ export function createMaxDraftStream(params: {
     draftLastText = trimmed;
     draftLastEditAt = now;
 
-    try {
-      if (!draftMid) {
-        // First chunk — send new message
-        const res = await sendMaxMessage(chatId, trimmed, {
-          token: account.token,
-          replyToMessageId: params.replyToId,
-          format: 'markdown',
-        });
-        draftMid = res.messageId || null;
-        statusSink?.({ lastOutboundAt: Date.now() });
-      } else {
-        // Edit existing message
-        await editMaxMessage(draftMid, trimmed, {
-          token: account.token,
-          format: 'markdown',
-        });
+    const run = inflight.then(async () => {
+      // Stopped meanwhile (the final answer took over).
+      if (draftStopped) return;
+      try {
+        if (!draftMid) {
+          // First chunk — send new message
+          // The draft is the message the user is notified about: account defaults apply.
+          const res = await sendMaxMessage(chatId, trimmed, {
+            token: account.token,
+            replyToMessageId: params.replyToId,
+            format: 'markdown',
+            ...resolveMaxSendFlags(account.config),
+          });
+          draftMid = res.messageId || null;
+          statusSink?.({ lastOutboundAt: Date.now() });
+        } else {
+          // Edit existing message
+          await editMaxMessage(draftMid, trimmed, {
+            token: account.token,
+            format: 'markdown',
+          });
+        }
+      } catch (err) {
+        draftStopped = true;
+        log?.debug?.(`[${account.accountId}] MAX draft stream failed: ${String(err)}`);
       }
-    } catch (err) {
-      draftStopped = true;
-      log?.debug?.(`[${account.accountId}] MAX draft stream failed: ${String(err)}`);
-    }
+    });
+    inflight = run;
+    await run;
   };
 
   return {
     get messageId() {
       return draftMid;
     },
+    get finalized() {
+      return draftFinalized;
+    },
     update: draftUpdate,
     finalize: async (finalText, buttons) => {
       // Final delivery replaces the draft message with final text. The
       // keyboard (presentation buttons) goes onto the same edit, otherwise
       // the final answer would lose its buttons.
-      if (draftMid && (finalText !== draftLastText || buttons?.length)) {
-        try {
-          await editMaxMessage(draftMid, finalText, {
-            token: account.token,
-            format: 'markdown',
-            buttons,
-          });
-          draftLastText = finalText;
-        } catch {
-          /* best effort */
-        }
+      await stop();
+      if (!draftMid) return false;
+      if (finalText === draftLastText && !buttons?.length) {
+        draftFinalized = true;
+        return true;
+      }
+      try {
+        await editMaxMessage(draftMid, finalText, {
+          token: account.token,
+          format: 'markdown',
+          buttons,
+        });
+        draftLastText = finalText;
+        draftFinalized = true;
+        return true;
+      } catch (err) {
+        log?.warn(`[${account.accountId}] MAX draft final edit failed: ${String(err)}`);
+        return false;
       }
-      draftStopped = true;
     },
-    clear: async () => {
-      if (draftTimer) {
-        clearTimeout(draftTimer);
-        draftTimer = null;
+    discard: async () => {
+      await stop();
+      if (!draftMid) return true;
+      try {
+        await deleteMaxMessage(draftMid, { token: account.token });
+        draftMid = null;
+        return true;
+      } catch (err) {
+        log?.warn(`[${account.accountId}] MAX draft delete failed: ${String(err)}`);
+        return false;
       }
-      draftStopped = true;
     },
+    clear: stop,
+    settle: stop,
   };
 }

package/src/turn-adoption.ts

@@ -0,0 +1,33 @@
+/**
+ * Hand-off between a journaled webhook update and core's own restart recovery.
+ *
+ * Core records a recovery claim when it adopts an agent turn and resumes that
+ * turn after a crash by itself. The journal row of the update must therefore
+ * be completed at adoption, not only when the dispatch returns: replaying it
+ * after a crash mid-turn would run the turn twice (SDK durable ingress rule:
+ * "mark the event complete at dispatch adoption"). The webhook queue and the
+ * polling loop run each journaled dispatch with its completion callback (for
+ * polling: remembering the dedupe key); the reply dispatch passes
+ * it on as the public `turnAdoptionLifecycle` reply option. Without `admission`
+ * or `ownerKey` core groups queued follow-ups exactly as without a lifecycle.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const adoption = new AsyncLocalStorage<() => Promise<void>>();
+
+/** Run a dispatch whose agent turn, once adopted by core, calls `onAdopted`. */
+export function runWithMaxTurnAdoption<T>(
+  onAdopted: () => Promise<void>,
+  dispatch: () => Promise<T>,
+): Promise<T> {
+  return adoption.run(onAdopted, dispatch);
+}
+
+/** Reply options fragment carrying the current update's adoption callback, if any. */
+export function maxTurnAdoptionReplyOptions(): {
+  turnAdoptionLifecycle?: { onAdopted: () => Promise<void> };
+} {
+  const onAdopted = adoption.getStore();
+  return onAdopted ? { turnAdoptionLifecycle: { onAdopted } } : {};
+}

package/src/types.ts

@@ -75,11 +75,16 @@ export interface MaxAttachment {
   [key: string]: unknown;
 }
 
+/**
+ * LinkedMessage (schema.yaml): the forwarded or replied-to message. `message`
+ * is a MessageBody (mid, text, attachments, markup), not a full Message;
+ * `sender` is null for posts made on behalf of a channel.
+ */
 export interface MaxLinkedMessage {
   type: 'forward' | 'reply';
-  sender?: MaxUser;
+  sender?: MaxUser | null;
   chat_id?: number;
-  message?: MaxMessage;
+  message?: MaxMessageBody | null;
 }
 
 export interface MaxUpdatesResponse {
@@ -224,7 +229,8 @@ export interface MaxMessage {
   recipient: MaxRecipient;
   timestamp: number;
   link?: MaxLinkedMessage | null;
-  body: MaxMessageBody;
+  /** Null when the message consists only of a forward (content in link.message). */
+  body: MaxMessageBody | null;
   stat?: { views?: number } | null;
   url?: string | null;
 }

package/src/typing.ts

@@ -0,0 +1,77 @@
+/**
+ * MAX typing indicator ("typing_on") on the SDK typing lifecycle.
+ *
+ * MAX shows the indicator for a few seconds and has no explicit stop action,
+ * so a long turn needs periodic refreshes. The shared SDK keepalive owns the
+ * refresh loop, the failure circuit breaker and the safety TTL; core stops it
+ * when the run completes, fails or is aborted.
+ */
+
+import { createTypingCallbacks } from 'openclaw/plugin-sdk/channel-outbound';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+
+import { resolveMaxAccount } from './accounts.js';
+import { MaxApi } from './api.js';
+import { resolveMaxTarget } from './send.js';
+
+/** Refresh period: shorter than the indicator lifetime on MAX clients. */
+export const MAX_TYPING_KEEPALIVE_MS = 4_000;
+
+/** Deadline for one typing request; a slow one is dropped, not retried. */
+const MAX_TYPING_TIMEOUT_MS = 5_000;
+
+/**
+ * One typing_on request. Best effort: a single attempt with a short deadline,
+ * since a retried indicator could land after the reply it announced. The
+ * actions endpoint is not a message send, so the per-chat send limiter does
+ * not apply; the keepalive period keeps it far below 2 requests per second.
+ */
+export async function sendMaxTypingAction(
+  api: MaxApi,
+  chatId: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  await api.sendAction(chatId, 'typing_on', {
+    retryAttempts: 0,
+    timeoutMs: MAX_TYPING_TIMEOUT_MS,
+    ...(signal ? { signal } : {}),
+  });
+}
+
+/** Typing callbacks for one inbound turn in `chatId`; failures are only logged. */
+export function createMaxTypingCallbacks(params: {
+  api: MaxApi;
+  chatId: number;
+  onError: (err: unknown) => void;
+}): ReturnType<typeof createTypingCallbacks> {
+  return createTypingCallbacks({
+    start: () => sendMaxTypingAction(params.api, params.chatId),
+    onStartError: params.onError,
+    keepaliveIntervalMs: MAX_TYPING_KEEPALIVE_MS,
+  });
+}
+
+/**
+ * heartbeat.sendTyping / sendTypingGuarded: core wraps them in the same
+ * keepalive lifecycle (heartbeat runs; gateway runs and task progress use the
+ * guarded variant with a cancellation signal and a send-authorization check). Only chat targets can show typing (the actions endpoint takes
+ * a chat id); user:<id> targets and accounts without a token are skipped.
+ */
+export async function sendMaxHeartbeatTyping(params: {
+  cfg: OpenClawConfig;
+  to: string;
+  accountId?: string | null;
+  /** Guarded variant: cancellation of the owning run. */
+  signal?: AbortSignal;
+  /** Guarded variant: throws when the run may no longer send to the platform. */
+  assertPlatformSendAuthorized?: () => void;
+}): Promise<void> {
+  const account = resolveMaxAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.token) return;
+  const api = new MaxApi({ token: account.token });
+  const target = await resolveMaxTarget(api, params.to);
+  if (!('chat_id' in target) || params.signal?.aborted) return;
+  // Recheck right before the physical send: the owner may have ended meanwhile.
+  params.assertPlatformSendAuthorized?.();
+  await sendMaxTypingAction(api, target.chat_id, params.signal);
+}

package/src/update-journal.ts

@@ -0,0 +1,302 @@
+/**
+ * Durable journal of MAX updates: accepted webhook updates survive a gateway
+ * restart or crash, and completion tombstones reject a redelivered update
+ * across restarts (webhook and polling).
+ *
+ * Why a plugin-owned journal: the SDK's durable ingress
+ * (createChannelIngressMonitor over runtime.state.openChannelIngressQueue) is
+ * refused to plugins that are neither bundled nor trusted official installs
+ * (PluginTrustRefusalError), and this plugin is neither. The journal follows
+ * the same contract: append before the webhook ack, one row per event,
+ * completion tombstones for replay dedupe, bounded retention.
+ *
+ * Layout: <stateDir>/max/inbox-<account>/ (0700)
+ *   u-<seq>.json    one pending update (0600), deleted once handled
+ *   completed.json  dedupe keys of handled updates with their completion time
+ *
+ * Update bodies are conversation content: they never reach the log.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { readJsonFileWithFallback, writeJsonFileAtomically } from 'openclaw/plugin-sdk/json-store';
+import { resolveStateDir } from 'openclaw/plugin-sdk/state-paths';
+
+import type { MaxUpdate } from './api.js';
+
+/** How long a handled update's key rejects a redelivery (MAX retries within 8 h). */
+export const MAX_JOURNAL_COMPLETED_TTL_MS = 24 * 60 * 60 * 1000;
+/** Most dedupe keys kept; the oldest go first. */
+export const MAX_JOURNAL_COMPLETED_MAX_ENTRIES = 5000;
+/** Unknown files (e.g. a temp file of a write cut by a crash) older than this are removed. */
+const STRAY_FILE_MIN_AGE_MS = 60_000;
+
+const ENTRY_FILE = /^u-(\d{13}-\d{6})\.json$/;
+const COMPLETED_FILE = 'completed.json';
+
+export type MaxJournalEntry = {
+  v: 1;
+  seq: string;
+  receivedAt: number;
+  key?: string;
+  update: MaxUpdate;
+};
+
+type CompletedFile = { v: 1; keys: Record<string, number> };
+
+export function resolveMaxJournalDir(accountId: string): string {
+  const safeId = accountId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(resolveStateDir(), 'max', `inbox-${safeId}`);
+}
+
+export type MaxUpdateJournalOptions = {
+  accountId: string;
+  /** Default: resolveMaxJournalDir(accountId). */
+  dir?: string;
+  now?: () => number;
+  completedTtlMs?: number;
+  completedMaxEntries?: number;
+  warn?: (message: string) => void;
+};
+
+/** One journal per directory in a process: overlapping account tasks share ownership. */
+const openJournals = new Map<string, MaxUpdateJournal>();
+
+/**
+ * Open (or reuse) the journal of an account. Rejects when the directory cannot
+ * be created or written; callers then fall back to the in-memory queue.
+ */
+export async function openMaxUpdateJournal(
+  options: MaxUpdateJournalOptions,
+): Promise<MaxUpdateJournal> {
+  const dir = options.dir ?? resolveMaxJournalDir(options.accountId);
+  const existing = openJournals.get(dir);
+  if (existing) {
+    if (options.warn) existing.warn = options.warn;
+    return existing;
+  }
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  await fs.chmod(dir, 0o700);
+  await fs.access(dir, fs.constants.W_OK);
+  const journal = new MaxUpdateJournal(dir, options);
+  await journal.loadCompleted();
+  const raced = openJournals.get(dir);
+  if (raced) return raced;
+  openJournals.set(dir, journal);
+  return journal;
+}
+
+export class MaxUpdateJournal {
+  warn?: (message: string) => void;
+  private readonly now: () => number;
+  private readonly completedTtlMs: number;
+  private readonly completedMaxEntries: number;
+  /** Dedupe key → completion time, oldest first. */
+  private readonly completed = new Map<string, number>();
+  /** Entries this process holds (queued or dispatching): recovery skips them. */
+  private readonly owned = new Set<string>();
+  /** Keys of entries still on disk. */
+  private readonly pendingKeys = new Set<string>();
+  private lastSeqMs = 0;
+  private seqCounter = 0;
+  private scheduledWrite: Promise<void> | undefined;
+  private lastWrite: Promise<void> = Promise.resolve();
+
+  constructor(
+    readonly dir: string,
+    options: MaxUpdateJournalOptions,
+  ) {
+    this.warn = options.warn;
+    this.now = options.now ?? Date.now;
+    this.completedTtlMs = options.completedTtlMs ?? MAX_JOURNAL_COMPLETED_TTL_MS;
+    this.completedMaxEntries = options.completedMaxEntries ?? MAX_JOURNAL_COMPLETED_MAX_ENTRIES;
+  }
+
+  /** @internal */
+  async loadCompleted(): Promise<void> {
+    const file = path.join(this.dir, COMPLETED_FILE);
+    const { value, exists } = await readJsonFileWithFallback<CompletedFile | null>(file, null);
+    const keys = value && typeof value === 'object' ? value.keys : undefined;
+    if (!keys || typeof keys !== 'object' || Array.isArray(keys)) {
+      if (exists)
+        this.warn?.(`MAX journal ${this.dir}: unreadable ${COMPLETED_FILE}, starting empty`);
+      return;
+    }
+    const entries = Object.entries(keys)
+      .filter((entry): entry is [string, number] => typeof entry[1] === 'number')
+      .sort((a, b) => a[1] - b[1]);
+    for (const [key, at] of entries) this.completed.set(key, at);
+    this.pruneCompleted();
+  }
+
+  /** True when the key belongs to a pending update or was handled within the TTL. */
+  isDuplicate(key: string): boolean {
+    return this.pendingKeys.has(key) || this.hasCompleted(key);
+  }
+
+  hasCompleted(key: string): boolean {
+    const at = this.completed.get(key);
+    return at !== undefined && this.now() - at < this.completedTtlMs;
+  }
+
+  /** Durably record an accepted update; resolves once it is on disk. */
+  async append(update: MaxUpdate, key: string | undefined): Promise<MaxJournalEntry> {
+    const receivedAt = this.now();
+    const entry: MaxJournalEntry = {
+      v: 1,
+      seq: this.nextSeq(receivedAt),
+      receivedAt,
+      ...(key ? { key } : {}),
+      update,
+    };
+    // Owned before the file exists, so a concurrent recovery never takes it.
+    this.owned.add(entry.seq);
+    if (key) this.pendingKeys.add(key);
+    try {
+      await writeJsonFileAtomically(this.entryPath(entry.seq), entry);
+    } catch (err) {
+      this.owned.delete(entry.seq);
+      if (key) this.pendingKeys.delete(key);
+      await fs.rm(this.entryPath(entry.seq), { force: true }).catch(() => undefined);
+      throw err;
+    }
+    return entry;
+  }
+
+  /**
+   * Entries on disk that this process does not hold (left by an earlier
+   * process), oldest first. They become owned. Unreadable entries are deleted
+   * and counted.
+   */
+  async readPending(): Promise<{ entries: MaxJournalEntry[]; unreadable: number }> {
+    const names = await fs.readdir(this.dir);
+    const entries: MaxJournalEntry[] = [];
+    let unreadable = 0;
+    for (const name of names.sort()) {
+      const match = ENTRY_FILE.exec(name);
+      if (!match) {
+        await this.removeStray(name);
+        continue;
+      }
+      const seq = match[1] as string;
+      if (this.owned.has(seq)) continue;
+      const file = this.entryPath(seq);
+      const { value } = await readJsonFileWithFallback<unknown>(file, null);
+      if (!isJournalEntry(value, seq)) {
+        unreadable += 1;
+        await fs.rm(file, { force: true }).catch(() => undefined);
+        continue;
+      }
+      this.owned.add(seq);
+      if (value.key) this.pendingKeys.add(value.key);
+      entries.push(value);
+    }
+    return { entries, unreadable };
+  }
+
+  /**
+   * The update was handled (or deliberately skipped): remember its key, then
+   * delete the entry. A failed tombstone write is logged, the entry is still
+   * deleted — replaying a handled update on every start would be worse.
+   */
+  async complete(entry: MaxJournalEntry): Promise<void> {
+    if (entry.key) await this.remember(entry.key);
+    try {
+      await fs.rm(this.entryPath(entry.seq), { force: true });
+    } catch (err) {
+      this.warn?.(`MAX journal: could not delete handled entry ${entry.seq}: ${errorCode(err)}`);
+    }
+    this.owned.delete(entry.seq);
+    if (entry.key) this.pendingKeys.delete(entry.key);
+  }
+
+  /** Stop holding an entry without handling it: the next recovery takes it. */
+  release(entry: MaxJournalEntry): void {
+    this.owned.delete(entry.seq);
+  }
+
+  /** Record a handled update's key (polling uses this without an entry). */
+  async remember(key: string): Promise<void> {
+    this.completed.delete(key);
+    this.completed.set(key, this.now());
+    this.pruneCompleted();
+    try {
+      await this.saveCompleted();
+    } catch (err) {
+      this.warn?.(`MAX journal: could not save ${COMPLETED_FILE}: ${errorCode(err)}`);
+    }
+  }
+
+  private pruneCompleted(): void {
+    const cutoff = this.now() - this.completedTtlMs;
+    for (const [key, at] of this.completed) {
+      if (at > cutoff && this.completed.size <= this.completedMaxEntries) break;
+      this.completed.delete(key);
+    }
+  }
+
+  /** Coalesced, serialized writes: a caller resolves once a write with its change is done. */
+  private saveCompleted(): Promise<void> {
+    if (this.scheduledWrite) return this.scheduledWrite;
+    const write = this.lastWrite
+      .catch(() => undefined)
+      .then(async () => {
+        this.scheduledWrite = undefined;
+        const file: CompletedFile = { v: 1, keys: Object.fromEntries(this.completed) };
+        await writeJsonFileAtomically(path.join(this.dir, COMPLETED_FILE), file);
+      });
+    this.scheduledWrite = write;
+    this.lastWrite = write;
+    return write;
+  }
+
+  private async removeStray(name: string): Promise<void> {
+    if (name === COMPLETED_FILE) return;
+    const file = path.join(this.dir, name);
+    try {
+      const stat = await fs.lstat(file);
+      if (stat.isFile() && this.now() - stat.mtimeMs > STRAY_FILE_MIN_AGE_MS) {
+        await fs.rm(file, { force: true });
+      }
+    } catch {
+      // Gone meanwhile or not ours to judge: leave it.
+    }
+  }
+
+  private nextSeq(at: number): string {
+    const ms = Math.max(at, this.lastSeqMs);
+    this.seqCounter = ms === this.lastSeqMs ? this.seqCounter + 1 : 0;
+    this.lastSeqMs = ms;
+    return `${String(ms).padStart(13, '0')}-${String(this.seqCounter).padStart(6, '0')}`;
+  }
+
+  private entryPath(seq: string): string {
+    return path.join(this.dir, `u-${seq}.json`);
+  }
+}
+
+function isJournalEntry(value: unknown, seq: string): value is MaxJournalEntry {
+  if (!value || typeof value !== 'object') return false;
+  const entry = value as Partial<MaxJournalEntry>;
+  return (
+    entry.v === 1 &&
+    entry.seq === seq &&
+    typeof entry.receivedAt === 'number' &&
+    (entry.key === undefined || typeof entry.key === 'string') &&
+    !!entry.update &&
+    typeof entry.update === 'object' &&
+    typeof (entry.update as { update_type?: unknown }).update_type === 'string'
+  );
+}
+
+/** Error code only: messages of fs errors carry paths, never needed in logs here. */
+function errorCode(err: unknown): string {
+  const code = (err as { code?: unknown })?.code;
+  return typeof code === 'string' ? code : String(err);
+}
+
+/** @internal test helper: forget cached journals. */
+export function resetMaxUpdateJournalsForTest(): void {
+  openJournals.clear();
+}