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

package/dist/src/api-client.js

@@ -1,5 +1,120 @@
 import { ClawlingApiError, } from "./api-types.js";
 import { CHANNEL_ID } from "./config.js";
+/**
+ * §A.0 — decode the access token's `exp` claim locally (base64url-decode the
+ * JWT payload segment, read `exp` as epoch seconds). Returns `null` when the
+ * token is not a parseable JWT or carries no numeric `exp`, in which case the
+ * caller falls back to `activated_at + 24h`. We never persist a separate
+ * expiry column; this is derived from the token on every load.
+ */
+export function decodeJwtExp(token) {
+    if (typeof token !== "string")
+        return null;
+    const segments = token.split(".");
+    if (segments.length < 2)
+        return null;
+    const payloadSegment = segments[1];
+    if (!payloadSegment)
+        return null;
+    try {
+        const json = Buffer.from(payloadSegment, "base64url").toString("utf8");
+        const parsed = JSON.parse(json);
+        const exp = parsed?.exp;
+        return typeof exp === "number" && Number.isFinite(exp) ? exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Backend envelope codes for `POST /v1/auth/refresh` (§0). */
+const CODE_OK = 0;
+const CODE_INTERNAL = 1; // CodeInternal — transient.
+const CODE_BAD_REQUEST = 400; // bad body / device id — permanent (client bug).
+const CODE_INVALID_REFRESH = 10003; // CodeInvalidRefresh — permanent.
+/**
+ * §0/§B — call `POST /v1/auth/refresh` to rotate the access+refresh token.
+ *
+ * Unauthenticated: the refresh token in the body IS the credential, so we send
+ * NO `Authorization` header. `X-Device-Id` MUST equal the connect-time device
+ * id (the backend rejects on `sess.DeviceID != X-Device-Id`). The endpoint is
+ * always HTTP 200 — branch on the envelope `code`, NOT on HTTP status. This is
+ * a standalone function (not a method on the token-bearing client) precisely
+ * because no bearer token participates.
+ */
+export async function authRefresh(opts, params) {
+    const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    if (!params.refreshToken?.trim()) {
+        return { kind: "permanent", code: CODE_INVALID_REFRESH, message: "missing refresh token" };
+    }
+    let res;
+    try {
+        res = await fetchImpl(`${baseUrl}/v1/auth/refresh`, {
+            method: "POST",
+            // No `Authorization` header — refresh is unauthenticated by design.
+            headers: {
+                "content-type": "application/json",
+                "x-device-id": params.deviceId,
+            },
+            body: JSON.stringify({ refresh_token: params.refreshToken.trim() }),
+        });
+    }
+    catch (err) {
+        // Network error / timeout / DNS — TRANSIENT (no rotation committed).
+        return {
+            kind: "transient",
+            message: `refresh fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (res.status !== 200) {
+        // Any non-200 (500/LB/transport) — TRANSIENT, regardless of body.
+        const text = await res.text().catch(() => "");
+        return {
+            kind: "transient",
+            status: res.status,
+            message: `refresh http ${res.status} ${text.slice(0, 200)}`,
+        };
+    }
+    const text = await res.text().catch(() => "");
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    const code = typeof parsed?.code === "number" ? parsed.code : Number.NaN;
+    const message = (typeof parsed?.msg === "string" && parsed.msg) ||
+        (typeof parsed?.message === "string" && parsed.message) ||
+        `code=${code}`;
+    if (!Number.isFinite(code)) {
+        // 200 with no usable envelope — treat as transient (do not auto-logout).
+        return { kind: "transient", status: 200, message: "refresh: missing numeric code" };
+    }
+    if (code === CODE_OK) {
+        const data = parsed?.data && typeof parsed.data === "object"
+            ? parsed.data
+            : {};
+        const accessToken = typeof data.access_token === "string" ? data.access_token : "";
+        const refreshToken = typeof data.refresh_token === "string" ? data.refresh_token : "";
+        if (!accessToken || !refreshToken) {
+            // Rotation succeeded server-side but the body is malformed — transient so
+            // we retry; the next attempt will return 10003 (rotation single-use) and
+            // escalate to permanent (§B transient→permanent).
+            return { kind: "transient", status: 200, message: "refresh: rotation body incomplete" };
+        }
+        return { kind: "success", accessToken, refreshToken };
+    }
+    if (code === CODE_INVALID_REFRESH || code === CODE_BAD_REQUEST) {
+        return { kind: "permanent", code, message };
+    }
+    if (code === CODE_INTERNAL) {
+        return { kind: "transient", status: 200, code, message };
+    }
+    // Unknown non-zero code — conservatively transient (never auto-logout on an
+    // unrecognized code; only 10003/400 are permanent per §0).
+    return { kind: "transient", status: 200, code, message };
+}
 export function createOpenclawClawlingApiClient(opts) {
     if (!/^https?:\/\//i.test(opts.baseUrl)) {
         throw new ClawlingApiError("validation", `clawchat-plugin-openclaw baseUrl must start with http:// or https:// (got "${opts.baseUrl}")`);
@@ -33,44 +148,49 @@ export function createOpenclawClawlingApiClient(opts) {
                 path,
             });
         }
-        if (!res.ok) {
-            const snippet = await res.text().catch(() => "");
-            throw new ClawlingApiError("transport", `http ${res.status} ${snippet.slice(0, 200)}`, {
-                status: res.status,
-                path,
-            });
-        }
+        // §15.3: HTTP status stays meaningful for proxies, but application code
+        // should branch on the business `code`, not the HTTP status. Parse the body
+        // FIRST — even on a non-2xx — so callers receive the precise business code
+        // (e.g. 41301 vs 41501) rather than a generic transport error. Only fall
+        // back to the HTTP status when no structured envelope is present.
+        const text = await res.text().catch(() => "");
         let parsed;
         try {
-            parsed = await res.json();
+            parsed = text ? JSON.parse(text) : undefined;
         }
-        catch (err) {
-            throw new ClawlingApiError("transport", `non-JSON response: ${err instanceof Error ? err.message : String(err)}`, { status: res.status, path });
+        catch {
+            parsed = undefined;
         }
         // Unified envelope: `{ code: number, msg: string, data: T }`.
         // `code === 0` means success; any other value is a business error whose
         // `msg` is surfaced to callers and `code` is preserved on the error meta.
-        const env = parsed;
-        const code = typeof env.code === "number" ? env.code : Number.NaN;
-        const msg = typeof env.msg === "string"
-            ? env.msg
-            : typeof env.message === "string"
-                ? env.message
-                : "";
-        if (!Number.isFinite(code)) {
-            throw new ClawlingApiError("transport", "invalid envelope: missing numeric `code`", {
-                status: res.status,
-                path,
-            });
+        const env = parsed && typeof parsed === "object"
+            ? parsed
+            : undefined;
+        const code = typeof env?.code === "number" ? env.code : Number.NaN;
+        if (env && Number.isFinite(code)) {
+            const msg = typeof env.msg === "string"
+                ? env.msg
+                : typeof env.message === "string"
+                    ? env.message
+                    : "";
+            if (code !== 0) {
+                throw new ClawlingApiError("api", msg || `code=${code}`, {
+                    code,
+                    status: res.status,
+                    path,
+                });
+            }
+            return env.data;
         }
-        if (code !== 0) {
-            throw new ClawlingApiError("api", msg || `code=${code}`, {
-                code,
+        // No usable envelope — fall back to the HTTP status signal.
+        if (!res.ok) {
+            throw new ClawlingApiError("transport", `http ${res.status} ${text.slice(0, 200)}`, {
                 status: res.status,
                 path,
             });
         }
-        return env.data;
+        throw new ClawlingApiError("transport", text ? "invalid envelope: missing numeric `code`" : "non-JSON response: empty body", { status: res.status, path });
     }
     async function call(method, path, init) {
         let res;

package/dist/src/client.js

@@ -8,10 +8,13 @@ export function resolveOpenclawClawlingDeviceId(account) {
     return `${CHANNEL_ID}-${digest}`;
 }
 export function createOpenclawClawlingClient(account, overrides = {}) {
+    const deviceId = overrides.deviceIdOverride && overrides.deviceIdOverride.trim()
+        ? overrides.deviceIdOverride.trim()
+        : resolveOpenclawClawlingDeviceId(account);
     const client = createClawChatClient({
         url: account.websocketUrl,
         token: account.token,
-        deviceId: resolveOpenclawClawlingDeviceId(account),
+        deviceId,
         ...(overrides.transport ? { transport: overrides.transport } : {}),
         reconnect: {
             enabled: true,

package/dist/src/inbound.js

@@ -10,8 +10,10 @@ function normalizeSender(sender) {
     if (!id)
         return null;
     const nickName = typeof s.nick_name === "string" ? s.nick_name : id;
-    const profileType = s.type === "agent" || s.type === "user" ? s.type : null;
-    return { id, nickName, profileType };
+    // §4.1: `sender.type` is the server-stamped routing type and is always
+    // "direct" — it never carries the human/agent distinction. The sender's
+    // profile_type is resolved downstream from chat metadata, not from the wire.
+    return { id, nickName };
 }
 function requireChatId(envelope) {
     const chatId = envelope.chat_id;
@@ -85,6 +87,18 @@ export async function dispatchOpenclawClawlingInbound(params) {
         log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw skip non-business event=${envelope.event} trace=${envelope.trace_id}`);
         return;
     }
+    // Fail-closed self-echo guard: the self-echo check below
+    // (`sender.id === account.userId`) is only meaningful when `account.userId`
+    // is known. A reactivation auth failure can leave `account.userId` as an
+    // empty string (see runtime.ts reactivation edge); with an empty userId the
+    // `account.userId && …` short-circuit would silently treat EVERY frame —
+    // including our own echoed messages — as non-self and feed it back into the
+    // LLM pipeline (self-reply loop). Refuse to process materialized messages in
+    // that state rather than risk echoing our own output.
+    if (!account.userId) {
+        log?.error?.(`[${account.accountId}] clawchat-plugin-openclaw skip (fail-closed): empty account.userId, cannot apply self-echo guard event=${envelope.event} trace=${envelope.trace_id}`);
+        return;
+    }
     if (isMaterializedMessage && !isInboundMessagePayload(envelope.payload)) {
         log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw skip: invalid payload trace=${envelope.trace_id}`);
         return;
@@ -107,7 +121,11 @@ export async function dispatchOpenclawClawlingInbound(params) {
     }
     const chatType = envelope.chat_type === "group" ? "group" : "direct";
     const isGroup = chatType === "group";
-    if (isMaterializedMessage && payload.message_mode !== "normal") {
+    // §7.5: the server does not default message_mode — an omitted field arrives
+    // as "" on the downlink. Empty/absent is equivalent to "normal", so only
+    // skip genuinely non-normal modes (e.g. "thinking").
+    const messageMode = payload.message_mode ?? "";
+    if (isMaterializedMessage && messageMode !== "normal" && messageMode !== "") {
         log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw skip non-normal mode=${payload.message_mode}`);
         return;
     }
@@ -152,7 +170,6 @@ export async function dispatchOpenclawClawlingInbound(params) {
         peer: { kind: isGroup ? "group" : "direct", id: chatId },
         senderId: sender.id,
         senderNickName: sender.nickName,
-        ...(sender.profileType ? { senderProfileType: sender.profileType } : {}),
         rawBody,
         messageId: payload.message_id,
         traceId: envelope.trace_id,

package/dist/src/login.runtime.js

@@ -197,6 +197,10 @@ export async function runOpenclawClawlingLogin(params) {
             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 {

package/dist/src/outbound.js

@@ -1,3 +1,4 @@
+import { randomInt } from "node:crypto";
 import { MessageSendError } from "./protocol-types.js";
 import { createAttachedChannelResultAdapter, } from "openclaw/plugin-sdk/channel-send-result";
 import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
@@ -198,8 +199,13 @@ async function sendAlignedAckableEnvelope(params) {
                     return;
                 const payload = ack.payload;
                 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")
@@ -354,13 +360,18 @@ export async function sendOpenclawClawlingText(params) {
     const useReply = Boolean(params.replyCtx?.replyPreviewSenderId
         && 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;
     let mode;
     if (useReply && params.replyCtx) {
         mode = "reply";
         const payload = {
-            ...(messageId ? { message_id: messageId } : {}),
+            message_id: messageId,
             message_mode: "normal",
             message: {
                 body: { fragments },
@@ -395,7 +406,7 @@ export async function sendOpenclawClawlingText(params) {
             }
             : null;
         const payload = {
-            ...(messageId ? { message_id: messageId } : {}),
+            message_id: messageId,
             message_mode: "normal",
             message: {
                 body: { fragments },
@@ -411,7 +422,7 @@ export async function sendOpenclawClawlingText(params) {
             ...(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}`);
     }
     params.log?.info?.(`[${params.account.accountId}] clawchat-plugin-openclaw outbound mode=${mode} msg=${ack.payload.message_id} text_len=${text.length} media=${mediaFragments.length} trace=${ack.trace_id}`);
@@ -474,8 +485,32 @@ export async function sendOpenclawClawlingMedia(params) {
         ...(params.log ? { log: params.log } : {}),
     });
 }
-function mintOutboundMessageId(account) {
-    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 = Date.now()) {
+    let time = now;
+    const out = new Array(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() {
+    return `msg-${ulid()}`;
+}
+function mintOutboundMessageId(_account) {
+    return mintMessageId();
 }
 function resolveChannelOutboundStore() {
     try {

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