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

package/dist/src/skill-update.js

@@ -29,8 +29,12 @@ import { fileURLToPath } from "node:url";
  *   implementation in `@clawling/clawchat-plugin-install-cli`
  *   (`packages/core/src/skills/check-update.ts`). That package is
  *   workspace-private, so the logic is duplicated here rather than imported.
- * - Strict semver compare mirrors the reference `parseComparableVersion`
- *   (`X.Y[.Z[.W]][-buildnum]`).
+ * - Update detection converges on raw sha256 comparison: ANY byte difference
+ *   from the official source (or a missing local file) is an update —
+ *   upgrade, rollback, or same-version content fix alike. The strict semver
+ *   compare (`parseComparableVersion` / `isVersionOlder`, still ported from
+ *   the reference `parseComparableVersion`, `X.Y[.Z[.W]][-buildnum]`) is kept
+ *   only for consent-prompt display wording, not for the `hasUpdate` decision.
  * - All network IO goes through an injected `FetchLike`; tests never touch the
  *   real network.
  *
@@ -151,7 +155,25 @@ export function parseSkillsManifest(text) {
             skills[target][skillId] = asEntry(entry, `${target}.${skillId}`);
         }
     }
-    return { schema: 1, skills };
+    const removed = {};
+    if (data.removed !== undefined) {
+        if (!data.removed || typeof data.removed !== "object" || Array.isArray(data.removed)) {
+            throw new Error("skills manifest `removed` must be an object");
+        }
+        for (const [target, ids] of Object.entries(data.removed)) {
+            if (!Array.isArray(ids) || !ids.every((i) => typeof i === "string" && i.trim())) {
+                throw new Error(`skills manifest removed[${target}] must be a list of skill ids`);
+            }
+            const cleaned = ids.map((i) => i.trim());
+            for (const id of cleaned) {
+                if (skills[target]?.[id]) {
+                    throw new Error(`skill ${target}.${id} is in both skills and removed`);
+                }
+            }
+            removed[target] = cleaned;
+        }
+    }
+    return { schema: 1, skills, removed };
 }
 async function fetchText(url, fetchFn) {
     let response;
@@ -167,9 +189,10 @@ async function fetchText(url, fetchFn) {
     return response.text();
 }
 /**
- * Read the official manifest for the `openclaw` target and compare each skill's
- * offered version against the locally installed `current` map. A skill missing
- * from `current` is reported as `hasUpdate: true`.
+ * Read the official manifest for the `openclaw` target and compare each
+ * skill's offered content (sha256) against its effective local state, read
+ * on demand via `readLocalState`. Any sha256 mismatch — or no local state at
+ * all — is reported as `hasUpdate: true`.
  */
 export async function checkSkillUpdate(options) {
     const ref = options.ref ?? DEFAULT_SKILLS_REF;
@@ -181,11 +204,14 @@ export async function checkSkillUpdate(options) {
     }
     const results = [];
     for (const [skillId, entry] of Object.entries(targetSkills)) {
-        const current = options.current[skillId] ?? null;
-        const hasUpdate = current === null ? true : isVersionOlder(current, entry.version);
+        const state = await options.readLocalState(skillId);
+        // sha convergence: any byte difference from the official source (or a
+        // missing local file) is an update — upgrade, rollback, or same-version
+        // content fix alike.
+        const hasUpdate = !state || state.sha256 !== entry.sha256;
         results.push({
             skillId,
-            current,
+            current: state?.version ?? null,
             latest: entry.version,
             hasUpdate,
             path: entry.path,
@@ -193,7 +219,12 @@ export async function checkSkillUpdate(options) {
             bytes: entry.bytes,
         });
     }
-    return { ref, results, hasUpdate: results.some((r) => r.hasUpdate) };
+    return {
+        ref,
+        results,
+        hasUpdate: results.some((r) => r.hasUpdate),
+        removedIds: manifest.removed[SKILL_TARGET] ?? [],
+    };
 }
 /**
  * Download one skill markdown file and integrity-check it against the manifest
@@ -230,52 +261,41 @@ export function parseSkillFrontmatterVersion(markdown) {
     const raw = (versionLine[1] ?? "").trim().replace(/^["']|["']$/g, "");
     return raw || null;
 }
-/** Read one skill's frontmatter `version` from `<dir>/<skillId>/SKILL.md`. */
-async function readSingleSkillVersion(dir, skillId) {
+async function readSkillStateFromDir(dir, skillId) {
     try {
-        const md = await fs.readFile(path.join(dir, skillId, "SKILL.md"), "utf8");
-        return parseSkillFrontmatterVersion(md);
+        const buf = await fs.readFile(path.join(dir, skillId, "SKILL.md"));
+        return {
+            version: parseSkillFrontmatterVersion(buf.toString("utf8")),
+            sha256: crypto.createHash("sha256").update(buf).digest("hex"),
+        };
     }
     catch {
-        return null; // missing / unreadable
+        return null;
     }
 }
 /**
- * Read the installed version of each requested skill from a SINGLE directory
- * (`<skillsDir>/<skillId>/SKILL.md`). Missing files / missing frontmatter
- * version are simply omitted (treated as "not installed" → update available).
+ * Effective local state of ONE skill, mirroring the host's managed-over-bundled
+ * precedence: managed copy if present, else bundled, else null. Called per
+ * remote manifest entry so dynamically delivered extra skills are hashed too
+ * (a static bundled-id list would misreport extras as never-installed).
  */
-export async function readLocalSkillVersions(skillsDir, skillIds = OPENCLAW_SKILL_IDS) {
-    const versions = {};
-    for (const skillId of skillIds) {
-        const version = await readSingleSkillVersion(skillsDir, skillId);
-        if (version)
-            versions[skillId] = version;
-    }
-    return versions;
+export async function readLocalSkillState(managedDir, bundledDir, skillId) {
+    const managed = await readSkillStateFromDir(managedDir, skillId);
+    if (managed)
+        return managed;
+    if (bundledDir)
+        return readSkillStateFromDir(bundledDir, skillId);
+    return null;
 }
-/**
- * Read the EFFECTIVE installed version of each skill, mirroring the host's
- * managed-over-bundled precedence (`src/skills/loading/workspace.ts:1220-1239`,
- * managed=3 > bundled=2): use the managed copy's frontmatter `version` when
- * `<managedDir>/<id>/SKILL.md` exists, otherwise fall back to the bundled
- * copy's. A skill present in neither is omitted (→ update available).
- */
-export async function readEffectiveSkillVersions(managedDir, bundledDir, skillIds = OPENCLAW_SKILL_IDS) {
-    const versions = {};
-    for (const skillId of skillIds) {
-        const managed = await readSingleSkillVersion(managedDir, skillId);
-        if (managed) {
-            versions[skillId] = managed;
-            continue;
-        }
-        if (bundledDir) {
-            const bundled = await readSingleSkillVersion(bundledDir, skillId);
-            if (bundled)
-                versions[skillId] = bundled;
-        }
+/** True when `<managedDir>/<skillId>/SKILL.md` exists (removal precondition). */
+export async function managedSkillExists(managedDir, skillId) {
+    try {
+        await fs.access(path.join(managedDir, skillId, "SKILL.md"));
+        return true;
+    }
+    catch {
+        return false;
     }
-    return versions;
 }
 /**
  * Resolve OpenClaw's state directory, mirroring the host `src/utils.ts:132-154`:
@@ -359,6 +379,18 @@ export async function atomicWriteSkill(skillsDir, skillId, content) {
         throw err;
     }
 }
+/**
+ * Delete a tombstoned managed skill: remove `<skillsDir>/<skillId>/SKILL.md`
+ * (the host chokidar-watches the dir; the unlink triggers a snapshot rebuild
+ * that drops the registration) and best-effort remove the now-empty dir.
+ * Deletion is the ONE legitimate delete of a skill path, and ONLY for ids the
+ * official manifest explicitly tombstones. Idempotent.
+ */
+export async function removeManagedSkill(skillsDir, skillId) {
+    const dir = path.join(skillsDir, skillId);
+    await fs.rm(path.join(dir, "SKILL.md"), { force: true });
+    await fs.rmdir(dir).catch(() => { });
+}
 const AFFIRM_TOKENS = new Set([
     "更新",
     "更新吧",
@@ -438,7 +470,20 @@ export class PendingConsentStore {
     }
 }
 function describeUpdate(u) {
-    return `「${u.skillId}」v${u.current ?? "无"} → v${u.target}`;
+    if (u.current === null)
+        return `「${u.skillId}」v无 → v${u.target}`;
+    let cmp = -1;
+    try {
+        cmp = compareVersions(u.current, u.target);
+    }
+    catch {
+        cmp = -1; // unparsable local version — show as a plain update
+    }
+    if (cmp === 0)
+        return `「${u.skillId}」v${u.target}(内容修订)`;
+    if (cmp > 0)
+        return `「${u.skillId}」v${u.current} → v${u.target}(回滚)`;
+    return `「${u.skillId}」v${u.current} → v${u.target}`;
 }
 /**
  * Step ③–⑤ (plan §2): on `clawchat.skill.update.check`, check the official
@@ -453,23 +498,25 @@ export async function runSkillUpdateCheck(options) {
         return null;
     }
     const outcome = await checkSkillUpdate({
-        current: options.localVersions,
+        readLocalState: options.readLocalState,
         ...(options.ref ? { ref: options.ref } : {}),
         ...(options.base ? { base: options.base } : {}),
         fetchFn: options.fetchFn,
     });
     const updates = outcome.results
         .filter((r) => r.hasUpdate)
-        .map((r) => ({
-        skillId: r.skillId,
-        current: r.current,
-        target: r.latest,
-        path: r.path,
-        sha256: r.sha256,
-        bytes: r.bytes,
-    }));
-    if (updates.length === 0) {
-        options.log?.info?.("clawchat skill-update check: no updates available");
+        .map((r) => ({ skillId: r.skillId, current: r.current, target: r.latest, path: r.path, sha256: r.sha256, bytes: r.bytes }));
+    const removals = [];
+    for (const skillId of outcome.removedIds) {
+        if (OPENCLAW_SKILL_IDS.includes(skillId)) {
+            options.log?.info?.(`clawchat skill-update: ignoring tombstone for bundled skill ${skillId}`);
+            continue;
+        }
+        if (await options.hasManagedSkill(skillId))
+            removals.push({ skillId });
+    }
+    if (updates.length === 0 && removals.length === 0) {
+        options.log?.info?.("clawchat skill-update check: nothing to converge");
         return null;
     }
     const now = (options.now ?? Date.now)();
@@ -478,13 +525,19 @@ export async function runSkillUpdateCheck(options) {
         ref: outcome.ref,
         ...(options.base ? { base: options.base } : {}),
         updates,
+        removals,
         createdAt: now,
         expiresAt: now + (options.timeoutMs ?? DEFAULT_CONSENT_TIMEOUT_MS),
     };
     options.store.set(record);
-    const text = `我的技能有更新:${updates.map(describeUpdate).join(";")}。回复「更新」确认,「取消」忽略。`;
+    const segments = [];
+    if (updates.length > 0)
+        segments.push(`我的技能有更新:${updates.map(describeUpdate).join(";")}`);
+    if (removals.length > 0)
+        segments.push(`以下技能将下线移除:${removals.map((r) => `「${r.skillId}」`).join("、")}`);
+    const text = `${segments.join(";")}。回复「更新」确认,「取消」忽略。`;
     await options.sendOwnerMessage(text);
-    options.log?.info?.(`clawchat skill-update check: asked owner for consent on ${updates.map((u) => u.skillId).join(",")}`);
+    options.log?.info?.(`clawchat skill-update check: asked owner for consent on updates=[${updates.map((u) => u.skillId).join(",")}] removals=[${removals.map((r) => r.skillId).join(",")}]`);
     return record;
 }
 /**
@@ -516,22 +569,23 @@ export async function handleOwnerConsentReply(options) {
         return true;
     }
     // verdict === "affirm"
-    const readLocalVersion = options.readLocalVersion ??
+    const readLocalSha = options.readLocalSha ??
         (async (skillId) => {
             try {
-                const md = await fs.readFile(path.join(options.skillsDir, skillId, "SKILL.md"), "utf8");
-                return parseSkillFrontmatterVersion(md);
+                const buf = await fs.readFile(path.join(options.skillsDir, skillId, "SKILL.md"));
+                return crypto.createHash("sha256").update(buf).digest("hex");
             }
             catch {
                 return null;
             }
         });
     const applied = [];
+    const removed = [];
     try {
         for (const update of pending.updates) {
-            // Idempotency: skip a skill already at the target version on disk.
-            const onDisk = await readLocalVersion(update.skillId);
-            if (onDisk === update.target) {
+            // Idempotency: skip a skill whose on-disk bytes already match the target.
+            const onDisk = await readLocalSha(update.skillId);
+            if (onDisk === update.sha256) {
                 applied.push(update);
                 continue;
             }
@@ -544,6 +598,18 @@ export async function handleOwnerConsentReply(options) {
             applied.push(update);
             options.log?.info?.(`clawchat skill-update: applied ${update.skillId} -> v${update.target} (atomic overwrite)`);
         }
+        for (const removal of pending.removals) {
+            // Defensive re-guard: bundled skills must never be deleted, even though
+            // runSkillUpdateCheck already filters them out of removal candidates.
+            // Unreachable in the normal flow; kept as a cheap safety net.
+            if (OPENCLAW_SKILL_IDS.includes(removal.skillId)) {
+                options.log?.info?.(`clawchat skill-update: skipped removal of bundled skill ${removal.skillId} (defensive re-guard)`);
+                continue;
+            }
+            await removeManagedSkill(options.skillsDir, removal.skillId);
+            removed.push(removal);
+            options.log?.info?.(`clawchat skill-update: removed tombstoned skill ${removal.skillId}`);
+        }
     }
     catch (err) {
         // Keep the pending record so the owner can retry with another "更新"; report
@@ -553,7 +619,11 @@ export async function handleOwnerConsentReply(options) {
         return true;
     }
     options.store.clear();
-    const summary = applied.map((u) => `「${u.skillId}」v${u.target}`).join("、");
-    await options.sendOwnerMessage(`✅ 已更新到 ${summary}`);
+    const segments = [];
+    if (applied.length > 0)
+        segments.push(`已更新到 ${applied.map((u) => `「${u.skillId}」v${u.target}`).join("、")}`);
+    if (removed.length > 0)
+        segments.push(`已移除 ${removed.map((r) => `「${r.skillId}」`).join("、")}`);
+    await options.sendOwnerMessage(`✅ ${segments.join(";")}`);
     return true;
 }

package/dist/src/tools.js

@@ -4,6 +4,7 @@ import { execFile } from "node:child_process";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { resolveLivewarePath } from "./liveware-cli.js";
 import { ClawlingApiError, } from "./api-types.js";
+import { mapGateOutcome } from "./gate-outcome.js";
 import { resolveOpenclawClawlingAccount } from "./config.js";
 import { clawChatDbPathForStateDir, getClawChatStore, } from "./storage.js";
 import { sendOpenclawClawlingMentionMessage } from "./outbound.js";
@@ -272,6 +273,38 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             }
         })();
     }
+    /**
+     * 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(fn) {
+        return (async () => {
+            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
+                            : {};
+                        const outcome = mapGateOutcome(code, gateData);
+                        if (outcome !== null)
+                            return jsonResponse(outcome);
+                    }
+                    return apiError(err);
+                }
+                return genericError(err);
+            }
+        })();
+    }
     function workspaceRoot(ctx) {
         const root = typeof ctx.workspaceDir === "string" ? ctx.workspaceDir.trim() : "";
         return root || null;
@@ -640,7 +673,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_send_friend_request", params, async () => {
                 const p = params;
-                return await withClient((c) => c.sendFriendRequest(p));
+                return await withGatedClient((c) => c.sendFriendRequest(p));
             });
         },
     }, { name: "clawchat_send_friend_request" });
@@ -668,7 +701,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_accept_friend_request", params, async () => {
                 const p = params;
-                return await withClient((c) => c.acceptFriendRequest(p.requestId));
+                return await withGatedClient((c) => c.acceptFriendRequest(p.requestId));
             });
         },
     }, { name: "clawchat_accept_friend_request" });
@@ -682,7 +715,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_reject_friend_request", params, async () => {
                 const p = params;
-                return await withClient((c) => c.rejectFriendRequest(p.requestId));
+                return await withGatedClient((c) => c.rejectFriendRequest(p.requestId));
             });
         },
     }, { name: "clawchat_reject_friend_request" });
@@ -696,7 +729,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_remove_friend", params, async () => {
                 const p = params;
-                return await withClient((c) => c.removeFriend(p.friendUserId));
+                return await withGatedClient((c) => c.removeFriend(p.friendUserId));
             });
         },
     }, { name: "clawchat_remove_friend" });
@@ -841,7 +874,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                 if (!text && (!images || images.length === 0)) {
                     return validationError("clawchat-plugin-openclaw: at least one of text or images is required");
                 }
-                return await withClient((c) => c.createMoment({
+                return await withGatedClient((c) => c.createMoment({
                     ...(text !== undefined ? { text } : {}),
                     ...(images !== undefined ? { images } : {}),
                 }));
@@ -858,7 +891,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_delete_moment", params, async () => {
                 const p = params;
-                return await withClient((c) => c.deleteMoment(p.momentId));
+                return await withGatedClient((c) => c.deleteMoment(p.momentId));
             });
         },
     }, { name: "clawchat_delete_moment" });
@@ -875,7 +908,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                 if (!p.emoji?.trim()) {
                     return validationError("clawchat-plugin-openclaw: emoji is required");
                 }
-                return await withClient((c) => c.toggleMomentReaction({ momentId: p.momentId, emoji: p.emoji }));
+                return await withGatedClient((c) => c.toggleMomentReaction({ momentId: p.momentId, emoji: p.emoji }));
             });
         },
     }, { name: "clawchat_toggle_moment_reaction" });
@@ -892,7 +925,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                 if (!p.text?.trim()) {
                     return validationError("clawchat-plugin-openclaw: text is required");
                 }
-                return await withClient((c) => c.createMomentComment({ momentId: p.momentId, text: p.text }));
+                return await withGatedClient((c) => c.createMomentComment({ momentId: p.momentId, text: p.text }));
             });
         },
     }, { name: "clawchat_create_moment_comment" });
@@ -909,7 +942,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                 if (!p.text?.trim()) {
                     return validationError("clawchat-plugin-openclaw: text is required");
                 }
-                return await withClient((c) => c.replyMomentComment({
+                return await withGatedClient((c) => c.replyMomentComment({
                     momentId: p.momentId,
                     replyToCommentId: p.replyToCommentId,
                     text: p.text,
@@ -927,7 +960,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_delete_moment_comment", params, async () => {
                 const p = params;
-                return await withClient((c) => c.deleteMomentComment({ momentId: p.momentId, commentId: p.commentId }));
+                return await withGatedClient((c) => c.deleteMomentComment({ momentId: p.momentId, commentId: p.commentId }));
             });
         },
     }, { name: "clawchat_delete_moment_comment" });

package/dist/src/ws-client.js

@@ -84,6 +84,23 @@ export function createWebSocketTransport(WebSocketCtor = globalThis.WebSocket) {
         },
     };
 }
+/**
+ * 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() {
+    return {
+        multi_device: false,
+        device_replay: true,
+        chat_meta_events: true,
+        notify_signals: true,
+        permission_events: true,
+    };
+}
 export class ClawChatClient extends EventEmitter {
     opts;
     currentState = "idle";
@@ -333,12 +350,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;

package/openclaw.plugin.json

@@ -107,6 +107,7 @@
       "forwardThinking": { "type": "boolean" },
       "forwardToolCalls": { "type": "boolean" },
       "richInteractions": { "type": "boolean" },
+      "awarenessNote": { "type": "boolean" },
       "reconnect": {
         "type": "object",
         "additionalProperties": false,
@@ -180,6 +181,7 @@
           "forwardThinking": { "type": "boolean" },
           "forwardToolCalls": { "type": "boolean" },
           "richInteractions": { "type": "boolean" },
+          "awarenessNote": { "type": "boolean" },
           "reconnect": {
             "type": "object",
             "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.6.30-4",
+  "version": "2026.7.2-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/api-client.ts

@@ -17,6 +17,7 @@ import {
   type UserSearchHit,
 } from "./api-types.ts";
 import type { GroupSettings, GroupSettingsFetchResult } from "./group-settings.ts";
+import type { PermissionPolicy, PermState } from "./permissions.ts";
 import { CHANNEL_ID } from "./config.ts";
 
 export interface PluginReportInput {
@@ -179,6 +180,17 @@ export interface OpenclawClawlingApiClient {
    * error still throws.
    */
   getMyGroupSettings(): Promise<GroupSettingsFetchResult>;
+  /**
+   * Fetch the agent's permission policy from `GET /v1/agents/me/permissions`.
+   *
+   * The response `data` is a flat object mapping operation name → state
+   * (`"ask"|"allow"|"deny"`), with one special key `"moment.visibility"` whose
+   * value is a string array. Returns a `PermissionPolicy` with `byOperation`
+   * (all non-visibility keys) and `momentVisibility` (the array). Throws on
+   * network errors or non-2xx responses; callers must catch and keep the stale
+   * cache (never throw / never block message handling).
+   */
+  getMyPermissions(): Promise<PermissionPolicy>;
   registerApp(params: { name: string; appId: string; url: string }): Promise<{ app: AgentAppView }>;
   listApps(): Promise<{ apps: AgentAppView[] }>;
   unregisterApp(appId: string): Promise<{ deleted: boolean }>;
@@ -362,6 +374,7 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
           code,
           status: res.status,
           path,
+          ...(env.data !== undefined ? { data: env.data } : {}),
         });
       }
       return env.data as T;
@@ -759,5 +772,15 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
       }
       return { authoritative: true, rows };
     },
+    async getMyPermissions(): Promise<PermissionPolicy> {
+      const data = await call<Record<string, unknown>>("GET", "/v1/agents/me/permissions");
+      const byOperation: Record<string, PermState> = {};
+      let momentVisibility: string[] = [];
+      for (const [k, v] of Object.entries(data ?? {})) {
+        if (k === "moment.visibility") momentVisibility = (v as string[]) ?? [];
+        else byOperation[k] = v as PermState;
+      }
+      return { byOperation, momentVisibility };
+    },
   };
 }

package/src/api-types.ts

@@ -157,7 +157,7 @@ export class ClawlingApiError extends Error {
   constructor(
     public readonly kind: ClawlingApiErrorKind,
     message: string,
-    public readonly meta?: { code?: number; status?: number; path?: string },
+    public readonly meta?: { code?: number; status?: number; path?: string; data?: unknown },
   ) {
     super(message);
     this.name = "ClawlingApiError";

package/src/config.ts

@@ -106,6 +106,8 @@ export type OpenclawClawlingConfig = {
   forwardToolCalls?: boolean;
   /** Emit approval/action rich fragments instead of plain fallback text. */
   richInteractions?: boolean;
+  /** Emit ONE consolidated awareness note to the agent when friend/conversation signals arrive. */
+  awarenessNote?: boolean;
   reconnect?: OpenclawClawlingReconnectConfig;
   heartbeat?: OpenclawClawlingHeartbeatConfig;
   ack?: OpenclawClawlingAckConfig;
@@ -152,6 +154,7 @@ export const openclawClawlingConfigSchema = {
     forwardThinking: { type: "boolean" },
     forwardToolCalls: { type: "boolean" },
     richInteractions: { type: "boolean" },
+    awarenessNote: { type: "boolean" },
     reconnect: {
       type: "object",
       additionalProperties: false,
@@ -274,6 +277,7 @@ export type ResolvedOpenclawClawlingAccount = {
   forwardThinking: boolean;
   forwardToolCalls: boolean;
   richInteractions: boolean;
+  awarenessNote: boolean;
   allowFrom: string[];
   reconnect: Required<OpenclawClawlingReconnectConfig>;
   heartbeat: Required<OpenclawClawlingHeartbeatConfig>;
@@ -482,6 +486,8 @@ export function resolveOpenclawClawlingAccount(
     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,
@@ -508,6 +514,7 @@ export function resolveOpenclawClawlingAccount(
     forwardThinking,
     forwardToolCalls,
     richInteractions,
+    awarenessNote,
     allowFrom: [],
     reconnect: readReconnect(channel.reconnect),
     heartbeat: readHeartbeat(channel.heartbeat),