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

package/dist/src/refresh-manager.js

@@ -0,0 +1,278 @@
+import { authRefresh, decodeJwtExp, } from "./api-client.js";
+/**
+ * §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;
+/**
+ * §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) {
+    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, activatedAtMs) {
+    const exp = decodeJwtExp(token);
+    if (exp != null)
+        return exp * 1000;
+    if (activatedAtMs != null)
+        return activatedAtMs + ACCESS_TOKEN_TTL_MS;
+    return null;
+}
+export class RefreshManager {
+    ports;
+    inFlight = null;
+    /** §A.3 — the access token a refresh was last attempted for. */
+    rejectedToken = null;
+    /** §A.3 — epoch-ms of the last refresh attempt (any token). */
+    lastAttemptAt = 0;
+    proactiveTimer = null;
+    stopped = false;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    now() {
+        return (this.ports.now ?? Date.now)();
+    }
+    setTimer(cb, ms) {
+        return (this.ports.setTimer ?? setTimeout)(cb, ms);
+    }
+    clearTimer(handle) {
+        (this.ports.clearTimer ?? clearTimeout)(handle);
+    }
+    /**
+     * §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) {
+        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;
+    }
+    async runRefresh(accessToken, refreshToken, reason) {
+        this.ports.log?.info?.(`clawchat-plugin-openclaw refresh attempt (${reason})`);
+        let result;
+        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) {
+        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.
+     */
+    async runProactiveRefresh() {
+        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() {
+        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) {
+        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() {
+        this.stopped = true;
+        this.disarmProactiveTimer();
+    }
+    /** Test/inspection seam — the latched (rejected) access token, if any. */
+    getRejectedToken() {
+        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() {
+        return { rejectedToken: this.rejectedToken, lastAttemptAt: this.lastAttemptAt };
+    }
+    /** §A.3/§A.4 — restore guard state from a prior manager (see `exportState`). */
+    restoreState(state) {
+        this.rejectedToken = state.rejectedToken;
+        this.lastAttemptAt = state.lastAttemptAt;
+    }
+}
+function decodeJwtIat(token) {
+    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);
+        const iat = parsed?.iat;
+        return typeof iat === "number" && Number.isFinite(iat) ? iat : null;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultJitter() {
+    return (Math.random() * 2 - 1) * PROACTIVE_JITTER_MS;
+}

package/dist/src/reply-dispatcher.js

@@ -3,7 +3,7 @@ import { resolveOutboundMediaUrls } from "openclaw/plugin-sdk/reply-payload";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { effectiveOutputVisibility, } from "./config.js";
 import { uploadOutboundMedia } from "./media-runtime.js";
-import { sendOpenclawClawlingText, } from "./outbound.js";
+import { mintMessageId, sendOpenclawClawlingText, } from "./outbound.js";
 import { isClawChatNoopResponseText } from "./profile-prompt.js";
 import { consumeTerminalClawChatSend } from "./terminal-send.js";
 import { openclawLlmContextDebug } from "./llm-context-debug.js";
@@ -416,7 +416,10 @@ export function createOpenclawClawlingReplyDispatcher(options) {
         }
         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) => {
         if (!isTyping && !typingActive)
             return;