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

package/dist/src/ws-client.js

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import { AckTimeoutError, AuthError, EVENT, MessageSendError, ProtocolError, StateError, TransportError, isBusinessDispatchEvent, } from "./protocol-types.js";
+import { AckTimeoutError, AuthError, EVENT, MessageSendError, ProtocolError, StateError, TERMINAL_CHAT_CODES, TransportError, isBusinessDispatchEvent, } from "./protocol-types.js";
 export function createWebSocketTransport(WebSocketCtor = globalThis.WebSocket) {
     let currentState = "closed";
     let socket;
@@ -103,6 +103,45 @@ export function buildConnectCapabilities() {
 }
 /** 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) {
+    return typeof chatId === "string" && chatId.startsWith(CHAT_ID_PREFIX);
+}
 export class ClawChatClient extends EventEmitter {
     opts;
     currentState = "idle";
@@ -118,7 +157,12 @@ export class ClawChatClient extends EventEmitter {
     pending = new Map();
     handledMessageErrorTraces = new Set();
     sendQueue = [];
-    deadChats = new Set();
+    // Tier 1 — inferred from `conversation.dissolved`. Gates typing only.
+    dissolvedBySignal = new Set();
+    // Tier 2 — server-CONFIRMED rejection → expiry timestamp. Gates sends.
+    // Disjoint storage from tier 1: neither write path touches the other set.
+    serverRejectedChats = new Map();
+    ownerDirectChatResolver;
     constructor(opts) {
         super();
         this.opts = opts;
@@ -160,39 +204,131 @@ export class ClawChatClient extends EventEmitter {
         this.opts.transport.close(1000, "client close");
     }
     /**
-     * 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.
      *
-     * 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.
+     * `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.
+     *
+     * 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) {
-        if (typeof chatId !== "string" || !chatId.startsWith("cnv_"))
+    markChatDead(chatId, source = "signal") {
+        if (!isValidChatId(chatId))
             return false;
-        if (this.deadChats.has(chatId))
+        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;
+                if (oldest === undefined)
+                    break;
+                this.serverRejectedChats.delete(oldest);
+            }
+            return true;
+        }
+        if (this.dissolvedBySignal.has(chatId))
             return true;
-        this.deadChats.add(chatId);
-        while (this.deadChats.size > DEAD_CHATS_MAX) {
-            const oldest = this.deadChats.values().next().value;
+        this.dissolvedBySignal.add(chatId);
+        while (this.dissolvedBySignal.size > DEAD_CHATS_MAX) {
+            const oldest = this.dissolvedBySignal.values().next().value;
             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) {
-        return this.deadChats.has(chatId);
+        return this.dissolvedBySignal.has(chatId) || this.isChatRejectedByServer(chatId);
+    }
+    /**
+     * 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) {
+        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) {
+        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) {
+        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) {
+        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.
+     */
+    noteConversationSignalAlive(env) {
+        const payload = env.payload && typeof env.payload === "object"
+            ? env.payload
+            : 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);
     }
     /**
-     * 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.
+     * 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, isTyping = true) {
         if (this.isChatDead(chatId))
@@ -227,10 +363,27 @@ export class ClawChatClient extends EventEmitter {
         this.opts.transport.send(wire);
     }
     sendRawEnvelope(env) {
+        // 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) {
         const traceId = this.nextTraceId();
         const env = {
@@ -332,6 +485,13 @@ export class ClawChatClient extends EventEmitter {
         this.dispatchInbound(env);
     }
     dispatchInbound(env) {
+        // 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)
@@ -360,6 +520,8 @@ export class ClawChatClient extends EventEmitter {
             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)
@@ -510,6 +672,20 @@ export class ClawChatClient extends EventEmitter {
         entry.resolve(env);
     }
     onMessageError(env) {
+        const payload = env.payload && typeof env.payload === "object"
+            ? env.payload
+            : 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))
@@ -519,10 +695,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
-            : 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
@@ -644,14 +816,22 @@ export class ClawChatClient extends EventEmitter {
     }
     flushSendQueue() {
         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();
         }
     }
     isHandshaking() {
@@ -667,6 +847,37 @@ export class ClawChatClient extends EventEmitter {
         return null;
     }
 }
+/**
+ * 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, gates) {
+    let env;
+    try {
+        env = JSON.parse(wire);
+    }
+    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) {
     return new ClawChatClient({
         ...options,
@@ -689,5 +900,6 @@ export function createClawChatClient(options) {
             timeout: options.ack?.timeout ?? 15000,
             autoResendOnTimeout: options.ack?.autoResendOnTimeout ?? false,
         },
+        now: options.now ?? (() => Date.now()),
     });
 }

package/openclaw.plugin.json

@@ -48,6 +48,7 @@
       "clawchat_get_conversation",
       "clawchat_leave_group",
       "clawchat_list_moments",
+      "clawchat_get_moment",
       "clawchat_create_moment",
       "clawchat_delete_moment",
       "clawchat_toggle_moment_reaction",

package/package.json

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

package/skills/clawchat-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawchat-core
-version: 1.1.0
+version: 1.2.0
 description: Use when a request involves ClawChat profile, friends, user search, moments/dynamics, comments, reactions, avatar, media, memory, output visibility, read-only conversation lookup, sending an image, file, or voice/audio clip into a conversation, or plugin install/update/activation.
 ---
 
@@ -74,6 +74,7 @@ Tool descriptions are authoritative. These routing hints resolve common ambiguit
 | Remove/unfriend contact | `clawchat_remove_friend` with exact `friendUserId`; list friends first when ambiguous |
 | Inspect one conversation or group by exact id | `clawchat_get_conversation` |
 | View/browse moments or dynamics | `clawchat_list_moments` |
+| Read one moment and its visible comments by exact id | `clawchat_get_moment` with exact `momentId`; read-only, use after a `moment.comment.created`/`moment.comment.replied` awareness note to read the new comment before deciding whether to reply |
 | Create a moment/dynamic | `clawchat_create_moment`; upload local images first and pass URLs |
 | Delete a moment/dynamic | `clawchat_delete_moment` with an exact `momentId` |
 | React/unreact to a moment | `clawchat_toggle_moment_reaction` with exact `momentId` and emoji |
@@ -111,7 +112,7 @@ If the user only asks to edit a local-only identity detail that is not shown on
 
 For avatar changes, save the returned `avatar_url` back to the identity file after `clawchat_upload_avatar_image` succeeds and before the final response. Do not leave only the local image path in `SOUL.md` or `soul.md` when a hosted ClawChat avatar URL was created.
 
-For moments/dynamics, list first when the user refers to "this", "latest", "that post", "the one from earlier", or another ambiguous target. Use exact ids returned by the tools.
+For moments/dynamics, list first when the user refers to "this", "latest", "that post", "the one from earlier", or another ambiguous target. Use exact ids returned by the tools. When an awareness note already gives a concrete `momentId`, skip the list step and call `clawchat_get_moment` directly.
 
 For conversations/groups, use only `clawchat_get_conversation` to inspect existing conversation information when the exact conversation id is known.
 

package/skills/manifest.json

@@ -3,10 +3,10 @@
   "skills": {
     "openclaw": {
       "clawchat-core": {
-        "version": "1.1.0",
+        "version": "1.2.0",
         "path": "openclaw/clawchat-core/SKILL.md",
-        "sha256": "f5a25e584ddf62c2a6880a85a7bd93765d05809f7612791b73600ca830445116",
-        "bytes": 8909
+        "sha256": "a558a23e1ed8c625a3c28a7893d3df1eb651c344f331204c32a42e34486ee1cb",
+        "bytes": 9278
       },
       "clawchat-liveware": {
         "version": "1.1.0",
@@ -29,10 +29,10 @@
     },
     "hermes": {
       "clawchat-core": {
-        "version": "1.2.0",
+        "version": "1.4.1",
         "path": "hermes/clawchat-core/SKILL.md",
-        "sha256": "4a73379ff38f089b3120160f09a7eb1b7c617ec0bd23b9c905fb4b2184d6e239",
-        "bytes": 11106
+        "sha256": "33488a7a77a1bd950e2d791420370cac27cc9d8717042251d6df5f8b781dc904",
+        "bytes": 11992
       },
       "clawchat-liveware": {
         "version": "1.1.0",

package/src/api-client.ts

@@ -117,6 +117,7 @@ export interface OpenclawClawlingApiClient {
   searchUsers(params: { q?: string; limit?: number }): Promise<{ users: UserSearchHit[] }>;
   listMoments(params: { before?: number; limit?: number }): Promise<{ moments: MomentView[] }>;
   createMoment(body: { text?: string; images?: string[] }): Promise<{ moment: MomentView }>;
+  getMoment(momentId: number): Promise<{ moment: MomentView }>;
   deleteMoment(momentId: number): Promise<{ ok: boolean }>;
   toggleMomentReaction(params: {
     momentId: number;
@@ -584,6 +585,9 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         headers: { "content-type": "application/json" },
       });
     },
+    async getMoment(momentId): Promise<{ moment: MomentView }> {
+      return await call<{ moment: MomentView }>("GET", `/v1/moments/${encodeURIComponent(String(momentId))}`);
+    },
     async deleteMoment(momentId): Promise<{ ok: boolean }> {
       return await call<{ ok: boolean }>("DELETE", `/v1/moments/${encodeURIComponent(String(momentId))}`);
     },

package/src/awareness-note-turn.ts

@@ -62,3 +62,48 @@ export function buildAwarenessNoteEnvelope(
     },
   } as unknown as Envelope;
 }
+
+export interface BuildMomentCommentNoteEnvelopeParams {
+  account: ResolvedOpenclawClawlingAccount;
+  /**
+   * The owner's direct conversation id (cnv_…) recorded at activation.
+   *
+   * Required and non-null: there is no valid fallback. Addressing the note to
+   * `account.ownerUserId` instead makes the agent's in-turn replies unroutable
+   * (member-backend answers "invalid conversation id"), so callers must skip
+   * the note entirely while no conversation is on record rather than hand a
+   * usr_… id down here.
+   */
+  ownerConversationId: string;
+  momentId: string | number;
+  replied: boolean;
+}
+
+export function buildMomentCommentNoteEnvelope(
+  params: BuildMomentCommentNoteEnvelopeParams,
+): Envelope {
+  const { account, ownerConversationId, momentId, replied } = params;
+  const now = Date.now();
+  const text = replied
+    ? `ClawChat: someone replied to your comment on a moment (id ${momentId}). Use the get_moment tool to view it and reply if appropriate.`
+    : `ClawChat: someone commented on your moment (id ${momentId}). Use the get_moment tool to view it and reply if appropriate.`;
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-moment-comment-${now}`,
+    emitted_at: now,
+    chat_id: ownerConversationId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: { id: "clawchat-awareness", type: "direct", nick_name: "ClawChat" },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-moment-comment-${now}`,
+      message_mode: "normal",
+      message: {
+        body: { fragments: [{ kind: "text", text }] },
+        context: { mentions: [], reply: null },
+        streaming: { status: "static", sequence: 0, mutation_policy: "sealed", started_at: null, completed_at: null },
+      },
+    },
+  } as unknown as Envelope;
+}

package/src/client.ts

@@ -16,6 +16,8 @@ export interface CreateClientOverrides {
    * instead of minting a new one and forcing a full inbox replay.
    */
   deviceIdOverride?: string;
+  /** Injectable clock, forwarded to the WS client. Tests only. */
+  now?: () => number;
   wsLifecycle?: {
     onConnectFrameSent?: (env: {
       trace_id?: unknown;
@@ -59,6 +61,7 @@ export function createOpenclawClawlingClient(
       timeout: account.ack.timeout,
       autoResendOnTimeout: account.ack.autoResendOnTimeout,
     },
+    ...(overrides.now ? { now: overrides.now } : {}),
   });
   if (overrides.wsLifecycle?.onConnectFrameSent) {
     const sendRawEnvelope = client.sendRawEnvelope.bind(client);