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

package/dist/index.js

@@ -16,5 +16,12 @@ export default defineChannelPluginEntry({
         registerOpenclawClawlingCommands(api);
         registerClawChatPromptInjection(api);
         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/dist/setup-entry.js

@@ -1,3 +1,33 @@
 import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { CHANNEL_ID } from "./src/config.js";
 import { openclawClawlingSetupPlugin } from "./src/channel.setup.js";
-export default defineSetupPluginEntry(openclawClawlingSetupPlugin);
+import { migrateLegacyClawChatChannelConfig } from "./src/config-compat.js";
+/**
+ * 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) {
+    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,
+};

package/dist/src/api-client.js

@@ -1,5 +1,129 @@
 import { ClawlingApiError, } from "./api-types.js";
 import { CHANNEL_ID } from "./config.js";
+export function buildPluginReportBody(input) {
+    return {
+        device_id: input.deviceId,
+        platform: input.platform,
+        plugin_version: input.pluginVersion,
+        runtime_name: input.runtimeName,
+        runtime_version: input.runtimeVersion,
+    };
+}
+/**
+ * §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) {
+    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);
+        const exp = parsed?.exp;
+        return typeof exp === "number" && Number.isFinite(exp) ? exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 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, params) {
+    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;
+    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;
+    try {
+        parsed = text ? JSON.parse(text) : 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
+            : {};
+        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) {
     if (!/^https?:\/\//i.test(opts.baseUrl)) {
         throw new ClawlingApiError("validation", `clawchat-plugin-openclaw baseUrl must start with http:// or https:// (got "${opts.baseUrl}")`);
@@ -33,44 +157,49 @@ export function createOpenclawClawlingApiClient(opts) {
                 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;
         try {
-            parsed = await res.json();
+            parsed = text ? JSON.parse(text) : undefined;
         }
-        catch (err) {
-            throw new ClawlingApiError("transport", `non-JSON response: ${err instanceof Error ? err.message : String(err)}`, { status: res.status, path });
+        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;
-        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
+            : 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;
         }
-        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;
+        throw new ClawlingApiError("transport", text ? "invalid envelope: missing numeric `code`" : "non-JSON response: empty body", { status: res.status, path });
     }
     async function call(method, path, init) {
         let res;
@@ -296,5 +425,14 @@ export function createOpenclawClawlingApiClient(opts) {
             fd.set("file", file);
             return await call("POST", "/v1/files/upload-url", { body: fd });
         },
+        async reportPlugin(input, opts) {
+            const path = opts?.authenticated
+                ? "/v1/agents/me/plugin-report"
+                : "/v1/agents/plugin-report";
+            await call("POST", path, {
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(buildPluginReportBody(input)),
+            });
+        },
     };
 }

package/dist/src/client.js

@@ -8,10 +8,13 @@ export function resolveOpenclawClawlingDeviceId(account) {
     return `${CHANNEL_ID}-${digest}`;
 }
 export function createOpenclawClawlingClient(account, overrides = {}) {
+    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/dist/src/config-compat.js

@@ -0,0 +1,120 @@
+import { CHANNEL_ID } from "./config.js";
+/**
+ * Compatibility migration for the plugin rename (commit 260044f): the plugin
+ * `id` and channel key changed from the OLD `openclaw-clawchat` to the NEW
+ * `clawchat-plugin-openclaw` (= {@link CHANNEL_ID}).
+ *
+ * Users upgrading from the old version have all their state — channel block
+ * (token/userId/ownerUserId/refreshToken/…), `plugins.allow`,
+ * `plugins.entries`, and `tools.allow`/`tools.alsoAllow` — keyed under the old
+ * id. The new code only reads the new id, so the channel silently fails to
+ * load. This migration moves the old-keyed state onto the new id.
+ *
+ * The function is PURE: it clones the input via `structuredClone` and never
+ * mutates its argument. It is IDEMPOTENT: a config with no old id anywhere
+ * returns an equivalent config with `changes: []`.
+ */
+export const LEGACY_CHANNEL_ID = "openclaw-clawchat";
+export const TARGET_CHANNEL_ID = CHANNEL_ID;
+const BLOCKED_OBJECT_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+function isBlockedObjectKey(key) {
+    return BLOCKED_OBJECT_KEYS.has(key);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyRecord(value) {
+    return isRecord(value) && Object.keys(value).length > 0;
+}
+/**
+ * Copy keys from `source` into `target` only when they are absent/undefined in
+ * `target` (target is more current — never overwrite an existing value).
+ * Recurses into nested records. Skips prototype-pollution keys.
+ */
+function mergeMissing(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined || isBlockedObjectKey(key))
+            continue;
+        const existing = target[key];
+        if (existing === undefined) {
+            target[key] = value;
+            continue;
+        }
+        if (isRecord(existing) && isRecord(value))
+            mergeMissing(existing, value);
+    }
+}
+/** Replace `from` → `to` in a string array, preserving order and deduping. */
+function replaceAndDedup(list, from, to) {
+    const out = [];
+    for (const raw of list) {
+        const value = raw === from ? to : raw;
+        if (!out.includes(value))
+            out.push(value);
+    }
+    return out;
+}
+export function migrateLegacyClawChatChannelConfig(config) {
+    const changes = [];
+    if (!isRecord(config))
+        return { config, changes };
+    const next = structuredClone(config);
+    // 1. channels — move/merge the old channel block onto the new id.
+    const channels = next.channels;
+    if (isRecord(channels)) {
+        const oldChannel = channels[LEGACY_CHANNEL_ID];
+        if (isNonEmptyRecord(oldChannel)) {
+            const newChannel = channels[TARGET_CHANNEL_ID];
+            if (!isNonEmptyRecord(newChannel)) {
+                channels[TARGET_CHANNEL_ID] = oldChannel;
+                changes.push(`Moved channel "${LEGACY_CHANNEL_ID}" → "${TARGET_CHANNEL_ID}".`);
+            }
+            else {
+                mergeMissing(newChannel, oldChannel);
+                changes.push(`Merged channel "${LEGACY_CHANNEL_ID}" → "${TARGET_CHANNEL_ID}" (filled missing fields; kept existing values).`);
+            }
+            delete channels[LEGACY_CHANNEL_ID];
+        }
+    }
+    // plugins.* live under a single `plugins` record.
+    const plugins = next.plugins;
+    if (isRecord(plugins)) {
+        // 2. plugins.allow — replace old id with new id (append if missing), dedup.
+        const allow = plugins.allow;
+        if (Array.isArray(allow) && allow.includes(LEGACY_CHANNEL_ID)) {
+            const replaced = replaceAndDedup(allow.filter((v) => typeof v === "string"), LEGACY_CHANNEL_ID, TARGET_CHANNEL_ID);
+            plugins.allow = replaced;
+            changes.push(`Updated plugins.allow: "${LEGACY_CHANNEL_ID}" → "${TARGET_CHANNEL_ID}".`);
+        }
+        // 3. plugins.entries — merge-missing the old entry into the new one.
+        const entries = plugins.entries;
+        if (isRecord(entries)) {
+            const oldEntry = entries[LEGACY_CHANNEL_ID];
+            if (oldEntry !== undefined) {
+                if (isRecord(oldEntry)) {
+                    const newEntry = entries[TARGET_CHANNEL_ID];
+                    if (!isRecord(newEntry)) {
+                        entries[TARGET_CHANNEL_ID] = oldEntry;
+                    }
+                    else {
+                        mergeMissing(newEntry, oldEntry);
+                    }
+                }
+                delete entries[LEGACY_CHANNEL_ID];
+                changes.push(`Merged plugins.entries["${LEGACY_CHANNEL_ID}"] → plugins.entries["${TARGET_CHANNEL_ID}"].`);
+            }
+        }
+    }
+    // 4. tools.allow + tools.alsoAllow — replace old id with new id, dedup.
+    const tools = next.tools;
+    if (isRecord(tools)) {
+        for (const key of ["allow", "alsoAllow"]) {
+            const list = tools[key];
+            if (Array.isArray(list) && list.includes(LEGACY_CHANNEL_ID)) {
+                tools[key] = replaceAndDedup(list.filter((v) => typeof v === "string"), LEGACY_CHANNEL_ID, TARGET_CHANNEL_ID);
+                changes.push(`Updated tools.${key}: "${LEGACY_CHANNEL_ID}" → "${TARGET_CHANNEL_ID}".`);
+            }
+        }
+    }
+    return { config: next, changes };
+}

package/dist/src/inbound.js

@@ -10,8 +10,10 @@ function normalizeSender(sender) {
     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) {
     const chatId = envelope.chat_id;
@@ -85,6 +87,18 @@ export async function dispatchOpenclawClawlingInbound(params) {
         log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw skip non-business event=${envelope.event} trace=${envelope.trace_id}`);
         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}`);
         return;
@@ -107,7 +121,11 @@ export async function dispatchOpenclawClawlingInbound(params) {
     }
     const 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}`);
         return;
     }
@@ -152,7 +170,6 @@ export async function dispatchOpenclawClawlingInbound(params) {
         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/dist/src/login.runtime.js

@@ -197,6 +197,10 @@ export async function runOpenclawClawlingLogin(params) {
             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 {

package/dist/src/outbound.js

@@ -1,3 +1,4 @@
+import { randomInt } from "node:crypto";
 import { MessageSendError } from "./protocol-types.js";
 import { createAttachedChannelResultAdapter, } from "openclaw/plugin-sdk/channel-send-result";
 import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
@@ -198,8 +199,13 @@ async function sendAlignedAckableEnvelope(params) {
                     return;
                 const payload = ack.payload;
                 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")
@@ -354,13 +360,18 @@ export async function sendOpenclawClawlingText(params) {
     const useReply = Boolean(params.replyCtx?.replyPreviewSenderId
         && 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;
     let mode;
     if (useReply && params.replyCtx) {
         mode = "reply";
         const payload = {
-            ...(messageId ? { message_id: messageId } : {}),
+            message_id: messageId,
             message_mode: "normal",
             message: {
                 body: { fragments },
@@ -395,7 +406,7 @@ export async function sendOpenclawClawlingText(params) {
             }
             : null;
         const payload = {
-            ...(messageId ? { message_id: messageId } : {}),
+            message_id: messageId,
             message_mode: "normal",
             message: {
                 body: { fragments },
@@ -411,7 +422,7 @@ export async function sendOpenclawClawlingText(params) {
             ...(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}`);
     }
     params.log?.info?.(`[${params.account.accountId}] clawchat-plugin-openclaw outbound mode=${mode} msg=${ack.payload.message_id} text_len=${text.length} media=${mediaFragments.length} trace=${ack.trace_id}`);
@@ -474,8 +485,32 @@ export async function sendOpenclawClawlingMedia(params) {
         ...(params.log ? { log: params.log } : {}),
     });
 }
-function mintOutboundMessageId(account) {
-    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 = Date.now()) {
+    let time = now;
+    const out = new Array(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() {
+    return `msg-${ulid()}`;
+}
+function mintOutboundMessageId(_account) {
+    return mintMessageId();
 }
 function resolveChannelOutboundStore() {
     try {

package/dist/src/plugin-report.js

@@ -0,0 +1,36 @@
+import { createRequire } from "node:module";
+import { createOpenclawClawlingApiClient } from "./api-client.js";
+/** Best-effort read of this plugin's package version; "unknown" on failure. */
+export function resolvePluginVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require("../package.json");
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Fire one plugin-version report. Best-effort: any failure is logged at debug
+ * and swallowed so it can never block, delay, or crash gateway startup.
+ */
+export async function reportPluginVersionSafe(p) {
+    try {
+        const client = createOpenclawClawlingApiClient({
+            baseUrl: p.baseUrl,
+            mediaBaseUrl: p.mediaBaseUrl,
+            token: p.token,
+        });
+        await client.reportPlugin({
+            deviceId: p.deviceId,
+            platform: "openclaw",
+            pluginVersion: p.pluginVersion,
+            runtimeName: "node",
+            runtimeVersion: process.version,
+        }, { authenticated: p.authenticated });
+    }
+    catch (err) {
+        p.log?.debug?.(`clawchat-plugin-openclaw plugin report failed (authenticated=${p.authenticated}): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/src/protocol-types.js

@@ -13,6 +13,8 @@ export const EVENT = {
     MESSAGE_FAILED: "message.failed",
     TYPING_UPDATE: "typing.update",
     CHAT_METADATA_INVALIDATED: "chat.metadata.invalidated",
+    NOTIFY_SIGNAL: "notify.signal",
+    REPLAY_DONE: "replay.done",
     OFFLINE_BATCH: "offline.batch",
     OFFLINE_ACK: "offline.ack",
     OFFLINE_DONE: "offline.done",