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

package/dist/src/storage.js

@@ -126,6 +126,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;
 `,
     },
 ];
@@ -193,12 +200,13 @@ 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,
@@ -209,15 +217,53 @@ 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(input.platform, input.accountId, userId, ownerUserId, accessToken, refreshToken, now, input.loginMethod ?? null, conversationId, conversationId ? 0 : 1, null, now);
+                .run(input.platform, input.accountId, userId, ownerUserId, accessToken, refreshToken, now, input.loginMethod ?? null, 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) {
+        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) {
+        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) {
         return this.read(() => {
             const row = this.requireDb()
-                .prepare(`SELECT user_id, owner_user_id, access_token, refresh_token
+                .prepare(`SELECT user_id, owner_user_id, access_token, refresh_token, activated_at, device_id
           FROM activations
           WHERE platform = ?
             AND account_id = ?`)
@@ -228,9 +274,15 @@ export class ClawChatStore {
             const refreshToken = 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;
     }
     getActivationConversation(input) {
@@ -398,6 +450,30 @@ export class ClawChatStore {
                 .run(input.state, now, input.closeCode ?? null, input.closeReason ?? null, input.error ?? null, now, connectionId);
         });
     }
+    /**
+     * 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) {
+        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);
+            return typeof row?.resolved_device_id === "string" && row.resolved_device_id.trim()
+                ? row.resolved_device_id.trim()
+                : null;
+        }) ?? null;
+    }
     recordToolCall(input) {
         this.write(() => {
             const startedAt = input.startedAt ?? Date.now();

package/dist/src/ws-alignment.js

@@ -159,7 +159,8 @@ export function createProtocolControlHandler(options) {
                     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: {},
                 }));
                 return true;
@@ -176,3 +177,70 @@ export function createProtocolControlHandler(options) {
         },
     };
 }
+/**
+ * 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) {
+    const maxSeen = options.maxSeen ?? 512;
+    const seen = new Set();
+    const order = [];
+    const context = () => options.context?.() ?? { attempt: 1, reconnectCount: 0, state: "ready" };
+    const logSignal = (event, action, fields) => {
+        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) {
+            const payload = env.payload && typeof env.payload === "object"
+                ? env.payload
+                : 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/dist/src/ws-client.js

@@ -301,6 +301,10 @@ 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.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");
     }
@@ -322,7 +326,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;
@@ -374,7 +390,34 @@ 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;
@@ -421,10 +464,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
+            : 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));
     }
     startHeartbeat() {
         if (!this.opts.heartbeat.enabled)

package/index.ts

@@ -20,5 +20,12 @@ export default defineChannelPluginEntry({
     registerOpenclawClawlingCommands(api);
     registerClawChatPromptInjection(api as unknown as ClawChatPromptInjectionApi);
     registerOpenclawClawlingTools(api);
+    // NOTE: the legacy-rename config migration is intentionally NOT registered
+    // here. The host's setup-migration runner only loads a plugin's SETUP source
+    // (`openclaw.setupEntry`/`runtimeSetupEntry` → setup-entry.ts) and calls its
+    // `register(api)` in "setup-only" mode; registrations made in `registerFull`
+    // (full/tool-discovery modes) are never collected for migrations, and this
+    // gated full-load path doesn't run for the rename scenario anyway. The
+    // migration is wired into setup-entry.ts instead.
   },
 });

package/openclaw.plugin.json

@@ -1,6 +1,13 @@
 {
   "id": "clawchat-plugin-openclaw",
   "kind": "channel",
+  "legacyPluginIds": ["openclaw-clawchat"],
+  "configContracts": {
+    "compatibilityMigrationPaths": [
+      "channels.openclaw-clawchat",
+      "plugins.entries.openclaw-clawchat"
+    ]
+  },
   "channels": ["clawchat-plugin-openclaw"],
   "skills": ["./skills"],
   "activation": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.5.12-39",
+  "version": "2026.5.13-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "files": [

package/setup-entry.ts

@@ -1,4 +1,54 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { CHANNEL_ID } from "./src/config.ts";
 import { openclawClawlingSetupPlugin } from "./src/channel.setup.ts";
+import { migrateLegacyClawChatChannelConfig } from "./src/config-compat.ts";
 
-export default defineSetupPluginEntry(openclawClawlingSetupPlugin);
+/**
+ * Minimal shape of the host setup-registration api we touch. The host calls
+ * `register(api)` on the SETUP source (this module) in `registrationMode:
+ * "setup-only"`; `registerConfigMigration` is the hook that collects
+ * compatibility migrations (run by `openclaw doctor` / setup). It is optional
+ * here so a host that doesn't expose it can't throw.
+ */
+interface SetupRegisterApi {
+  registerConfigMigration?: (
+    migration: (config: OpenClawConfig) => {
+      config: OpenClawConfig;
+      changes: string[];
+    },
+  ) => void;
+}
+
+/**
+ * Host setup-source `register` hook.
+ *
+ * The OpenClaw setup-migration runner (`setup-registry`) loads this module as
+ * the plugin's setup source (resolved from `package.json` `openclaw.setupEntry`
+ * / `runtimeSetupEntry`), unwraps the default export, and — when that export is
+ * an object exposing a `register` function whose `id` matches the plugin id —
+ * calls `register(api)` in setup-only mode. This is the ONLY ungated path that
+ * collects config migrations for the plugin-rename scenario.
+ *
+ * Mirrors the host's own built-in pattern (e.g. amazon-bedrock setup-api.js:
+ * `api.registerConfigMigration((config) => migrateAmazonBedrockLegacyConfig(config))`).
+ */
+export function register(api: SetupRegisterApi): void {
+  api.registerConfigMigration?.((config) =>
+    migrateLegacyClawChatChannelConfig(config),
+  );
+}
+
+/**
+ * Default export consumed by BOTH host loaders of this setup source:
+ *  - the channel-setup loader unwraps `default` and reads `.plugin`
+ *    (`defineSetupPluginEntry` yields `{ plugin }`);
+ *  - the setup-migration runner unwraps `default` and reads `.register`,
+ *    rejecting it unless `.id` matches the plugin id.
+ * So the default export must carry `plugin`, `id`, and `register` together.
+ */
+export default {
+  ...defineSetupPluginEntry(openclawClawlingSetupPlugin),
+  id: CHANNEL_ID,
+  register,
+};