@clawling/clawchat-plugin-openclaw 2026.5.13-dev.0 → 2026.5.13-dev.2

package/src/protocol-types.ts

@@ -111,7 +111,9 @@ export interface TextFragment {
 
 export interface MentionFragment {
   kind: "mention";
-  user_id: string;
+  // §10.1/§10.2: both fields are optional on the wire — a server-emitted
+  // mention may carry only `display` with no resolvable `user_id`.
+  user_id?: string;
   display?: string;
 }
 
@@ -204,8 +206,12 @@ export interface MessageAckPayload {
 }
 
 export interface MessageErrorPayload {
+  // §14.3 negative-ack on the send path.
+  message_id?: string;
   code: string;
-  message: string;
+  /** Human-readable hint; omitted by the server when empty. */
+  reason?: string;
+  rejected_at?: number;
 }
 
 export interface ChatMetadataInvalidatedPayload {

package/src/refresh-manager.ts

@@ -0,0 +1,371 @@
+import {
+  authRefresh,
+  decodeJwtExp,
+  type AuthRefreshResult,
+} from "./api-client.ts";
+
+/**
+ * §A–§D — ClawChat token refresh + auto-logout orchestration for the OpenClaw
+ * plugin.
+ *
+ * The manager is the single owner of:
+ *  - single-flight dedupe (§A.3): concurrent callers (proactive timer, reactive
+ *    REST 401, reactive WS hello-fail) await one in-flight refresh;
+ *  - the rejected-token latch (§A.3): never re-attempt for the same access token
+ *    until it actually changes;
+ *  - the minimum interval (§A.3): a reconnect storm cannot become a refresh storm;
+ *  - the proactive `setTimeout` timer (§A.1), armed from the live token's `exp`;
+ *  - the persist→swap ordering (§0): the rotated pair is persisted to BOTH stores
+ *    BEFORE the in-memory token is swapped, then the WS is reconnected (§D).
+ *
+ * It is deliberately decoupled from the runtime via a small port object so it is
+ * unit-testable without a live WS / config / SQLite.
+ */
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+
+/** §A.3 — floor between refresh attempts of the same token. */
+export const MIN_REFRESH_INTERVAL_MS = 30_000;
+/** §A.1 — proactive jitter (±5min). */
+export const PROACTIVE_JITTER_MS = 5 * MINUTE_MS;
+/** §A.0 — fallback access-token TTL when `exp` is unparseable. */
+export const ACCESS_TOKEN_TTL_MS = 24 * HOUR_MS;
+
+/** Opaque timer handle — `setTimeout` returns a `Timeout` in node, a number in others. */
+export type TimerHandle = ReturnType<typeof setTimeout> | number;
+
+export type RefreshOutcome =
+  | { kind: "success"; accessToken: string; refreshToken: string }
+  | { kind: "permanent"; code: number; message: string }
+  | { kind: "transient"; message: string }
+  // deduped onto an already in-flight refresh, or skipped by a latch/min-interval.
+  | { kind: "skipped"; reason: "in-flight" | "rejected-latch" | "min-interval" | "no-refresh-token" };
+
+export interface RefreshManagerPorts {
+  /** Server base URL for `POST /v1/auth/refresh`. */
+  baseUrl: string;
+  /** Connect-time device id (§E) sent as `X-Device-Id`. */
+  deviceId: string;
+  /** Current in-memory access token (read live so swaps are observed). */
+  getAccessToken: () => string;
+  /** Current in-memory refresh token, or `null`/empty when absent. */
+  getRefreshToken: () => string | null;
+  /**
+   * §0 — persist the rotated pair to BOTH config and SQLite. MUST resolve only
+   * after both writes succeed; the manager swaps the in-memory token only after
+   * this resolves.
+   */
+  persistRotatedTokens: (tokens: { accessToken: string; refreshToken: string }) => Promise<void>;
+  /** Swap the in-memory access+refresh token AFTER persistence (§0). */
+  swapInMemoryTokens: (tokens: { accessToken: string; refreshToken: string }) => void;
+  /** §C — auto-logout: clear creds in both stores, flip not-configured, notify. */
+  onPermanentFailure: (info: { code: number; message: string }) => Promise<void> | void;
+  /**
+   * §A.1/§D — invoked AFTER a successful PROACTIVE-timer refresh has persisted +
+   * swapped the in-memory token, so the runtime can perform the §D close-then-
+   * reconnect (a token only enters via a fresh `connect` envelope; it cannot be
+   * hot-swapped onto a live socket). Not called for reactive refreshes, whose
+   * callers already own the reconnect.
+   */
+  onProactiveRefreshed?: (tokens: { accessToken: string; refreshToken: string }) => Promise<void> | void;
+  /** Test override for the HTTP impl. */
+  fetchImpl?: typeof fetch;
+  /** Test override for the clock. */
+  now?: () => number;
+  /** Test override for setTimeout (returns an opaque handle). */
+  setTimer?: (cb: () => void, ms: number) => TimerHandle;
+  clearTimer?: (handle: TimerHandle) => void;
+  /** Test override for jitter in [-PROACTIVE_JITTER_MS, +PROACTIVE_JITTER_MS]. */
+  jitter?: () => number;
+  log?: { debug?: (m: string) => void; info?: (m: string) => void; error?: (m: string) => void };
+}
+
+/**
+ * §A.0/§A.1 — compute the absolute epoch-ms at which to proactively refresh.
+ * `refresh_at = exp - max(30min, min(2h, 0.25 * (exp - iat)))` plus jitter.
+ * `iatMs` is the token issue time; when unknown we approximate the lifetime as
+ * the full TTL so the lead time clamps to 2h for a 24h token.
+ */
+export function computeProactiveRefreshAtMs(params: {
+  expMs: number;
+  iatMs?: number | null;
+  nowMs: number;
+  jitterMs?: number;
+}): number {
+  const lifetimeMs =
+    typeof params.iatMs === "number" && Number.isFinite(params.iatMs)
+      ? params.expMs - params.iatMs
+      : ACCESS_TOKEN_TTL_MS;
+  const lead = Math.max(30 * MINUTE_MS, Math.min(2 * HOUR_MS, 0.25 * lifetimeMs));
+  return params.expMs - lead + (params.jitterMs ?? 0);
+}
+
+/**
+ * §A.0 — derive the access token's expiry (epoch ms). Prefer the JWT `exp`;
+ * fall back to `activatedAt + 24h` when the token has no parseable `exp`.
+ */
+export function resolveAccessTokenExpiryMs(
+  token: string,
+  activatedAtMs: number | null,
+): number | null {
+  const exp = decodeJwtExp(token);
+  if (exp != null) return exp * 1000;
+  if (activatedAtMs != null) return activatedAtMs + ACCESS_TOKEN_TTL_MS;
+  return null;
+}
+
+export class RefreshManager {
+  private inFlight: Promise<RefreshOutcome> | null = null;
+  /** §A.3 — the access token a refresh was last attempted for. */
+  private rejectedToken: string | null = null;
+  /** §A.3 — epoch-ms of the last refresh attempt (any token). */
+  private lastAttemptAt = 0;
+  private proactiveTimer: TimerHandle | null = null;
+  private stopped = false;
+
+  constructor(private readonly ports: RefreshManagerPorts) {}
+
+  private now(): number {
+    return (this.ports.now ?? Date.now)();
+  }
+
+  private setTimer(cb: () => void, ms: number): TimerHandle {
+    return (this.ports.setTimer ?? setTimeout)(cb, ms);
+  }
+
+  private clearTimer(handle: TimerHandle): void {
+    (this.ports.clearTimer ?? clearTimeout)(handle as ReturnType<typeof setTimeout>);
+  }
+
+  /**
+   * §A.3 — run a single-flight refresh. Concurrent callers receive the same
+   * in-flight promise. Honors the rejected-token latch and the min-interval.
+   */
+  refresh(reason: string): Promise<RefreshOutcome> {
+    if (this.stopped) return Promise.resolve({ kind: "skipped", reason: "in-flight" });
+    if (this.inFlight) {
+      this.ports.log?.debug?.(`clawchat-plugin-openclaw refresh deduped onto in-flight (${reason})`);
+      return this.inFlight;
+    }
+    const accessToken = this.ports.getAccessToken();
+    // §A.3 rejected-token latch: don't re-attempt for an unchanged dead token.
+    if (this.rejectedToken !== null && this.rejectedToken === accessToken) {
+      this.ports.log?.debug?.(
+        `clawchat-plugin-openclaw refresh skipped rejected-latch (${reason})`,
+      );
+      return Promise.resolve({ kind: "skipped", reason: "rejected-latch" });
+    }
+    // §A.3 min-interval floor.
+    const sinceLast = this.now() - this.lastAttemptAt;
+    if (this.lastAttemptAt !== 0 && sinceLast < MIN_REFRESH_INTERVAL_MS) {
+      this.ports.log?.debug?.(
+        `clawchat-plugin-openclaw refresh skipped min-interval (${reason}) sinceLast=${sinceLast}ms`,
+      );
+      return Promise.resolve({ kind: "skipped", reason: "min-interval" });
+    }
+    const refreshToken = this.ports.getRefreshToken();
+    if (!refreshToken || !refreshToken.trim()) {
+      return Promise.resolve({ kind: "skipped", reason: "no-refresh-token" });
+    }
+
+    this.lastAttemptAt = this.now();
+    const promise = this.runRefresh(accessToken, refreshToken, reason).finally(() => {
+      this.inFlight = null;
+    });
+    this.inFlight = promise;
+    return promise;
+  }
+
+  private async runRefresh(
+    accessToken: string,
+    refreshToken: string,
+    reason: string,
+  ): Promise<RefreshOutcome> {
+    this.ports.log?.info?.(`clawchat-plugin-openclaw refresh attempt (${reason})`);
+    let result: AuthRefreshResult;
+    try {
+      result = await authRefresh(
+        { baseUrl: this.ports.baseUrl, ...(this.ports.fetchImpl ? { fetchImpl: this.ports.fetchImpl } : {}) },
+        { refreshToken, deviceId: this.ports.deviceId },
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { kind: "transient", message };
+    }
+
+    if (result.kind === "success") {
+      // §0 rotation hazard — persist FIRST, swap SECOND. If persistence REJECTS
+      // (a store/config write failed), DO NOT swap the in-memory token: a
+      // sqlite-sourced agent must not keep a now-dead refresh token in its row
+      // while running on the rotated token. Treat as transient so the WS stays
+      // in backoff with the CURRENT tokens and the next attempt retries. The
+      // server already rotated, so the next attempt may return `code:10003`
+      // (which escalates to permanent per §B) — that is the accepted hazard, not
+      // a silent brick.
+      try {
+        await this.ports.persistRotatedTokens({
+          accessToken: result.accessToken,
+          refreshToken: result.refreshToken,
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.ports.log?.error?.(
+          `clawchat-plugin-openclaw refresh persistence failed; not swapping in-memory token: ${message}`,
+        );
+        return { kind: "transient", message };
+      }
+      this.ports.swapInMemoryTokens({
+        accessToken: result.accessToken,
+        refreshToken: result.refreshToken,
+      });
+      // Clear the latch; the access token has actually changed.
+      this.rejectedToken = null;
+      this.ports.log?.info?.("clawchat-plugin-openclaw refresh success (token rotated)");
+      return { kind: "success", accessToken: result.accessToken, refreshToken: result.refreshToken };
+    }
+
+    if (result.kind === "permanent") {
+      // §A.3 — latch the dead token so reconnect storms don't re-fire refresh.
+      this.rejectedToken = accessToken;
+      this.ports.log?.error?.(
+        `clawchat-plugin-openclaw refresh permanent failure code=${result.code}: ${result.message}`,
+      );
+      await this.ports.onPermanentFailure({ code: result.code, message: result.message });
+      return { kind: "permanent", code: result.code, message: result.message };
+    }
+
+    // Transient — never auto-logout; the old refresh token is still valid.
+    this.ports.log?.info?.(
+      `clawchat-plugin-openclaw refresh transient failure: ${result.message}`,
+    );
+    return { kind: "transient", message: result.message };
+  }
+
+  /**
+   * §A.1 — (re)arm the proactive timer from the live access token's `exp`.
+   * Called when a connection becomes ready and after every successful refresh.
+   */
+  armProactiveTimer(activatedAtMs: number | null): void {
+    if (this.stopped) return;
+    this.disarmProactiveTimer();
+    const token = this.ports.getAccessToken();
+    const expMs = resolveAccessTokenExpiryMs(token, activatedAtMs);
+    if (expMs == null) {
+      this.ports.log?.debug?.("clawchat-plugin-openclaw proactive timer not armed (no expiry)");
+      return;
+    }
+    const iat = decodeJwtIat(token);
+    const jitterMs = (this.ports.jitter ?? defaultJitter)();
+    const refreshAtMs = computeProactiveRefreshAtMs({
+      expMs,
+      iatMs: iat != null ? iat * 1000 : null,
+      nowMs: this.now(),
+      jitterMs,
+    });
+    const delayMs = Math.max(0, refreshAtMs - this.now());
+    this.ports.log?.debug?.(
+      `clawchat-plugin-openclaw proactive timer armed delayMs=${delayMs}`,
+    );
+    this.proactiveTimer = this.setTimer(() => {
+      this.proactiveTimer = null;
+      void this.runProactiveRefresh();
+    }, delayMs);
+  }
+
+  /**
+   * §A.1/§D — the proactive-timer body. Runs the single-flight refresh and, on
+   * success, hands the rotated token to the runtime's `onProactiveRefreshed` port
+   * so the live WS is closed and reconnected with the new token (the in-memory
+   * swap alone does NOT reach the running socket, which captured the old token at
+   * `connect` time). Transient/skipped outcomes leave the WS untouched — the next
+   * proactive arm (or a reactive hello-fail) handles it.
+   */
+  private async runProactiveRefresh(): Promise<void> {
+    const outcome = await this.refresh("proactive-timer");
+    if (this.stopped) return;
+    if (outcome.kind !== "success") return;
+    if (this.ports.onProactiveRefreshed) {
+      try {
+        await this.ports.onProactiveRefreshed({
+          accessToken: outcome.accessToken,
+          refreshToken: outcome.refreshToken,
+        });
+      } catch (err) {
+        this.ports.log?.error?.(
+          `clawchat-plugin-openclaw proactive reconnect hook failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  disarmProactiveTimer(): void {
+    if (this.proactiveTimer != null) {
+      this.clearTimer(this.proactiveTimer);
+      this.proactiveTimer = null;
+    }
+  }
+
+  /**
+   * §A.4 — true when the stored access token is past or within the proactive
+   * margin of expiry, so the caller should refresh BEFORE the first connect.
+   */
+  isNearExpiry(activatedAtMs: number | null): boolean {
+    const token = this.ports.getAccessToken();
+    const expMs = resolveAccessTokenExpiryMs(token, activatedAtMs);
+    if (expMs == null) return false;
+    const iat = decodeJwtIat(token);
+    const refreshAtMs = computeProactiveRefreshAtMs({
+      expMs,
+      iatMs: iat != null ? iat * 1000 : null,
+      nowMs: this.now(),
+      jitterMs: 0,
+    });
+    return this.now() >= refreshAtMs;
+  }
+
+  /** Stop the manager — clears the proactive timer; no further refreshes arm. */
+  stop(): void {
+    this.stopped = true;
+    this.disarmProactiveTimer();
+  }
+
+  /** Test/inspection seam — the latched (rejected) access token, if any. */
+  getRejectedToken(): string | null {
+    return this.rejectedToken;
+  }
+
+  /**
+   * §A.3/§A.4 — export the single-flight guard state so it can be carried across
+   * a gateway re-enter (a refresh-driven reconnect builds a fresh manager; without
+   * restoring this state the rejected-token latch + min-interval would reset and
+   * the guards would not bound a cross-reconnect loop).
+   */
+  exportState(): { rejectedToken: string | null; lastAttemptAt: number } {
+    return { rejectedToken: this.rejectedToken, lastAttemptAt: this.lastAttemptAt };
+  }
+
+  /** §A.3/§A.4 — restore guard state from a prior manager (see `exportState`). */
+  restoreState(state: { rejectedToken: string | null; lastAttemptAt: number }): void {
+    this.rejectedToken = state.rejectedToken;
+    this.lastAttemptAt = state.lastAttemptAt;
+  }
+}
+
+function decodeJwtIat(token: string): number | null {
+  if (typeof token !== "string") return null;
+  const segments = token.split(".");
+  if (segments.length < 2 || !segments[1]) return null;
+  try {
+    const json = Buffer.from(segments[1], "base64url").toString("utf8");
+    const parsed = JSON.parse(json) as { iat?: unknown };
+    const iat = parsed?.iat;
+    return typeof iat === "number" && Number.isFinite(iat) ? iat : null;
+  } catch {
+    return null;
+  }
+}
+
+function defaultJitter(): number {
+  return (Math.random() * 2 - 1) * PROACTIVE_JITTER_MS;
+}

package/src/reply-dispatcher.ts

@@ -19,6 +19,7 @@ import {
 } from "./config.ts";
 import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
 import {
+  mintMessageId,
   sendOpenclawClawlingText,
   type OutboundReplyCtx,
   type SendResult,
@@ -542,8 +543,10 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     return merged;
   };
 
-  const mintStaticMessageId = () =>
-    `${account.userId}-msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  // §7.6 (binding): client-supplied message_id MUST be `msg-` + a 26-char
+  // Crockford base32 ULID. Use the shared conformant minter — do not invent a
+  // different scheme (planned msghub Phase-4 validation will reject it).
+  const mintStaticMessageId = () => mintMessageId();
 
   const emitTyping = (isTyping: boolean) => {
     if (!isTyping && !typingActive) return;