@clawling/clawchat-plugin-openclaw 2026.7.2 → 2026.7.6-2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.7.2",
+  "version": "2026.7.6-2",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/activation-greeting.ts

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// 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.
+const ACTIVATION_BOOTSTRAP_FALLBACK = [
+  "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");
+
+// Cross-plugin, user-editable override read lazily so edits apply on the next
+// first-load without a restart. Any read failure falls back to the built-in text.
+export function buildActivationBootstrapText(homeDir: string = os.homedir()): string {
+  const greetingPath = path.join(homeDir, "clawchat", "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 as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      console.warn(`clawchat.greeting failed to read override ${greetingPath}:`, error);
+    }
+  }
+  return ACTIVATION_BOOTSTRAP_FALLBACK;
+}

package/src/api-client.ts

@@ -24,6 +24,7 @@ export interface PluginReportInput {
   deviceId: string;
   platform: string;
   pluginVersion: string;
+  agentVersion: string;
   runtimeName: string;
   runtimeVersion: string;
 }
@@ -33,6 +34,7 @@ export function buildPluginReportBody(input: PluginReportInput): Record<string,
     device_id: input.deviceId,
     platform: input.platform,
     plugin_version: input.pluginVersion,
+    agent_version: input.agentVersion,
     runtime_name: input.runtimeName,
     runtime_version: input.runtimeVersion,
   };

package/src/config.ts

@@ -341,7 +341,7 @@ function decodeJwtStringClaim(token: string, claim: string): string {
  * userId that disagrees with `sub` is always wrong for the session this token
  * creates, and it silently breaks self-echo detection: with the OWNER's id
  * here, every owner message is dropped as the bot's own echo (2026-07-02
- * clawnest incident — a provisioner wrote the owner id into the config). Token
+ * production incident — a provisioner wrote the owner id into the config). Token
  * wins; the mismatch is logged. Also derives userId from `sub` when nothing is
  * configured, mirroring the `oid` fallback above.
  */

package/src/plugin-report.ts

@@ -46,6 +46,7 @@ export interface ReportParams {
   token: string;
   deviceId: string;
   pluginVersion: string;
+  agentVersion: string;
   authenticated: boolean;
   log?: { debug?: (msg: string) => void };
 }
@@ -66,6 +67,7 @@ export async function reportPluginVersionSafe(p: ReportParams): Promise<void> {
         deviceId: p.deviceId,
         platform: "openclaw",
         pluginVersion: p.pluginVersion,
+        agentVersion: p.agentVersion,
         runtimeName: "node",
         runtimeVersion: process.version,
       },

package/src/refresh-manager.ts

@@ -32,6 +32,13 @@ export const MIN_REFRESH_INTERVAL_MS = 30_000;
 export const PROACTIVE_JITTER_MS = 5 * MINUTE_MS;
 /** §A.0 — fallback access-token TTL when `exp` is unparseable. */
 export const ACCESS_TOKEN_TTL_MS = 24 * HOUR_MS;
+/**
+ * §A.1 — Node stores a `setTimeout` delay in a signed 32-bit int; a delay above
+ * this silently clamps to 1ms and fires *immediately*. Long-lived (~30-day)
+ * access tokens push `refresh_at - now` well past this, so the proactive wait is
+ * chunked into at-most-this-long sleeps that re-arm until the real time.
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647; // 2^31 - 1
 
 /** Opaque timer handle — `setTimeout` returns a `Timeout` in node, a number in others. */
 export type TimerHandle = ReturnType<typeof setTimeout> | number;
@@ -296,6 +303,20 @@ export class RefreshManager {
       jitterMs,
     });
     const delayMs = Math.max(0, refreshAtMs - this.now());
+    if (delayMs > MAX_TIMER_DELAY_MS) {
+      // Too far out for a single setTimeout without 32-bit overflow (which would
+      // fire at 1ms and trigger an immediate refresh + WS reconnect, cancelling
+      // any in-flight send). Sleep one max chunk, then re-arm from the still-live
+      // token for the remaining wait.
+      this.ports.log?.debug?.(
+        `clawchat-plugin-openclaw proactive timer chunked delayMs=${delayMs} chunk=${MAX_TIMER_DELAY_MS}`,
+      );
+      this.proactiveTimer = this.setTimer(() => {
+        this.proactiveTimer = null;
+        this.armProactiveTimer(activatedAtMs);
+      }, MAX_TIMER_DELAY_MS);
+      return;
+    }
     this.ports.log?.debug?.(
       `clawchat-plugin-openclaw proactive timer armed delayMs=${delayMs}`,
     );

package/src/runtime.ts

@@ -15,6 +15,7 @@ import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
 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 { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.ts";
 import { ensureLivewareCli } from "./liveware-cli.ts";
 import { ClawlingApiError } from "./api-types.ts";
@@ -38,7 +39,8 @@ import { dispatchOpenclawClawlingInbound, type IngestTurnParams } from "./inboun
 import {
   PendingConsentStore,
   handleOwnerConsentReply,
-  readEffectiveSkillVersions,
+  managedSkillExists,
+  readLocalSkillState,
   resolveBundledSkillsDir,
   resolveManagedSkillsDir,
   runSkillUpdateCheck,
@@ -100,6 +102,7 @@ type RuntimeConnectionStore = Pick<
     Pick<
       ClawChatStore,
       | "getActivationCredentials"
+      | "upsertActivation"
       | "rotateActivationTokens"
       | "clearActivationCredentials"
       | "insertMessage"
@@ -455,21 +458,6 @@ function withClawChatSessionScope(cfg: OpenClawConfig): OpenClawConfig {
   };
 }
 
-function buildActivationBootstrapText(): string {
-  // 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 [
-    "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: {
   account: ResolvedOpenclawClawlingAccount;
   conversationId: string;
@@ -871,6 +859,28 @@ async function waitForActivationCredentials(params: {
 }): Promise<{ account: ResolvedOpenclawClawlingAccount; source: "configured" | "sqlite" } | null> {
   const { abortSignal, getStatus, setStatus, store, log } = params;
   const accountId = params.account.accountId;
+  // SQLite-first: activation and token rotation persist to the activations
+  // row, so a complete row is the durable credential source of truth even
+  // when channel config/env also carries credentials. Config/env credentials
+  // only bootstrap the no-row case (the caller seeds a row from them).
+  if (store?.getActivationCredentials) {
+    const stored = store.getActivationCredentials({ platform: "openclaw", accountId });
+    if (stored && stored.accessToken !== params.rejectedActivationToken) {
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw loaded activation credentials from sqlite`,
+      );
+      return {
+        source: "sqlite",
+        account: {
+          ...params.account,
+          configured: true,
+          token: stored.accessToken,
+          userId: stored.userId,
+          ownerUserId: stored.ownerUserId,
+        },
+      };
+    }
+  }
   if (accountHasConnectCredentials(params.account)) {
     return { account: params.account, source: "configured" };
   }
@@ -956,12 +966,14 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // so the backend links both to the same row. Imported from ./client.ts.
   const reportDeviceId = resolveOpenclawClawlingDeviceId(account);
   const pluginVersion = resolvePluginVersion();
+  const agentVersion = runtime.version ?? "";
   void reportPluginVersionSafe({
     baseUrl: account.baseUrl,
     mediaBaseUrl: account.mediaBaseUrl,
     token: "",
     deviceId: reportDeviceId,
     pluginVersion,
+    agentVersion,
     authenticated: false,
     log,
   });
@@ -1001,6 +1013,27 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   });
   if (!activationAccount) return;
   account = activationAccount.account;
+  // Config/env bootstrap seeding: converge on SQLite as the single durable
+  // credential store, so token rotation always has a row to update and the
+  // next startup resolves SQLite-first to the same credentials.
+  if (activationAccount.source === "configured" && store?.upsertActivation) {
+    try {
+      store.upsertActivation({
+        platform: "openclaw",
+        accountId,
+        userId: account.userId,
+        ownerUserId: account.ownerUserId,
+        accessToken: account.token,
+        refreshToken: readConfigRefreshToken(cfg),
+        loginMethod: "config-seed",
+        deviceId: CHANNEL_ID,
+      });
+    } catch (error) {
+      log?.error?.(
+        `[${accountId}] clawchat-plugin-openclaw sqlite credential seed failed; continuing with config credentials: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
   // Paired: link the report row via the authenticated endpoint, reusing the
   // SAME frozen device_id so the backend upserts the existing unpaired row.
   void reportPluginVersionSafe({
@@ -1009,12 +1042,15 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     token: account.token,
     deviceId: reportDeviceId,
     pluginVersion,
+    agentVersion,
     authenticated: true,
     log,
   });
-  // §A.0 — fallback expiry source. Prefer the SQLite `activated_at`; null when
-  // the credentials came from config (no activation row yet) — in that case the
-  // refresh manager relies on the JWT `exp` alone.
+  // §A.0 — fallback expiry source. Prefer the SQLite `activated_at`; null for a
+  // configured start even though the seed block above may have just created a
+  // row — this cell only ever queries `store.getActivationCredentials` when
+  // `source === "sqlite"`, so a config-sourced account relies on the JWT `exp`
+  // alone until its next SQLite-first resolution.
   let activatedAtMs: number | null =
     activationAccount.source === "sqlite" && store?.getActivationCredentials
       ? store.getActivationCredentials({ platform: "openclaw", accountId })?.activatedAt ?? null
@@ -1207,16 +1243,16 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     getAccessToken: () => account.token,
     getRefreshToken: () => latestRefreshToken,
     persistRotatedTokens: async (tokens) => {
-      // §0 — persist to BOTH stores BEFORE the in-memory swap. A failure in
-      // EITHER store must REJECT so the manager skips the in-memory swap and
-      // treats the refresh as transient (keep the current tokens, back off). Do
-      // NOT swallow the SQLite write error: `rotateActivationTokens` returns
-      // `null` when its internal `write()` caught an exception (a real write
-      // failure), `false` only when no activation row exists yet (config-sourced
-      // agent — legitimately nothing to update). A swallowed write failure must
-      // not leave the SQLite row holding the now-dead refresh token while the
-      // in-memory token is rotated, which would brick a sqlite-sourced agent on
-      // restart.
+      // §0 — persist durably BEFORE the in-memory swap. SQLite is the
+      // startup credential source of truth: when a store is available its
+      // write must succeed or the refresh stays transient (no swap, keep
+      // current tokens, back off). A 0-row UPDATE (`false`) means the
+      // activations row is missing (e.g. cleared out-of-band) rather than a
+      // write failure — self-heal by re-seeding it from the in-memory
+      // identity with the ROTATED pair (mirrors Hermes's seed-on-rotate
+      // §C.2 semantics), then continue exactly as on success. `null` is a
+      // caught write exception and stays transient — that's a real failure,
+      // not a missing row.
       if (store?.rotateActivationTokens) {
         const rotateResult = store.rotateActivationTokens({
           platform: "openclaw",
@@ -1224,12 +1260,41 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           accessToken: tokens.accessToken,
           refreshToken: tokens.refreshToken,
         });
-        if (rotateResult === null) {
+        if (rotateResult === false) {
+          if (!store.upsertActivation) {
+            throw new Error("clawchat-plugin-openclaw sqlite rotate activation tokens failed");
+          }
+          try {
+            store.upsertActivation({
+              platform: "openclaw",
+              accountId,
+              userId: account.userId,
+              ownerUserId: account.ownerUserId,
+              accessToken: tokens.accessToken,
+              refreshToken: tokens.refreshToken,
+              loginMethod: "config-seed",
+              deviceId: refreshDeviceId,
+            });
+          } catch {
+            throw new Error("clawchat-plugin-openclaw sqlite rotate activation tokens failed");
+          }
+        } else if (rotateResult === null) {
           throw new Error("clawchat-plugin-openclaw sqlite rotate activation tokens failed");
         }
+        // Channel config is a human-readable mirror once SQLite holds the
+        // pair — sync best-effort, never fail the refresh over it.
+        try {
+          await persistConfigTokens(tokens);
+        } catch (error) {
+          log?.error?.(
+            `[${accountId}] clawchat-plugin-openclaw config token mirror failed (sqlite already rotated): ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+        return;
       }
-      // A config write failure rejects out of `mutateConfigFile` and propagates
-      // here, which is what we want — persistence incomplete ⇒ no swap.
+      // No SQLite store available — channel config is the only durable
+      // store, so its write failure must reject and keep the refresh
+      // transient (pre-existing behavior for store-less test transports).
       await persistConfigTokens(tokens);
     },
     swapInMemoryTokens: (tokens) => {
@@ -2154,6 +2219,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // 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`).
+  // Update detection converges on raw sha256 (readLocalSkillState), not the
+  // frontmatter version, so a same-version content fix still applies; a
+  // manifest `removed` id tombstones the LOCAL managed copy (never bundled)
+  // via removeManagedSkill, deleting only ids the official manifest names.
   const skillUpdateConsent = new PendingConsentStore();
   const managedSkillsDir = resolveManagedSkillsDir();
   let bundledSkillsDir: string | null = null;
@@ -2203,10 +2272,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       return;
     }
     // Effective current = managed copy if present, else bundled (host precedence).
-    const localVersions = await readEffectiveSkillVersions(managedSkillsDir, bundledSkillsDir);
     await runSkillUpdateCheck({
       ownerUserId,
-      localVersions,
+      readLocalState: (id) => readLocalSkillState(managedSkillsDir, bundledSkillsDir, id),
+      hasManagedSkill: (id) => managedSkillExists(managedSkillsDir, id),
       fetchFn: globalThis.fetch,
       store: skillUpdateConsent,
       sendOwnerMessage: sendOwnerSkillMessage,