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

package/dist/src/api-client.js

@@ -196,6 +196,7 @@ export function createOpenclawClawlingApiClient(opts) {
                     code,
                     status: res.status,
                     path,
+                    ...(env.data !== undefined ? { data: env.data } : {}),
                 });
             }
             return env.data;
@@ -516,5 +517,17 @@ export function createOpenclawClawlingApiClient(opts) {
             }
             return { authoritative: true, rows };
         },
+        async getMyPermissions() {
+            const data = await call("GET", "/v1/agents/me/permissions");
+            const byOperation = {};
+            let momentVisibility = [];
+            for (const [k, v] of Object.entries(data ?? {})) {
+                if (k === "moment.visibility")
+                    momentVisibility = v ?? [];
+                else
+                    byOperation[k] = v;
+            }
+            return { byOperation, momentVisibility };
+        },
     };
 }

package/dist/src/config.js

@@ -81,6 +81,7 @@ export const openclawClawlingConfigSchema = {
         forwardThinking: { type: "boolean" },
         forwardToolCalls: { type: "boolean" },
         richInteractions: { type: "boolean" },
+        awarenessNote: { type: "boolean" },
         reconnect: {
             type: "object",
             additionalProperties: false,
@@ -206,6 +207,28 @@ function decodeJwtStringClaim(token, claim) {
         return "";
     }
 }
+/**
+ * Resolve the bot-account userId, validated against the token's `sub` claim.
+ *
+ * The WS session authenticates with the access token, so the backend binds the
+ * session to the token's `sub` — that IS the bot's user id for this session.
+ * Unlike ownerUserId (explicit config wins over the `oid` claim), a configured
+ * userId that disagrees with `sub` is always wrong for the session this token
+ * creates, and it silently breaks self-echo detection: with the OWNER's id
+ * here, every owner message is dropped as the bot's own echo (2026-07-02
+ * clawnest incident — a provisioner wrote the owner id into the config). Token
+ * wins; the mismatch is logged. Also derives userId from `sub` when nothing is
+ * configured, mirroring the `oid` fallback above.
+ */
+function resolveUserId(token, configured) {
+    const tokenSub = decodeJwtStringClaim(token, "sub");
+    if (!tokenSub)
+        return configured;
+    if (configured && configured !== tokenSub) {
+        console.warn(`clawchat userId mismatch: configured ${configured} does not equal the access token's sub claim ${tokenSub}; using the token value. A misconfigured userId (e.g. the owner's id) breaks self-echo detection and mention gating — fix the channel userId / CLAWCHAT_USER_ID.`);
+    }
+    return tokenSub;
+}
 function readGroupMode(value) {
     return value === "mention" ? "mention" : "all";
 }
@@ -311,7 +334,7 @@ export function resolveOpenclawClawlingAccount(cfg, env = process.env) {
     const mediaBaseUrl = readOptionalString(channel.mediaBaseUrl) || readEnvString(env, CLAWCHAT_MEDIA_BASE_URL_ENV);
     const token = readOptionalString(channel.token) || readEnvString(env, CLAWCHAT_TOKEN_ENV);
     const agentId = readOptionalString(channel.agentId) || readEnvString(env, CLAWCHAT_AGENT_ID_ENV);
-    const userId = readOptionalString(channel.userId) || readEnvString(env, CLAWCHAT_USER_ID_ENV);
+    const userId = resolveUserId(token, readOptionalString(channel.userId) || readEnvString(env, CLAWCHAT_USER_ID_ENV));
     const ownerUserId = readOptionalString(channel.ownerUserId) ||
         readEnvString(env, CLAWCHAT_OWNER_USER_ID_ENV) ||
         // Fall back to the access token's `oid` (owner) claim. A provisioner may
@@ -328,6 +351,7 @@ export function resolveOpenclawClawlingAccount(cfg, env = process.env) {
     const forwardThinking = typeof channel.forwardThinking === "boolean" ? channel.forwardThinking : true;
     const forwardToolCalls = typeof channel.forwardToolCalls === "boolean" ? channel.forwardToolCalls : false;
     const richInteractions = typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
+    const awarenessNote = typeof channel.awarenessNote === "boolean" ? channel.awarenessNote : false;
     return {
         accountId: DEFAULT_ACCOUNT_ID,
         name: CHANNEL_ID,
@@ -353,6 +377,7 @@ export function resolveOpenclawClawlingAccount(cfg, env = process.env) {
         forwardThinking,
         forwardToolCalls,
         richInteractions,
+        awarenessNote,
         allowFrom: [],
         reconnect: readReconnect(channel.reconnect),
         heartbeat: readHeartbeat(channel.heartbeat),

package/dist/src/friend-request-turn.js

@@ -0,0 +1,73 @@
+/**
+ * Synthetic reasoning-turn builder for `friend.request` notify.signal events.
+ *
+ * When the server fires a `friend.request` signal the runtime dispatches one
+ * deduped synthetic `message.send` envelope so the agent can reason about the
+ * pending request. The prompt text varies by the current "friend.add" permission
+ * policy state: a deny policy yields a decline/inform prompt; ask or allow
+ * yields a prompt that instructs the agent to review the request via the
+ * `clawchat_list_friend_requests` tool.
+ */
+import { EVENT } from "./protocol-types.js";
+/**
+ * Returns canned prompt text for a friend-request reasoning turn based on the
+ * current "friend.add" permission policy state.
+ *
+ * - `deny`  → inform the agent it should decline; no accept instruction.
+ * - `ask` / `allow` → instruct the agent to review the pending request.
+ */
+export function friendRequestPromptFor(state) {
+    if (state === "deny") {
+        return [
+            "A new friend request has arrived.",
+            "Your current friend-add policy is set to deny.",
+            "Do not add this contact.",
+            "You may inform the requester that you cannot add them at this time.",
+        ].join(" ");
+    }
+    return [
+        "A new friend request has arrived.",
+        "Please review the pending request by calling `clawchat_list_friend_requests`",
+        "and decide whether to accept it.",
+    ].join(" ");
+}
+/**
+ * Builds a synthetic `message.send` envelope that triggers one agent reasoning
+ * turn for a pending friend request. The envelope shape mirrors the
+ * activation-bootstrap envelope; it targets the owner's direct conversation so
+ * the agent has context about who it is reasoning for.
+ */
+export function buildFriendRequestEnvelope(params) {
+    const { account, state, entityId } = params;
+    const text = friendRequestPromptFor(state);
+    const now = Date.now();
+    return {
+        version: "2",
+        event: EVENT.MESSAGE_SEND,
+        trace_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${now}`,
+        emitted_at: now,
+        chat_id: account.ownerUserId,
+        chat_type: "direct",
+        to: { id: account.userId, type: "direct" },
+        sender: {
+            id: "clawchat-friend-request",
+            type: "direct",
+            nick_name: "ClawChat",
+        },
+        payload: {
+            message_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${now}`,
+            message_mode: "normal",
+            message: {
+                body: { fragments: [{ kind: "text", text }] },
+                context: { mentions: [], reply: null },
+                streaming: {
+                    status: "static",
+                    sequence: 0,
+                    mutation_policy: "sealed",
+                    started_at: null,
+                    completed_at: null,
+                },
+            },
+        },
+    };
+}

package/dist/src/gate-outcome.js

@@ -0,0 +1,26 @@
+/**
+ * Maps backend owner-approval gate codes to structured tool outcomes.
+ *
+ * Backend gate codes (confirmed live contract):
+ *   21001 — pending owner approval (payload: { request_id, operation, expires_at })
+ *   21003 — policy forbidden       (payload: { operation })
+ *
+ * Returns null for any other code so callers can fall through to normal handling.
+ */
+export function mapGateOutcome(code, data) {
+    if (code === 21001) {
+        return {
+            status: "pending_owner_approval",
+            request_id: typeof data.request_id === "string" ? data.request_id : "",
+            operation: typeof data.operation === "string" ? data.operation : "",
+            expires_at: typeof data.expires_at === "number" ? data.expires_at : 0,
+        };
+    }
+    if (code === 21003) {
+        return {
+            status: "forbidden_by_owner",
+            operation: typeof data.operation === "string" ? data.operation : "",
+        };
+    }
+    return null;
+}

package/dist/src/inbound.js

@@ -115,6 +115,17 @@ export async function dispatchOpenclawClawlingInbound(params) {
         return;
     }
     if (sender.id === "system") {
+        // Intercept `permission_result` receipts before the generic system-message
+        // drop. The discriminator is `payload.metadata.kind === "permission_result"`;
+        // all other system messages (group-join notifications, etc.) still drop.
+        const rawPayload = envelope.payload;
+        const meta = rawPayload.metadata;
+        if (params.consumePermissionResult &&
+            meta != null &&
+            meta.kind === "permission_result") {
+            await params.consumePermissionResult(meta);
+            return;
+        }
         log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw skip system message msg=${payload.message_id}`);
         return;
     }

package/dist/src/permission-result.js

@@ -0,0 +1,107 @@
+/**
+ * Consumer for `permission_result` system-message receipts.
+ *
+ * When the backend delivers a `permission_result` outcome as a
+ * `message.send` system frame (`sender.id="system"`, `payload.metadata.kind
+ * ="permission_result"`), this module deduplicates by `request_id` and
+ * produces a synthetic context-note turn so the agent can close the loop
+ * on the original permission request.
+ *
+ * Wire shape (authoritative):
+ * ```
+ * payload.metadata = {
+ *   kind: "permission_result",
+ *   operation: "friend.add",
+ *   outcome: "approved" | "denied" | "expired" | "failed",
+ *   reason: "owner_allowed" | …,
+ *   request_id: "prq_…",
+ * }
+ * ```
+ * The discriminator is `payload.metadata.kind === "permission_result"`.
+ */
+import { EVENT } from "./protocol-types.js";
+// Module-level dedup set — `request_id` values are stable backend identifiers.
+// A duplicate receipt (e.g. from WS replay on reconnect) must not re-trigger
+// an agent turn.
+const _seenRequestIds = new Set();
+/**
+ * @internal Test helper — reset the dedup set between isolated test runs.
+ * Never call this in production code.
+ */
+export function _resetPermissionResultDedup() {
+    _seenRequestIds.clear();
+}
+function buildOutcomeNote(metadata) {
+    const { operation, outcome, reason } = metadata;
+    const outcomeLabel = outcome === "approved"
+        ? "approved"
+        : outcome === "denied"
+            ? "denied"
+            : outcome === "expired"
+                ? "expired"
+                : "failed";
+    const resolution = outcome === "approved"
+        ? "The requested action has been completed."
+        : "No further action was taken.";
+    return [
+        `Permission request for operation "${operation}" has been ${outcomeLabel}.`,
+        `Reason: ${reason}.`,
+        resolution,
+    ].join(" ");
+}
+/**
+ * Builds a synthetic `message.send` envelope that delivers a
+ * `permission_result` context note to the agent.
+ *
+ * Mirrors the `buildFriendRequestEnvelope` pattern: a synthetic inbound
+ * `message.send` targeting the owner's direct conversation, routed through
+ * `handleInboundEnvelope` so the agent can reason about the outcome.
+ */
+export function buildPermissionResultEnvelope(params) {
+    const { account, metadata } = params;
+    const text = buildOutcomeNote(metadata);
+    const now = Date.now();
+    return {
+        version: "2",
+        event: EVENT.MESSAGE_SEND,
+        trace_id: `clawchat-plugin-openclaw-permission-result-${metadata.request_id}-${now}`,
+        emitted_at: now,
+        chat_id: account.ownerUserId,
+        chat_type: "direct",
+        to: { id: account.userId, type: "direct" },
+        sender: {
+            id: "clawchat-permission-result",
+            type: "direct",
+            nick_name: "ClawChat",
+        },
+        payload: {
+            message_id: `clawchat-plugin-openclaw-permission-result-${metadata.request_id}-${now}`,
+            message_mode: "normal",
+            message: {
+                body: { fragments: [{ kind: "text", text }] },
+                context: { mentions: [], reply: null },
+                streaming: {
+                    status: "static",
+                    sequence: 0,
+                    mutation_policy: "sealed",
+                    started_at: null,
+                    completed_at: null,
+                },
+            },
+        },
+    };
+}
+/**
+ * Handles a `permission_result` receipt. Deduplicates by `request_id`
+ * (idempotent — WS replay on reconnect may deliver the same receipt again).
+ *
+ * Returns a synthetic context-note {@link Envelope} on a fresh receipt so
+ * the caller can feed it to `handleInboundEnvelope`; returns `null` when
+ * the `request_id` has already been processed.
+ */
+export function handlePermissionResult(metadata, account) {
+    if (_seenRequestIds.has(metadata.request_id))
+        return null;
+    _seenRequestIds.add(metadata.request_id);
+    return buildPermissionResultEnvelope({ account, metadata });
+}

package/dist/src/permissions.js

@@ -0,0 +1,6 @@
+export class PermissionCache {
+    p = { byOperation: {}, momentVisibility: [] };
+    get() { return this.p; }
+    set(p) { this.p = p; }
+    stateOf(op) { return this.p.byOperation[op] ?? "ask"; }
+}

package/dist/src/runtime.js

@@ -28,6 +28,9 @@ import { clearClawChatPromptInjectionForSession, stageClawChatPromptInjection, }
 import { createGroupMessageCoalescer } from "./group-message-coalescer.js";
 import { openclawLlmContextDebug } from "./llm-context-debug.js";
 import { GroupSettingsCache } from "./group-settings.js";
+import { PermissionCache } from "./permissions.js";
+import { buildFriendRequestEnvelope } from "./friend-request-turn.js";
+import { handlePermissionResult } from "./permission-result.js";
 const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } = createPluginRuntimeStore("clawchat-plugin-openclaw runtime not initialized");
 export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 const activeClients = new Map();
@@ -1381,6 +1384,7 @@ export async function startOpenclawClawlingGateway(params) {
         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
@@ -1454,6 +1458,25 @@ export async function startOpenclawClawlingGateway(params) {
             }
         })();
     };
+    // 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) => {
+        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) => {
         if (authFailureLogged)
             return;
@@ -1585,6 +1608,8 @@ export async function startOpenclawClawlingGateway(params) {
             // 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).
@@ -1746,14 +1771,29 @@ export async function startOpenclawClawlingGateway(params) {
     catch (err) {
         log?.info?.(`[${accountId}] clawchat-plugin-openclaw skill-update: bundled skills dir not resolvable (using managed-only current): ${err instanceof Error ? err.message : String(err)}`);
     }
-    const sendOwnerSkillMessage = async (text) => {
+    // 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 = () => {
         const ownerUserId = account.ownerUserId?.trim();
         if (!ownerUserId)
+            return null;
+        const conversationId = store
+            ?.getActivationConversation?.({ platform: "openclaw", accountId })
+            ?.conversationId?.trim();
+        return conversationId || null;
+    };
+    const sendOwnerSkillMessage = async (text) => {
+        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,
         });
@@ -1796,6 +1836,10 @@ export async function startOpenclawClawlingGateway(params) {
             },
         });
     };
+    // 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) => {
         // §9.4 reliable system notification. The plugin holds no friend/roster
         // cache (friends are fetched on demand via REST tools), so there is nothing
@@ -1807,10 +1851,15 @@ export async function startOpenclawClawlingGateway(params) {
                 ? env.payload
                 : 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
@@ -1820,6 +1869,62 @@ export async function startOpenclawClawlingGateway(params) {
                     log?.error?.(`[${accountId}] clawchat-plugin-openclaw skill-update check failed: ${err instanceof Error ? err.message : String(err)}`);
                 });
             }
+            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,
+                                    },
+                                },
+                            },
+                        });
+                    });
+                }
+            }
         }
     });
     client.on("replay:done", (env) => {
@@ -2318,16 +2423,16 @@ export async function startOpenclawClawlingGateway(params) {
         },
     });
     const forwardGroupApprovalSlashToOwner = async (turn) => {
-        const ownerUserId = account.ownerUserId?.trim();
-        if (!ownerUserId) {
-            log?.error?.(`[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_user_id chat_id=${turn.peer.id} msg=${turn.messageId}`);
+        const ownerConversationId = resolveOwnerDirectConversationId();
+        if (!ownerConversationId) {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_conversation chat_id=${turn.peer.id} msg=${turn.messageId}`);
             return "skipped";
         }
         try {
             await sendOpenclawClawlingText({
                 client,
                 account,
-                to: { chatId: ownerUserId, chatType: "direct" },
+                to: { chatId: ownerConversationId, chatType: "direct" },
                 text: groupOwnerAttentionText(turn.peer.id, turn.rawBody),
                 log,
             });
@@ -2439,6 +2544,16 @@ export async function startOpenclawClawlingGateway(params) {
                 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);
                 },
@@ -2525,6 +2640,9 @@ export async function startOpenclawClawlingGateway(params) {
     // 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.