@clawling/clawchat-plugin-openclaw 2026.5.12-39 → 2026.5.13-dev.1

package/src/login.runtime.ts

@@ -268,6 +268,10 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
       refreshToken: normalizedResult.refresh_token || null,
       conversationId: normalizedResult.conversation?.id ?? null,
       loginMethod: "login",
+      // §E — record the exact `X-Device-Id` sent at connect (the constant
+      // `CHANNEL_ID`, see `authHeaders` in api-client.ts), so a later refresh
+      // sends the same device id the backend baked into the session.
+      deviceId: CHANNEL_ID,
     });
   } catch {
     runtime.log("clawchat-plugin-openclaw sqlite activation persistence failed; login continues.");

package/src/outbound.ts

@@ -1,3 +1,4 @@
+import { randomInt } from "node:crypto";
 import { MessageSendError, type Envelope, type Fragment, type MentionFragment, type MessageAckPayload, type MessageErrorPayload } from "./protocol-types.ts";
 import type { ClawlingChatClient } from "./ws-client.ts";
 import {
@@ -321,10 +322,15 @@ async function sendAlignedAckableEnvelope(params: {
       if (ack.trace_id !== traceId) return;
       if (ack.event === "message.error") {
         if (state === "acked" || state === "failed") return;
-        const payload = ack.payload as Partial<MessageErrorPayload>;
+        const payload = ack.payload as Partial<MessageErrorPayload> & { message?: unknown };
         const code = typeof payload.code === "string" && payload.code ? payload.code : "unknown";
-        const message = typeof payload.message === "string" && payload.message ? payload.message : "message send failed";
-        fail(new MessageSendError(traceId, code, message, ack.chat_id));
+        // §14.3: the human-readable hint is `reason` (fall back to legacy `message`).
+        const hint = typeof payload.reason === "string" && payload.reason
+          ? payload.reason
+          : typeof payload.message === "string" && payload.message
+            ? payload.message
+            : "message send failed";
+        fail(new MessageSendError(traceId, code, hint, ack.chat_id));
         return;
       }
       if (ack.event !== "message.ack") return;
@@ -491,14 +497,19 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
       && params.replyCtx.replyPreviewNickName
       && params.replyCtx.replyPreviewText,
   );
-  const messageId = params.messageId;
+  // Outbound message_id is ALWAYS present (at-least-once delivery, protocol
+  // §3.1.9): the server's inbox UNIQUE(recipient, message_id) absorbs a
+  // bounded resend of the same frame as one coalesced row. A bounded resend
+  // (non-terminal socket close → re-enqueue of the same captured wire) reuses
+  // this exact id, so a duplicate write is deduped rather than fanned out.
+  const messageId = params.messageId ?? mintMessageId();
 
   let ack: Envelope<MessageAckPayload>;
   let mode: "send" | "reply";
   if (useReply && params.replyCtx) {
     mode = "reply";
     const payload = {
-      ...(messageId ? { message_id: messageId } : {}),
+      message_id: messageId,
       message_mode: "normal",
       message: {
         body: { fragments },
@@ -532,7 +543,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
         }
       : null;
     const payload = {
-      ...(messageId ? { message_id: messageId } : {}),
+      message_id: messageId,
       message_mode: "normal",
       message: {
         body: { fragments },
@@ -548,7 +559,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
       ...(params.log ? { log: params.log } : {}),
     });
   }
-  if (messageId && ack.payload.message_id !== messageId) {
+  if (ack.payload.message_id !== messageId) {
     throw new Error(
       `ack message_id mismatch: expected ${messageId} got ${ack.payload.message_id}`,
     );
@@ -638,8 +649,35 @@ export async function sendOpenclawClawlingMedia(
 
 type OutboundClaimStore = Pick<ClawChatStore, "claimMessageOnce" | "markMessageAcknowledged">;
 
-function mintOutboundMessageId(account: ResolvedOpenclawClawlingAccount): string {
-  return `${account.userId}-msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+// Crockford base32 alphabet (ULID spec).
+const ULID_ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/**
+ * Generate a Canonical ULID: 10 chars of millisecond timestamp + 16 chars of
+ * randomness, Crockford base32, 26 chars total. Implemented locally (no extra
+ * dependency) because this repo has no ULID dep and only needs minting, not
+ * monotonic ordering or decoding.
+ */
+function ulid(now: number = Date.now()): string {
+  let time = now;
+  const out = new Array<string>(26);
+  for (let i = 9; i >= 0; i--) {
+    out[i] = ULID_ENCODING[time % 32]!;
+    time = Math.floor(time / 32);
+  }
+  for (let i = 10; i < 26; i++) {
+    out[i] = ULID_ENCODING[randomInt(0, 32)]!;
+  }
+  return out.join("");
+}
+
+/** Client-minted message id: `msg-` + ULID (protocol §7.6 format contract). */
+export function mintMessageId(): string {
+  return `msg-${ulid()}`;
+}
+
+function mintOutboundMessageId(_account: ResolvedOpenclawClawlingAccount): string {
+  return mintMessageId();
 }
 
 function resolveChannelOutboundStore(): OutboundClaimStore | null {

package/src/protocol-types.ts

@@ -13,6 +13,8 @@ export const EVENT = {
   MESSAGE_FAILED: "message.failed",
   TYPING_UPDATE: "typing.update",
   CHAT_METADATA_INVALIDATED: "chat.metadata.invalidated",
+  NOTIFY_SIGNAL: "notify.signal",
+  REPLAY_DONE: "replay.done",
   OFFLINE_BATCH: "offline.batch",
   OFFLINE_ACK: "offline.ack",
   OFFLINE_DONE: "offline.done",
@@ -78,6 +80,11 @@ export interface ConnectCapabilities {
   multi_device?: boolean;
   device_replay?: boolean;
   chat_meta_events?: boolean;
+  delivery_receipt?: boolean;
+  notify_signals?: boolean;
+  permission_events?: boolean;
+  history_sync?: boolean;
+  e2ee?: boolean;
 }
 
 export interface ConnectPayload {
@@ -104,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;
 }
 
@@ -197,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 {
@@ -207,6 +220,25 @@ export interface ChatMetadataInvalidatedPayload {
   updated_at?: number;
 }
 
+/**
+ * Reliable, inbox-coalesced system notification (§9.4). Content-free — only
+ * enough identity to dedup and to decide which REST surface to refetch. The
+ * agent plugin keeps no friend/roster cache, so this is consumed as an
+ * observability signal (see `createNotifySignalObserver`), not a cache refresh.
+ */
+export interface NotifySignalPayload {
+  /** Logical event type the client routes on, e.g. `friend.added`. */
+  type: string;
+  /** Id of the changed entity (meaning depends on `type`). */
+  entity_id: string;
+  /** Monotonic cursor (ms since epoch at mutation time). */
+  version: number;
+  /** Globally-unique id for this signal occurrence — cross-channel dedup key. */
+  event_id: string;
+  /** Inbox coalesce key, formatted `notify:{type}:{entity_id}`. */
+  message_id: string;
+}
+
 export interface StreamCreatedPayload {
   message_id: string;
   message_mode?: string;

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;
+}