@clawling/clawchat-plugin-openclaw 2026.7.29-3 → 2026.8.2-1

package/src/ws-client.ts

@@ -6,6 +6,7 @@ import {
   MessageSendError,
   ProtocolError,
   StateError,
+  TERMINAL_CHAT_CODES,
   TransportError,
   isBusinessDispatchEvent,
   type ConnState,
@@ -128,6 +129,8 @@ export interface ClawChatClientOptions {
   };
   heartbeat?: { enabled?: boolean; interval?: number; timeout?: number };
   ack?: { timeout?: number; autoResendOnTimeout?: boolean };
+  /** Injectable clock; defaults to Date.now. Exists so TTL logic is testable. */
+  now?: () => number;
 }
 
 export interface NormalizedClawChatClientOptions {
@@ -139,6 +142,7 @@ export interface NormalizedClawChatClientOptions {
   reconnect: Required<NonNullable<ClawChatClientOptions["reconnect"]>>;
   heartbeat: Required<NonNullable<ClawChatClientOptions["heartbeat"]>>;
   ack: Required<NonNullable<ClawChatClientOptions["ack"]>>;
+  now: () => number;
 }
 
 type PendingAck = {
@@ -168,6 +172,63 @@ export function buildConnectCapabilities(): ConnectCapabilities {
 /** Bounded FIFO of conversations known to be dissolved. */
 export const DEAD_CHATS_MAX = 512;
 
+/**
+ * How long a server rejection keeps gating uplinks for a conversation.
+ *
+ * A rejection is a fact with a shelf life, NOT a permanent verdict: the server
+ * soft-deletes conversations and can revive one in place under the SAME `cnv_`
+ * id — which is exactly the path an agent takes when it is re-paired. A
+ * permanent mark would leave a re-paired agent silently mute forever.
+ *
+ * 10 minutes: an order of magnitude above the server's own 30s negative cache
+ * for unresolvable chats (so a post-TTL retry lands after the server has
+ * re-resolved rather than on a stale negative entry), while still bounding the
+ * waste to at most one frame per dead conversation per 10 minutes. Two faster
+ * clears (`noteChatAlive`) handle the common cases; this is only the backstop.
+ *
+ * MUST stay identical to the hermes plugin's value — cross-plugin parity is
+ * pinned by src/parity.test.ts.
+ */
+export const SERVER_REJECTION_TTL_MS = 600_000;
+
+/**
+ * Every ClawChat conversation id is minted by member-backend with this prefix,
+ * and msghub resolves a chat_id only through member-backend. Anything else — a
+ * `usr_…` user idcode, a host-composed `direct:{self}:{peer}` key, a bare
+ * adapter name, a placeholder — is refused upstream with
+ * `code=400: invalid conversation id`.
+ *
+ * MUST stay identical to the hermes plugin's `CHAT_ID_PREFIX`.
+ */
+export const CHAT_ID_PREFIX = "cnv_";
+
+/**
+ * Whether `chatId` can name a ClawChat conversation at all.
+ *
+ * A purely *static* check: it says nothing about whether the conversation
+ * exists, is alive, or admits this sender. Those are server-side questions
+ * answered by `message.error`; this one is answerable locally, and a frame that
+ * fails it is always wrong to put on the wire.
+ */
+export function isValidChatId(chatId: unknown): chatId is string {
+  return typeof chatId === "string" && chatId.startsWith(CHAT_ID_PREFIX);
+}
+
+/**
+ * How a conversation came to be considered dead. The two sources write to two
+ * SEPARATE stores; nothing writes both.
+ *
+ * - `"signal"` — inferred from a `conversation.dissolved` push. Gates
+ *   `typing.update` ONLY. The protocol explicitly forbids gating `message.send`
+ *   on this signal, because the inference can be wrong and a false positive
+ *   must never swallow a real message. Never expires.
+ * - `"server"` — the server itself rejected an uplink on this chat with a
+ *   terminal code. Gates outbound sends (via `isSendBlocked`) and typing. It
+ *   never causes inbound frames to be dropped and never evicts local state.
+ *   Expires; see SERVER_REJECTION_TTL_MS.
+ */
+export type DeadChatSource = "signal" | "server";
+
 export class ClawChatClient extends EventEmitter {
   private currentState: ConnState = "idle";
   private connectResolve?: () => void;
@@ -182,7 +243,12 @@ export class ClawChatClient extends EventEmitter {
   private readonly pending = new Map<string, PendingAck>();
   private readonly handledMessageErrorTraces = new Set<string>();
   private readonly sendQueue: string[] = [];
-  private readonly deadChats = new Set<string>();
+  // Tier 1 — inferred from `conversation.dissolved`. Gates typing only.
+  private readonly dissolvedBySignal = new Set<string>();
+  // Tier 2 — server-CONFIRMED rejection → expiry timestamp. Gates sends.
+  // Disjoint storage from tier 1: neither write path touches the other set.
+  private readonly serverRejectedChats = new Map<string, number>();
+  private ownerDirectChatResolver?: () => string | null;
 
   constructor(private readonly opts: NormalizedClawChatClientOptions) {
     super();
@@ -232,38 +298,129 @@ export class ClawChatClient extends EventEmitter {
   }
 
   /**
-   * Record a conversation as dissolved so no further uplink is sent for it.
+   * Record a conversation as dead so no further uplink is sent for it.
    * Only `cnv_`-prefixed ids are accepted: a bad entity_id must never mute a
    * live conversation. Returns whether the id was accepted (and thus actually
-   * evicted) so callers can log/act on rejection distinctly from acceptance.
+   * recorded) so callers can log/act on rejection distinctly from acceptance.
+   *
+   * `source` selects WHICH STORE is written — see {@link DeadChatSource}. The
+   * two stores are disjoint; a signal never writes the server tier and a server
+   * rejection never writes the signal tier.
    *
-   * Eviction is FIFO by first-mark order, not LRU: `Set` iteration order is
-   * insertion order, and the `has()` early-return above means re-marking an
-   * already-dead id does NOT refresh its position. A chat marked dead long ago
-   * is evicted from the set before one marked dead a moment ago, even if the
-   * former has been re-signaled dissolved more recently.
+   * Signal tier eviction is FIFO by first-mark order, not LRU: `Set` iteration
+   * order is insertion order and the `has()` early-return means re-marking does
+   * NOT refresh position. The server tier deliberately does the opposite — a
+   * re-rejection re-arms the TTL *and* moves the id to the tail — because its
+   * whole point is "how long since the server last said no".
    */
-  markChatDead(chatId: string): boolean {
-    if (typeof chatId !== "string" || !chatId.startsWith("cnv_")) return false;
-    if (this.deadChats.has(chatId)) return true;
-    this.deadChats.add(chatId);
-    while (this.deadChats.size > DEAD_CHATS_MAX) {
-      const oldest = this.deadChats.values().next().value as string | undefined;
+  markChatDead(chatId: string, source: DeadChatSource = "signal"): boolean {
+    if (!isValidChatId(chatId)) return false;
+    if (source === "server") {
+      // Delete-then-set so the re-insert also moves the id to the FIFO tail.
+      this.serverRejectedChats.delete(chatId);
+      this.serverRejectedChats.set(chatId, this.opts.now() + SERVER_REJECTION_TTL_MS);
+      while (this.serverRejectedChats.size > DEAD_CHATS_MAX) {
+        const oldest = this.serverRejectedChats.keys().next().value as string | undefined;
+        if (oldest === undefined) break;
+        this.serverRejectedChats.delete(oldest);
+      }
+      return true;
+    }
+    if (this.dissolvedBySignal.has(chatId)) return true;
+    this.dissolvedBySignal.add(chatId);
+    while (this.dissolvedBySignal.size > DEAD_CHATS_MAX) {
+      const oldest = this.dissolvedBySignal.values().next().value as string | undefined;
       if (oldest === undefined) break;
-      this.deadChats.delete(oldest);
+      this.dissolvedBySignal.delete(oldest);
     }
     return true;
   }
 
+  /**
+   * True for a chat dead by EITHER tier — a derived union, not a third store.
+   * Gates `typing.update` only. Never gate message delivery on this.
+   */
   isChatDead(chatId: string): boolean {
-    return this.deadChats.has(chatId);
+    return this.dissolvedBySignal.has(chatId) || this.isChatRejectedByServer(chatId);
   }
 
   /**
-   * The ONLY dead-chat guard in this client. `sendAckableEnvelope` (backing
-   * `message.send` / `message.reply`) is deliberately left unguarded: a
-   * false-positive dead-mark must never block message delivery, only the
-   * cosmetic `typing.update` indicator. Do not extend the guard there.
+   * True only for a chat the SERVER rejected with a terminal code, and only
+   * while that rejection is still fresh. Expiry is lazy: the entry is dropped
+   * on the first read past its deadline, so there is no timer to leak.
+   */
+  isChatRejectedByServer(chatId: string): boolean {
+    const expiresAt = this.serverRejectedChats.get(chatId);
+    if (expiresAt === undefined) return false;
+    if (this.opts.now() >= expiresAt) {
+      this.serverRejectedChats.delete(chatId);
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * The ONLY predicate allowed to gate an outbound `message.send` /
+   * `message.reply` / `message.reaction`. Narrower than `isChatRejectedByServer`
+   * by one exemption: the owner's direct conversation is never blocked, because
+   * it is the only channel through which the agent can explain why it went
+   * dark. The rejection is still RECORDED for the owner chat — the exemption
+   * decides whether to send, not whether to remember.
+   */
+  isSendBlocked(chatId: string): boolean {
+    if (!this.isChatRejectedByServer(chatId)) return false;
+    const ownerChatId = this.ownerDirectChatResolver?.();
+    return !(ownerChatId && ownerChatId === chatId);
+  }
+
+  /** Injected by the runtime once the owner's direct conversation is known. */
+  setOwnerDirectChatResolver(resolver: () => string | null): void {
+    this.ownerDirectChatResolver = resolver;
+  }
+
+  /**
+   * Evidence that a conversation is reachable again — drop any server-rejection
+   * record for it. Called from the inbound path; see `dispatchInbound`.
+   *
+   * Only the SERVER tier is cleared. The signal tier is deliberately left
+   * alone: `conversation.dissolved` gates nothing but the cosmetic typing
+   * indicator, and un-muting it on a replayed frame would be churn with no
+   * user-visible benefit.
+   */
+  noteChatAlive(chatId: string): void {
+    if (typeof chatId !== "string" || !chatId) return;
+    this.serverRejectedChats.delete(chatId);
+  }
+
+  /**
+   * `conversation.*` signals other than `dissolved` mean the server still has
+   * this conversation (created / updated / membership changed) — clear any
+   * stale rejection. `conversation.dissolved` is the opposite signal and must
+   * not clear anything.
+   */
+  private noteConversationSignalAlive(env: Envelope): void {
+    const payload = env.payload && typeof env.payload === "object"
+      ? env.payload as { type?: unknown; entity_id?: unknown }
+      : undefined;
+    const type = typeof payload?.type === "string" ? payload.type : "";
+    if (!type.startsWith("conversation.") || type === "conversation.dissolved") return;
+    const entityId = typeof payload?.entity_id === "string" ? payload.entity_id : "";
+    if (entityId) this.noteChatAlive(entityId);
+  }
+
+  /**
+   * Gated on `isChatDead` — BOTH tiers. `sendAckableEnvelope` (backing
+   * `message.send` / `message.reply`) is deliberately left unguarded against
+   * this predicate: a false-positive SIGNAL-derived dead-mark must never block
+   * message delivery, only the cosmetic `typing.update` indicator. The
+   * protocol states this explicitly for `conversation.dissolved` — "agents …
+   * stop sending typing.update for that chat_id; message.send MUST NOT be
+   * gated on this". Do not extend `isChatDead` to the send path.
+   *
+   * The send path IS gated, but on the narrower `isSendBlocked` (see
+   * src/outbound.ts) — a chat the server itself rejected is fact, not
+   * inference, so the false-positive argument above does not apply to it.
+   * That fact expires; this one does not.
    */
   typing(chatId: string, isTyping = true): void {
     if (this.isChatDead(chatId)) return;
@@ -300,11 +457,27 @@ export class ClawChatClient extends EventEmitter {
   }
 
   sendRawEnvelope(env: Envelope): void {
+    // Static addressing check. A frame carrying a chat_id that cannot name a
+    // conversation is refused by msghub with `invalid conversation id`, so it
+    // never had a recipient; dropping it here costs the caller nothing and
+    // keeps the error out of msghub's logs.
+    //
+    // Unlike the dead-chat gate — a revocable server state a queued frame can
+    // fall into, which is why `shouldDropQueuedWire` re-checks on replay — a
+    // malformed chat_id is wrong at construction time and can never become
+    // valid. Rejecting at this entry point is therefore sufficient: the frame
+    // never reaches the reconnect queue, so no replay path can resurrect it.
+    //
+    // Frames with no chat_id (connect / ping / pong) are untouched.
+    if (env.chat_id !== undefined && !isValidChatId(env.chat_id)) return;
     this.sendWire(JSON.stringify(env), { bypassReconnectQueue: env.event === EVENT.CONNECT });
   }
 
-  // Deliberately does NOT consult `deadChats` — see the comment on `typing()`.
-  // Message delivery must never be gated by the dead-chat guard.
+  // Deliberately does NOT consult the dead-chat state — see the comment on
+  // `typing()`. Signal-inferred death must never gate message delivery. (The
+  // narrower `isSendBlocked` gate lives on the aligned path in src/outbound.ts,
+  // which is what the reply dispatcher actually uses; this legacy ackable path
+  // is kept ungated so the two tiers stay distinguishable.)
   async sendAckableEnvelope(params: {
     eventName: "message.send" | "message.reply";
     chatId: string;
@@ -415,6 +588,13 @@ export class ClawChatClient extends EventEmitter {
   }
 
   private dispatchInbound(env: Envelope): void {
+    // A frame the server routed to us for this chat proves the chat is
+    // reachable again — a deleted conversation can be revived in place under
+    // the same id. `message.error` is excluded: it IS the rejection, not
+    // evidence of life.
+    if (typeof env.chat_id === "string" && env.event !== EVENT.MESSAGE_ERROR) {
+      this.noteChatAlive(env.chat_id);
+    }
     if (env.event === EVENT.CONNECT_CHALLENGE) return this.onChallenge(env);
     if (env.event === EVENT.HELLO_OK) return this.onHelloOk(env);
     if (env.event === EVENT.HELLO_FAIL) return this.onHelloFail(env);
@@ -429,6 +609,7 @@ export class ClawChatClient extends EventEmitter {
     if (env.event === EVENT.MESSAGE_FAILED) this.emit("message:failed", env);
     if (env.event === EVENT.TYPING_UPDATE) this.emit("typing", env);
     if (env.event === EVENT.CHAT_METADATA_INVALIDATED) this.emit("metadata:invalidated", env);
+    if (env.event === EVENT.NOTIFY_SIGNAL) this.noteConversationSignalAlive(env);
     if (env.event === EVENT.NOTIFY_SIGNAL) this.emit("notify:signal", env);
     if (env.event === EVENT.REPLAY_DONE) this.emit("replay:done", env);
     if (env.event === EVENT.OFFLINE_DONE) this.emit("offline:done");
@@ -576,6 +757,20 @@ export class ClawChatClient extends EventEmitter {
   }
 
   private onMessageError(env: Envelope<MessageErrorPayload>): void {
+    const payload = env.payload && typeof env.payload === "object"
+      ? env.payload as { code?: unknown; reason?: unknown; message?: unknown }
+      : undefined;
+    const code = typeof payload?.code === "string" && payload.code ? payload.code : "unknown";
+    // Mark BEFORE the pending-ack lookup: an unmatched error frame still
+    // carries an authoritative `chat_id` + `code` and must participate in the
+    // dead-chat decision. Unmatched is the NORMAL case here — the aligned queue
+    // owns its own ack matching (markMessageErrorHandled makes the branch below
+    // return silently) and a reconnect drops pending entries. Deferring the
+    // mark until after the lookup would make tier-2 feeding random.
+    // Parity: hermes notifies its dead-chat state at the same point.
+    if (typeof env.chat_id === "string" && TERMINAL_CHAT_CODES.has(code)) {
+      this.markChatDead(env.chat_id, "server");
+    }
     const entry = this.pending.get(env.trace_id);
     if (!entry) {
       if (this.handledMessageErrorTraces.delete(env.trace_id)) return;
@@ -584,10 +779,6 @@ export class ClawChatClient extends EventEmitter {
     }
     clearTimeout(entry.timer);
     this.pending.delete(env.trace_id);
-    const payload = env.payload && typeof env.payload === "object"
-      ? env.payload as { code?: unknown; reason?: unknown; message?: unknown }
-      : undefined;
-    const code = typeof payload?.code === "string" && payload.code ? payload.code : "unknown";
     // §14.3: the human-readable hint is `reason` (fall back to legacy `message`).
     const hint = typeof payload?.reason === "string" && payload.reason
       ? payload.reason
@@ -710,13 +901,24 @@ export class ClawChatClient extends EventEmitter {
 
   private flushSendQueue(): void {
     while (this.sendQueue.length > 0) {
-      const wire = this.sendQueue.shift()!;
-      try {
-        this.sendWire(wire);
-      } catch (err) {
-        this.sendQueue.unshift(wire);
-        throw err;
+      const wire = this.sendQueue[0]!;
+      // Re-check the dead-chat gates at replay time: a conversation can be
+      // rejected AFTER a frame was buffered here, and this path bypasses every
+      // caller-side guard.
+      if (
+        shouldDropQueuedWire(wire, {
+          isChatDead: (chatId) => this.isChatDead(chatId),
+          isSendBlocked: (chatId) => this.isSendBlocked(chatId),
+        })
+      ) {
+        this.sendQueue.shift();
+        continue;
       }
+      // Read the head first and shift only after a successful write, so a
+      // failure leaves the frame at the head (same as the previous
+      // shift/unshift pair; `onHelloOk`'s catch closes and reconnects).
+      this.sendWire(wire);
+      this.sendQueue.shift();
     }
   }
 
@@ -735,6 +937,38 @@ export class ClawChatClient extends EventEmitter {
   }
 }
 
+/**
+ * Decide whether a wire string sitting in the transport-level reconnect queue
+ * must be dropped instead of replayed.
+ *
+ * This queue holds ALREADY-SERIALIZED frames, so the only way to see the
+ * `chat_id` is to parse. That is acceptable here and nowhere else: the queue
+ * fills only during a reconnect window and is drained exactly once per
+ * successful handshake — unlike `sendWire`, which is the hot path.
+ *
+ * Asymmetry mirrors the live path: `typing.update` is gated on EITHER tier
+ * (`isChatDead`), everything else only on a server-confirmed, non-owner
+ * rejection (`isSendBlocked`). Unparseable or chat-less frames are always kept:
+ * `connect` / `ping` / `pong` must never be dropped.
+ *
+ * Exported for direct unit testing; `flushSendQueue` is the only producer.
+ */
+export function shouldDropQueuedWire(
+  wire: string,
+  gates: { isChatDead: (chatId: string) => boolean; isSendBlocked: (chatId: string) => boolean },
+): boolean {
+  let env: { event?: unknown; chat_id?: unknown };
+  try {
+    env = JSON.parse(wire) as { event?: unknown; chat_id?: unknown };
+  } catch {
+    return false;
+  }
+  const chatId = typeof env.chat_id === "string" ? env.chat_id : "";
+  if (!chatId) return false;
+  if (env.event === EVENT.TYPING_UPDATE) return gates.isChatDead(chatId);
+  return gates.isSendBlocked(chatId);
+}
+
 export function createClawChatClient(options: ClawChatClientOptions): ClawChatClient {
   return new ClawChatClient({
     ...options,
@@ -758,6 +992,7 @@ export function createClawChatClient(options: ClawChatClientOptions): ClawChatCl
       timeout: options.ack?.timeout ?? 15000,
       autoResendOnTimeout: options.ack?.autoResendOnTimeout ?? false,
     },
+    now: options.now ?? (() => Date.now()),
   });
 }