@clawling/clawchat-plugin-openclaw 2026.5.12-39 → 2026.5.13-dev.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/package.json

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

package/skills/clawchat/SKILL.md

@@ -13,7 +13,6 @@ This skill guides agent behavior for ClawChat-aware tasks. Use the registered Cl
 
 - Use registered ClawChat plugin tools for account/profile, friends, users, moments, comments, reactions, avatar, media, and read-only conversation lookup.
 - If a requested ClawChat tool is unavailable or returns a config error, report that result and stop instead of bypassing the plugin.
-- Use the `/clawchat-output` slash command when the user asks to change how much ClawChat runtime output is shown in the current conversation.
 
 ## OpenClaw CLI
 
@@ -31,18 +30,6 @@ Use `update --force` only when local ClawChat plugin or skill files look corrupt
 
 If `channels add` reports `Unknown channel: clawchat-plugin-openclaw`, use the runtime slash command `/clawchat-activate CODE` after the operator ensures the plugin is loaded.
 
-## Output Visibility
-
-When the user asks to change ClawChat output verbosity, use the runtime slash command for the current conversation. Treat natural-language wording as aliases for the three supported modes:
-
-| User wording | Command |
-| --- | --- |
-| quiet mode, silent mode, minimal output, final-only output, `minimal` | `/clawchat-output minimal` |
-| conversation mode, normal mode, regular mode, default output, `normal` | `/clawchat-output normal` |
-| dev mode, developer mode, verbose mode, full output, `full` | `/clawchat-output full` |
-
-Do not edit config files directly for this request. If the slash command returns an error, report that error instead of claiming the mode changed.
-
 ## Plugin Tool Routing
 
 Tool descriptions are authoritative. These routing hints resolve common ambiguity:

package/src/api-client.ts

@@ -28,6 +28,47 @@ export interface ApiClientOptions {
   fetchImpl?: typeof fetch;
 }
 
+/**
+ * §A.0 — decode the access token's `exp` claim locally (base64url-decode the
+ * JWT payload segment, read `exp` as epoch seconds). Returns `null` when the
+ * token is not a parseable JWT or carries no numeric `exp`, in which case the
+ * caller falls back to `activated_at + 24h`. We never persist a separate
+ * expiry column; this is derived from the token on every load.
+ */
+export function decodeJwtExp(token: string): number | null {
+  if (typeof token !== "string") return null;
+  const segments = token.split(".");
+  if (segments.length < 2) return null;
+  const payloadSegment = segments[1];
+  if (!payloadSegment) return null;
+  try {
+    const json = Buffer.from(payloadSegment, "base64url").toString("utf8");
+    const parsed = JSON.parse(json) as { exp?: unknown };
+    const exp = parsed?.exp;
+    return typeof exp === "number" && Number.isFinite(exp) ? exp : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * §0/§B — outcome classes for `POST /v1/auth/refresh`. The endpoint is
+ * always HTTP 200; callers branch on the envelope `code`. Distinct kinds keep
+ * the permanent/transient decision (and auto-logout vs. backoff) explicit.
+ */
+export type AuthRefreshResult =
+  | { kind: "success"; accessToken: string; refreshToken: string }
+  // `code:10003` invalid refresh OR `code:400` bad request — PERMANENT.
+  | { kind: "permanent"; code: number; message: string }
+  // `code:1` internal, any non-200, or a network error — TRANSIENT.
+  | { kind: "transient"; message: string; status?: number; code?: number };
+
+export interface AuthRefreshParams {
+  refreshToken: string;
+  /** The connect-time `X-Device-Id` (OpenClaw: `CHANNEL_ID`). */
+  deviceId: string;
+}
+
 export interface OpenclawClawlingApiClient {
   getMyProfile(): Promise<Profile>;
   getAgentProfile(agentId: string): Promise<{ agent: AgentProfile }>;
@@ -92,6 +133,102 @@ export interface OpenclawClawlingApiClient {
   }): Promise<AvatarUploadResult>;
 }
 
+/** Backend envelope codes for `POST /v1/auth/refresh` (§0). */
+const CODE_OK = 0;
+const CODE_INTERNAL = 1; // CodeInternal — transient.
+const CODE_BAD_REQUEST = 400; // bad body / device id — permanent (client bug).
+const CODE_INVALID_REFRESH = 10003; // CodeInvalidRefresh — permanent.
+
+/**
+ * §0/§B — call `POST /v1/auth/refresh` to rotate the access+refresh token.
+ *
+ * Unauthenticated: the refresh token in the body IS the credential, so we send
+ * NO `Authorization` header. `X-Device-Id` MUST equal the connect-time device
+ * id (the backend rejects on `sess.DeviceID != X-Device-Id`). The endpoint is
+ * always HTTP 200 — branch on the envelope `code`, NOT on HTTP status. This is
+ * a standalone function (not a method on the token-bearing client) precisely
+ * because no bearer token participates.
+ */
+export async function authRefresh(
+  opts: { baseUrl: string; fetchImpl?: typeof fetch },
+  params: AuthRefreshParams,
+): Promise<AuthRefreshResult> {
+  const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  if (!params.refreshToken?.trim()) {
+    return { kind: "permanent", code: CODE_INVALID_REFRESH, message: "missing refresh token" };
+  }
+  let res: Response;
+  try {
+    res = await fetchImpl(`${baseUrl}/v1/auth/refresh`, {
+      method: "POST",
+      // No `Authorization` header — refresh is unauthenticated by design.
+      headers: {
+        "content-type": "application/json",
+        "x-device-id": params.deviceId,
+      },
+      body: JSON.stringify({ refresh_token: params.refreshToken.trim() }),
+    });
+  } catch (err) {
+    // Network error / timeout / DNS — TRANSIENT (no rotation committed).
+    return {
+      kind: "transient",
+      message: `refresh fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (res.status !== 200) {
+    // Any non-200 (500/LB/transport) — TRANSIENT, regardless of body.
+    const text = await res.text().catch(() => "");
+    return {
+      kind: "transient",
+      status: res.status,
+      message: `refresh http ${res.status} ${text.slice(0, 200)}`,
+    };
+  }
+
+  const text = await res.text().catch(() => "");
+  let parsed: { code?: unknown; msg?: unknown; message?: unknown; data?: unknown } | undefined;
+  try {
+    parsed = text ? (JSON.parse(text) as typeof parsed) : undefined;
+  } catch {
+    parsed = undefined;
+  }
+  const code = typeof parsed?.code === "number" ? parsed.code : Number.NaN;
+  const message =
+    (typeof parsed?.msg === "string" && parsed.msg) ||
+    (typeof parsed?.message === "string" && parsed.message) ||
+    `code=${code}`;
+
+  if (!Number.isFinite(code)) {
+    // 200 with no usable envelope — treat as transient (do not auto-logout).
+    return { kind: "transient", status: 200, message: "refresh: missing numeric code" };
+  }
+  if (code === CODE_OK) {
+    const data = parsed?.data && typeof parsed.data === "object"
+      ? (parsed.data as { access_token?: unknown; refresh_token?: unknown })
+      : {};
+    const accessToken = typeof data.access_token === "string" ? data.access_token : "";
+    const refreshToken = typeof data.refresh_token === "string" ? data.refresh_token : "";
+    if (!accessToken || !refreshToken) {
+      // Rotation succeeded server-side but the body is malformed — transient so
+      // we retry; the next attempt will return 10003 (rotation single-use) and
+      // escalate to permanent (§B transient→permanent).
+      return { kind: "transient", status: 200, message: "refresh: rotation body incomplete" };
+    }
+    return { kind: "success", accessToken, refreshToken };
+  }
+  if (code === CODE_INVALID_REFRESH || code === CODE_BAD_REQUEST) {
+    return { kind: "permanent", code, message };
+  }
+  if (code === CODE_INTERNAL) {
+    return { kind: "transient", status: 200, code, message };
+  }
+  // Unknown non-zero code — conservatively transient (never auto-logout on an
+  // unrecognized code; only 10003/400 are permanent per §0).
+  return { kind: "transient", status: 200, code, message };
+}
+
 export function createOpenclawClawlingApiClient(opts: ApiClientOptions): OpenclawClawlingApiClient {
   if (!/^https?:\/\//i.test(opts.baseUrl)) {
     throw new ClawlingApiError(
@@ -134,48 +271,54 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         path,
       });
     }
-    if (!res.ok) {
-      const snippet = await res.text().catch(() => "");
-      throw new ClawlingApiError("transport", `http ${res.status} ${snippet.slice(0, 200)}`, {
-        status: res.status,
-        path,
-      });
-    }
+    // §15.3: HTTP status stays meaningful for proxies, but application code
+    // should branch on the business `code`, not the HTTP status. Parse the body
+    // FIRST — even on a non-2xx — so callers receive the precise business code
+    // (e.g. 41301 vs 41501) rather than a generic transport error. Only fall
+    // back to the HTTP status when no structured envelope is present.
+    const text = await res.text().catch(() => "");
     let parsed: unknown;
     try {
-      parsed = await res.json();
-    } catch (err) {
-      throw new ClawlingApiError(
-        "transport",
-        `non-JSON response: ${err instanceof Error ? err.message : String(err)}`,
-        { status: res.status, path },
-      );
+      parsed = text ? JSON.parse(text) : undefined;
+    } catch {
+      parsed = undefined;
     }
     // Unified envelope: `{ code: number, msg: string, data: T }`.
     // `code === 0` means success; any other value is a business error whose
     // `msg` is surfaced to callers and `code` is preserved on the error meta.
-    const env = parsed as { code?: unknown; msg?: unknown; message?: unknown; data?: T };
-    const code = typeof env.code === "number" ? env.code : Number.NaN;
-    const msg =
-      typeof env.msg === "string"
-        ? env.msg
-        : typeof env.message === "string"
-          ? env.message
-          : "";
-    if (!Number.isFinite(code)) {
-      throw new ClawlingApiError("transport", "invalid envelope: missing numeric `code`", {
-        status: res.status,
-        path,
-      });
+    const env =
+      parsed && typeof parsed === "object"
+        ? (parsed as { code?: unknown; msg?: unknown; message?: unknown; data?: T })
+        : undefined;
+    const code = typeof env?.code === "number" ? env.code : Number.NaN;
+    if (env && Number.isFinite(code)) {
+      const msg =
+        typeof env.msg === "string"
+          ? env.msg
+          : typeof env.message === "string"
+            ? env.message
+            : "";
+      if (code !== 0) {
+        throw new ClawlingApiError("api", msg || `code=${code}`, {
+          code,
+          status: res.status,
+          path,
+        });
+      }
+      return env.data as T;
     }
-    if (code !== 0) {
-      throw new ClawlingApiError("api", msg || `code=${code}`, {
-        code,
+    // No usable envelope — fall back to the HTTP status signal.
+    if (!res.ok) {
+      throw new ClawlingApiError("transport", `http ${res.status} ${text.slice(0, 200)}`, {
         status: res.status,
         path,
       });
     }
-    return env.data as T;
+    throw new ClawlingApiError(
+      "transport",
+      text ? "invalid envelope: missing numeric `code`" : "non-JSON response: empty body",
+      { status: res.status, path },
+    );
   }
 
   async function call<T>(

package/src/client.ts

@@ -9,6 +9,13 @@ export type { ChatType } from "./protocol-types.ts";
 export interface CreateClientOverrides {
   /** Transport override — only intended for tests (e.g. MockTransport). */
   transport?: Transport;
+  /**
+   * Device id to present on `connect`, overriding the hostname-derived default.
+   * Supplied with a previously server-resolved `device_id` (persisted from an
+   * earlier `hello-ok`) so a pod restart reuses the same device identity
+   * instead of minting a new one and forcing a full inbox replay.
+   */
+  deviceIdOverride?: string;
   wsLifecycle?: {
     onConnectFrameSent?: (env: {
       trace_id?: unknown;
@@ -27,10 +34,14 @@ export function createOpenclawClawlingClient(
   account: ResolvedOpenclawClawlingAccount,
   overrides: CreateClientOverrides = {},
 ): ClawlingChatClient {
+  const deviceId =
+    overrides.deviceIdOverride && overrides.deviceIdOverride.trim()
+      ? overrides.deviceIdOverride.trim()
+      : resolveOpenclawClawlingDeviceId(account);
   const client = createClawChatClient({
     url: account.websocketUrl,
     token: account.token,
-    deviceId: resolveOpenclawClawlingDeviceId(account),
+    deviceId,
     ...(overrides.transport ? { transport: overrides.transport } : {}),
     reconnect: {
       enabled: true,

package/src/inbound.ts

@@ -72,14 +72,16 @@ type SenderLike = {
   type?: unknown;
 };
 
-function normalizeSender(sender: unknown): { id: string; nickName: string; profileType: string | null } | null {
+function normalizeSender(sender: unknown): { id: string; nickName: string } | null {
   if (!sender || typeof sender !== "object") return null;
   const s = sender as SenderLike;
   const id = typeof s.id === "string" ? s.id : "";
   if (!id) return null;
   const nickName = typeof s.nick_name === "string" ? s.nick_name : id;
-  const profileType = s.type === "agent" || s.type === "user" ? s.type : null;
-  return { id, nickName, profileType };
+  // §4.1: `sender.type` is the server-stamped routing type and is always
+  // "direct" — it never carries the human/agent distinction. The sender's
+  // profile_type is resolved downstream from chat metadata, not from the wire.
+  return { id, nickName };
 }
 
 function requireChatId(envelope: Envelope<unknown>): string | null {
@@ -166,6 +168,20 @@ export async function dispatchOpenclawClawlingInbound(
     );
     return;
   }
+  // Fail-closed self-echo guard: the self-echo check below
+  // (`sender.id === account.userId`) is only meaningful when `account.userId`
+  // is known. A reactivation auth failure can leave `account.userId` as an
+  // empty string (see runtime.ts reactivation edge); with an empty userId the
+  // `account.userId && …` short-circuit would silently treat EVERY frame —
+  // including our own echoed messages — as non-self and feed it back into the
+  // LLM pipeline (self-reply loop). Refuse to process materialized messages in
+  // that state rather than risk echoing our own output.
+  if (!account.userId) {
+    log?.error?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip (fail-closed): empty account.userId, cannot apply self-echo guard event=${envelope.event} trace=${envelope.trace_id}`,
+    );
+    return;
+  }
   if (isMaterializedMessage && !isInboundMessagePayload(envelope.payload)) {
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw skip: invalid payload trace=${envelope.trace_id}`,
@@ -214,7 +230,11 @@ export async function dispatchOpenclawClawlingInbound(
   }
   const chatType: ChatType = envelope.chat_type === "group" ? "group" : "direct";
   const isGroup = chatType === "group";
-  if (isMaterializedMessage && payload.message_mode !== "normal") {
+  // §7.5: the server does not default message_mode — an omitted field arrives
+  // as "" on the downlink. Empty/absent is equivalent to "normal", so only
+  // skip genuinely non-normal modes (e.g. "thinking").
+  const messageMode = payload.message_mode ?? "";
+  if (isMaterializedMessage && messageMode !== "normal" && messageMode !== "") {
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw skip non-normal mode=${payload.message_mode}`,
     );
@@ -271,7 +291,6 @@ export async function dispatchOpenclawClawlingInbound(
     peer: { kind: isGroup ? "group" : "direct", id: chatId },
     senderId: sender.id,
     senderNickName: sender.nickName,
-    ...(sender.profileType ? { senderProfileType: sender.profileType } : {}),
     rawBody,
     messageId: payload.message_id,
     traceId: envelope.trace_id,