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

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;

package/dist/src/ws-client.js

@@ -329,6 +329,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,
@@ -386,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;
@@ -433,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.13-dev.0",
+  "version": "2026.5.13-dev.2",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "files": [

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,

package/src/login.runtime.ts

@@ -268,6 +268,10 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
       refreshToken: normalizedResult.refresh_token || null,
       conversationId: normalizedResult.conversation?.id ?? null,
       loginMethod: "login",
+      // §E — record the exact `X-Device-Id` sent at connect (the constant
+      // `CHANNEL_ID`, see `authHeaders` in api-client.ts), so a later refresh
+      // sends the same device id the backend baked into the session.
+      deviceId: CHANNEL_ID,
     });
   } catch {
     runtime.log("clawchat-plugin-openclaw sqlite activation persistence failed; login continues.");

package/src/outbound.ts

@@ -1,3 +1,4 @@
+import { randomInt } from "node:crypto";
 import { MessageSendError, type Envelope, type Fragment, type MentionFragment, type MessageAckPayload, type MessageErrorPayload } from "./protocol-types.ts";
 import type { ClawlingChatClient } from "./ws-client.ts";
 import {
@@ -321,10 +322,15 @@ async function sendAlignedAckableEnvelope(params: {
       if (ack.trace_id !== traceId) return;
       if (ack.event === "message.error") {
         if (state === "acked" || state === "failed") return;
-        const payload = ack.payload as Partial<MessageErrorPayload>;
+        const payload = ack.payload as Partial<MessageErrorPayload> & { message?: unknown };
         const code = typeof payload.code === "string" && payload.code ? payload.code : "unknown";
-        const message = typeof payload.message === "string" && payload.message ? payload.message : "message send failed";
-        fail(new MessageSendError(traceId, code, message, ack.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";
+        fail(new MessageSendError(traceId, code, hint, ack.chat_id));
         return;
       }
       if (ack.event !== "message.ack") return;
@@ -491,14 +497,19 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
       && params.replyCtx.replyPreviewNickName
       && params.replyCtx.replyPreviewText,
   );
-  const messageId = params.messageId;
+  // Outbound message_id is ALWAYS present (at-least-once delivery, protocol
+  // §3.1.9): the server's inbox UNIQUE(recipient, message_id) absorbs a
+  // bounded resend of the same frame as one coalesced row. A bounded resend
+  // (non-terminal socket close → re-enqueue of the same captured wire) reuses
+  // this exact id, so a duplicate write is deduped rather than fanned out.
+  const messageId = params.messageId ?? mintMessageId();
 
   let ack: Envelope<MessageAckPayload>;
   let mode: "send" | "reply";
   if (useReply && params.replyCtx) {
     mode = "reply";
     const payload = {
-      ...(messageId ? { message_id: messageId } : {}),
+      message_id: messageId,
       message_mode: "normal",
       message: {
         body: { fragments },
@@ -532,7 +543,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
         }
       : null;
     const payload = {
-      ...(messageId ? { message_id: messageId } : {}),
+      message_id: messageId,
       message_mode: "normal",
       message: {
         body: { fragments },
@@ -548,7 +559,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
       ...(params.log ? { log: params.log } : {}),
     });
   }
-  if (messageId && ack.payload.message_id !== messageId) {
+  if (ack.payload.message_id !== messageId) {
     throw new Error(
       `ack message_id mismatch: expected ${messageId} got ${ack.payload.message_id}`,
     );
@@ -638,8 +649,35 @@ export async function sendOpenclawClawlingMedia(
 
 type OutboundClaimStore = Pick<ClawChatStore, "claimMessageOnce" | "markMessageAcknowledged">;
 
-function mintOutboundMessageId(account: ResolvedOpenclawClawlingAccount): string {
-  return `${account.userId}-msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+// Crockford base32 alphabet (ULID spec).
+const ULID_ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/**
+ * Generate a Canonical ULID: 10 chars of millisecond timestamp + 16 chars of
+ * randomness, Crockford base32, 26 chars total. Implemented locally (no extra
+ * dependency) because this repo has no ULID dep and only needs minting, not
+ * monotonic ordering or decoding.
+ */
+function ulid(now: number = Date.now()): string {
+  let time = now;
+  const out = new Array<string>(26);
+  for (let i = 9; i >= 0; i--) {
+    out[i] = ULID_ENCODING[time % 32]!;
+    time = Math.floor(time / 32);
+  }
+  for (let i = 10; i < 26; i++) {
+    out[i] = ULID_ENCODING[randomInt(0, 32)]!;
+  }
+  return out.join("");
+}
+
+/** Client-minted message id: `msg-` + ULID (protocol §7.6 format contract). */
+export function mintMessageId(): string {
+  return `msg-${ulid()}`;
+}
+
+function mintOutboundMessageId(_account: ResolvedOpenclawClawlingAccount): string {
+  return mintMessageId();
 }
 
 function resolveChannelOutboundStore(): OutboundClaimStore | null {