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

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: {},
           }),
         );

package/src/ws-client.ts

@@ -394,6 +394,10 @@ export class ClawChatClient extends EventEmitter {
       // 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,
@@ -451,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;
@@ -499,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 {