@clawling/clawchat-plugin-openclaw 2026.6.30-4 → 2026.7.2

package/src/runtime.ts

@@ -78,6 +78,9 @@ import {
 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 { buildFriendRequestEnvelope } from "./friend-request-turn.ts";
+import { handlePermissionResult } from "./permission-result.ts";
 
 type Log = { debug?: (m: string) => void; info?: (m: string) => void; error?: (m: string) => void };
 type ChannelContextBuilder = (params: Record<string, unknown>) => unknown;
@@ -1752,6 +1755,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     context: wsLogContext,
   });
   const groupSettingsCache = new GroupSettingsCache();
+  const permissionCache = new PermissionCache();
   // Findings 2 & 3 — gate group dispatch on the IN-FLIGHT settings pull, not just
   // the first one. The pull is fire-and-forget, so replayed/live group messages
   // could otherwise enter the governance gate against a stale/empty cache
@@ -1829,6 +1833,28 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }
     })();
   };
+  // Best-effort pull of the agent's permission policy from the backend.
+  // Called at startup (bypassRefresh: true, mirrors pullGroupSettings startup)
+  // and on every successful (re)connect after hello-ok. On failure, logs and
+  // keeps the stale cache — never throws, never blocks message handling.
+  const pullPermissions = (opts?: { bypassRefresh?: boolean }): void => {
+    void (async () => {
+      try {
+        const policy = opts?.bypassRefresh
+          ? await (conversationApiClient ??= buildConversationApiClient()).getMyPermissions()
+          : await getConversationApiClient().getMyPermissions();
+        permissionCache.set(policy);
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw permissions pull ok ops=${Object.keys(policy.byOperation).length}`,
+        );
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] clawchat-plugin-openclaw permissions pull failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        // Keep stale cache; never throw.
+      }
+    })();
+  };
   const logAuthFailure = (reason: string) => {
     if (authFailureLogged) return;
     authFailureLogged = true;
@@ -1962,6 +1988,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       // Re-pull per-group agent settings on every successful (re)connect so the
       // cache stays current after a network interruption or token refresh.
       pullGroupSettings();
+      // Re-pull permission policy alongside group settings on every (re)connect.
+      pullPermissions();
       // §A.1 — arm the proactive refresh timer from the live token's `exp`
       // every time a connection becomes ready (re-armed after every refresh via
       // the gateway re-enter).
@@ -2138,13 +2166,30 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }`,
     );
   }
-  const sendOwnerSkillMessage = async (text: string): Promise<void> => {
+  // A usr_... id is not a valid chat_id — member-backend rejects it with
+  // "invalid conversation id" and msghub never acks the send. Proactive owner
+  // messages must be addressed to the direct conversation recorded at
+  // activation (parity with the hermes adapter's _owner_direct_chat_id).
+  const resolveOwnerDirectConversationId = (): string | null => {
     const ownerUserId = account.ownerUserId?.trim();
-    if (!ownerUserId) return;
+    if (!ownerUserId) return null;
+    const conversationId = store
+      ?.getActivationConversation?.({ platform: "openclaw", accountId })
+      ?.conversationId?.trim();
+    return conversationId || null;
+  };
+  const sendOwnerSkillMessage = async (text: string): Promise<void> => {
+    const conversationId = resolveOwnerDirectConversationId();
+    if (!conversationId) {
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw skill-update owner message skipped: no activation conversation recorded`,
+      );
+      return;
+    }
     await sendOpenclawClawlingText({
       client,
       account,
-      to: { chatId: ownerUserId, chatType: "direct" },
+      to: { chatId: conversationId, chatType: "direct" },
       text,
       log,
     });
@@ -2193,6 +2238,11 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     });
   };
 
+  // Debounce flag for lighter-awareness consolidated notes.
+  // A single queueMicrotask coalesces all awareness signals that arrive in
+  // the same synchronous turn into exactly one handleInboundEnvelope call.
+  let pendingAwarenessNote = false;
+
   client.on("notify:signal", (env: Envelope) => {
     // §9.4 reliable system notification. The plugin holds no friend/roster
     // cache (friends are fetched on demand via REST tools), so there is nothing
@@ -2204,11 +2254,17 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         ? (env.payload as Record<string, unknown>)
         : undefined;
       const type = typeof payload?.type === "string" ? payload.type : "";
+      const entityId = typeof payload?.entity_id === "string" ? payload.entity_id : "";
       if (type === "agent.config.changed") {
         log?.info?.(
           `[${accountId}] clawchat-plugin-openclaw agent.config.changed signal received; re-pulling group settings`,
         );
         pullGroupSettings();
+      } else if (type === "agent.permission.changed") {
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw agent.permission.changed signal received; re-pulling permissions`,
+        );
+        pullPermissions();
       } 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
@@ -2223,6 +2279,66 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             }`,
           );
         });
+      } else if (type === "friend.request") {
+        // Dedup is already applied above by notifySignalObserver.observe (the live
+        // frame and its reliable-inbox replay share the same event_id and collapse
+        // to one observation). Build one synthetic reasoning turn so the agent can
+        // act on the pending request; the prompt text varies by policy state.
+        const state = permissionCache.stateOf("friend.add");
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw friend.request signal received; dispatching reasoning turn entity_id=${entityId} policy=${state}`,
+        );
+        void handleInboundEnvelope(buildFriendRequestEnvelope({ account, state, entityId }));
+      } else if (
+        type === "friend.added" ||
+        type === "friend.removed" ||
+        type === "friend.profile_updated" ||
+        type.startsWith("conversation.")
+      ) {
+        // Lighter-awareness: log + optional single consolidated note. Never
+        // injects a full reasoning turn per event (unlike friend.request).
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw ${type} signal received; lighter-awareness handling`,
+        );
+        if (account.awarenessNote && !pendingAwarenessNote) {
+          pendingAwarenessNote = true;
+          queueMicrotask(() => {
+            pendingAwarenessNote = false;
+            const now = Date.now();
+            void handleInboundEnvelope({
+              version: "2",
+              event: EVENT.MESSAGE_SEND,
+              trace_id: `clawchat-plugin-openclaw-awareness-${now}`,
+              emitted_at: now,
+              chat_id: account.ownerUserId,
+              chat_type: "direct",
+              to: { id: account.userId, type: "direct" },
+              sender: { id: "clawchat-awareness", type: "direct", nick_name: "ClawChat" },
+              payload: {
+                message_id: `clawchat-plugin-openclaw-awareness-${now}`,
+                message_mode: "normal",
+                message: {
+                  body: {
+                    fragments: [
+                      {
+                        kind: "text",
+                        text: "ClawChat awareness: your contacts or conversations have been updated.",
+                      },
+                    ],
+                  },
+                  context: { mentions: [], reply: null },
+                  streaming: {
+                    status: "static",
+                    sequence: 0,
+                    mutation_policy: "sealed",
+                    started_at: null,
+                    completed_at: null,
+                  },
+                },
+              },
+            } as unknown as Envelope);
+          });
+        }
       }
     }
   });
@@ -2787,10 +2903,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   });
 
   const forwardGroupApprovalSlashToOwner = async (turn: IngestTurnParams): Promise<IngestTurnResult> => {
-    const ownerUserId = account.ownerUserId?.trim();
-    if (!ownerUserId) {
+    const ownerConversationId = resolveOwnerDirectConversationId();
+    if (!ownerConversationId) {
       log?.error?.(
-        `[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_user_id chat_id=${turn.peer.id} msg=${turn.messageId}`,
+        `[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_conversation chat_id=${turn.peer.id} msg=${turn.messageId}`,
       );
       return "skipped";
     }
@@ -2798,7 +2914,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       await sendOpenclawClawlingText({
         client,
         account,
-        to: { chatId: ownerUserId, chatType: "direct" },
+        to: { chatId: ownerConversationId, chatType: "direct" },
         text: groupOwnerAttentionText(turn.peer.id, turn.rawBody),
         log,
       });
@@ -2924,6 +3040,18 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         account,
         log,
         consumeOwnerConsent: consumeOwnerSkillConsent,
+        consumePermissionResult: async (metadata) => {
+          // A permission_result receipt closes the loop on an earlier request.
+          // Dedup by request_id; on a fresh receipt feed the synthetic context
+          // note back to the agent so it can react to the outcome.
+          const note = handlePermissionResult(metadata, account);
+          if (note) {
+            log?.info?.(
+              `[${accountId}] clawchat-plugin-openclaw permission_result receipt op=${metadata.operation} outcome=${metadata.outcome} request_id=${metadata.request_id}; dispatching context note`,
+            );
+            void handleInboundEnvelope(note);
+          }
+        },
         ingest: async (turn) => {
           ingestResult = await ingestTurn(turn);
         },
@@ -3020,6 +3148,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // rotating `account.token` out from under the already-constructed WS client.
   // Settling this releases the Finding-2 group-dispatch gate.
   pullGroupSettings({ bypassRefresh: true });
+  // Initial pull of permission policy at startup (best-effort; errors logged,
+  // stale cache kept). Uses bypassRefresh for the same reason as pullGroupSettings.
+  pullPermissions({ bypassRefresh: true });
   // Safety: never strand a held group message if the runtime is torn down while a
   // pull is in flight. `waitWithTimeout` already releases group waiters on abort,
   // but force the gate open too so any later `wait()` resolves immediately.

package/src/tools.ts

@@ -9,6 +9,7 @@ import {
   ClawlingApiError,
   type Profile,
 } from "./api-types.ts";
+import { mapGateOutcome } from "./gate-outcome.ts";
 import { resolveOpenclawClawlingAccount } from "./config.ts";
 import {
   clawChatDbPathForStateDir,
@@ -389,6 +390,39 @@ export function registerOpenclawClawlingTools(
     })();
   }
 
+  /**
+   * Like withClient, but maps gate codes (21001/21003) to structured outcomes
+   * via mapGateOutcome so the agent sees a clear pending/forbidden status
+   * instead of a generic error. Used for friend and moment mutation tools.
+   */
+  function withGatedClient<T>(
+    fn: (client: ReturnType<typeof createOpenclawClawlingApiClient>) => Promise<T>,
+  ): Promise<OpenClawAgentToolResult<unknown>> {
+    return (async (): Promise<OpenClawAgentToolResult<unknown>> => {
+      const built = buildClient();
+      if (!built.ok) return built.error;
+      try {
+        const data = await fn(built.client);
+        return jsonResponse(data);
+      } catch (err) {
+        if (err instanceof ClawlingApiError) {
+          const code = typeof err.meta?.code === "number" ? err.meta.code : null;
+          if (code !== null) {
+            const rawData = err.meta?.data;
+            const gateData =
+              rawData !== null && rawData !== undefined && typeof rawData === "object"
+                ? (rawData as Record<string, unknown>)
+                : {};
+            const outcome = mapGateOutcome(code, gateData);
+            if (outcome !== null) return jsonResponse(outcome);
+          }
+          return apiError(err);
+        }
+        return genericError(err);
+      }
+    })();
+  }
+
   function workspaceRoot(ctx: OpenClawPluginToolContext): string | null {
     const root = typeof ctx.workspaceDir === "string" ? ctx.workspaceDir.trim() : "";
     return root || null;
@@ -829,7 +863,7 @@ export function registerOpenclawClawlingTools(
       async execute(_callId, params) {
         return await recordClawchatToolCall("clawchat_send_friend_request", params, async () => {
           const p = params as ClawchatSendFriendRequestParams;
-          return await withClient((c) => c.sendFriendRequest(p));
+          return await withGatedClient((c) => c.sendFriendRequest(p));
         });
       },
     },
@@ -869,7 +903,7 @@ export function registerOpenclawClawlingTools(
       async execute(_callId, params) {
         return await recordClawchatToolCall("clawchat_accept_friend_request", params, async () => {
           const p = params as ClawchatAcceptFriendRequestParams;
-          return await withClient((c) => c.acceptFriendRequest(p.requestId));
+          return await withGatedClient((c) => c.acceptFriendRequest(p.requestId));
         });
       },
     },
@@ -889,7 +923,7 @@ export function registerOpenclawClawlingTools(
       async execute(_callId, params) {
         return await recordClawchatToolCall("clawchat_reject_friend_request", params, async () => {
           const p = params as ClawchatRejectFriendRequestParams;
-          return await withClient((c) => c.rejectFriendRequest(p.requestId));
+          return await withGatedClient((c) => c.rejectFriendRequest(p.requestId));
         });
       },
     },
@@ -909,7 +943,7 @@ export function registerOpenclawClawlingTools(
       async execute(_callId, params) {
         return await recordClawchatToolCall("clawchat_remove_friend", params, async () => {
           const p = params as ClawchatRemoveFriendParams;
-          return await withClient((c) => c.removeFriend(p.friendUserId));
+          return await withGatedClient((c) => c.removeFriend(p.friendUserId));
         });
       },
     },
@@ -1084,7 +1118,7 @@ export function registerOpenclawClawlingTools(
           if (!text && (!images || images.length === 0)) {
             return validationError("clawchat-plugin-openclaw: at least one of text or images is required");
           }
-          return await withClient((c) =>
+          return await withGatedClient((c) =>
             c.createMoment({
               ...(text !== undefined ? { text } : {}),
               ...(images !== undefined ? { images } : {}),
@@ -1109,7 +1143,7 @@ export function registerOpenclawClawlingTools(
       async execute(_callId, params) {
         return await recordClawchatToolCall("clawchat_delete_moment", params, async () => {
           const p = params as ClawchatDeleteMomentParams;
-          return await withClient((c) => c.deleteMoment(p.momentId));
+          return await withGatedClient((c) => c.deleteMoment(p.momentId));
         });
       },
     },
@@ -1132,7 +1166,7 @@ export function registerOpenclawClawlingTools(
           if (!p.emoji?.trim()) {
             return validationError("clawchat-plugin-openclaw: emoji is required");
           }
-          return await withClient((c) =>
+          return await withGatedClient((c) =>
             c.toggleMomentReaction({ momentId: p.momentId, emoji: p.emoji }),
           );
         });
@@ -1157,7 +1191,7 @@ export function registerOpenclawClawlingTools(
           if (!p.text?.trim()) {
             return validationError("clawchat-plugin-openclaw: text is required");
           }
-          return await withClient((c) =>
+          return await withGatedClient((c) =>
             c.createMomentComment({ momentId: p.momentId, text: p.text }),
           );
         });
@@ -1182,7 +1216,7 @@ export function registerOpenclawClawlingTools(
           if (!p.text?.trim()) {
             return validationError("clawchat-plugin-openclaw: text is required");
           }
-          return await withClient((c) =>
+          return await withGatedClient((c) =>
             c.replyMomentComment({
               momentId: p.momentId,
               replyToCommentId: p.replyToCommentId,
@@ -1208,7 +1242,7 @@ export function registerOpenclawClawlingTools(
       async execute(_callId, params) {
         return await recordClawchatToolCall("clawchat_delete_moment_comment", params, async () => {
           const p = params as ClawchatDeleteMomentCommentParams;
-          return await withClient((c) =>
+          return await withGatedClient((c) =>
             c.deleteMomentComment({ momentId: p.momentId, commentId: p.commentId }),
           );
         });

package/src/ws-client.ts

@@ -9,6 +9,7 @@ import {
   TransportError,
   isBusinessDispatchEvent,
   type ConnState,
+  type ConnectCapabilities,
   type ConnectPayload,
   type EmptyPayload,
   type Envelope,
@@ -146,6 +147,24 @@ type PendingAck = {
   reject: (err: Error) => void;
 };
 
+/**
+ * Returns the capability set advertised in the connect handshake.
+ * Exported so tests can assert on the exact fields without a full WS setup.
+ *
+ * permission_events: forward-compat: advertises readiness for a future native
+ * `permission.receipt` wire frame; today the permission-decision receipt is
+ * delivered as a system message until msghub emits the native frame.
+ */
+export function buildConnectCapabilities(): ConnectCapabilities {
+  return {
+    multi_device: false,
+    device_replay: true,
+    chat_meta_events: true,
+    notify_signals: true,
+    permission_events: true,
+  };
+}
+
 export class ClawChatClient extends EventEmitter {
   private currentState: ConnState = "idle";
   private connectResolve?: () => void;
@@ -398,12 +417,8 @@ export class ClawChatClient extends EventEmitter {
       // *send* history.transit, which a single-device agent never does, and we
       // do not handle inbound history.transit — advertising it would invite
       // frames we cannot process. This is a deliberate, spec-legal omission.
-      capabilities: {
-        multi_device: false,
-        device_replay: true,
-        chat_meta_events: true,
-        notify_signals: true,
-      },
+      // permission_events: forward-compat; see buildConnectCapabilities().
+      capabilities: buildConnectCapabilities(),
     };
     const traceId = this.nextTraceId();
     this.expectedConnectTraceId = traceId;