@clawling/clawchat-plugin-openclaw 2026.7.29-3 → 2026.8.2-1

package/src/outbound.ts

@@ -1,6 +1,6 @@
 import { randomInt } from "node:crypto";
-import { EVENT, MessageSendError, type Envelope, type Fragment, type MentionFragment, type MessageAckPayload, type MessageErrorPayload, type MessageReactionPayload } from "./protocol-types.ts";
-import type { ClawlingChatClient } from "./ws-client.ts";
+import { EVENT, MessageSendError, TERMINAL_CHAT_CODES, type Envelope, type Fragment, type MentionFragment, type MessageAckPayload, type MessageErrorPayload, type MessageReactionPayload } from "./protocol-types.ts";
+import { CHAT_ID_PREFIX, isValidChatId, type ClawlingChatClient } from "./ws-client.ts";
 import {
   createAttachedChannelResultAdapter,
   type ChannelOutboundAdapter,
@@ -219,9 +219,25 @@ export function setAlignedOutboundLogContext(
   alignedOutboundContexts.set(client as object, context);
 }
 
+/**
+ * The single outbound gate predicate. Narrow by design: only a SERVER-confirmed
+ * rejection blocks, never a `conversation.dissolved` inference, and never the
+ * owner's direct chat (the client applies that exemption inside isSendBlocked).
+ * Optional-call form because outbound tests hand-roll a client mock.
+ */
+function isOutboundBlocked(client: ClawlingChatClient, chatId: string | undefined): boolean {
+  if (!chatId) return false;
+  return (client as { isSendBlocked?: (chatId: string) => boolean }).isSendBlocked?.(chatId) === true;
+}
+
 export function flushAlignedOutboundQueue(client: ClawlingChatClient): void {
   const queue = alignedOutboundQueues.get(client as object);
-  queue?.flush((wire) => client.sendWire(wire));
+  // Re-check the gate at write time: this replay path (called on every
+  // `connected` edge) does not re-enter sendAlignedAckableEnvelope.
+  queue?.flush(
+    (wire) => client.sendWire(wire),
+    { isBlocked: (item) => isOutboundBlocked(client, item.chatId) },
+  );
 }
 
 export function getAlignedOutboundQueueSize(client: ClawlingChatClient): number {
@@ -236,6 +252,68 @@ async function sendAlignedAckableEnvelope(params: {
   payload: object;
   log?: LogSink;
 }): Promise<Envelope<MessageAckPayload>> {
+  // Static addressing check, before any server state is consulted: this one is
+  // decidable locally and is never revocable, so it is not a "gate" that can
+  // later clear. msghub refuses such a frame with `invalid conversation id`.
+  if (!isValidChatId(params.chatId)) {
+    params.log?.info?.(
+      formatWsLog({
+        event: "send_blocked",
+        accountId: params.account.accountId,
+        ...(
+          alignedOutboundContexts.get(params.client as object)?.() ?? {
+            attempt: 1,
+            reconnectCount: 0,
+            state: params.client.transportState === "open" ? "ready" : "reconnecting",
+          }
+        ),
+        action: "drop",
+        fields: [
+          ["event_name", params.eventName],
+          ["chat_id", params.chatId],
+          ["reason", "invalid_chat_id"],
+        ],
+      }),
+    );
+    throw new MessageSendError(
+      "-",
+      "invalid_chat_id",
+      `"${params.chatId}" is not a ClawChat conversation id (expected ${CHAT_ID_PREFIX}…); refusing to send`,
+      params.chatId,
+    );
+  }
+  // The server has already rejected this conversation with a terminal code and
+  // that rejection has not expired. Stop here: every further frame would be
+  // refused the same way. Gated on the narrow server-confirmed tier ONLY — a
+  // `conversation.dissolved` signal must never reach this branch, and the
+  // owner's direct chat is exempt (see ClawChatClient.isSendBlocked).
+  if (isOutboundBlocked(params.client, params.chatId)) {
+    params.log?.info?.(
+      formatWsLog({
+        event: "send_blocked",
+        accountId: params.account.accountId,
+        ...(
+          alignedOutboundContexts.get(params.client as object)?.() ?? {
+            attempt: 1,
+            reconnectCount: 0,
+            state: params.client.transportState === "open" ? "ready" : "reconnecting",
+          }
+        ),
+        action: "drop",
+        fields: [
+          ["event_name", params.eventName],
+          ["chat_id", params.chatId],
+          ["reason", "chat_rejected_by_server"],
+        ],
+      }),
+    );
+    throw new MessageSendError(
+      "-",
+      "chat_rejected_local",
+      "conversation was rejected by the server; refusing to send",
+      params.chatId,
+    );
+  }
   const traceId = params.client.nextTraceId();
   const env = {
     version: "2" as const,
@@ -331,6 +409,19 @@ async function sendAlignedAckableEnvelope(params: {
           : typeof payload.message === "string" && payload.message
             ? payload.message
             : "message send failed";
+        // A terminal refusal proves the conversation is unreachable for this
+        // sender right now. Record it on the SERVER tier so the gates below
+        // stop subsequent frames — this is fact, not the inference that
+        // `conversation.dissolved` gives us. It expires; see the client.
+        if (
+          TERMINAL_CHAT_CODES.has(code)
+          && typeof ack.chat_id === "string"
+          && ack.chat_id
+        ) {
+          (params.client as {
+            markChatDead?: (chatId: string, source: "signal" | "server") => boolean;
+          }).markChatDead?.(ack.chat_id, "server");
+        }
         fail(new MessageSendError(traceId, code, hint, ack.chat_id));
         return;
       }
@@ -366,6 +457,14 @@ async function sendAlignedAckableEnvelope(params: {
       onDrop: () => {
         fail(new Error(`send queue full; dropped ${params.eventName} before write for trace_id=${traceId}`));
       },
+      onBlock: () => {
+        fail(new MessageSendError(
+          "-",
+          "chat_rejected_local",
+          "conversation was rejected by the server while this frame was queued",
+          params.chatId,
+        ));
+      },
     };
 
     function isTerminalClose(close: AlignedOutboundClose): boolean {
@@ -407,7 +506,10 @@ async function sendAlignedAckableEnvelope(params: {
 
     try {
       queue.enqueue(item);
-      queue.flush((queuedWire) => params.client.sendWire(queuedWire));
+      queue.flush(
+        (queuedWire) => params.client.sendWire(queuedWire),
+        { isBlocked: (queued) => isOutboundBlocked(params.client, queued.chatId) },
+      );
     } catch {
       // The queue keeps the failed frame at the head for reconnect retry, so
       // keep this promise pending until the frame is written+acked, dropped, or timed out.
@@ -663,6 +765,18 @@ export interface SendReactionParams {
  * path used for message.send/reply does not apply). Matches the mobile client.
  */
 export function sendOpenclawClawlingReaction(params: SendReactionParams): void {
+  if (!isValidChatId(params.chatId)) {
+    params.log?.info?.(
+      `clawchat reaction blocked chat_id=${params.chatId} reason=invalid_chat_id`,
+    );
+    return;
+  }
+  if (isOutboundBlocked(params.client, params.chatId)) {
+    params.log?.info?.(
+      `clawchat reaction blocked chat_id=${params.chatId} reason=chat_rejected_by_server`,
+    );
+    return;
+  }
   const payload: MessageReactionPayload = {
     target_message_id: params.targetMessageId,
     emoji: params.emoji,

package/src/protocol-types.ts

@@ -326,6 +326,25 @@ export class MessageSendError extends Error {
   }
 }
 
+/**
+ * `message.error` codes that PROVE the target conversation is unreachable for
+ * this sender right now (docs/client-integration.md §14.3). Both are documented
+ * as terminal for the affected uplink.
+ *
+ * Deliberately excludes `capability_missing` and `unsupported_version`: those
+ * are terminal too, but they indict THIS CLIENT's handshake/envelope, not the
+ * conversation — muting the chat on them would be a false positive.
+ *
+ * NOTE: "terminal for this uplink" is NOT "terminal forever". A deleted
+ * conversation can be revived in place under the same `cnv_` id (that is the
+ * path an agent re-pairing takes), so anything derived from these codes must
+ * be recoverable — see SERVER_REJECTION_TTL_MS in ws-client.ts.
+ */
+export const TERMINAL_CHAT_CODES: ReadonlySet<string> = new Set([
+  "chat_not_found",
+  "not_member",
+]);
+
 export class StateError extends Error {
   override name = "StateError";
 }

package/src/runtime.ts

@@ -19,7 +19,11 @@ import { buildActivationBootstrapText } from "./activation-greeting.ts";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.ts";
 import path from "node:path";
 import { ensureLivewareCli, resolveLivewarePath } from "./liveware-cli.ts";
-import { LivewareSampleSupervisor, type LivewareSampleStoreLike } from "./liveware-sample.ts";
+import {
+  LivewareSampleSupervisor,
+  type LivewareSampleStoreLike,
+  type LivewareSampleSupervisorDeps,
+} from "./liveware-sample.ts";
 import { ClawlingApiError } from "./api-types.ts";
 import { RefreshManager } from "./refresh-manager.ts";
 import {
@@ -85,7 +89,7 @@ import { createGroupMessageCoalescer } from "./group-message-coalescer.ts";
 import { openclawLlmContextDebug } from "./llm-context-debug.ts";
 import { GroupSettingsCache } from "./group-settings.ts";
 import { PermissionCache } from "./permissions.ts";
-import { buildAwarenessNoteEnvelope } from "./awareness-note-turn.ts";
+import { buildAwarenessNoteEnvelope, buildMomentCommentNoteEnvelope } from "./awareness-note-turn.ts";
 import { handlePermissionResult } from "./permission-result.ts";
 
 type Log = { debug?: (m: string) => void; info?: (m: string) => void; error?: (m: string) => void };
@@ -129,6 +133,18 @@ const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingR
 export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 
 const activeClients = new Map<string, ClawlingChatClient>();
+// Live liveware-sample supervisors, keyed by the gateway's abortSignal and then by
+// `platform:accountId`. startOpenclawClawlingGateway re-enters ITSELF (token-refresh
+// reconnect, transport backoff, post-auth-failed re-activation) carrying the same
+// `...params` — so the same abortSignal — and a per-call `new LivewareSampleSupervisor`
+// left the previous one running: both then raced the bootstrap "account has zero apps"
+// gate and each minted its own liveware app, leaving a duplicate app tile that no
+// SQLite row tracks (the single-row PK means the loser is orphaned forever). Keyed by
+// signal so an entry cannot outlive the channel it belongs to.
+const livewareSampleSupervisors = new WeakMap<
+  AbortSignal,
+  Map<string, LivewareSampleSupervisor>
+>();
 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
@@ -1111,7 +1127,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   let livewareSampleNotify: (text: string) => Promise<boolean> = async () => false;
   if (store) {
     const stateDirForSample = runtime.state?.resolveStateDir?.();
-    const livewareSampleSupervisor = new LivewareSampleSupervisor({
+    const livewareSampleDeps: LivewareSampleSupervisorDeps = {
       platform: "openclaw",
       accountId,
       enabled: account.livewareSample,
@@ -1139,9 +1155,31 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         debug: (m) => log?.debug?.(m),
         error: (m) => log?.error?.(m),
       },
-    });
-    abortSignal.addEventListener("abort", () => livewareSampleSupervisor.stop());
-    void livewareSampleSupervisor.start();
+    };
+    const supervisorsForSignal =
+      livewareSampleSupervisors.get(abortSignal) ?? new Map<string, LivewareSampleSupervisor>();
+    livewareSampleSupervisors.set(abortSignal, supervisorsForSignal);
+    const supervisorKey = `openclaw:${accountId}`;
+    const runningSupervisor = supervisorsForSignal.get(supervisorKey);
+    if (runningSupervisor) {
+      // A gateway re-entry (refresh/backoff reconnect), not a fresh channel start:
+      // hand the live supervisor this closure's token + REST client + notify path
+      // instead of constructing a second one that would register a duplicate app.
+      log?.debug?.(
+        `[${accountId}] clawchat-plugin-openclaw liveware-sample supervisor already live; re-pointing it at the re-entered gateway`,
+      );
+      runningSupervisor.adoptDeps(livewareSampleDeps);
+    } else {
+      const livewareSampleSupervisor = new LivewareSampleSupervisor(livewareSampleDeps);
+      supervisorsForSignal.set(supervisorKey, livewareSampleSupervisor);
+      abortSignal.addEventListener("abort", () => {
+        livewareSampleSupervisor.stop();
+        if (supervisorsForSignal.get(supervisorKey) === livewareSampleSupervisor) {
+          supervisorsForSignal.delete(supervisorKey);
+        }
+      });
+      void livewareSampleSupervisor.start();
+    }
   }
 
   const resolveMutateConfigFile = (): OpenclawClawchatMutateConfigFile | undefined => {
@@ -2236,6 +2274,31 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             ],
           }),
         );
+      } else if (env.event === "message.error") {
+        // Never fold this into `inbound_ignored`: `code` + `chat_id` are the
+        // only in-plugin evidence that an uplink was refused, and the
+        // 2026-07-19 incident needed a server-log dig purely because this line
+        // did not exist. `action=message_error` marks it as semantically seen.
+        const current = wsLogContext();
+        const errorPayload = env.payload && typeof env.payload === "object"
+          ? (env.payload as { code?: unknown })
+          : undefined;
+        log?.info?.(
+          formatWsLog({
+            event: "inbound_control",
+            accountId,
+            attempt: current.attempt,
+            reconnectCount: current.reconnectCount,
+            state: "ready",
+            action: "message_error",
+            fields: [
+              ["event_name", env.event],
+              ["trace_id", env.trace_id],
+              ["chat_id", env.chat_id],
+              ["code", typeof errorPayload?.code === "string" ? errorPayload.code : "-"],
+            ],
+          }),
+        );
       } else if (env.event !== "ping" && env.event !== "pong") {
         const current = wsLogContext();
         log?.info?.(
@@ -2310,6 +2373,12 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       ?.conversationId?.trim();
     return conversationId || null;
   };
+  // R3: the owner's direct conversation is never gated by the dead-chat send
+  // guard. If it were, the very message explaining why the agent went dark
+  // (skill-update notices, auth/logout notices, group owner-attention
+  // forwards) would be unreachable. Registered lazily — the activation
+  // conversation may be recorded after the client is constructed.
+  client.setOwnerDirectChatResolver(resolveOwnerDirectConversationId);
   const sendOwnerSkillMessage = async (text: string): Promise<void> => {
     const conversationId = resolveOwnerDirectConversationId();
     if (!conversationId) {
@@ -2406,7 +2475,11 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         // for it. Falls through to the awareness branch so the owner is told.
         const entityId =
           typeof payload?.entity_id === "string" ? payload.entity_id : "";
-        const evicted = client.markChatDead(entityId);
+        // "signal" tier: this gates typing only. The protocol forbids gating
+        // message.send on a dissolved signal — only a server rejection
+        // (message.error, see src/outbound.ts) may do that, and unlike this
+        // one that rejection expires.
+        const evicted = client.markChatDead(entityId, "signal");
         log?.info?.(
           evicted
             ? `[${accountId}] clawchat-plugin-openclaw conversation.dissolved signal received; evicting ${entityId}`
@@ -2437,6 +2510,38 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             }`,
           );
         });
+      } else if (type === "moment.comment.created" || type === "moment.comment.replied") {
+        // Content-free trigger: the note carries only the scenario + moment id
+        // and points the agent at the get_moment tool — never the comment
+        // text. Not gated behind account.awarenessNote and not debounced:
+        // each moment-comment signal yields its own note (msghub already
+        // coalesces multiple comments on one moment by entity_id).
+        const momentId =
+          typeof payload?.entity_id === "string" ? payload.entity_id : "";
+        // No activation conversation ⇒ no routable chat_id. Skip the note
+        // rather than address it to the owner's usr_… id, which
+        // member-backend rejects as "invalid conversation id" (the agent's
+        // in-turn replies are then dropped with no negative ack). Resolve
+        // this FIRST, mirroring the friend.*/conversation.* awareness
+        // branch's guard below.
+        const ownerConversationId = resolveOwnerDirectConversationId();
+        if (!ownerConversationId) {
+          log?.info?.(
+            `[${accountId}] clawchat-plugin-openclaw ${type} signal received but no owner conversation resolved; skipping moment awareness note (moment ${momentId})`,
+          );
+          return;
+        }
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw ${type} signal received; synthesizing moment awareness note (moment ${momentId})`,
+        );
+        void handleInboundEnvelope(
+          buildMomentCommentNoteEnvelope({
+            account,
+            ownerConversationId,
+            momentId,
+            replied: type === "moment.comment.replied",
+          }),
+        );
       } else if (
         type === "friend.added" ||
         type === "friend.removed" ||

package/src/storage.ts

@@ -180,14 +180,20 @@ export type LivewareSampleUpsert = {
   port: number;
   publicUrl?: string | null;
   sampleVersion: string;
-  status: "active" | "failed" | "disabled";
+  // "pending": `liveware app create` succeeded but the app is not registered with
+  // ClawChat yet. Persisted mid-bootstrap so a failure after create resumes with
+  // the same app id instead of minting (and leaking) another one.
+  status: "pending" | "active" | "failed" | "disabled";
   lastError?: string | null;
 };
 
 export type UpdateLivewareSampleStatusInput = {
   platform: string;
   accountId: string;
-  status: "active" | "failed" | "disabled";
+  // "pending": `liveware app create` succeeded but the app is not registered with
+  // ClawChat yet. Persisted mid-bootstrap so a failure after create resumes with
+  // the same app id instead of minting (and leaking) another one.
+  status: "pending" | "active" | "failed" | "disabled";
   lastError?: string | null;
 };
 

package/src/tools-schema.ts

@@ -323,6 +323,11 @@ export const ClawchatDeleteMomentSchema = Type.Object({
 });
 export type ClawchatDeleteMomentParams = Static<typeof ClawchatDeleteMomentSchema>;
 
+export const ClawchatGetMomentSchema = Type.Object({
+  momentId: Type.Integer({ minimum: 1, description: "Concrete ClawChat moment id to fetch (with its visible comments)" }),
+});
+export type ClawchatGetMomentParams = Static<typeof ClawchatGetMomentSchema>;
+
 export const ClawchatToggleMomentReactionSchema = Type.Object({
   momentId: Type.Integer({
     minimum: 1,

package/src/tools.ts

@@ -40,6 +40,7 @@ import {
 import {
   ClawchatGetAccountProfileSchema,
   ClawchatGetConversationSchema,
+  ClawchatGetMomentSchema,
   ClawchatGetUserProfileSchema,
   ClawchatLeaveGroupSchema,
   ClawchatAcceptFriendRequestSchema,
@@ -82,6 +83,7 @@ import {
   type ClawchatDeleteMomentParams,
   type ClawchatAcceptFriendRequestParams,
   type ClawchatGetConversationParams,
+  type ClawchatGetMomentParams,
   type ClawchatGetUserProfileParams,
   type ClawchatLeaveGroupParams,
   type ClawchatListFriendRequestsParams,
@@ -1194,6 +1196,24 @@ export function registerOpenclawClawlingTools(
     { name: "clawchat_list_moments" },
   );
 
+  api.registerTool(
+    {
+      name: "clawchat_get_moment",
+      label: "Get ClawChat Moment",
+      description: toolDescription(
+        "Fetch a single ClawChat moment by id together with the comments visible to this agent. TRIGGER - after a moment.comment.created / moment.comment.replied awareness note, call this with the moment id to read the new comment before deciding whether to reply.",
+      ),
+      parameters: ClawchatGetMomentSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_get_moment", params, async () => {
+          const p = (params ?? {}) as ClawchatGetMomentParams;
+          return await withClient((c) => c.getMoment(p.momentId));
+        });
+      },
+    },
+    { name: "clawchat_get_moment" },
+  );
+
   api.registerTool(
     {
       name: "clawchat_create_moment",
@@ -1544,6 +1564,6 @@ export function registerOpenclawClawlingTools(
   );
 
   api.logger.debug?.(
-    "clawchat-plugin-openclaw: registered 30 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, send_friend_request, list_friend_requests, accept_friend_request, reject_friend_request, remove_friend, search_users, get_conversation, mention_message, list_moments, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, memory_search, memory_read, memory_write, memory_edit, metadata_sync, metadata_update, register_app, list_apps, unregister_app, liveware_login)",
+    "clawchat-plugin-openclaw: registered 31 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, send_friend_request, list_friend_requests, accept_friend_request, reject_friend_request, remove_friend, search_users, get_conversation, mention_message, list_moments, get_moment, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, memory_search, memory_read, memory_write, memory_edit, metadata_sync, metadata_update, register_app, list_apps, unregister_app, liveware_login)",
   );
 }

package/src/ws-alignment.ts

@@ -9,6 +9,8 @@ export interface AlignedWsQueueItem {
   wire: string;
   onWrite?: () => void;
   onDrop?: () => void;
+  /** Called instead of `write` when the flush-time gate blocks this item. */
+  onBlock?: () => void;
 }
 
 export interface CreateAlignedWsQueueOptions {
@@ -85,9 +87,34 @@ export function createAlignedWsQueue(options: CreateAlignedWsQueueOptions) {
       logFrame("send_queued", "queue", item, [["queue_size", queue.length]]);
     },
 
-    flush(write: (wire: string) => void) {
+    /**
+     * Drain the queue. `isBlocked` is consulted PER ITEM at write time, not at
+     * enqueue time: a conversation can be rejected by the server *after* a
+     * frame was queued, and this replay path never re-enters the send function
+     * that guards the live path. Without this hook the outbound gate is
+     * bypassable by any reconnect (and by any batch flush that happens to carry
+     * a live chat's frame).
+     */
+    flush(
+      write: (wire: string) => void,
+      options: { isBlocked?: (item: AlignedWsQueueItem) => boolean } = {},
+    ) {
       while (queue.length > 0) {
         const item = queue[0]!;
+        if (options.isBlocked?.(item)) {
+          queue.shift();
+          logFrame(
+            "send_blocked",
+            "drop",
+            item,
+            [
+              ["reason", "chat_rejected_by_server"],
+              ["remaining", queue.length],
+            ],
+          );
+          item.onBlock?.();
+          continue;
+        }
         try {
           write(item.wire);
           queue.shift();