@clawling/clawchat-plugin-openclaw 2026.9.14-1 → 2026.9.16-1

package/dist/src/api-client.js

@@ -42,13 +42,23 @@ const CODE_INTERNAL = 1; // CodeInternal — transient.
 const CODE_BAD_REQUEST = 400; // bad body / device id — permanent (client bug).
 /**
  * CodeInvalidRefresh — returned for BOTH a genuinely revoked/invalid refresh
- * token AND a single-use refresh token that was already CONSUMED by a prior
- * successful rotation (a duplicate-supervisor / concurrent-refresh / stale-store
- * race). The stateless `authRefresh` cannot tell the two apart, so it reports
- * `permanent`; the stateful `RefreshManager` re-classifies a consumed-rotation
- * race back to transient (see §B race) before any auto-logout.
+ * token AND a refresh token that was already CONSUMED by a prior successful
+ * rotation (a duplicate-supervisor / concurrent-refresh / stale-store race), once
+ * the backend's short replay grace window no longer covers it. The stateless
+ * `authRefresh` cannot tell the two apart, so it reports `permanent`; the
+ * stateful `RefreshManager` re-classifies a consumed-rotation race back to
+ * transient (see §B race) before any auto-logout.
  */
 export const CODE_INVALID_REFRESH = 10003;
+/**
+ * §B attempt deadline — total wall clock for one refresh attempt (request AND
+ * response body). A hit aborts the request and is TRANSIENT. Kept below
+ * `MIN_REFRESH_INTERVAL_MS` (30s) so the min-interval floor, not the deadline,
+ * sets the retry cadence: a retry of the same refresh token then lands inside
+ * the backend refresh grace window if the server rotated but the response was
+ * lost.
+ */
+export const REFRESH_REQUEST_TIMEOUT_MS = 20_000;
 /**
  * §0/§B — call `POST /v1/auth/refresh` to rotate the access+refresh token.
  *
@@ -58,6 +68,11 @@ export const CODE_INVALID_REFRESH = 10003;
  * 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.
+ *
+ * The whole attempt is bounded by `REFRESH_REQUEST_TIMEOUT_MS` (§B attempt
+ * deadline): the request is aborted via its signal, and the deadline is also
+ * raced against the attempt so a fetch implementation that ignores the signal
+ * cannot hang the caller.
  */
 export async function authRefresh(opts, params) {
     const baseUrl = opts.baseUrl.replace(/\/+$/, "");
@@ -65,6 +80,26 @@ export async function authRefresh(opts, params) {
     if (!params.refreshToken?.trim()) {
         return { kind: "permanent", code: CODE_INVALID_REFRESH, message: "missing refresh token" };
     }
+    const timeoutMs = opts.timeoutMs ?? REFRESH_REQUEST_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            controller.abort(new Error("refresh request timed out"));
+            resolve({ kind: "transient", message: `refresh request timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([
+            authRefreshAttempt(baseUrl, fetchImpl, params, controller.signal),
+            deadline,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function authRefreshAttempt(baseUrl, fetchImpl, params, signal) {
     let res;
     try {
         res = await fetchImpl(`${baseUrl}/v1/auth/refresh`, {
@@ -75,6 +110,8 @@ export async function authRefresh(opts, params) {
                 "x-device-id": params.deviceId,
             },
             body: JSON.stringify({ refresh_token: params.refreshToken.trim() }),
+            // Still in effect while the body is read below.
+            signal,
         });
     }
     catch (err) {
@@ -117,8 +154,9 @@ export async function authRefresh(opts, params) {
         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).
+            // we retry; inside the backend grace window the retry redeems the old
+            // token again, after it the retry returns 10003 and escalates to
+            // permanent (§B transient→permanent).
             return { kind: "transient", status: 200, message: "refresh: rotation body incomplete" };
         }
         return { kind: "success", accessToken, refreshToken };
@@ -396,6 +434,13 @@ export function createOpenclawClawlingApiClient(opts) {
         async deleteMomentComment(params) {
             return await call("DELETE", `/v1/moments/${encodeURIComponent(String(params.momentId))}/comments/${encodeURIComponent(String(params.commentId))}`);
         },
+        async getDirectConversation(peerId) {
+            assertNonBlankId(peerId, "getDirectConversation: peerId");
+            return await call("POST", "/v1/conversations/direct", {
+                body: JSON.stringify({ peer_id: peerId.trim() }),
+                headers: { "content-type": "application/json" },
+            });
+        },
         async getConversation(conversationId) {
             return await call("GET", `/v1/conversations/${encodeURIComponent(conversationId)}`);
         },

package/dist/src/config.js

@@ -83,6 +83,7 @@ export const openclawClawlingAccountConfigSchema = {
         forwardToolCalls: { type: "boolean" },
         richInteractions: { type: "boolean" },
         awarenessNote: { type: "boolean" },
+        friendGreeting: { type: "boolean" },
         livewareSample: { type: "boolean" },
         reconnect: {
             type: "object",
@@ -448,6 +449,7 @@ export function resolveOpenclawClawlingAccount(cfg, accountId, env = process.env
     const forwardToolCalls = typeof channel.forwardToolCalls === "boolean" ? channel.forwardToolCalls : false;
     const richInteractions = typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
     const awarenessNote = typeof channel.awarenessNote === "boolean" ? channel.awarenessNote : false;
+    const friendGreeting = typeof channel.friendGreeting === "boolean" ? channel.friendGreeting : true;
     const livewareSample = typeof channel.livewareSample === "boolean" ? channel.livewareSample : true;
     return {
         accountId: resolvedAccountId,
@@ -475,6 +477,7 @@ export function resolveOpenclawClawlingAccount(cfg, accountId, env = process.env
         forwardToolCalls,
         richInteractions,
         awarenessNote,
+        friendGreeting,
         livewareSample,
         allowFrom: [],
         reconnect: readReconnect(channel.reconnect),

package/dist/src/friend-greeting.js

@@ -0,0 +1,80 @@
+/**
+ * First message to a newly added NON-owner friend.
+ *
+ * `friend.added` used to be a pure awareness event. The server creates the
+ * direct conversation inside the friend-accept transaction, but the signal
+ * only carries the counterparty `usr_…` — so the runtime resolves the
+ * conversation through `POST /v1/conversations/direct` and then feeds ONE
+ * synthetic inbound turn (built here) into the normal dispatch path, the same
+ * way the activation bootstrap greets the owner.
+ *
+ * The prompt is deliberately distinct from the owner activation prompt: this
+ * reader is a stranger, so "you are connected and ready" makes no sense and
+ * the agent must say whose agent it is instead.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { EVENT } from "./protocol-types.js";
+export const FRIEND_GREETING_FALLBACK = [
+    "A ClawChat user has just become your friend. You are now in a direct conversation with them; they are not your owner.",
+    "Reply now with one short, friendly greeting message in this conversation: introduce yourself by name, say you are an AI agent acting on behalf of your owner, and invite them to tell you what they need.",
+    "Send it as a normal chat reply. Do not write or create any files or notes, and do not call tools just to greet.",
+    "Do not share your owner's private information, and do not ask the user for personal information.",
+].join("\n");
+// Cross-plugin, user-editable override read lazily so edits apply on the next
+// friend without a restart. Any read failure falls back to the built-in text.
+// Mirrors `buildActivationBootstrapText` (`~/clawchat/greeting.md`).
+export function buildFriendGreetingText(homeDir = os.homedir()) {
+    const greetingPath = path.join(homeDir, "clawchat", "friend-greeting.md");
+    try {
+        const raw = fs.readFileSync(greetingPath);
+        const override = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim();
+        if (override.length > 0) {
+            return override;
+        }
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT") {
+            console.warn(`clawchat.friend-greeting failed to read override ${greetingPath}:`, error);
+        }
+    }
+    return FRIEND_GREETING_FALLBACK;
+}
+/**
+ * Synthetic inbound envelope for the friend greeting turn. Same invariant as
+ * `buildActivationBootstrapEnvelope`: `conversationId` MUST be a conversation
+ * idcode — the agent's reply inherits this chat_id, and anything else is
+ * refused at the outbound boundary after a full LLM turn has been spent.
+ */
+export function buildFriendGreetingEnvelope(params) {
+    const { account, conversationId, friendUserId } = params;
+    const text = buildFriendGreetingText();
+    const now = Date.now();
+    return {
+        version: "2",
+        event: EVENT.MESSAGE_SEND,
+        trace_id: `clawchat-plugin-openclaw-friend-greeting-${now}`,
+        emitted_at: now,
+        chat_id: conversationId,
+        chat_type: "direct",
+        to: { id: account.userId, type: "direct" },
+        sender: { id: friendUserId, type: "direct", nick_name: "" },
+        payload: {
+            message_id: `clawchat-plugin-openclaw-friend-greeting-${conversationId}-${now}`,
+            message_mode: "normal",
+            message: {
+                body: { fragments: [{ kind: "text", text }] },
+                context: { mentions: [], reply: null },
+                streaming: {
+                    status: "static",
+                    sequence: 0,
+                    mutation_policy: "sealed",
+                    started_at: null,
+                    completed_at: null,
+                },
+            },
+        },
+    };
+}

package/dist/src/protocol-types.js

@@ -17,6 +17,7 @@ export const EVENT = {
     CHAT_METADATA_INVALIDATED: "chat.metadata.invalidated",
     NOTIFY_SIGNAL: "notify.signal",
     REPLAY_DONE: "replay.done",
+    HISTORY_TRUNCATED: "history.truncated",
     OFFLINE_BATCH: "offline.batch",
     OFFLINE_ACK: "offline.ack",
     OFFLINE_DONE: "offline.done",

package/dist/src/refresh-manager.js

@@ -22,6 +22,15 @@ const HOUR_MS = 60 * MINUTE_MS;
 export const MIN_REFRESH_INTERVAL_MS = 30_000;
 /** §A.1 — proactive jitter (±5min). */
 export const PROACTIVE_JITTER_MS = 5 * MINUTE_MS;
+/**
+ * §B retry within the grace window — jitter bounds for the one-shot retry after
+ * a transient proactive refresh. The retry is due `MIN_REFRESH_INTERVAL_MS` +
+ * [1s, 5s] after the failed attempt BEGAN (31–35s): far above the backend's
+ * minimum replay age, inside its 90s replay window, and never faster than the
+ * min-interval floor (which would skip it).
+ */
+export const PROACTIVE_RETRY_JITTER_MIN_MS = 1_000;
+export const PROACTIVE_RETRY_JITTER_MAX_MS = 5_000;
 /** §A.0 — fallback access-token TTL when `exp` is unparseable. */
 export const ACCESS_TOKEN_TTL_MS = 24 * HOUR_MS;
 /**
@@ -70,6 +79,8 @@ export class RefreshManager {
     /** §A.3 — epoch-ms of the last refresh attempt (any token). */
     lastAttemptAt = 0;
     proactiveTimer = null;
+    /** §B — the pending one-shot retry after a transient proactive refresh. */
+    proactiveRetryTimer = null;
     stopped = false;
     constructor(ports) {
         this.ports = ports;
@@ -133,9 +144,10 @@ export class RefreshManager {
             // sqlite-sourced agent must not keep a now-dead refresh token in its row
             // while running on the rotated token. Treat as transient so the WS stays
             // in backoff with the CURRENT tokens and the next attempt retries. The
-            // server already rotated, so the next attempt may return `code:10003`
-            // (which escalates to permanent per §B) — that is the accepted hazard, not
-            // a silent brick.
+            // server already rotated: inside the backend grace window the retry
+            // redeems the old token again; after it the retry returns `code:10003`
+            // (which escalates to permanent per §B) — the accepted hazard, not a
+            // silent brick.
             try {
                 await this.ports.persistRotatedTokens({
                     accessToken: result.accessToken,
@@ -160,8 +172,9 @@ export class RefreshManager {
             return { kind: "success", accessToken: result.accessToken, refreshToken: result.refreshToken };
         }
         if (result.kind === "permanent") {
-            // §B race — a `code:10003` is also returned for a single-use refresh token
-            // already CONSUMED by a prior successful rotation. Before auto-logging-out
+            // §B race — a `code:10003` is also returned for a refresh token already
+            // CONSUMED by a prior successful rotation (once the backend grace window
+            // no longer covers it). Before auto-logging-out
             // (which wipes credentials and bricks the agent), distinguish that race
             // from a genuine revocation. It is a race when EITHER the submitted token
             // is one we already rotated away from, OR the live store refresh token has
@@ -234,13 +247,26 @@ export class RefreshManager {
      * success, hands the rotated token to the runtime's `onProactiveRefreshed` port
      * so the live WS is closed and reconnected with the new token (the in-memory
      * swap alone does NOT reach the running socket, which captured the old token at
-     * `connect` time). Transient/skipped outcomes leave the WS untouched — the next
-     * proactive arm (or a reactive hello-fail) handles it.
+     * `connect` time). Transient/skipped outcomes leave the WS untouched.
+     *
+     * §B retry within the grace window — a TRANSIENT outcome (e.g. the attempt
+     * deadline hit after the server may already have rotated) arms ONE retry, due
+     * 31–35s after that attempt began, so a replay of the same refresh token lands
+     * inside the backend grace window instead of waiting for the next arm /
+     * hello-fail / 401, possibly hours later. The retry itself never arms another.
+     * Success, permanent and skipped outcomes arm nothing (skipped means another
+     * in-flight attempt or a latch already owns the token).
      */
-    async runProactiveRefresh() {
-        const outcome = await this.refresh("proactive-timer");
+    async runProactiveRefresh(isRetry = false) {
+        const accessTokenAtAttempt = this.ports.getAccessToken();
+        const outcome = await this.refresh(isRetry ? "proactive-retry" : "proactive-timer");
         if (this.stopped)
             return;
+        if (outcome.kind === "transient") {
+            if (!isRetry)
+                this.armProactiveRetry(accessTokenAtAttempt);
+            return;
+        }
         if (outcome.kind !== "success")
             return;
         if (this.ports.onProactiveRefreshed) {
@@ -255,6 +281,42 @@ export class RefreshManager {
             }
         }
     }
+    /**
+     * §B — arm the one-shot retry, measured from the failed attempt's start
+     * (`lastAttemptAt`). It runs through `refresh()`, so single-flight dedupe, the
+     * rejected-token latch and the min-interval floor all still apply. It is
+     * skipped when the access token changed meanwhile (someone else rotated).
+     */
+    armProactiveRetry(accessTokenAtAttempt) {
+        this.clearProactiveRetry();
+        const rawJitter = (this.ports.proactiveRetryJitter ?? defaultProactiveRetryJitter)();
+        const jitterMs = Math.min(PROACTIVE_RETRY_JITTER_MAX_MS, Math.max(PROACTIVE_RETRY_JITTER_MIN_MS, rawJitter));
+        const dueAtMs = this.lastAttemptAt + MIN_REFRESH_INTERVAL_MS + jitterMs;
+        const delayMs = Math.max(0, dueAtMs - this.now());
+        this.ports.log?.info?.(`clawchat-plugin-openclaw proactive refresh transient; one-shot retry in ${delayMs}ms`);
+        this.proactiveRetryTimer = this.setTimer(() => {
+            this.proactiveRetryTimer = null;
+            if (this.stopped)
+                return;
+            if (this.ports.getAccessToken() !== accessTokenAtAttempt) {
+                this.ports.log?.debug?.("clawchat-plugin-openclaw proactive retry skipped (access token already changed)");
+                return;
+            }
+            void this.runProactiveRefresh(true);
+        }, delayMs);
+    }
+    clearProactiveRetry() {
+        if (this.proactiveRetryTimer != null) {
+            this.clearTimer(this.proactiveRetryTimer);
+            this.proactiveRetryTimer = null;
+        }
+    }
+    /**
+     * Clear the proactive `refresh_at` timer (called on WS disconnect). The §B
+     * one-shot retry is deliberately NOT cleared here: a refresh timeout usually
+     * coincides with the network drop that also closes the socket, and refresh
+     * does not need the socket. `stop()` clears both.
+     */
     disarmProactiveTimer() {
         if (this.proactiveTimer != null) {
             this.clearTimer(this.proactiveTimer);
@@ -279,10 +341,11 @@ export class RefreshManager {
         });
         return this.now() >= refreshAtMs;
     }
-    /** Stop the manager — clears the proactive timer; no further refreshes arm. */
+    /** Stop the manager — clears the proactive + retry timers; nothing further arms. */
     stop() {
         this.stopped = true;
         this.disarmProactiveTimer();
+        this.clearProactiveRetry();
     }
     /** Test/inspection seam — the latched (rejected) access token, if any. */
     getRejectedToken() {
@@ -327,3 +390,7 @@ function decodeJwtIat(token) {
 function defaultJitter() {
     return (Math.random() * 2 - 1) * PROACTIVE_JITTER_MS;
 }
+function defaultProactiveRetryJitter() {
+    return (PROACTIVE_RETRY_JITTER_MIN_MS +
+        Math.random() * (PROACTIVE_RETRY_JITTER_MAX_MS - PROACTIVE_RETRY_JITTER_MIN_MS));
+}

package/dist/src/runtime.js

@@ -5,6 +5,7 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient, resolveOpenclawClawlingDeviceId } from "./client.js";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { buildActivationBootstrapText } from "./activation-greeting.js";
+import { buildFriendGreetingEnvelope } from "./friend-greeting.js";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.js";
 import { ensureLivewareCli, livewareCliHomeDir, livewareSampleRootDir, resolveLivewarePath, } from "./liveware-cli.js";
 import { LivewareSampleSupervisor, } from "./liveware-sample.js";
@@ -1941,6 +1942,38 @@ export async function startOpenclawClawlingGateway(params) {
                     ],
                 }));
             }
+            else if (env.event === "history.truncated") {
+                // Replay-start boundary frame (docs/client-integration.md §11.7): part
+                // of the retained history will not be replayed to this device. This
+                // plugin advertises no reliable-delivery flag, so the server does not
+                // send it today; if one arrives it is logged explicitly. Never acked (no
+                // seq/dseq), never dispatched, no user-visible action. An absent or
+                // unrecognised `reason` means "pruned"; `oldest_seq` is an opaque token.
+                const current = wsLogContext();
+                const truncatedPayload = env.payload && typeof env.payload === "object"
+                    ? env.payload
+                    : undefined;
+                const rawReason = truncatedPayload?.reason;
+                const knownReason = rawReason === "pruned" || rawReason === "cursor_started_above_zero";
+                const fields = [
+                    ["event_name", env.event],
+                    ["trace_id", env.trace_id],
+                    ["oldest_seq", typeof truncatedPayload?.oldest_seq === "number" ? truncatedPayload.oldest_seq : "-"],
+                    ["reason", knownReason ? rawReason : "pruned"],
+                ];
+                if (!knownReason && typeof rawReason === "string" && rawReason) {
+                    fields.push(["raw_reason", rawReason]);
+                }
+                log?.info?.(formatWsLog({
+                    event: "inbound_control",
+                    accountId,
+                    attempt: current.attempt,
+                    reconnectCount: current.reconnectCount,
+                    state: "ready",
+                    action: "history_truncated",
+                    fields,
+                }));
+            }
             else if (env.event !== "ping" && env.event !== "pong") {
                 const current = wsLogContext();
                 log?.info?.(formatWsLog({
@@ -2088,6 +2121,77 @@ export async function startOpenclawClawlingGateway(params) {
     // A single queueMicrotask coalesces all awareness signals that arrive in
     // the same synchronous turn into exactly one handleInboundEnvelope call.
     let pendingAwarenessNote = false;
+    /**
+     * First message to a newly added NON-owner friend (`friend.added`).
+     *
+     * The signal only names the counterparty; the direct conversation the
+     * server created inside the accept transaction is resolved through
+     * `POST /v1/conversations/direct` and ONE synthetic greeting turn runs in
+     * it. Dedupe is persisted through the message ledger keyed on the signal's
+     * `event_id` (`message_id` is `notify:friend.added:<userId>` and would
+     * collide on remove + re-add, so it is only the fallback key) — a
+     * reconnect replay of the same signal cannot greet twice. The claim uses
+     * kind "message" because the ledger's once-only unique index is partial on
+     * kind = 'message'; chat_id stays null so the row never feeds a transcript.
+     * The owner's own `friend.added` is skipped: the activation bootstrap greets
+     * the owner.
+     */
+    const scheduleFriendGreeting = (payload) => {
+        if (!account.friendGreeting)
+            return;
+        const friendUserId = typeof payload?.entity_id === "string" ? payload.entity_id.trim() : "";
+        if (!friendUserId)
+            return;
+        const ownerUserId = account.ownerUserId?.trim();
+        if (ownerUserId && friendUserId === ownerUserId)
+            return;
+        const eventId = typeof payload?.event_id === "string" ? payload.event_id.trim() : "";
+        const messageId = typeof payload?.message_id === "string" ? payload.message_id.trim() : "";
+        const dedupeKey = eventId || messageId;
+        if (!dedupeKey) {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw friend greeting skipped friend=${friendUserId} reason=no_dedupe_key`);
+            return;
+        }
+        if (store?.claimMessageOnce) {
+            const claimed = recordConnection("friend greeting claim", () => store.claimMessageOnce?.({
+                platform: "openclaw",
+                accountId,
+                kind: "message",
+                direction: "inbound",
+                eventType: "friend.greeting",
+                traceId: null,
+                chatId: null,
+                messageId: `friend.greeting:${dedupeKey}`,
+                text: null,
+                raw: { friend_user_id: friendUserId },
+            }));
+            if (claimed !== true) {
+                // false = already greeted (replay); null = ledger undecided — fail
+                // closed rather than risk a duplicate unsolicited message.
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw friend greeting skipped friend=${friendUserId} key=${dedupeKey} claimed=${String(claimed)}`);
+                return;
+            }
+        }
+        void (async () => {
+            let conversationId = "";
+            try {
+                const result = await getConversationApiClient().getDirectConversation(friendUserId);
+                conversationId = result?.conversation?.id?.trim() ?? "";
+            }
+            catch (err) {
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw friend greeting conversation lookup failed friend=${friendUserId}: ${err instanceof Error ? err.message : String(err)}`);
+                return;
+            }
+            if (!isValidChatId(conversationId)) {
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw friend greeting skipped friend=${friendUserId} reason=no_conversation_id`);
+                return;
+            }
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw friend greeting dispatch friend=${friendUserId} chat_id=${conversationId}`);
+            await handleInboundEnvelope(buildFriendGreetingEnvelope({ account, conversationId, friendUserId }));
+        })().catch((err) => {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw friend greeting failed friend=${friendUserId}: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
     client.on("notify:signal", (env) => {
         // §9.4 reliable system notification. The plugin holds no friend/roster
         // cache (friends are fetched on demand via REST tools), so there is nothing
@@ -2177,6 +2281,9 @@ export async function startOpenclawClawlingGateway(params) {
                         void handleInboundEnvelope(buildAwarenessNoteEnvelope({ account, ownerConversationId }));
                     });
                 }
+                if (type === "friend.added") {
+                    scheduleFriendGreeting(payload);
+                }
             }
         }
     });
@@ -2373,7 +2480,22 @@ export async function startOpenclawClawlingGateway(params) {
                 log?.info?.(`[${accountId}] clawchat-plugin-openclaw skip duplicate stored msg=${turn.messageId}`);
                 return "skipped";
             }
+            if (claimed !== true) {
+                // Fail closed: a claim that could not be decided (store disabled, SQLite
+                // error, a throw converted to undefined by recordConnection) must not
+                // dispatch. Live delivery and device replay can carry the same message,
+                // and the outbound reply path (outbound.ts / reply-dispatcher.ts) already
+                // refuses to send without a claim — so dispatching here only re-ran the
+                // LLM/tools without delivering, or double-replied. Logged at error level
+                // with reason=claim_unavailable so a store outage is visible and is not
+                // mistaken for dedup. Accepted cost: a one-off transient claim failure
+                // drops that message.
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw inbound skipped msg=${turn.messageId} chat_id=${turn.peer.id} event=${String(env.event)} reason=claim_unavailable result=${String(claimed)}`);
+                return "skipped";
+            }
         }
+        // No store wired at all (injected test transport, or store construction
+        // threw at startup — which is itself logged) keeps the store-less pass-through.
         return "claimed";
     };
     const dispatchTurnToAgent = async (turn) => {
@@ -2730,7 +2852,10 @@ export async function startOpenclawClawlingGateway(params) {
             // replayed — permanently lost. Claiming first makes it durable; the abort
             // check below then returns without dispatching, but the frame is kept.
             // `claimInboundTurn` is INSERT OR IGNORE, so a genuine duplicate (same
-            // message_id) is still deduped here exactly once.
+            // message_id) is still deduped here exactly once. The claim fails CLOSED:
+            // only a successful claim proceeds; an undecided claim (store unavailable)
+            // skips with reason=claim_unavailable, because outbound replies also refuse
+            // to send without a claim, so dispatching would only waste the turn.
             const claimed = claimInboundTurn(turn);
             if (claimed === "skipped")
                 return "skipped";

package/dist/src/skill-update.js

@@ -66,7 +66,7 @@ export const OFFICIAL_SKILLS_BASE = "https://raw.githubusercontent.com/clawling/
  * in the install-cli repo, bump this constant, ship it. `liveware-sample.ts`
  * imports the same ref, so the `livewares` tree at that tag is pinned too.
  */
-export const DEFAULT_SKILLS_REF = "skills-v1.8.0";
+export const DEFAULT_SKILLS_REF = "skills-v1.9.0";
 /** Refuse to treat an absurdly large response as a skill file (defence in depth). */
 export const MAX_SKILL_BYTES = 256 * 1024;
 /** This adapter's host target inside `skills/manifest.json`. */

package/dist/src/tools-schema.js

@@ -123,6 +123,12 @@ export const ClawchatGetConversationSchema = Type.Object({
         description: "Concrete ClawChat conversation id to fetch",
     }),
 });
+export const ClawchatGetDirectConversationSchema = Type.Object({
+    userId: Type.String({
+        minLength: 1,
+        description: "Concrete ClawChat user id (usr_...) of the friend",
+    }),
+});
 export const ClawchatLeaveGroupSchema = Type.Object({
     conversationId: Type.String({
         description: "Concrete ClawChat group conversation id to leave",

package/dist/src/tools.js

@@ -12,7 +12,7 @@ import { getOpenclawClawlingClient, } from "./runtime.js";
 import { markTerminalClawChatSend, getCurrentTerminalSendScope } from "./terminal-send.js";
 import { editClawChatMemoryBody, readClawChatMemoryFile, resolveClawChatMemoryPath, searchClawChatMemory, writeClawChatMemoryBody, } from "./clawchat-memory.js";
 import { pullGroupMetadata, pullOwnerMetadata, pullUserMetadata, pushMetadata, updateMetadata, } from "./clawchat-metadata.js";
-import { ClawchatGetAccountProfileSchema, ClawchatGetConversationSchema, ClawchatGetMomentSchema, ClawchatGetUserProfileSchema, ClawchatLeaveGroupSchema, ClawchatAddGroupMemberSchema, ClawchatAcceptFriendRequestSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemorySearchSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListFriendRequestsSchema, ClawchatListMomentsSchema, ClawchatMentionMessageSchema, ClawchatReactMessageSchema, ClawchatReplyMomentCommentSchema, ClawchatRejectFriendRequestSchema, ClawchatRemoveFriendSchema, ClawchatSearchUsersSchema, ClawchatSendFriendRequestSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatRegisterAppSchema, ClawchatListAppsSchema, ClawchatUnregisterAppSchema, ClawchatLivewareLoginSchema, } from "./tools-schema.js";
+import { ClawchatGetAccountProfileSchema, ClawchatGetConversationSchema, ClawchatGetDirectConversationSchema, ClawchatGetMomentSchema, ClawchatGetUserProfileSchema, ClawchatLeaveGroupSchema, ClawchatAddGroupMemberSchema, ClawchatAcceptFriendRequestSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemorySearchSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListFriendRequestsSchema, ClawchatListMomentsSchema, ClawchatMentionMessageSchema, ClawchatReactMessageSchema, ClawchatReplyMomentCommentSchema, ClawchatRejectFriendRequestSchema, ClawchatRemoveFriendSchema, ClawchatSearchUsersSchema, ClawchatSendFriendRequestSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatRegisterAppSchema, ClawchatListAppsSchema, ClawchatUnregisterAppSchema, ClawchatLivewareLoginSchema, } from "./tools-schema.js";
 const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
 // Owner-approval gate business codes (must match the ClawChat backend's owner-approval codes).
 const CODE_PENDING_APPROVAL = 21001;
@@ -840,6 +840,37 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             },
         };
     }, { name: "clawchat_get_conversation" });
+    api.registerTool((ctx) => {
+        const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+        return {
+            name: "clawchat_get_direct_conversation",
+            label: "Get ClawChat Direct Conversation With User",
+            description: toolDescription("Resolve the direct (1:1) ClawChat conversation with a specific user to its conversation id (cnv_...), creating it if needed. " +
+                "TRIGGER - invoke when you need to send a message to a ClawChat user and only know their userId (usr_...), for example to start a conversation with a newly added friend. " +
+                "The user must already be your friend; otherwise the server rejects the call. " +
+                "Use the returned conversation.id as chatId for clawchat_mention_message. " +
+                "Never pass a userId or a name as a chatId."),
+            parameters: ClawchatGetDirectConversationSchema,
+            async execute(_callId, params) {
+                return await recordClawchatToolCall(accountId, "clawchat_get_direct_conversation", params, async () => {
+                    const p = params;
+                    const built = buildClient(accountId);
+                    if (!built.ok)
+                        return built.error;
+                    try {
+                        const data = await built.client.getDirectConversation(p.userId);
+                        return jsonResponse(data);
+                    }
+                    catch (err) {
+                        if (err instanceof ClawlingApiError) {
+                            return apiError(err);
+                        }
+                        return genericError(err);
+                    }
+                });
+            },
+        };
+    }, { name: "clawchat_get_direct_conversation" });
     api.registerTool((ctx) => {
         const accountId = resolveOpenclawClawlingToolAccountId(ctx);
         return {

package/dist/src/ws-client.js

@@ -643,6 +643,11 @@ export class ClawChatClient extends EventEmitter {
             this.emit("notify:signal", env);
         if (env.event === EVENT.REPLAY_DONE)
             this.emit("replay:done", env);
+        // Replay-start boundary frame (docs/client-integration.md §11.7). Control
+        // only: it carries no seq/dseq, so it is never acked and never becomes a
+        // `message`. Its own emitter keeps it out of the unknown-event path.
+        if (env.event === EVENT.HISTORY_TRUNCATED)
+            this.emit("history:truncated", env);
         if (env.event === EVENT.OFFLINE_DONE)
             this.emit("offline:done");
     }