@clawling/clawchat-plugin-openclaw 2026.6.24-1 → 2026.6.30-2

package/README.md

@@ -90,20 +90,26 @@ src/
   api-types.ts          /v1/* request/response type definitions
   inbound.ts            envelope → agent turn
   outbound.ts           agent reply → envelope
-  streaming.ts          progressive reply emitter
-  buffered-stream.ts    chunk coalescing + flush policy
   message-mapper.ts     fragment ↔ text/media mapping
   group-message-coalescer.ts
                         per-group idle/max batching for non-mention turns
+  group-settings.ts     per-group agent settings cache (GET /v1/agents/me/
+                        group-settings)
   reply-dispatcher.ts   static vs stream routing
+  no-reply.ts           clawchat:no-reply / :silent suppression token guard
   login.runtime.ts      invite-code exchange flow
+  refresh-manager.ts    ClawChat token refresh + auto-logout orchestration
+  skill-update.ts       conversational, adapter-driven skill hot-update
   media-runtime.ts      media download/upload pipeline
+  liveware-cli.ts       liveware asset download helper (custom CDN User-Agent)
   tools.ts              clawchat_* agent tools (account / media / memory /
                         metadata / moments / mention)
   tools-schema.ts       JSON schemas for the clawchat_* tools
   protocol.ts           inbound payload type guards
   protocol-types.ts     v2 envelope, fragment, transport shapes
   config.ts             defaults + typebox schema
+  config-compat.ts      migration for the plugin rename (openclaw-clawchat →
+                        clawchat-plugin-openclaw id/channel key)
   storage.ts            plugin-owned SQLite (activations, connections,
                         clawchat_messages, tool_calls)
   clawchat-memory.ts    file-backed memory tools (see docs/clawchat-memory.md)
@@ -114,6 +120,8 @@ src/
   plugin-prompts.ts     loads prompts/platform.md and default-* prompts
   ws-alignment.ts       handshake capabilities + hello-ok diagnostics
   ws-log.ts             clawchat.ws single-line log formatting
+  llm-context-debug.ts  opt-in LLM input/output snapshot capture for debugging
+  plugin-report.ts      best-effort read of this plugin's package version
   commands.ts           /clawchat-activate runtime slash command
   terminal-send.ts      terminal-send suppression for clawchat_mention_message
   mock-transport.ts     in-memory Transport double for tests
@@ -178,4 +186,4 @@ plugin tests or publish the package.
 
 ## License
 
-See the repository root.
+MIT — see [LICENSE](./LICENSE).

package/dist/src/api-client.js

@@ -418,6 +418,9 @@ export function createOpenclawClawlingApiClient(opts) {
             if (userId?.trim()) {
                 body.user_id = userId.trim();
             }
+            if (opts.pluginVersion?.trim()) {
+                body.plugin_version = opts.pluginVersion.trim();
+            }
             return await call("POST", "/v1/agents/connect", {
                 // `X-Device-Id` is added globally via `authHeaders` on every request.
                 headers: { "content-type": "application/json" },

package/dist/src/inbound.js

@@ -149,6 +149,27 @@ export async function dispatchOpenclawClawlingInbound(params) {
         chatType,
         userId: account.userId,
     });
+    // Pending-consent gate for conversational skill hot-update. Only owner direct
+    // messages can answer a pending skill-update ask; the gate parses consent
+    // conservatively and, when it consumes the reply (affirm/deny), the message
+    // does NOT continue to the LLM. Ambiguous/unrelated replies return false and
+    // flow on normally (pending survives until timeout). See src/skill-update.ts.
+    if (chatType === "direct" &&
+        params.consumeOwnerConsent &&
+        account.ownerUserId &&
+        sender.id === account.ownerUserId) {
+        let consumed = false;
+        try {
+            consumed = await params.consumeOwnerConsent({ senderId: sender.id, text: rawBody, chatId });
+        }
+        catch (err) {
+            log?.error?.(`[${account.accountId}] clawchat-plugin-openclaw skill-update consent gate error msg=${payload.message_id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (consumed) {
+            log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw owner reply consumed as skill-update consent msg=${payload.message_id}`);
+            return;
+        }
+    }
     // NOTE: the static mention-mode early-drop was removed here (Task 7 fix).
     // Non-mention group messages now always flow through to ingestTurn, which
     // applies the dynamic gate (GroupSettingsCache.effective) and returns

package/dist/src/login.runtime.js

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { ClawlingApiError } from "./api-types.js";
+import { resolvePluginVersion } from "./plugin-report.js";
 import { CHANNEL_ID, mergeOpenclawClawchatRuntimePluginActivation, mergeOpenclawClawchatToolAllow, resolveOpenclawClawlingAccount, } from "./config.js";
 import { getClawChatStore } from "./storage.js";
 /**
@@ -135,6 +136,7 @@ export async function runOpenclawClawlingLogin(params) {
         // Pre-login we may not have a token yet. Send the current one (or empty)
         // — the server should accept an unauthenticated invite-code exchange.
         token: account.token || "",
+        pluginVersion: resolvePluginVersion(),
     });
     runtime.log("Verifying invite code …");
     let result;

package/dist/src/reply-dispatcher.js

@@ -418,7 +418,7 @@ export function createOpenclawClawlingReplyDispatcher(options) {
     };
     // §7.6 (binding): client-supplied message_id MUST be `msg-` + a 26-char
     // Crockford base32 ULID. Use the shared conformant minter — do not invent a
-    // different scheme (planned msghub Phase-4 validation will reject it).
+    // different scheme (planned backend validation will reject it).
     const mintStaticMessageId = () => mintMessageId();
     const emitTyping = (isTyping) => {
         if (!isTyping && !typingActive)

package/dist/src/runtime.js

@@ -11,6 +11,7 @@ import { RefreshManager } from "./refresh-manager.js";
 import { runOpenclawClawlingLogin, } from "./login.runtime.js";
 import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, effectiveGroupMode, hasOpenclawClawlingConnectCredentials, resolveOpenclawClawlingAccount, } from "./config.js";
 import { dispatchOpenclawClawlingInbound } from "./inbound.js";
+import { PendingConsentStore, handleOwnerConsentReply, readEffectiveSkillVersions, resolveBundledSkillsDir, resolveManagedSkillsDir, runSkillUpdateCheck, } from "./skill-update.js";
 import { fetchInboundMedia } from "./media-runtime.js";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
 import { runWithTerminalClawChatSendScope } from "./terminal-send.js";
@@ -278,12 +279,17 @@ function withClawChatSessionScope(cfg) {
     };
 }
 function buildActivationBootstrapText() {
+    // Worded to make the greeting the single required action. Earlier wording
+    // ("ClawChat activation bootstrap: ... do both ...") led some agents to treat
+    // it as a setup task and write a `BOOTSTRAP.md` file instead of replying, so
+    // no greeting reached the user. Lead with the chat reply, forbid file/tool
+    // detours, and keep the profile update strictly optional and secondary.
     return [
-        "ClawChat activation bootstrap: You are now connected to this ClawChat direct conversation.",
-        "Please do both:",
-        "1. Send a brief, friendly greeting to the user in this ClawChat direct conversation.",
-        "2. If you have local profile information for yourself, such as display name, bio, or avatar, update the connected ClawChat account profile using the available ClawChat tools. Use `clawchat_update_account_profile` for display name/bio/avatar URL, and use `clawchat_upload_avatar_image` first if the avatar is only available as a local image path. If you do not have local profile information, skip profile updates and only greet the user.",
-        "Do not ask the user for profile information just for this bootstrap.",
+        "You are now connected to a ClawChat direct conversation with your user.",
+        "Reply now with one short, friendly greeting message in this conversation: introduce yourself and say you are connected and ready.",
+        "Send it as a normal chat reply. Do not write or create any files or notes, and do not call tools just to greet.",
+        "Only if you already have your own profile details (display name, bio, or avatar) may you also call `clawchat_update_account_profile` (use `clawchat_upload_avatar_image` first for a local avatar image); otherwise skip that and just greet.",
+        "Do not ask the user for profile information.",
     ].join("\n");
 }
 function buildActivationBootstrapEnvelope(params) {
@@ -1439,6 +1445,11 @@ export async function startOpenclawClawlingGateway(params) {
         }));
     };
     let dispatchActivationBootstrap = async () => { };
+    // Set by dispatchTurnToAgent when it dispatches the synthetic
+    // `clawchat-bootstrap` turn: true only if the agent actually produced a final
+    // outbound message (the greeting). The bootstrap dispatcher reads it to decide
+    // whether to mark the bootstrap sent or leave it pending for a later retry.
+    let bootstrapProducedFinal = false;
     client.on("state", ({ from, to }) => {
         log?.info?.(`[${accountId}] clawchat-plugin-openclaw state ${from} -> ${to}`);
         wsReady = to === "connected";
@@ -1655,6 +1666,75 @@ export async function startOpenclawClawlingGateway(params) {
     client.on("metadata:invalidated", (env) => {
         void handleMetadataInvalidation(env);
     });
+    // --- Conversational skill hot-update (adapter-driven; see src/skill-update.ts) ---
+    // One pending-consent record per runtime.
+    // WRITE target = the OpenClaw-managed skills dir (`<stateDir>/skills`): it is
+    // chokidar-watched (host src/skills/runtime/refresh.ts:107) so a write bumps
+    // the snapshot + rebuilds the prompt next turn, and it loads at HIGHER
+    // precedence than plugin-bundled skills (managed=3 > bundled=2, host
+    // src/skills/loading/workspace.ts:1220-1239), overriding the bundled copy.
+    // The bundled `./skills` dir is READ-ONLY here: a first-boot fallback for the
+    // "current installed version" only — never written (it lives in node_modules
+    // → may be read-only and is clobbered on `openclaw plugins update`).
+    const skillUpdateConsent = new PendingConsentStore();
+    const managedSkillsDir = resolveManagedSkillsDir();
+    let bundledSkillsDir = null;
+    try {
+        bundledSkillsDir = resolveBundledSkillsDir();
+    }
+    catch (err) {
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw skill-update: bundled skills dir not resolvable (using managed-only current): ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const sendOwnerSkillMessage = async (text) => {
+        const ownerUserId = account.ownerUserId?.trim();
+        if (!ownerUserId)
+            return;
+        await sendOpenclawClawlingText({
+            client,
+            account,
+            to: { chatId: ownerUserId, chatType: "direct" },
+            text,
+            log,
+        });
+    };
+    const triggerSkillUpdateCheck = async () => {
+        const ownerUserId = account.ownerUserId?.trim();
+        if (!ownerUserId) {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw skill-update check skipped: no owner user id`);
+            return;
+        }
+        // Effective current = managed copy if present, else bundled (host precedence).
+        const localVersions = await readEffectiveSkillVersions(managedSkillsDir, bundledSkillsDir);
+        await runSkillUpdateCheck({
+            ownerUserId,
+            localVersions,
+            fetchFn: globalThis.fetch,
+            store: skillUpdateConsent,
+            sendOwnerMessage: sendOwnerSkillMessage,
+            log: {
+                info: (m) => log?.info?.(`[${accountId}] clawchat-plugin-openclaw ${m}`),
+                error: (m) => log?.error?.(`[${accountId}] clawchat-plugin-openclaw ${m}`),
+            },
+        });
+    };
+    const consumeOwnerSkillConsent = async (args) => {
+        const ownerUserId = account.ownerUserId?.trim();
+        if (!ownerUserId)
+            return false;
+        return handleOwnerConsentReply({
+            ownerUserId,
+            senderId: args.senderId,
+            text: args.text,
+            store: skillUpdateConsent,
+            fetchFn: globalThis.fetch,
+            skillsDir: managedSkillsDir,
+            sendOwnerMessage: sendOwnerSkillMessage,
+            log: {
+                info: (m) => log?.info?.(`[${accountId}] clawchat-plugin-openclaw ${m}`),
+                error: (m) => log?.error?.(`[${accountId}] clawchat-plugin-openclaw ${m}`),
+            },
+        });
+    };
     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
@@ -1670,6 +1750,15 @@ export async function startOpenclawClawlingGateway(params) {
                 log?.info?.(`[${accountId}] clawchat-plugin-openclaw agent.config.changed signal received; re-pulling group settings`);
                 pullGroupSettings();
             }
+            else if (type === "clawchat.skill.update.check") {
+                // Content-free trigger: check the official skill source in code and, if
+                // there is an update, ask the owner in chat for consent. The atomic
+                // overwrite happens later when the owner affirms (consent gate).
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw clawchat.skill.update.check signal received; checking official skill source`);
+                void triggerSkillUpdateCheck().catch((err) => {
+                    log?.error?.(`[${accountId}] clawchat-plugin-openclaw skill-update check failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
         }
     });
     client.on("replay:done", (env) => {
@@ -2052,6 +2141,12 @@ export async function startOpenclawClawlingGateway(params) {
                 });
                 const counts = dispatchResult?.counts ?? {};
                 const queuedFinal = Boolean(dispatchResult?.queuedFinal);
+                if (turn.senderId === "clawchat-bootstrap") {
+                    // Did the agent actually emit a greeting? A final outbound message
+                    // means yes; block/tool-only (or nothing) means the greeting never
+                    // reached the user, so the bootstrap dispatcher will keep it pending.
+                    bootstrapProducedFinal = queuedFinal || (counts.final ?? 0) > 0;
+                }
                 log?.info?.(`[${accountId}] clawchat-plugin-openclaw dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`);
                 if (!queuedFinal && Object.values(counts).every((n) => !n)) {
                     log?.info?.(`[${accountId}] clawchat-plugin-openclaw NO reply was produced (no final / block / tool dispatched). ` +
@@ -2278,6 +2373,7 @@ export async function startOpenclawClawlingGateway(params) {
                 runtime,
                 account,
                 log,
+                consumeOwnerConsent: consumeOwnerSkillConsent,
                 ingest: async (turn) => {
                     ingestResult = await ingestTurn(turn);
                 },
@@ -2308,11 +2404,22 @@ export async function startOpenclawClawlingGateway(params) {
             if (!bootstrap)
                 return;
             const claimedBootstrap = bootstrap;
+            bootstrapProducedFinal = false;
             const result = await handleInboundEnvelope(buildActivationBootstrapEnvelope({ account, conversationId: claimedBootstrap.conversationId }));
             if (result !== "submitted") {
                 releaseBootstrap();
                 return;
             }
+            // Only mark the bootstrap done once the agent has actually sent a greeting
+            // (a final outbound message). If the turn was handed off but produced no
+            // final reply — e.g. the agent went off to write a file/note instead of
+            // replying — leave the bootstrap pending (release the claim) so the next
+            // ready re-dispatches it, rather than silently consuming it forever.
+            if (!bootstrapProducedFinal) {
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw activation bootstrap dispatched but produced no final reply; leaving pending for retry`);
+                releaseBootstrap();
+                return;
+            }
             recordConnection("activation bootstrap sent", () => store.markActivationBootstrapSent?.({
                 platform: "openclaw",
                 accountId,