@clawling/clawchat-plugin-openclaw 2026.8.26-1 → 2026.8.27-1

package/README.md

@@ -6,7 +6,7 @@ OpenClaw channel plugin that connects an agent to ClawChat over ClawChat Protoco
 
 - Plugin-owned WebSocket transport with auto-reconnect (exponential backoff + jitter), heartbeat, and ack tracking
 - Inbound `message.send` / `message.reply` with reply context
-- Outbound text replies in `static` or `stream` mode, with a consolidated final `message.reply`
+- Outbound text replies as complete `message.send` / `message.reply` frames — the plugin consumes inbound streams but never emits streaming lifecycle frames
 - Typing indicators and filtered forwarding for thinking / tool-call content
 - Media fragments (image / file / audio / video) in either direction
 - Invite-code onboarding (no raw credentials) via `/clawchat-activate` or supported `openclaw channels add`, plus always-registered `clawchat_*` account/media tools
@@ -95,7 +95,7 @@ src/
                         per-group idle/max batching for non-mention turns
   group-settings.ts     per-group agent settings cache (GET /v1/agents/me/
                         group-settings)
-  reply-dispatcher.ts   static vs stream routing
+  reply-dispatcher.ts   outbound reply routing (complete frames only)
   no-reply.ts           clawchat:no-reply / :silent suppression token guard
   login.runtime.ts      invite-code exchange flow
   refresh-manager.ts    ClawChat token refresh + auto-logout orchestration
@@ -153,7 +153,7 @@ The main reference is
 - Full configuration reference
 - Onboarding / activation details
 - REST endpoint table
-- Streaming frame shapes (`message.created` / `message.add` / `message.done` / `message.reply`)
+- Inbound streaming frame shapes (`message.created` / `message.add` / `message.done` / `message.reply`) — consumed, never produced
 - End-to-end sequence diagram
 - Media pipeline (inbound download / outbound upload)
 - Troubleshooting

package/dist/src/runtime.js

@@ -108,20 +108,26 @@ function isRecord(value) {
 }
 /**
  * §A.2 — classify a WS `hello-fail` reason for refresh gating.
- *  - "token-rejected": reason names an authentication failure → refresh.
+ *  - "token-rejected": the ONE terminal reason → refresh.
  *  - "auth-unavailable": 5xx auth-backend outage → backoff, DO NOT refresh.
- *  - "generic": unattributed → refresh only if the token is at/near expiry.
+ *  - "generic": anything else → transient; backoff with the current token.
  *
- * `auth service unavailable` is already split off by the ws-client into a
- * TransportError (backoff), but we classify defensively here too.
+ * msghub Protocol v2 §3.5 pins the matching contract: `"authentication failed"`
+ * is matched by exact equality (case / surrounding whitespace tolerant, like the
+ * hermes plugin's `_is_token_rejected`), never by substring or prefix, and no
+ * speculative matchers (`invalid token`, `token expired`, `unauthorized`, …) may
+ * be added — msghub does not emit them, and matching them would turn a reason
+ * added later into a forced refresh and, on a rotated refresh token, a re-pair.
+ * The ws-client already routes every non-terminal reason as a TransportError
+ * (backoff), so only the exact terminal string normally reaches this classifier;
+ * it stays defensive for the live-session path.
  */
 export function classifyHelloFailReason(reason) {
-    const r = (reason || "").toLowerCase();
+    const r = (reason || "").trim().toLowerCase();
     if (/auth service unavailable|temporarily unavailable/.test(r))
         return "auth-unavailable";
-    if (/authentication failed|invalid token|token expired|unauthorized|auth failed|invalid credentials/.test(r)) {
+    if (r === "authentication failed")
         return "token-rejected";
-    }
     return "generic";
 }
 /** Read `channels.<CHANNEL_ID>.refreshToken` from a live config, or null. */

package/dist/src/ws-client.js

@@ -185,6 +185,62 @@ export function isValidChatId(chatId) {
     }
     return true;
 }
+/**
+ * §3.5 terminal `hello-fail` reason. Exact equality after trimming and
+ * lower-casing (parity with the hermes plugin's `_is_token_rejected`); never a
+ * substring or prefix match — see `onHelloFail`.
+ */
+export const TERMINAL_HELLO_FAIL_REASON = "authentication failed";
+export function isTerminalHelloFailReason(reason) {
+    return (reason ?? "").trim().toLowerCase() === TERMINAL_HELLO_FAIL_REASON;
+}
+/**
+ * §3.6 duplicate-session refusal. msghub turns away the NEWER connection with
+ * this close code and a JSON reason `{reason, retry_after_ms}` when the opt-in
+ * guard is on. The server owns the 60s → 300s escalation, so the client only
+ * has to wait the value it is handed.
+ */
+export const CLOSE_CODE_DUPLICATE_THROTTLED = 4002;
+/** Floor used when a 4002 close carries no parseable retry_after_ms. */
+export const DEFAULT_REFUSAL_FLOOR_MS = 60_000;
+/**
+ * §3.6 duplicate-session takeover. msghub closes the OLDER socket with 4001
+ * when a newer session for the same (user, device) takes over. Reconnecting at
+ * the ordinary initial delay races that session and kicks it back — the
+ * mutual-eviction storm.
+ *
+ * A single eviction waits the base floor; consecutive evictions of the same
+ * connection escalate it (doubling, capped), so whichever instance keeps losing
+ * withdraws further each round until the other simply stays connected. Prod
+ * measured 9–163 s per eviction (msghub 2026-08-18), longer than the base, so a
+ * flat floor cannot break a persistent loop — only the escalation does. The
+ * streak survives `hello-ok` (an eviction happens *after* we connect) and is
+ * reset only by a non-4001 close, mirroring the hermes plugin.
+ */
+export const CLOSE_CODE_REPLACED = 4001;
+/** Base floor for the first takeover eviction (the §3.6 minimum). */
+export const TAKEOVER_FLOOR_MS = 5_000;
+/** Ceiling for the escalating takeover floor. */
+export const TAKEOVER_FLOOR_MAX_MS = 600_000;
+/** Reconnect floor for `streak` consecutive 4001 evictions (0 → no floor). */
+export function takeoverFloorMs(streak) {
+    if (streak <= 0)
+        return 0;
+    return Math.min(TAKEOVER_FLOOR_MS * 2 ** (streak - 1), TAKEOVER_FLOOR_MAX_MS);
+}
+export function parseRefusalRetryAfterMs(reason) {
+    if (reason) {
+        try {
+            const value = JSON.parse(reason).retry_after_ms;
+            if (typeof value === "number" && Number.isFinite(value) && value > 0)
+                return value;
+        }
+        catch {
+            // fall through to the default floor
+        }
+    }
+    return DEFAULT_REFUSAL_FLOOR_MS;
+}
 export class ClawChatClient extends EventEmitter {
     opts;
     currentState = "idle";
@@ -194,6 +250,10 @@ export class ClawChatClient extends EventEmitter {
     pongTimer;
     reconnectTimer;
     reconnectAttempts = 0;
+    // Consecutive 4001 duplicate-session evictions. Unlike reconnectAttempts it
+    // is NOT reset on hello-ok (the eviction lands after we connect); a non-4001
+    // close resets it. Drives the escalating takeover floor (§3.6).
+    takeoverStreak = 0;
     closing = false;
     authFailed = false;
     expectedConnectTraceId;
@@ -664,13 +724,16 @@ export class ClawChatClient extends EventEmitter {
             this.failHandshake(new ProtocolError("invalid hello-fail payload", env), 4002, "protocol error");
             return;
         }
-        // §14.1: distinguish upstream auth-service unavailability (5xx) from token
-        // rejection (4xx). On a 5xx the token may still be valid and the auth backend
-        // is down — backoff-reconnect with the SAME token and do
-        // NOT refresh (a 5xx storm must not become a mass token-refresh storm). Until
-        // the server emits the distinct 5xx reason, every other hello-fail is treated
-        // as a terminal token rejection (the caller acquires a fresh token first).
-        if (/auth service unavailable/i.test(reason)) {
+        // §3.5: `"authentication failed"` — matched by EXACT equality, never a
+        // substring — is the one terminal reason (the token was rejected by upstream
+        // auth). Every other reason is transient: `remote auth service unavailable`
+        // (the auth backend is down, the token may still be valid — §14.1), `nonce
+        // mismatch`, `invalid connect …`, and any string msghub adds after this
+        // client shipped. For all of those: backoff-reconnect with the SAME token,
+        // keep the outbound queue, and do NOT refresh (a 5xx storm must not become
+        // a mass token-refresh storm; a new server-side reason must not brick old
+        // clients). Widening the terminal branch breaks that forward-compat rule.
+        if (!isTerminalHelloFailReason(reason)) {
             const err = new TransportError(reason);
             this.expectedConnectTraceId = undefined;
             this.clearTimers();
@@ -680,8 +743,12 @@ export class ClawChatClient extends EventEmitter {
             this.connectReject = undefined;
             this.emitError(err);
             if (this.opts.transport.state !== "closed") {
-                // Close WITHOUT marking closing/authFailed so handleClose backoff-reconnects.
-                this.opts.transport.close(4001, "auth service unavailable");
+                // Close WITHOUT marking closing/authFailed so handleClose
+                // backoff-reconnects. Use 1000, NOT 4001: 4001 is the server's
+                // duplicate-session takeover code that handleClose now floors to 5s
+                // (§3.6), and this client-initiated transient teardown must reconnect
+                // on the ordinary backoff instead of inheriting that floor.
+                this.opts.transport.close(1000, reason);
             }
             else if (!this.closing && this.opts.reconnect.enabled) {
                 this.scheduleReconnect(reason);
@@ -796,7 +863,27 @@ export class ClawChatClient extends EventEmitter {
             this.connectReject?.(closeError);
             return;
         }
-        this.scheduleReconnect(reason || `close ${code}`);
+        // §3.6: raise an explicit reconnect floor for the two server-timed
+        // duplicate-session closes. 4002 (refusal) waits the server's
+        // retry_after_ms, which exceeds the maxDelay cap; 4001 (takeover) waits at
+        // least 5s so an instant reconnect doesn't re-enter the eviction storm.
+        let floorMs;
+        if (code === CLOSE_CODE_DUPLICATE_THROTTLED) {
+            // A refusal is not a takeover-loss — reset the streak and wait the
+            // server's retry_after_ms.
+            this.takeoverStreak = 0;
+            floorMs = parseRefusalRetryAfterMs(reason);
+        }
+        else if (code === CLOSE_CODE_REPLACED) {
+            this.takeoverStreak += 1;
+            floorMs = takeoverFloorMs(this.takeoverStreak);
+        }
+        else {
+            // Any other close (ordinary drop, backpressure kick) is not an eviction
+            // loss — reset so the next takeover starts from the base floor again.
+            this.takeoverStreak = 0;
+        }
+        this.scheduleReconnect(reason || `close ${code}`, floorMs);
     }
     failHandshake(err, code, reason) {
         this.clearTimers();
@@ -813,7 +900,7 @@ export class ClawChatClient extends EventEmitter {
             this.opts.transport.close(code, reason);
         }
     }
-    scheduleReconnect(reason) {
+    scheduleReconnect(reason, floorMs) {
         if (this.reconnectTimer)
             return;
         if (this.reconnectAttempts >= this.opts.reconnect.maxRetries) {
@@ -823,7 +910,10 @@ export class ClawChatClient extends EventEmitter {
             return;
         }
         this.reconnectAttempts += 1;
-        const baseDelay = Math.min(this.opts.reconnect.maxDelay, this.opts.reconnect.initialDelay * 2 ** Math.max(0, this.reconnectAttempts - 1));
+        const cappedDelay = Math.min(this.opts.reconnect.maxDelay, this.opts.reconnect.initialDelay * 2 ** Math.max(0, this.reconnectAttempts - 1));
+        // An explicit floor (a 4002 retry_after_ms) overrides the maxDelay cap: the
+        // server's wait is deliberately longer than the ordinary backoff ceiling.
+        const baseDelay = floorMs !== undefined ? Math.max(cappedDelay, floorMs) : cappedDelay;
         const jitter = baseDelay * this.opts.reconnect.jitterRatio * Math.random();
         const delay = Math.round(baseDelay + jitter);
         this.transition("reconnecting");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.8.26-1",
+  "version": "2026.8.27-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/runtime.ts

@@ -210,21 +210,26 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 
 /**
  * §A.2 — classify a WS `hello-fail` reason for refresh gating.
- *  - "token-rejected": reason names an authentication failure → refresh.
+ *  - "token-rejected": the ONE terminal reason → refresh.
  *  - "auth-unavailable": 5xx auth-backend outage → backoff, DO NOT refresh.
- *  - "generic": unattributed → refresh only if the token is at/near expiry.
+ *  - "generic": anything else → transient; backoff with the current token.
  *
- * `auth service unavailable` is already split off by the ws-client into a
- * TransportError (backoff), but we classify defensively here too.
+ * msghub Protocol v2 §3.5 pins the matching contract: `"authentication failed"`
+ * is matched by exact equality (case / surrounding whitespace tolerant, like the
+ * hermes plugin's `_is_token_rejected`), never by substring or prefix, and no
+ * speculative matchers (`invalid token`, `token expired`, `unauthorized`, …) may
+ * be added — msghub does not emit them, and matching them would turn a reason
+ * added later into a forced refresh and, on a rotated refresh token, a re-pair.
+ * The ws-client already routes every non-terminal reason as a TransportError
+ * (backoff), so only the exact terminal string normally reaches this classifier;
+ * it stays defensive for the live-session path.
  */
 export function classifyHelloFailReason(
   reason: string,
 ): "token-rejected" | "auth-unavailable" | "generic" {
-  const r = (reason || "").toLowerCase();
+  const r = (reason || "").trim().toLowerCase();
   if (/auth service unavailable|temporarily unavailable/.test(r)) return "auth-unavailable";
-  if (/authentication failed|invalid token|token expired|unauthorized|auth failed|invalid credentials/.test(r)) {
-    return "token-rejected";
-  }
+  if (r === "authentication failed") return "token-rejected";
   return "generic";
 }
 

package/src/ws-client.ts

@@ -270,6 +270,65 @@ export function isValidChatId(chatId: unknown): chatId is string {
  */
 export type DeadChatSource = "signal" | "server";
 
+/**
+ * §3.5 terminal `hello-fail` reason. Exact equality after trimming and
+ * lower-casing (parity with the hermes plugin's `_is_token_rejected`); never a
+ * substring or prefix match — see `onHelloFail`.
+ */
+export const TERMINAL_HELLO_FAIL_REASON = "authentication failed";
+
+export function isTerminalHelloFailReason(reason: string | undefined): boolean {
+  return (reason ?? "").trim().toLowerCase() === TERMINAL_HELLO_FAIL_REASON;
+}
+
+/**
+ * §3.6 duplicate-session refusal. msghub turns away the NEWER connection with
+ * this close code and a JSON reason `{reason, retry_after_ms}` when the opt-in
+ * guard is on. The server owns the 60s → 300s escalation, so the client only
+ * has to wait the value it is handed.
+ */
+export const CLOSE_CODE_DUPLICATE_THROTTLED = 4002;
+/** Floor used when a 4002 close carries no parseable retry_after_ms. */
+export const DEFAULT_REFUSAL_FLOOR_MS = 60_000;
+
+/**
+ * §3.6 duplicate-session takeover. msghub closes the OLDER socket with 4001
+ * when a newer session for the same (user, device) takes over. Reconnecting at
+ * the ordinary initial delay races that session and kicks it back — the
+ * mutual-eviction storm.
+ *
+ * A single eviction waits the base floor; consecutive evictions of the same
+ * connection escalate it (doubling, capped), so whichever instance keeps losing
+ * withdraws further each round until the other simply stays connected. Prod
+ * measured 9–163 s per eviction (msghub 2026-08-18), longer than the base, so a
+ * flat floor cannot break a persistent loop — only the escalation does. The
+ * streak survives `hello-ok` (an eviction happens *after* we connect) and is
+ * reset only by a non-4001 close, mirroring the hermes plugin.
+ */
+export const CLOSE_CODE_REPLACED = 4001;
+/** Base floor for the first takeover eviction (the §3.6 minimum). */
+export const TAKEOVER_FLOOR_MS = 5_000;
+/** Ceiling for the escalating takeover floor. */
+export const TAKEOVER_FLOOR_MAX_MS = 600_000;
+
+/** Reconnect floor for `streak` consecutive 4001 evictions (0 → no floor). */
+export function takeoverFloorMs(streak: number): number {
+  if (streak <= 0) return 0;
+  return Math.min(TAKEOVER_FLOOR_MS * 2 ** (streak - 1), TAKEOVER_FLOOR_MAX_MS);
+}
+
+export function parseRefusalRetryAfterMs(reason: string | undefined): number {
+  if (reason) {
+    try {
+      const value = (JSON.parse(reason) as { retry_after_ms?: unknown }).retry_after_ms;
+      if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+    } catch {
+      // fall through to the default floor
+    }
+  }
+  return DEFAULT_REFUSAL_FLOOR_MS;
+}
+
 export class ClawChatClient extends EventEmitter {
   private currentState: ConnState = "idle";
   private connectResolve?: () => void;
@@ -278,6 +337,10 @@ export class ClawChatClient extends EventEmitter {
   private pongTimer?: ReturnType<typeof setTimeout>;
   private reconnectTimer?: ReturnType<typeof setTimeout>;
   private reconnectAttempts = 0;
+  // Consecutive 4001 duplicate-session evictions. Unlike reconnectAttempts it
+  // is NOT reset on hello-ok (the eviction lands after we connect); a non-4001
+  // close resets it. Drives the escalating takeover floor (§3.6).
+  private takeoverStreak = 0;
   private closing = false;
   private authFailed = false;
   private expectedConnectTraceId?: string;
@@ -747,13 +810,16 @@ export class ClawChatClient extends EventEmitter {
       this.failHandshake(new ProtocolError("invalid hello-fail payload", env), 4002, "protocol error");
       return;
     }
-    // §14.1: distinguish upstream auth-service unavailability (5xx) from token
-    // rejection (4xx). On a 5xx the token may still be valid and the auth backend
-    // is down — backoff-reconnect with the SAME token and do
-    // NOT refresh (a 5xx storm must not become a mass token-refresh storm). Until
-    // the server emits the distinct 5xx reason, every other hello-fail is treated
-    // as a terminal token rejection (the caller acquires a fresh token first).
-    if (/auth service unavailable/i.test(reason)) {
+    // §3.5: `"authentication failed"` — matched by EXACT equality, never a
+    // substring — is the one terminal reason (the token was rejected by upstream
+    // auth). Every other reason is transient: `remote auth service unavailable`
+    // (the auth backend is down, the token may still be valid — §14.1), `nonce
+    // mismatch`, `invalid connect …`, and any string msghub adds after this
+    // client shipped. For all of those: backoff-reconnect with the SAME token,
+    // keep the outbound queue, and do NOT refresh (a 5xx storm must not become
+    // a mass token-refresh storm; a new server-side reason must not brick old
+    // clients). Widening the terminal branch breaks that forward-compat rule.
+    if (!isTerminalHelloFailReason(reason)) {
       const err = new TransportError(reason);
       this.expectedConnectTraceId = undefined;
       this.clearTimers();
@@ -763,8 +829,12 @@ export class ClawChatClient extends EventEmitter {
       this.connectReject = undefined;
       this.emitError(err);
       if (this.opts.transport.state !== "closed") {
-        // Close WITHOUT marking closing/authFailed so handleClose backoff-reconnects.
-        this.opts.transport.close(4001, "auth service unavailable");
+        // Close WITHOUT marking closing/authFailed so handleClose
+        // backoff-reconnects. Use 1000, NOT 4001: 4001 is the server's
+        // duplicate-session takeover code that handleClose now floors to 5s
+        // (§3.6), and this client-initiated transient teardown must reconnect
+        // on the ordinary backoff instead of inheriting that floor.
+        this.opts.transport.close(1000, reason);
       } else if (!this.closing && this.opts.reconnect.enabled) {
         this.scheduleReconnect(reason);
       } else {
@@ -875,7 +945,25 @@ export class ClawChatClient extends EventEmitter {
       this.connectReject?.(closeError);
       return;
     }
-    this.scheduleReconnect(reason || `close ${code}`);
+    // §3.6: raise an explicit reconnect floor for the two server-timed
+    // duplicate-session closes. 4002 (refusal) waits the server's
+    // retry_after_ms, which exceeds the maxDelay cap; 4001 (takeover) waits at
+    // least 5s so an instant reconnect doesn't re-enter the eviction storm.
+    let floorMs: number | undefined;
+    if (code === CLOSE_CODE_DUPLICATE_THROTTLED) {
+      // A refusal is not a takeover-loss — reset the streak and wait the
+      // server's retry_after_ms.
+      this.takeoverStreak = 0;
+      floorMs = parseRefusalRetryAfterMs(reason);
+    } else if (code === CLOSE_CODE_REPLACED) {
+      this.takeoverStreak += 1;
+      floorMs = takeoverFloorMs(this.takeoverStreak);
+    } else {
+      // Any other close (ordinary drop, backpressure kick) is not an eviction
+      // loss — reset so the next takeover starts from the base floor again.
+      this.takeoverStreak = 0;
+    }
+    this.scheduleReconnect(reason || `close ${code}`, floorMs);
   }
 
   private failHandshake(err: Error, code: number, reason: string): void {
@@ -894,7 +982,7 @@ export class ClawChatClient extends EventEmitter {
     }
   }
 
-  private scheduleReconnect(reason: string): void {
+  private scheduleReconnect(reason: string, floorMs?: number): void {
     if (this.reconnectTimer) return;
     if (this.reconnectAttempts >= this.opts.reconnect.maxRetries) {
       this.sendQueue.length = 0;
@@ -903,10 +991,13 @@ export class ClawChatClient extends EventEmitter {
       return;
     }
     this.reconnectAttempts += 1;
-    const baseDelay = Math.min(
+    const cappedDelay = Math.min(
       this.opts.reconnect.maxDelay,
       this.opts.reconnect.initialDelay * 2 ** Math.max(0, this.reconnectAttempts - 1),
     );
+    // An explicit floor (a 4002 retry_after_ms) overrides the maxDelay cap: the
+    // server's wait is deliberately longer than the ordinary backoff ceiling.
+    const baseDelay = floorMs !== undefined ? Math.max(cappedDelay, floorMs) : cappedDelay;
     const jitter = baseDelay * this.opts.reconnect.jitterRatio * Math.random();
     const delay = Math.round(baseDelay + jitter);
     this.transition("reconnecting");