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

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;
@@ -1850,10 +1876,11 @@ 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;
+  // `clawchat-bootstrap` turn: true only if the greeting was actually delivered
+  // (a real successful outbound send — block or final). The bootstrap dispatcher
+  // reads it to decide whether to mark the bootstrap sent or leave it pending for
+  // a later retry.
+  let bootstrapGreetingDelivered = 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.
@@ -1961,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).
@@ -2192,6 +2221,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
@@ -2203,11 +2237,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
@@ -2222,6 +2262,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);
+          });
+        }
       }
     }
   });
@@ -2603,7 +2703,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         chatType: turn.peer.kind,
         agentId: route.agentId,
       });
-      const { dispatcher, replyOptions, markDispatchIdle } =
+      const { dispatcher, replyOptions, markDispatchIdle, getOutboundDeliveredCount } =
         createOpenclawClawlingReplyDispatcher({
           cfg,
           runtime,
@@ -2649,10 +2749,14 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           (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;
+          // Did the greeting actually reach the user? The reliable signal is a
+          // real, successful outbound send (the agent may deliver the greeting
+          // as a `block`, not a `final`, and a cancelled send still shows up in
+          // host `counts.block`). Treat a queued/counted final as delivered too,
+          // to cover deferred/human-delay finals not yet flushed at this point.
+          const deliveredOutbound = getOutboundDeliveredCount?.() ?? 0;
+          bootstrapGreetingDelivered =
+            deliveredOutbound > 0 || queuedFinal || (counts.final ?? 0) > 0;
         }
         log?.info?.(
           `[${accountId}] clawchat-plugin-openclaw dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`,
@@ -2919,6 +3023,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);
         },
@@ -2961,7 +3077,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       const claimedBootstrap = bootstrap;
       claimedInFlight = true;
       incrementActivationBootstrapInFlight(accountId);
-      bootstrapProducedFinal = false;
+      bootstrapGreetingDelivered = false;
       const result = await handleInboundEnvelope(
         buildActivationBootstrapEnvelope({ account, conversationId: claimedBootstrap.conversationId }),
       );
@@ -2970,15 +3086,15 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         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
+      // Only mark the bootstrap done once the greeting was actually delivered
+      // (a real successful outbound send). If the turn was handed off but nothing
+      // reached the user — 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) {
+      if (!bootstrapGreetingDelivered) {
         log?.info?.(
-          `[${accountId}] clawchat-plugin-openclaw activation bootstrap dispatched but produced no final reply; leaving pending for retry`,
+          `[${accountId}] clawchat-plugin-openclaw activation bootstrap dispatched but greeting was not delivered; leaving pending for retry`,
         );
         releaseBootstrap();
         armBootstrapRetry();
@@ -3015,6 +3131,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;