@clawling/clawchat-plugin-openclaw 2026.10.11-2 → 2026.10.13-1

package/src/inbound.ts

@@ -27,6 +27,12 @@ export interface IngestTurnParams {
   senderIsOwner?: boolean;
   senderIsGroupOwner?: boolean;
   rawBody: string;
+  /**
+   * Group only: the text after the @-mentions the message opens with, when
+   * those mentions address this agent (or @everyone). `@agent /new` yields
+   * `/new`, which the runtime checks as a group slash command.
+   */
+  addressedCommandBody?: string;
   messageId: string;
   /**
    * All constituent message IDs represented by this turn. Single messages
@@ -66,6 +72,34 @@ export interface IngestTurnParams {
   envelope: Envelope<unknown>;
 }
 
+/**
+ * The text after the mention fragments a message opens with (only blank text
+ * may sit between them), when one of those mentions is `userId` or
+ * @everyone. Mention fragments are the source of truth: a display name may
+ * contain spaces, so the rendered `@name` cannot be split off by pattern.
+ */
+export function textAfterLeadingMentionsOf(
+  fragments: Array<Record<string, unknown>>,
+  userId: string | undefined,
+): string | null {
+  if (!userId || !Array.isArray(fragments)) return null;
+  const ids: string[] = [];
+  let index = 0;
+  for (; index < fragments.length; index += 1) {
+    const fragment = fragments[index];
+    if (fragment?.kind === "mention") {
+      const id = typeof fragment.user_id === "string" ? fragment.user_id.trim() : "";
+      if (id) ids.push(id);
+      continue;
+    }
+    if (fragment?.kind === "text" && typeof fragment.text === "string" && !fragment.text.trim()) continue;
+    break;
+  }
+  if (!ids.includes(userId) && !ids.includes(MENTION_ALL_USER_ID)) return null;
+  const rest = fragmentsToText(fragments.slice(index) as never);
+  return rest || null;
+}
+
 export interface DispatchInboundParams {
   envelope: Envelope<unknown>;
   cfg: OpenClawConfig;
@@ -313,6 +347,10 @@ export async function dispatchOpenclawClawlingInbound(
     mentionFallbackIds: mentionIds,
   });
   const mediaItems = extractMediaFragments(message.body.fragments as never);
+  const afterMentions = isGroup
+    ? textAfterLeadingMentionsOf(message.body.fragments as Array<Record<string, unknown>>, account.userId)
+    : null;
+  const addressedCommandBody = afterMentions?.startsWith("/") ? afterMentions : null;
   const wasMentioned = detectMention({
     mentions: mentionIds,
     chatType,
@@ -376,6 +414,7 @@ export async function dispatchOpenclawClawlingInbound(
     senderId: sender.id,
     senderNickName: sender.nickName,
     rawBody,
+    ...(addressedCommandBody ? { addressedCommandBody } : {}),
     messageId: payload.message_id,
     // Single inbound message — allMessageIds starts as a one-element array.
     // The group coalescer merges these into the full set for batched turns.

package/src/refresh-manager.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 import {
   authRefresh,
   CODE_INVALID_REFRESH,
@@ -5,6 +7,13 @@ import {
   type AuthRefreshResult,
 } from "./api-client.ts";
 
+export type RevokedRefreshMarker = { fingerprint: string; revokedAt: number };
+
+/** Fingerprint only: revoked refresh credentials must never enter marker storage. */
+export function fingerprintRefreshToken(token: string): string {
+  return createHash("sha256").update(token.trim()).digest("hex");
+}
+
 /**
  * §A–§D — ClawChat token refresh + auto-logout orchestration for the OpenClaw
  * plugin.
@@ -77,7 +86,7 @@ export interface RefreshManagerPorts {
   /** Swap the in-memory access+refresh token AFTER persistence (§0). */
   swapInMemoryTokens: (tokens: { accessToken: string; refreshToken: string }) => void;
   /** §C — auto-logout: clear creds in both stores, flip not-configured, notify. */
-  onPermanentFailure: (info: { code: number; message: string }) => Promise<void> | void;
+  onPermanentFailure: (info: { code: number; message: string }, revokedRefresh: RevokedRefreshMarker) => Promise<void> | void;
   /**
    * §A.1/§D — invoked AFTER a successful PROACTIVE-timer refresh has persisted +
    * swapped the in-memory token, so the runtime can perform the §D close-then-
@@ -138,12 +147,9 @@ export class RefreshManager {
   private inFlight: Promise<RefreshOutcome> | null = null;
   /** §A.3 — the access token a refresh was last attempted for. */
   private rejectedToken: string | null = null;
-  /**
-   * §B race — the refresh token we last successfully rotated AWAY from (now
-   * consumed server-side). A subsequent `code:10003` for this exact token is a
-   * consumed-rotation race, NOT a revocation, so it must not auto-logout.
-   */
+  /** Consumed-token history is diagnostic; a live successor is required to recover. */
   private lastRotatedFromToken: string | null = null;
+  private consecutiveRaceDowngrades = 0;
   /** §A.3 — epoch-ms of the last refresh attempt (any token). */
   private lastAttemptAt = 0;
   private proactiveTimer: TimerHandle | null = null;
@@ -217,11 +223,13 @@ export class RefreshManager {
         { refreshToken, deviceId: this.ports.deviceId },
       );
     } catch (err) {
+      this.consecutiveRaceDowngrades = 0;
       const message = err instanceof Error ? err.message : String(err);
       return { kind: "transient", message };
     }
 
     if (result.kind === "success") {
+      this.consecutiveRaceDowngrades = 0;
       // §0 rotation hazard — persist FIRST, swap SECOND. If persistence REJECTS
       // (a store/config write failed), DO NOT swap the in-memory token: a
       // sqlite-sourced agent must not keep a now-dead refresh token in its row
@@ -247,8 +255,7 @@ export class RefreshManager {
         accessToken: result.accessToken,
         refreshToken: result.refreshToken,
       });
-      // §B race — record the now-consumed refresh token so a later `10003` for it
-      // is recognized as a rotation race rather than a revocation.
+      // Keep rotation history for inspection; it never overrides the live-token check.
       this.lastRotatedFromToken = refreshToken;
       // Clear the latch; the access token has actually changed.
       this.rejectedToken = null;
@@ -257,25 +264,15 @@ export class RefreshManager {
     }
 
     if (result.kind === "permanent") {
-      // §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
-      // moved on since we read it (another worker rotated underneath us). In
-      // either case the credential chain is still alive — report transient (no
-      // latch, no logout) so the next attempt proceeds with the live token. A
-      // `code:400` (client bug) is never a race.
+      // A consumed-token race is recoverable only with a real live successor.
+      // Bound repeated downgrades, including across gateway re-enters.
       if (result.code === CODE_INVALID_REFRESH) {
         const liveRefresh = this.ports.getRefreshToken();
-        const rotatedByUs =
-          this.lastRotatedFromToken !== null && refreshToken === this.lastRotatedFromToken;
-        const rotatedUnderneath =
-          !!liveRefresh && liveRefresh.trim().length > 0 && liveRefresh !== refreshToken;
-        if (rotatedByUs || rotatedUnderneath) {
+        const hasSuccessor = !!liveRefresh?.trim() && liveRefresh !== refreshToken;
+        if (hasSuccessor && this.consecutiveRaceDowngrades < 2) {
+          this.consecutiveRaceDowngrades += 1;
           this.ports.log?.info?.(
-            `clawchat-plugin-openclaw refresh 10003 treated as consumed-rotation race (rotatedByUs=${rotatedByUs} rotatedUnderneath=${rotatedUnderneath}); recovering with live token`,
+            "clawchat-plugin-openclaw refresh 10003 treated as consumed-rotation race; recovering with live token",
           );
           return { kind: "transient", message: "refresh token already rotated (race); retrying with current token" };
         }
@@ -285,10 +282,14 @@ export class RefreshManager {
       this.ports.log?.error?.(
         `clawchat-plugin-openclaw refresh permanent failure code=${result.code}: ${result.message}`,
       );
-      await this.ports.onPermanentFailure({ code: result.code, message: result.message });
+      await this.ports.onPermanentFailure({
+        code: result.code,
+        message: result.message,
+      }, { fingerprint: fingerprintRefreshToken(refreshToken), revokedAt: this.now() });
       return { kind: "permanent", code: result.code, message: result.message };
     }
 
+    this.consecutiveRaceDowngrades = 0;
     // Transient — never auto-logout; the old refresh token is still valid.
     this.ports.log?.info?.(
       `clawchat-plugin-openclaw refresh transient failure: ${result.message}`,
@@ -470,11 +471,13 @@ export class RefreshManager {
     rejectedToken: string | null;
     lastAttemptAt: number;
     lastRotatedFromToken: string | null;
+    consecutiveRaceDowngrades: number;
   } {
     return {
       rejectedToken: this.rejectedToken,
       lastAttemptAt: this.lastAttemptAt,
       lastRotatedFromToken: this.lastRotatedFromToken,
+      consecutiveRaceDowngrades: this.consecutiveRaceDowngrades,
     };
   }
 
@@ -483,10 +486,12 @@ export class RefreshManager {
     rejectedToken: string | null;
     lastAttemptAt: number;
     lastRotatedFromToken?: string | null;
+    consecutiveRaceDowngrades?: number;
   }): void {
     this.rejectedToken = state.rejectedToken;
     this.lastAttemptAt = state.lastAttemptAt;
     this.lastRotatedFromToken = state.lastRotatedFromToken ?? null;
+    this.consecutiveRaceDowngrades = state.consecutiveRaceDowngrades ?? 0;
   }
 }
 

package/src/reply-dispatcher.ts

@@ -29,6 +29,7 @@ import {
 } from "./media-runtime.ts";
 import {
   mintMessageId,
+  sendOpenclawClawlingReaction,
   sendOpenclawClawlingText,
   type OutboundMessageMode,
   type OutboundReplyCtx,
@@ -94,6 +95,14 @@ export interface ReplyDispatcherOptions {
    * paths are never loaded. Legacy standalone callers default to owner behavior.
    */
   nonOwnerTurn?: boolean;
+  /**
+   * Set for an owner's slash command in a group (not one that starts an agent
+   * turn). Each reply goes to the owner's direct chat, led by `header`, and
+   * the first one that lands puts a ✅ on the command (`commandMessageId`) in
+   * the group. With no owner chat on record, or a failed direct send, the
+   * reply goes to the group as before and a warning is logged.
+   */
+  ownerCommandReceipt?: { header: string; commandMessageId: string };
   log?: { info?: (m: string) => void; warn?: (m: string) => void; error?: (m: string) => void };
 }
 
@@ -438,6 +447,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     store,
     resolveOwnerConversationId,
     resolveOwnerLocale,
+    ownerCommandReceipt,
     log,
   } = options;
   const isGroupTarget = target.chatType === "group";
@@ -592,6 +602,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     messageId: string,
     text: string,
     raw: unknown,
+    chatId: string = target.chatId,
   ): true | false | null => {
     if (!store || !messageId) return null;
     try {
@@ -601,7 +612,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
         kind: "message",
         direction: "outbound",
         eventType,
-        chatId: target.chatId,
+        chatId,
         messageId,
         text,
         raw,
@@ -786,6 +797,79 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     replyStream = null;
   };
 
+  // ----- Owner command receipt -------------------------------------------
+  //
+  // The owner's group command answers in the owner's direct chat, so the
+  // group sees only a ✅ on the command. Any failure falls back to the group:
+  // a noisy group beats an owner who never hears back.
+  let receiptReacted = false;
+  const receiptTarget = (): { chatId: string; chatType: "direct" } | null => {
+    if (!ownerCommandReceipt || !isGroupTarget) return null;
+    const ownerTarget = ownerDirectTarget();
+    if (!ownerTarget) {
+      log?.warn?.(
+        `[${account.accountId}] clawchat-plugin-openclaw owner command receipt kept in group reason=missing_owner_conversation group=${target.chatId}`,
+      );
+    }
+    return ownerTarget;
+  };
+  const markCommandReceived = () => {
+    if (!ownerCommandReceipt || receiptReacted) return;
+    receiptReacted = true;
+    try {
+      sendOpenclawClawlingReaction({
+        client,
+        chatId: target.chatId,
+        targetMessageId: ownerCommandReceipt.commandMessageId,
+        emoji: "✅",
+        removed: false,
+        log,
+      });
+    } catch (error) {
+      log?.warn?.(
+        `[${account.accountId}] clawchat-plugin-openclaw owner command ✅ failed group=${target.chatId}: ${String(error)}`,
+      );
+    }
+  };
+  const sendOwnerCommandReceipt = async (
+    ownerTarget: { chatId: string; chatType: "direct" },
+    text: string,
+    mediaFragments: ClawlingMediaFragment[],
+    richFragments: Fragment[],
+    messageMode: OutboundMessageMode,
+  ): Promise<{ result: SendResult | null; messageId: string } | null> => {
+    const messageId = mintStaticMessageId();
+    const receiptText = text.trim()
+      ? `${ownerCommandReceipt!.header}\n\n${text}`
+      : ownerCommandReceipt!.header;
+    const raw = { target: ownerTarget, mode: "owner-command-receipt", group: target.chatId };
+    if (claimOutbound("message.send", messageId, receiptText, raw, ownerTarget.chatId) !== true) return null;
+    try {
+      const result = await sendOpenclawClawlingText({
+        client,
+        account,
+        to: ownerTarget,
+        text: receiptText,
+        messageId,
+        ...(richFragments.length > 0 ? { richFragments } : {}),
+        ...(mediaFragments.length > 0 ? { mediaFragments } : {}),
+        ...(messageMode !== "normal" ? { messageMode } : {}),
+        log,
+      });
+      if (!result) return null;
+      log?.info?.(
+        `[${account.accountId}] clawchat-plugin-openclaw owner command receipt sent to owner chat group=${target.chatId} msg=${messageId}`,
+      );
+      markCommandReceived();
+      return { result, messageId };
+    } catch (error) {
+      log?.warn?.(
+        `[${account.accountId}] clawchat-plugin-openclaw owner command receipt kept in group reason=owner_send_failed group=${target.chatId}: ${String(error)}`,
+      );
+      return null;
+    }
+  };
+
   // ----- Static send ------------------------------------------------------
 
   const sendStatic = async (
@@ -823,6 +907,15 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     }
     if (!text.trim() && mediaFragments.length === 0 && richFragments.length === 0) return null;
     if (consumeTerminalSend("static")) return null;
+    const ownerTarget = receiptTarget();
+    if (ownerTarget) {
+      const receipt = await sendOwnerCommandReceipt(ownerTarget, text, mediaFragments, richFragments, messageMode);
+      if (receipt) {
+        recordOutboundAck("message", receipt.messageId, receipt.result);
+        if (messageMode === "normal") outboundDeliveredCount += 1;
+        return receipt.result;
+      }
+    }
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw sending static mode=${messageMode} text_len=${text.length} media=${mediaFragments.length} rich=${richFragments.length} to=${target.chatId}`,
     );