@clawling/clawchat-plugin-openclaw 2026.6.30-1 → 2026.6.30-3

package/dist/src/runtime.js

@@ -33,6 +33,34 @@ export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 const activeClients = new Map();
 const CLAWCHAT_PLUGIN_SLASH_COMMANDS = new Set(["clawchat-activate", "clawchat-output"]);
 const ACTIVATION_CREDENTIAL_POLL_INTERVAL_MS = 2_000;
+// Activation-bootstrap retry on the live connection. The bootstrap greeting is
+// otherwise only (re)dispatched on a fresh `connected` edge, so if its send is
+// cancelled mid-turn (e.g. a proactive token-refresh reconnect closed the
+// transport) or a reconnect's claim no-op'd while a stale in-flight dispatch
+// still held the claim, the greeting would stay pending forever on a now-stable
+// connection. These bound an in-connection retry that re-attempts until the
+// greeting lands or the per-connection budget is spent (then it falls back to
+// the next reconnect, as before).
+const ACTIVATION_BOOTSTRAP_RETRY_DELAY_MS = 5_000;
+const ACTIVATION_BOOTSTRAP_MAX_RETRIES = 6;
+// Count of in-flight activation-bootstrap dispatches per account, shared across
+// gateway re-enters so a fresh connection can tell "nothing pending" (don't
+// retry) apart from "a prior dispatch still holds the claim" (retry once it
+// releases).
+const activationBootstrapInFlight = new Map();
+function incrementActivationBootstrapInFlight(accountId) {
+    activationBootstrapInFlight.set(accountId, (activationBootstrapInFlight.get(accountId) ?? 0) + 1);
+}
+function decrementActivationBootstrapInFlight(accountId) {
+    const next = (activationBootstrapInFlight.get(accountId) ?? 0) - 1;
+    if (next <= 0)
+        activationBootstrapInFlight.delete(accountId);
+    else
+        activationBootstrapInFlight.set(accountId, next);
+}
+function activationBootstrapInFlightCount(accountId) {
+    return activationBootstrapInFlight.get(accountId) ?? 0;
+}
 // Upper bound (ms) on how long group ingest waits for the FIRST group-settings
 // pull to settle before proceeding anyway. Best-effort governance must never
 // permanently disable group traffic, so a stalled initial GET (endpoint accepts
@@ -279,12 +307,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) {
@@ -1440,6 +1473,38 @@ 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;
+    // Per-connection retry for a pending activation bootstrap (see the module-level
+    // constants). Re-attempts on the live connection while `wsReady`, bounded by
+    // ACTIVATION_BOOTSTRAP_MAX_RETRIES; the budget resets on each fresh connect.
+    let bootstrapRetryTimer;
+    let bootstrapRetryAttempts = 0;
+    const bootstrapRetryDelayMs = Math.max(1, params.activationBootstrapRetryDelayMs ?? ACTIVATION_BOOTSTRAP_RETRY_DELAY_MS);
+    const clearBootstrapRetry = () => {
+        if (bootstrapRetryTimer !== undefined) {
+            clearTimeout(bootstrapRetryTimer);
+            bootstrapRetryTimer = undefined;
+        }
+    };
+    const armBootstrapRetry = () => {
+        if (bootstrapRetryTimer !== undefined)
+            return;
+        if (!wsReady)
+            return;
+        if (bootstrapRetryAttempts >= ACTIVATION_BOOTSTRAP_MAX_RETRIES)
+            return;
+        bootstrapRetryTimer = setTimeout(() => {
+            bootstrapRetryTimer = undefined;
+            if (!wsReady)
+                return;
+            bootstrapRetryAttempts += 1;
+            void dispatchActivationBootstrap();
+        }, bootstrapRetryDelayMs);
+    };
     client.on("state", ({ from, to }) => {
         log?.info?.(`[${accountId}] clawchat-plugin-openclaw state ${from} -> ${to}`);
         wsReady = to === "connected";
@@ -1512,6 +1577,9 @@ export async function startOpenclawClawlingGateway(params) {
                 // The queue keeps the failed frame at the head and will retry after the next reconnect.
             }
             void refreshConversationCacheAfterReady();
+            // Fresh connection → fresh retry budget; cancel any stale timer first.
+            bootstrapRetryAttempts = 0;
+            clearBootstrapRetry();
             void dispatchActivationBootstrap();
             // Re-pull per-group agent settings on every successful (re)connect so the
             // cache stays current after a network interruption or token refresh.
@@ -1523,6 +1591,8 @@ export async function startOpenclawClawlingGateway(params) {
         }
         else if (to === "disconnected") {
             reconnectTracker.markClosed();
+            // Stop the bootstrap retry while down; it re-arms on the next ready.
+            clearBootstrapRetry();
             // §A.1 — clear the proactive timer on disconnect; it re-arms on the next
             // ready, or the gateway re-enter arms a fresh one.
             if (!reconnectWithRefreshedToken)
@@ -2131,6 +2201,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). ` +
@@ -2373,6 +2449,7 @@ export async function startOpenclawClawlingGateway(params) {
         if (!store?.claimPendingActivationBootstrap || !store.markActivationBootstrapSent)
             return;
         let bootstrap;
+        let claimedInFlight = false;
         const releaseBootstrap = () => {
             if (!bootstrap || !store.releaseActivationBootstrapClaim)
                 return;
@@ -2385,12 +2462,34 @@ export async function startOpenclawClawlingGateway(params) {
         };
         try {
             bootstrap = recordConnection("activation bootstrap claim", () => store.claimPendingActivationBootstrap?.({ platform: "openclaw", accountId }));
-            if (!bootstrap)
+            if (!bootstrap) {
+                // Nothing claimable right now. If another dispatch (e.g. a pre-reconnect
+                // one that was about to fail) still holds the claim, keep retrying on
+                // this live connection so the greeting isn't stranded once it releases.
+                if (activationBootstrapInFlightCount(accountId) > 0)
+                    armBootstrapRetry();
                 return;
+            }
             const claimedBootstrap = bootstrap;
+            claimedInFlight = true;
+            incrementActivationBootstrapInFlight(accountId);
+            bootstrapProducedFinal = false;
             const result = await handleInboundEnvelope(buildActivationBootstrapEnvelope({ account, conversationId: claimedBootstrap.conversationId }));
             if (result !== "submitted") {
                 releaseBootstrap();
+                armBootstrapRetry();
+                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 greeting send was cancelled by a reconnect, or the
+            // agent went off to write a file/note instead of replying — leave the
+            // bootstrap pending (release the claim) and retry on the live connection,
+            // rather than silently consuming it forever or waiting for the next reconnect.
+            if (!bootstrapProducedFinal) {
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw activation bootstrap dispatched but produced no final reply; leaving pending for retry`);
+                releaseBootstrap();
+                armBootstrapRetry();
                 return;
             }
             recordConnection("activation bootstrap sent", () => store.markActivationBootstrapSent?.({
@@ -2398,11 +2497,18 @@ export async function startOpenclawClawlingGateway(params) {
                 accountId,
                 conversationId: claimedBootstrap.conversationId,
             }));
+            // Delivered — stop any pending retry.
+            clearBootstrapRetry();
         }
         catch (err) {
             releaseBootstrap();
+            armBootstrapRetry();
             log?.error?.(`[${accountId}] clawchat-plugin-openclaw activation bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
         }
+        finally {
+            if (claimedInFlight)
+                decrementActivationBootstrapInFlight(accountId);
+        }
     };
     client.on("message", (env) => {
         void (async () => {
@@ -2514,6 +2620,7 @@ export async function startOpenclawClawlingGateway(params) {
         log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime abort received; closing client`);
         activeClients.delete(accountId);
         closingForAbort = true;
+        clearBootstrapRetry();
         // §A.1 — stop the proactive refresh timer on shutdown.
         refreshManager.stop();
         groupCoalescer.cancelAll();

package/package.json

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

package/src/runtime.ts

@@ -120,6 +120,32 @@ export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 const activeClients = new Map<string, ClawlingChatClient>();
 const CLAWCHAT_PLUGIN_SLASH_COMMANDS = new Set(["clawchat-activate", "clawchat-output"]);
 const ACTIVATION_CREDENTIAL_POLL_INTERVAL_MS = 2_000;
+// Activation-bootstrap retry on the live connection. The bootstrap greeting is
+// otherwise only (re)dispatched on a fresh `connected` edge, so if its send is
+// cancelled mid-turn (e.g. a proactive token-refresh reconnect closed the
+// transport) or a reconnect's claim no-op'd while a stale in-flight dispatch
+// still held the claim, the greeting would stay pending forever on a now-stable
+// connection. These bound an in-connection retry that re-attempts until the
+// greeting lands or the per-connection budget is spent (then it falls back to
+// the next reconnect, as before).
+const ACTIVATION_BOOTSTRAP_RETRY_DELAY_MS = 5_000;
+const ACTIVATION_BOOTSTRAP_MAX_RETRIES = 6;
+// Count of in-flight activation-bootstrap dispatches per account, shared across
+// gateway re-enters so a fresh connection can tell "nothing pending" (don't
+// retry) apart from "a prior dispatch still holds the claim" (retry once it
+// releases).
+const activationBootstrapInFlight = new Map<string, number>();
+function incrementActivationBootstrapInFlight(accountId: string): void {
+  activationBootstrapInFlight.set(accountId, (activationBootstrapInFlight.get(accountId) ?? 0) + 1);
+}
+function decrementActivationBootstrapInFlight(accountId: string): void {
+  const next = (activationBootstrapInFlight.get(accountId) ?? 0) - 1;
+  if (next <= 0) activationBootstrapInFlight.delete(accountId);
+  else activationBootstrapInFlight.set(accountId, next);
+}
+function activationBootstrapInFlightCount(accountId: string): number {
+  return activationBootstrapInFlight.get(accountId) ?? 0;
+}
 // Upper bound (ms) on how long group ingest waits for the FIRST group-settings
 // pull to settle before proceeding anyway. Best-effort governance must never
 // permanently disable group traffic, so a stalled initial GET (endpoint accepts
@@ -427,12 +453,17 @@ 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 [
-    "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");
 }
 
@@ -538,6 +569,8 @@ export interface StartGatewayParams {
   backoffTimer?: (cb: () => void, ms: number) => void;
   /** Test hook only — fixed transport-backoff delay (ms) for re-enter. */
   transportBackoffDelayMs?: number;
+  /** Test hook only — retry delay (ms) for re-dispatching a pending activation bootstrap. */
+  activationBootstrapRetryDelayMs?: number;
 }
 
 /**
@@ -1816,6 +1849,37 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     );
   };
   let dispatchActivationBootstrap: () => Promise<void> = 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;
+  // Per-connection retry for a pending activation bootstrap (see the module-level
+  // constants). Re-attempts on the live connection while `wsReady`, bounded by
+  // ACTIVATION_BOOTSTRAP_MAX_RETRIES; the budget resets on each fresh connect.
+  let bootstrapRetryTimer: ReturnType<typeof setTimeout> | undefined;
+  let bootstrapRetryAttempts = 0;
+  const bootstrapRetryDelayMs = Math.max(
+    1,
+    params.activationBootstrapRetryDelayMs ?? ACTIVATION_BOOTSTRAP_RETRY_DELAY_MS,
+  );
+  const clearBootstrapRetry = () => {
+    if (bootstrapRetryTimer !== undefined) {
+      clearTimeout(bootstrapRetryTimer);
+      bootstrapRetryTimer = undefined;
+    }
+  };
+  const armBootstrapRetry = () => {
+    if (bootstrapRetryTimer !== undefined) return;
+    if (!wsReady) return;
+    if (bootstrapRetryAttempts >= ACTIVATION_BOOTSTRAP_MAX_RETRIES) return;
+    bootstrapRetryTimer = setTimeout(() => {
+      bootstrapRetryTimer = undefined;
+      if (!wsReady) return;
+      bootstrapRetryAttempts += 1;
+      void dispatchActivationBootstrap();
+    }, bootstrapRetryDelayMs);
+  };
 
   client.on("state", ({ from, to }) => {
     log?.info?.(`[${accountId}] clawchat-plugin-openclaw state ${from} -> ${to}`);
@@ -1890,6 +1954,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         // The queue keeps the failed frame at the head and will retry after the next reconnect.
       }
       void refreshConversationCacheAfterReady();
+      // Fresh connection → fresh retry budget; cancel any stale timer first.
+      bootstrapRetryAttempts = 0;
+      clearBootstrapRetry();
       void dispatchActivationBootstrap();
       // Re-pull per-group agent settings on every successful (re)connect so the
       // cache stays current after a network interruption or token refresh.
@@ -1900,6 +1967,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       refreshManager.armProactiveTimer(activatedAtMs);
     } else if (to === "disconnected") {
       reconnectTracker.markClosed();
+      // Stop the bootstrap retry while down; it re-arms on the next ready.
+      clearBootstrapRetry();
       // §A.1 — clear the proactive timer on disconnect; it re-arms on the next
       // ready, or the gateway re-enter arms a fresh one.
       if (!reconnectWithRefreshedToken) refreshManager.disarmProactiveTimer();
@@ -2579,6 +2648,12 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         const queuedFinal = Boolean(
           (dispatchResult as { queuedFinal?: boolean } | undefined)?.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)}`,
         );
@@ -2860,6 +2935,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   dispatchActivationBootstrap = async (): Promise<void> => {
     if (!store?.claimPendingActivationBootstrap || !store.markActivationBootstrapSent) return;
     let bootstrap: { conversationId: string } | null | undefined;
+    let claimedInFlight = false;
     const releaseBootstrap = () => {
       if (!bootstrap || !store.releaseActivationBootstrapClaim) return;
       const claimedBootstrap = bootstrap;
@@ -2875,13 +2951,37 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       bootstrap = recordConnection("activation bootstrap claim", () =>
         store.claimPendingActivationBootstrap?.({ platform: "openclaw", accountId }),
       );
-      if (!bootstrap) return;
+      if (!bootstrap) {
+        // Nothing claimable right now. If another dispatch (e.g. a pre-reconnect
+        // one that was about to fail) still holds the claim, keep retrying on
+        // this live connection so the greeting isn't stranded once it releases.
+        if (activationBootstrapInFlightCount(accountId) > 0) armBootstrapRetry();
+        return;
+      }
       const claimedBootstrap = bootstrap;
+      claimedInFlight = true;
+      incrementActivationBootstrapInFlight(accountId);
+      bootstrapProducedFinal = false;
       const result = await handleInboundEnvelope(
         buildActivationBootstrapEnvelope({ account, conversationId: claimedBootstrap.conversationId }),
       );
       if (result !== "submitted") {
         releaseBootstrap();
+        armBootstrapRetry();
+        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 greeting send was cancelled by a reconnect, or the
+      // agent went off to write a file/note instead of replying — leave the
+      // bootstrap pending (release the claim) and retry on the live connection,
+      // rather than silently consuming it forever or waiting for the next reconnect.
+      if (!bootstrapProducedFinal) {
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw activation bootstrap dispatched but produced no final reply; leaving pending for retry`,
+        );
+        releaseBootstrap();
+        armBootstrapRetry();
         return;
       }
       recordConnection("activation bootstrap sent", () =>
@@ -2891,11 +2991,16 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           conversationId: claimedBootstrap.conversationId,
         }),
       );
+      // Delivered — stop any pending retry.
+      clearBootstrapRetry();
     } catch (err) {
       releaseBootstrap();
+      armBootstrapRetry();
       log?.error?.(
         `[${accountId}] clawchat-plugin-openclaw activation bootstrap failed: ${err instanceof Error ? err.message : String(err)}`,
       );
+    } finally {
+      if (claimedInFlight) decrementActivationBootstrapInFlight(accountId);
     }
   };
 
@@ -3020,6 +3125,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime abort received; closing client`);
     activeClients.delete(accountId);
     closingForAbort = true;
+    clearBootstrapRetry();
     // §A.1 — stop the proactive refresh timer on shutdown.
     refreshManager.stop();
     groupCoalescer.cancelAll();