@clawling/clawchat-plugin-openclaw 2026.9.14-2 → 2026.9.17-1

package/src/runtime.ts

@@ -17,7 +17,9 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient, resolveOpenclawClawlingDeviceId } from "./client.ts";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { buildActivationBootstrapText } from "./activation-greeting.ts";
+import { buildFriendGreetingEnvelope } from "./friend-greeting.ts";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.ts";
+import { readOnboardingReport } from "./onboarding-report.ts";
 import path from "node:path";
 import {
   ensureLivewareCli,
@@ -32,6 +34,7 @@ import {
 } from "./liveware-sample.ts";
 import { ClawlingApiError } from "./api-types.ts";
 import { RefreshManager } from "./refresh-manager.ts";
+import { RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
 import {
   runOpenclawClawlingLogin,
   type LoginParams,
@@ -209,9 +212,13 @@ const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
 ]);
 const GROUP_OWNER_ATTENTION_TITLE = "requires owner attention";
 // §C.1 — user-visible message emitted on permanent token expiry. Kept
-// byte-identical to the Hermes plugin (parity spec §C.1.4).
-const CLAWCHAT_TOKEN_EXPIRED_MESSAGE =
-  "ClawChat token expired and could not be refreshed. Re-pair with `/clawchat-activate <code>`.";
+// byte-identical to the Hermes plugin (parity spec §C.1.4). Points the owner
+// at the reconnect prompt (a code bound to this identity) rather than at a
+// slash command: a fresh create code spent here would mint a second agent.
+export const CLAWCHAT_TOKEN_EXPIRED_MESSAGE =
+  "ClawChat token expired and could not be refreshed. Ask your owner to send you the reconnect prompt from the ClawChat app, then follow " +
+  RECONNECT_GUIDE_URL +
+  ".";
 const CLAWCHAT_TOKEN_EXPIRED_LAST_ERROR = "token expired — re-pair required";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -1066,6 +1073,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     pluginVersion,
     agentVersion,
     authenticated: false,
+    onboarding: readOnboardingReport(),
     log,
   });
   // Ensure the liveware CLI is installed (async, never blocks startup).
@@ -1138,6 +1146,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     pluginVersion,
     agentVersion,
     authenticated: true,
+    onboarding: readOnboardingReport(),
     log,
   });
   // §A.0 — fallback expiry source. Prefer the SQLite `activated_at`; null for a
@@ -2368,6 +2377,39 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             ],
           }),
         );
+      } 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 as { oldest_seq?: unknown; reason?: unknown })
+          : undefined;
+        const rawReason = truncatedPayload?.reason;
+        const knownReason = rawReason === "pruned" || rawReason === "cursor_started_above_zero";
+        const fields: Array<[string, string | number]> = [
+          ["event_name", env.event],
+          ["trace_id", env.trace_id],
+          ["oldest_seq", typeof truncatedPayload?.oldest_seq === "number" ? truncatedPayload.oldest_seq : "-"],
+          ["reason", knownReason ? (rawReason as string) : "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?.(
@@ -2527,6 +2569,93 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // 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: Record<string, unknown> | undefined): void => {
+    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: Envelope) => {
     // §9.4 reliable system notification. The plugin holds no friend/roster
@@ -2641,6 +2770,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             );
           });
         }
+        if (type === "friend.added") {
+          scheduleFriendGreeting(payload as Record<string, unknown> | undefined);
+        }
       }
     }
   });

package/src/skill-update.ts

@@ -71,7 +71,7 @@ export const OFFICIAL_SKILLS_BASE =
  * 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.10.0";
 
 /** Refuse to treat an absurdly large response as a skill file (defence in depth). */
 export const MAX_SKILL_BYTES = 256 * 1024;

package/src/tools-schema.ts

@@ -201,6 +201,14 @@ export const ClawchatGetConversationSchema = Type.Object({
 });
 export type ClawchatGetConversationParams = Static<typeof ClawchatGetConversationSchema>;
 
+export const ClawchatGetDirectConversationSchema = Type.Object({
+  userId: Type.String({
+    minLength: 1,
+    description: "Concrete ClawChat user id (usr_...) of the friend",
+  }),
+});
+export type ClawchatGetDirectConversationParams = Static<typeof ClawchatGetDirectConversationSchema>;
+
 export const ClawchatLeaveGroupSchema = Type.Object({
   conversationId: Type.String({
     description: "Concrete ClawChat group conversation id to leave",

package/src/tools.ts

@@ -44,6 +44,7 @@ import {
 import {
   ClawchatGetAccountProfileSchema,
   ClawchatGetConversationSchema,
+  ClawchatGetDirectConversationSchema,
   ClawchatGetMomentSchema,
   ClawchatGetUserProfileSchema,
   ClawchatLeaveGroupSchema,
@@ -88,6 +89,7 @@ import {
   type ClawchatDeleteMomentParams,
   type ClawchatAcceptFriendRequestParams,
   type ClawchatGetConversationParams,
+  type ClawchatGetDirectConversationParams,
   type ClawchatGetMomentParams,
   type ClawchatGetUserProfileParams,
   type ClawchatLeaveGroupParams,
@@ -1090,6 +1092,41 @@ export function registerOpenclawClawlingTools(
     { 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 as ClawchatGetDirectConversationParams;
+            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);

package/src/ws-client.ts

@@ -733,6 +733,10 @@ export class ClawChatClient extends EventEmitter {
     if (env.event === EVENT.NOTIFY_SIGNAL) this.noteConversationSignalAlive(env);
     if (env.event === EVENT.NOTIFY_SIGNAL) 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");
   }