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

package/src/storage.ts

@@ -21,6 +21,8 @@ export type ActivationInput = {
   conversationId?: string | null;
   activatedAt?: number;
   loginMethod?: string | null;
+  /** §E — exact `X-Device-Id` used at connect time (OpenClaw: `CHANNEL_ID`). */
+  deviceId?: string | null;
 };
 
 export type ActivationCredentials = {
@@ -28,6 +30,25 @@ export type ActivationCredentials = {
   ownerUserId: string;
   accessToken: string;
   refreshToken: string | null;
+  /** §A.0 — epoch ms the row was activated; expiry fallback (`activatedAt + 24h`). */
+  activatedAt: number | null;
+  /** §E — connect-time device id used as `X-Device-Id` on refresh. */
+  deviceId: string | null;
+};
+
+/** §0/§A.3 — persist a rotated `{access,refresh}` pair BEFORE the in-memory swap. */
+export type RotateActivationTokensInput = {
+  platform: string;
+  accountId: string;
+  accessToken: string;
+  refreshToken: string;
+  rotatedAt?: number;
+};
+
+/** §C.1 — blank the credential columns but KEEP identity for re-pair. */
+export type ClearActivationCredentialsInput = {
+  platform: string;
+  accountId: string;
 };
 
 export type ActivationBootstrapInput = {
@@ -242,6 +263,13 @@ ALTER TABLE clawchat_messages ADD COLUMN send_status TEXT;
 ALTER TABLE clawchat_messages ADD COLUMN protocol_message_id TEXT;
 ALTER TABLE clawchat_messages ADD COLUMN acked_at INTEGER;
 ALTER TABLE clawchat_messages ADD COLUMN send_error TEXT;
+`,
+  },
+  {
+    version: 7,
+    name: "activation_device_id",
+    sql: `
+ALTER TABLE activations ADD COLUMN device_id TEXT;
 `,
   },
 ];
@@ -320,13 +348,14 @@ export class ClawChatStore {
       const ownerUserId = input.ownerUserId?.trim() || null;
       const accessToken = input.accessToken?.trim() || null;
       const refreshToken = input.refreshToken?.trim() || null;
+      const deviceId = input.deviceId?.trim() || null;
       this.requireDb()
         .prepare(
           `INSERT INTO activations(
             platform, account_id, user_id, owner_user_id, access_token, refresh_token,
             activated_at, login_method, conversation_id, bootstrap_sent,
-            bootstrap_claimed_at, updated_at
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            bootstrap_claimed_at, device_id, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
           ON CONFLICT(platform, account_id) DO UPDATE SET
             user_id = excluded.user_id,
             owner_user_id = excluded.owner_user_id,
@@ -337,6 +366,7 @@ export class ClawChatStore {
             conversation_id = excluded.conversation_id,
             bootstrap_sent = excluded.bootstrap_sent,
             bootstrap_claimed_at = NULL,
+            device_id = excluded.device_id,
             updated_at = excluded.updated_at`,
         )
         .run(
@@ -351,17 +381,68 @@ export class ClawChatStore {
           conversationId,
           conversationId ? 0 : 1,
           null,
+          deviceId,
           now,
         );
       void conversationId;
     });
   }
 
+  /**
+   * §0/§A.3 — persist a rotated access+refresh pair durably BEFORE the caller
+   * swaps the in-memory token. Identity columns are untouched. Returns whether
+   * a row was updated (false ⇒ no activation row exists yet).
+   */
+  rotateActivationTokens(input: RotateActivationTokensInput): boolean | null {
+    return this.write(() => {
+      const now = input.rotatedAt ?? Date.now();
+      const result = this.requireDb()
+        .prepare(
+          `UPDATE activations SET
+            access_token = ?,
+            refresh_token = ?,
+            activated_at = ?,
+            updated_at = ?
+          WHERE platform = ? AND account_id = ?`,
+        )
+        .run(
+          input.accessToken,
+          input.refreshToken,
+          now,
+          now,
+          input.platform,
+          input.accountId,
+        );
+      return result.changes > 0;
+    });
+  }
+
+  /**
+   * §C.1 — auto-logout: blank the `access_token` / `refresh_token` columns so
+   * the agent can no longer mint tokens, but KEEP `user_id` / `owner_user_id` /
+   * `device_id` so a `/clawchat-activate <code>` re-pair reuses the identity.
+   */
+  clearActivationCredentials(input: ClearActivationCredentialsInput): boolean | null {
+    return this.write(() => {
+      const now = Date.now();
+      const result = this.requireDb()
+        .prepare(
+          `UPDATE activations SET
+            access_token = NULL,
+            refresh_token = NULL,
+            updated_at = ?
+          WHERE platform = ? AND account_id = ?`,
+        )
+        .run(now, input.platform, input.accountId);
+      return result.changes > 0;
+    });
+  }
+
   getActivationCredentials(input: ConversationAccountInput): ActivationCredentials | null {
     return this.read(() => {
       const row = this.requireDb()
         .prepare(
-          `SELECT user_id, owner_user_id, access_token, refresh_token
+          `SELECT user_id, owner_user_id, access_token, refresh_token, activated_at, device_id
           FROM activations
           WHERE platform = ?
             AND account_id = ?`,
@@ -372,6 +453,8 @@ export class ClawChatStore {
             owner_user_id?: unknown;
             access_token?: unknown;
             refresh_token?: unknown;
+            activated_at?: unknown;
+            device_id?: unknown;
           }
         | undefined;
       const userId = typeof row?.user_id === "string" ? row.user_id.trim() : "";
@@ -383,8 +466,16 @@ export class ClawChatStore {
         typeof row?.refresh_token === "string" && row.refresh_token.trim()
           ? row.refresh_token.trim()
           : null;
+      const activatedAt =
+        typeof row?.activated_at === "number" && Number.isFinite(row.activated_at)
+          ? row.activated_at
+          : null;
+      const deviceId =
+        typeof row?.device_id === "string" && row.device_id.trim()
+          ? row.device_id.trim()
+          : null;
       if (!userId || !ownerUserId || !accessToken) return null;
-      return { userId, ownerUserId, accessToken, refreshToken };
+      return { userId, ownerUserId, accessToken, refreshToken, activatedAt, deviceId };
     }) ?? null;
   }
 
@@ -670,6 +761,35 @@ export class ClawChatStore {
     });
   }
 
+  /**
+   * Return the most recent server-resolved `device_id` recorded from a
+   * `hello-ok` for this account, if any. Reused on reconnect so a pod restart
+   * (which mints a fresh hostname and therefore a fresh derived device id)
+   * does not present a brand-new device to the server — that would trigger a
+   * full inbox replay and orphan the previous device's cursor.
+   */
+  getLastResolvedDeviceId(input: ConversationAccountInput): string | null {
+    return this.read(() => {
+      const row = this.requireDb()
+        .prepare(
+          `SELECT resolved_device_id
+          FROM connections
+          WHERE platform = ?
+            AND account_id = ?
+            AND resolved_device_id IS NOT NULL
+            AND resolved_device_id <> ''
+          ORDER BY id DESC
+          LIMIT 1`,
+        )
+        .get(input.platform, input.accountId) as
+        | { resolved_device_id?: unknown }
+        | undefined;
+      return typeof row?.resolved_device_id === "string" && row.resolved_device_id.trim()
+        ? row.resolved_device_id.trim()
+        : null;
+    }) ?? null;
+  }
+
   recordToolCall(input: ToolCallInput): void {
     this.write(() => {
       const startedAt = input.startedAt ?? Date.now();

package/src/ws-alignment.ts

@@ -254,7 +254,8 @@ export function createProtocolControlHandler(options: CreateProtocolControlHandl
             version: "2",
             event: "pong",
             trace_id: env.trace_id ?? "-",
-            emitted_at: Date.now(),
+            // §12: echo the sender's emitted_at verbatim (do not restamp).
+            emitted_at: env.emitted_at ?? Date.now(),
             payload: {},
           }),
         );
@@ -273,3 +274,100 @@ export function createProtocolControlHandler(options: CreateProtocolControlHandl
     },
   };
 }
+
+export interface NotifySignalEnvelope {
+  event?: string;
+  trace_id?: string;
+  payload?: unknown;
+}
+
+export interface CreateNotifySignalObserverOptions {
+  accountId: string;
+  log: (msg: string) => void;
+  context?: () => WsLogContext;
+  /** Upper bound on retained event_ids for dedup (FIFO eviction). */
+  maxSeen?: number;
+}
+
+export type NotifySignalOutcome = "observed" | "duplicate" | "invalid";
+
+/**
+ * Observes reliable `notify.signal` frames (§9.4). The agent plugin keeps no
+ * friend/roster cache (friends are fetched on demand via REST tools), so there
+ * is nothing to invalidate — this is a pure observability hook: it dedups by
+ * `event_id` (the live frame and its reliable-inbox replay collapse to one),
+ * structured-logs the signal, and returns the outcome. It deliberately takes no
+ * action on the agent; wire a real reaction here if the product later needs one.
+ */
+export function createNotifySignalObserver(options: CreateNotifySignalObserverOptions) {
+  const maxSeen = options.maxSeen ?? 512;
+  const seen = new Set<string>();
+  const order: string[] = [];
+
+  const context = (): WsLogContext =>
+    options.context?.() ?? { attempt: 1, reconnectCount: 0, state: "ready" };
+
+  const logSignal = (
+    event: string,
+    action: string,
+    fields: Array<[string, string | number | boolean | null | undefined]>,
+  ) => {
+    const current = context();
+    options.log(
+      formatWsLog({
+        event,
+        accountId: options.accountId,
+        attempt: current.attempt,
+        reconnectCount: current.reconnectCount,
+        state: current.state,
+        action,
+        fields,
+      }),
+    );
+  };
+
+  return {
+    /** Returns whether this signal was newly observed, a duplicate, or malformed. */
+    observe(env: NotifySignalEnvelope): NotifySignalOutcome {
+      const payload = env.payload && typeof env.payload === "object"
+        ? env.payload as Record<string, unknown>
+        : undefined;
+      const eventId = typeof payload?.event_id === "string" ? payload.event_id : "";
+      const type = typeof payload?.type === "string" ? payload.type : "";
+      const entityId = typeof payload?.entity_id === "string" ? payload.entity_id : "";
+      const version = typeof payload?.version === "number" ? payload.version : undefined;
+
+      if (!eventId || !type) {
+        logSignal("notify_signal_invalid", "ignore", [
+          ["trace_id", env.trace_id],
+          ["type", type || null],
+          ["event_id", eventId || null],
+        ]);
+        return "invalid";
+      }
+
+      if (seen.has(eventId)) {
+        logSignal("notify_signal_duplicate", "ignore", [
+          ["type", type],
+          ["event_id", eventId],
+        ]);
+        return "duplicate";
+      }
+
+      seen.add(eventId);
+      order.push(eventId);
+      while (order.length > maxSeen) {
+        const evicted = order.shift();
+        if (evicted !== undefined) seen.delete(evicted);
+      }
+
+      logSignal("notify_signal_observed", "observe", [
+        ["type", type],
+        ["entity_id", entityId || null],
+        ["version", version ?? null],
+        ["event_id", eventId],
+      ]);
+      return "observed";
+    },
+  };
+}

package/src/ws-client.ts

@@ -369,6 +369,8 @@ 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.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");
   }
 
@@ -389,7 +391,19 @@ export class ClawChatClient extends EventEmitter {
       token: this.opts.token,
       nonce,
       ...(this.opts.deviceId ? { device_id: this.opts.deviceId } : {}),
-      capabilities: { multi_device: true, device_replay: true, chat_meta_events: true },
+      // Agent runtime is single-device: multi_device stays off so the server
+      // never self-fans-out this connection's own messages. notify_signals is
+      // advertised because we now handle the notify.signal frame (§9.4).
+      // history_sync (§11.4) is intentionally omitted: it is only required to
+      // *send* history.transit, which a single-device agent never does, and we
+      // do not handle inbound history.transit — advertising it would invite
+      // frames we cannot process. This is a deliberate, spec-legal omission.
+      capabilities: {
+        multi_device: false,
+        device_replay: true,
+        chat_meta_events: true,
+        notify_signals: true,
+      },
     };
     const traceId = this.nextTraceId();
     this.expectedConnectTraceId = traceId;
@@ -441,7 +455,32 @@ export class ClawChatClient extends EventEmitter {
       this.failHandshake(new ProtocolError("invalid hello-fail payload", env), 4002, "protocol error");
       return;
     }
-    const err = new AuthError(typeof reason === "string" ? reason : "authentication failed");
+    // §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
+    // (member-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)) {
+      const err = new TransportError(reason);
+      this.expectedConnectTraceId = undefined;
+      this.clearTimers();
+      this.rejectPending(err);
+      this.connectReject?.(err);
+      this.connectResolve = undefined;
+      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");
+      } else if (!this.closing && this.opts.reconnect.enabled) {
+        this.scheduleReconnect(reason);
+      } else {
+        this.transition("disconnected");
+      }
+      return;
+    }
+    const err = new AuthError(reason);
     this.authFailed = true;
     this.expectedConnectTraceId = undefined;
     this.sendQueue.length = 0;
@@ -489,10 +528,17 @@ 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 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";
-    const message = typeof payload?.message === "string" && payload.message ? payload.message : "message send failed";
-    entry.reject(new MessageSendError(env.trace_id, code, message, env.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";
+    entry.reject(new MessageSendError(env.trace_id, code, hint, env.chat_id));
   }
 
   private startHeartbeat(): void {

package/dist/src/buffered-stream.js

@@ -1,177 +0,0 @@
-import { emitStreamAdd, emitStreamCreated, emitStreamDone, emitStreamFailed, } from "./client.js";
-/**
- * Merge two views of the same progressively-revealed text.
- *
- * The agent runner may give us either:
- *   - full snapshots   ("Hel", "Hello", "Hello, world") where each item is
- *     a superset of the previous; or
- *   - overlapping slices ("hello ", "world hello ") that don't share a
- *     prefix but share an overlap at the join.
- *
- * This helper returns a longest-sensible combined string. Ported from
- * `clawling-channel/src/reply-dispatcher.ts`.
- */
-export function mergeStreamingText(previousText, nextText) {
-    const currentSnapshot = typeof previousText === "string" ? previousText : "";
-    const incomingText = typeof nextText === "string" ? nextText : "";
-    if (!incomingText)
-        return currentSnapshot;
-    if (!currentSnapshot || incomingText === currentSnapshot)
-        return incomingText;
-    if (incomingText.startsWith(currentSnapshot))
-        return incomingText;
-    if (currentSnapshot.startsWith(incomingText))
-        return currentSnapshot;
-    if (incomingText.includes(currentSnapshot))
-        return incomingText;
-    if (currentSnapshot.includes(incomingText))
-        return currentSnapshot;
-    const maxOverlap = Math.min(currentSnapshot.length, incomingText.length);
-    for (let overlap = maxOverlap; overlap > 0; overlap -= 1) {
-        if (currentSnapshot.slice(-overlap) === incomingText.slice(0, overlap)) {
-            return `${currentSnapshot}${incomingText.slice(overlap)}`;
-        }
-    }
-    return `${currentSnapshot}${incomingText}`;
-}
-function resolveRouting(options) {
-    if (options.routing)
-        return options.routing;
-    if (options.to)
-        return { chatId: options.to.id, chatType: options.to.type };
-    throw new Error("openclaw-clawchat buffered stream requires routing");
-}
-/**
- * Build a streaming session wrapper around message.created/add/done events.
- *
- * Usage pattern (matching clawling-channel):
- *   const session = openBufferedStreamingSession({...});
- *   await session.queueSnapshot("Hel");
- *   await session.queueSnapshot("Hello");
- *   await session.queueDelta(", world");
- *   await session.done();
- */
-export function openBufferedStreamingSession(options) {
-    const routing = resolveRouting(options);
-    const emitTyping = options.emitTyping !== false;
-    if (emitTyping)
-        options.client.typing(routing.chatId, true);
-    emitStreamCreated(options.client, {
-        messageId: options.messageId,
-        routing,
-    });
-    let bufferedSnapshot = "";
-    let flushedSnapshot = "";
-    let sequence = -1;
-    let flushTimer = null;
-    let pendingFlush = Promise.resolve();
-    let closed = false;
-    const clearTimer = () => {
-        if (flushTimer) {
-            clearTimeout(flushTimer);
-            flushTimer = null;
-        }
-    };
-    const performFlush = async () => {
-        clearTimer();
-        if (closed)
-            return;
-        if (bufferedSnapshot === flushedSnapshot)
-            return;
-        const snapshot = bufferedSnapshot;
-        const delta = snapshot.slice(flushedSnapshot.length);
-        if (!delta)
-            return;
-        sequence += 1;
-        emitStreamAdd(options.client, {
-            messageId: options.messageId,
-            routing,
-            sequence,
-            fullText: snapshot,
-            textDelta: delta,
-        });
-        flushedSnapshot = snapshot;
-    };
-    const flush = async () => {
-        pendingFlush = pendingFlush.then(performFlush);
-        await pendingFlush;
-    };
-    const scheduleFlush = () => {
-        if (flushTimer || closed)
-            return;
-        flushTimer = setTimeout(() => {
-            flushTimer = null;
-            void flush();
-        }, options.flushIntervalMs);
-    };
-    const queueSnapshot = async (snapshot) => {
-        if (closed || !snapshot)
-            return;
-        const base = bufferedSnapshot.length >= flushedSnapshot.length ? bufferedSnapshot : flushedSnapshot;
-        const merged = mergeStreamingText(base, snapshot);
-        if (merged === bufferedSnapshot)
-            return;
-        bufferedSnapshot = merged;
-        const deltaChars = Math.max(0, bufferedSnapshot.length - flushedSnapshot.length);
-        if (deltaChars >= options.minChunkChars || bufferedSnapshot.length >= options.maxBufferChars) {
-            await flush();
-        }
-        else {
-            scheduleFlush();
-        }
-    };
-    const queueDelta = async (delta) => {
-        if (closed || !delta)
-            return;
-        bufferedSnapshot = `${bufferedSnapshot}${delta}`;
-        const deltaChars = Math.max(0, bufferedSnapshot.length - flushedSnapshot.length);
-        if (deltaChars >= options.minChunkChars || bufferedSnapshot.length >= options.maxBufferChars) {
-            await flush();
-        }
-        else {
-            scheduleFlush();
-        }
-    };
-    const done = async () => {
-        if (closed)
-            return;
-        await flush();
-        closed = true;
-        clearTimer();
-        emitStreamDone(options.client, {
-            messageId: options.messageId,
-            routing,
-            finalSequence: Math.max(sequence, 0),
-            finalText: bufferedSnapshot,
-        });
-        if (emitTyping)
-            options.client.typing(routing.chatId, false);
-    };
-    const fail = async (reason) => {
-        if (closed)
-            return;
-        closed = true;
-        clearTimer();
-        emitStreamFailed(options.client, {
-            messageId: options.messageId,
-            routing,
-            sequence: Math.max(sequence, 0),
-            ...(reason !== undefined ? { reason } : {}),
-        });
-        if (emitTyping)
-            options.client.typing(routing.chatId, false);
-    };
-    return {
-        get currentText() {
-            return bufferedSnapshot;
-        },
-        get flushedText() {
-            return flushedSnapshot;
-        },
-        queueSnapshot,
-        queueDelta,
-        flush,
-        done,
-        fail,
-    };
-}

package/dist/src/streaming.js

@@ -1,65 +0,0 @@
-import { emitStreamAdd, emitStreamCreated, emitStreamDone, emitStreamFailed, } from "./client.js";
-function resolveRouting(params) {
-    if (params.routing)
-        return params.routing;
-    if (params.to)
-        return { chatId: params.to.id, chatType: params.to.type };
-    throw new Error("openclaw-clawchat streaming requires routing");
-}
-/**
- * Emit one full streaming lifecycle for a pre-chunked reply.
- *
- * Sequence:
- *   typing(true)
- *   message.created   (sequence 0)
- *   message.add       (sequence 1..N, one per chunk)
- *   message.done      (sequence N)
- *   typing(false)
- *
- * With zero chunks: typing(true) -> created -> done -> typing(false).
- */
-export async function sendStreamingText(params) {
-    const routing = resolveRouting(params);
-    const emitTyping = params.emitTyping !== false;
-    if (emitTyping) {
-        params.client.typing(routing.chatId, true);
-    }
-    emitStreamCreated(params.client, {
-        messageId: params.messageId,
-        routing,
-    });
-    let sequence = -1;
-    let fullText = "";
-    for (const chunk of params.chunks) {
-        sequence += 1;
-        fullText += chunk;
-        emitStreamAdd(params.client, {
-            messageId: params.messageId,
-            routing,
-            sequence,
-            fullText,
-            textDelta: chunk,
-        });
-    }
-    emitStreamDone(params.client, {
-        messageId: params.messageId,
-        routing,
-        finalSequence: Math.max(sequence, 0),
-        finalText: fullText,
-    });
-    if (emitTyping) {
-        params.client.typing(routing.chatId, false);
-    }
-}
-export async function sendStreamingFailure(params) {
-    const routing = resolveRouting(params);
-    emitStreamFailed(params.client, {
-        messageId: params.messageId,
-        routing,
-        sequence: params.currentSequence,
-        reason: params.reason,
-    });
-    if (params.emitTyping !== false) {
-        params.client.typing(routing.chatId, false);
-    }
-}