@clawling/clawchat-plugin-openclaw 2026.10.9-1 → 2026.10.9-3

package/src/tools.ts

@@ -36,6 +36,14 @@ import {
   writeClawChatMemoryBody,
   type ClawChatMemoryTargetType,
 } from "./clawchat-memory.ts";
+import {
+  canReadMemory,
+  memoryScopeNote,
+  memoryScopeRefusal,
+  resolveMemoryScope,
+  type MemoryScope,
+} from "./memory-scope.ts";
+import { clawChatSessionAccountId, NON_OWNER_TOOL_ALLOWLIST } from "./turn-boundary.ts";
 import {
   pullGroupMetadata,
   pullOwnerMetadata,
@@ -254,14 +262,18 @@ const MEMORY_READ_MAX_LIMIT = 100_000;
 type ToolStore = Pick<
   ClawChatStore,
   "recordToolCall"
->;
+> &
+  Partial<Pick<ClawChatStore, "lookupActivationIdentity" | "listRecentGroupMessages">>;
 
 function toolDescription(...parts: string[]): string {
   return `${parts.join("")} ${DIRECT_TOOL_GUARD}`;
 }
 
+const MEMORY_SCOPE_DESCRIPTION =
+  "In a non-owner direct chat only that person's note is readable; in a group only that group's note and its members' notes are readable. owner.md is readable only in the owner's direct chat. Replace, edit and metadata operations require a readable target; append may add facts to any target without revealing existing content.";
+
 function memoryToolDescription(...parts: string[]): string {
-  return parts.join("");
+  return `${parts.join("")} ${MEMORY_SCOPE_DESCRIPTION}`;
 }
 
 function inferMimeFromPath(filePath: string): string {
@@ -392,6 +404,36 @@ export function resolveOpenclawClawlingToolAccountId(ctx: OpenClawPluginToolCont
   return null;
 }
 
+// Names this plugin registered through its wrapper below. The host-tool guard
+// lets an allowlisted `clawchat_*` name through only when it is in this set,
+// so another plugin's tool under a lookalike name is not trusted by prefix.
+const registeredClawChatToolNames = new Set<string>();
+
+/** Snapshot of the tool names this plugin registered; callers cannot mutate the record. */
+export function getRegisteredClawChatToolNames(): ReadonlySet<string> {
+  return new Set(registeredClawChatToolNames);
+}
+
+type RegistrableTool = Parameters<OpenClawPluginApi["registerTool"]>[0];
+type PluginTool = Exclude<RegistrableTool, (...args: never[]) => unknown>;
+
+// Host tool search (OpenClaw 2026.9.6+) hides every tool not marked
+// `catalogMode: "direct-only"` behind tool_search/tool_call, whose hook ctx has
+// no requester. The allowlisted tools stay directly callable so non-owner
+// turns keep the full hook ctx; older hosts ignore the field.
+function markDirectOnly(tool: PluginTool): PluginTool {
+  return Object.assign(tool, { catalogMode: "direct-only" as const });
+}
+
+function directOnlyTool(tool: RegistrableTool): RegistrableTool {
+  if (typeof tool !== "function") return markDirectOnly(tool);
+  return (ctx) => {
+    const resolved = tool(ctx);
+    if (Array.isArray(resolved)) return resolved.map(markDirectOnly);
+    return resolved ? markDirectOnly(resolved) : resolved;
+  };
+}
+
 export function registerOpenclawClawlingTools(
   api: OpenClawPluginApi,
   options: { store?: ToolStore | null } = {},
@@ -405,8 +447,14 @@ export function registerOpenclawClawlingTools(
   // the end is derived from what was actually registered, not hand-maintained.
   const registeredToolNames: string[] = [];
   const registerTool: OpenClawPluginApi["registerTool"] = (tool, opts) => {
-    if (opts?.name) registeredToolNames.push(opts.name);
-    api.registerTool(tool, opts);
+    const directOnly = Boolean(opts?.name && NON_OWNER_TOOL_ALLOWLIST.includes(opts.name));
+    api.registerTool(directOnly ? directOnlyTool(tool) : tool, opts);
+    // Recorded only after registerTool returned without throwing (the SDK
+    // returns void, so host-side duplicate rejection is not observable here).
+    if (opts?.name) {
+      registeredToolNames.push(opts.name);
+      registeredClawChatToolNames.add(opts.name);
+    }
   };
 
   // Re-resolve at call time so config reloads pick up new tokens / baseUrl.
@@ -636,6 +684,48 @@ export function registerOpenclawClawlingTools(
     return /Unsafe clawchat memory|Resolved clawchat memory path is outside root/i.test(message);
   }
 
+  // One warning per failure class per registration; never tool arguments.
+  const scopeWarnings = new Set<string>();
+  function warnScopeOnce(failure: string): void {
+    if (scopeWarnings.has(failure)) return;
+    scopeWarnings.add(failure);
+    try {
+      api.logger.warn(`clawchat-plugin-openclaw: memory scope ${failure}; no additional notes readable`);
+    } catch {
+      // Logging must not widen or break the (restrictive) scope.
+    }
+  }
+
+  /**
+   * Scope of the conversation behind this call, resolved fresh on every call
+   * (activation and group membership can change between calls). The account
+   * comes from the direct session key and/or the trusted tool context; a
+   * missing or contradictory account reads nothing.
+   */
+  async function memoryScopeFor(ctx: OpenClawPluginToolContext, root: string): Promise<MemoryScope> {
+    const sessionAccount = clawChatSessionAccountId(ctx.sessionKey) ?? null;
+    const contextAccount = resolveOpenclawClawlingToolAccountId(ctx);
+    if (sessionAccount && contextAccount && sessionAccount !== contextAccount) {
+      warnScopeOnce("account-mismatch");
+      return { kind: "unknown", chatId: "", members: new Set() };
+    }
+    const accountId = sessionAccount ?? contextAccount;
+    if (!accountId) return { kind: "unknown", chatId: "", members: new Set() };
+    const delivery = ctx.deliveryContext;
+    return resolveMemoryScope({
+      root,
+      ctx: {
+        sessionKey: ctx.sessionKey,
+        requesterSenderId: ctx.requesterSenderId,
+        deliveryContext: delivery?.channel === CHANNEL_ID ? { to: delivery.to } : undefined,
+      },
+      accountId,
+      configOwnerUserId: resolveCurrent(accountId).ownerUserId,
+      store: resolveStore(),
+      warn: warnScopeOnce,
+    });
+  }
+
   function memoryToolError(err: unknown) {
     if (err instanceof ClawlingApiError) return apiError(err);
     const message = err instanceof Error ? err.message : String(err);
@@ -665,13 +755,14 @@ export function registerOpenclawClawlingTools(
           }
           try {
             const p = params as ClawchatMemorySearchParams;
-            return jsonResponse(
-              await searchClawChatMemory(root, {
-                query: p.query,
-                targetTypes: p.targetTypes,
-                maxResults: p.maxResults,
-              }),
-            );
+            const scope = await memoryScopeFor(ctx, root);
+            const result = await searchClawChatMemory(root, {
+              query: p.query,
+              targetTypes: p.targetTypes,
+              maxResults: p.maxResults,
+            }, { readable: (target) => canReadMemory(scope, target) });
+            const scopeNote = memoryScopeNote(scope);
+            return jsonResponse({ ...result, ...(scopeNote ? { scopeNote } : {}) });
           } catch (err) {
             return memoryToolError(err);
           }
@@ -700,8 +791,11 @@ export function registerOpenclawClawlingTools(
             const p = params as ClawchatMemoryReadParams;
             const targetError = validateTarget(root, p);
             if (targetError) return memoryToolError(new Error(targetError));
+            const target = targetFromParams(p);
+            const scope = await memoryScopeFor(ctx, root);
+            if (!canReadMemory(scope, target)) return jsonResponse(memoryScopeRefusal(scope, target));
             const { offset, limit } = normalizeReadBounds(p);
-            const file = await readClawChatMemoryFile(root, targetFromParams(p));
+            const file = await readClawChatMemoryFile(root, target);
             if (!file.exists) {
               return jsonResponse({
                 exists: false,
@@ -751,13 +845,23 @@ export function registerOpenclawClawlingTools(
           if (!root) {
             return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
           }
+          const p = params as ClawchatMemoryWriteParams;
+          let readable = false;
           try {
-            const p = params as ClawchatMemoryWriteParams;
             const targetError = validateTarget(root, p);
             if (targetError) return memoryToolError(new Error(targetError));
-            await writeClawChatMemoryBody(root, targetFromParams(p), p.mode, p.content);
+            const target = targetFromParams(p);
+            const scope = await memoryScopeFor(ctx, root);
+            readable = canReadMemory(scope, target);
+            // Replacing wipes what is there; append may go to any note.
+            if (p.mode !== "append" && !readable) return jsonResponse(memoryScopeRefusal(scope, target));
+            await writeClawChatMemoryBody(root, target, p.mode, p.content);
             return jsonResponse({ ok: true, targetType: p.targetType, targetId: p.targetId, mode: p.mode });
           } catch (err) {
+            // An unreadable note's failure text could reveal its state.
+            if (p.mode === "append" && !readable) {
+              return jsonResponse({ error: "memory_write_failed", message: "The memory append could not be completed." });
+            }
             return memoryToolError(err);
           }
         },
@@ -787,7 +891,10 @@ export function registerOpenclawClawlingTools(
             const p = params as ClawchatMemoryEditParams;
             const targetError = validateTarget(root, p);
             if (targetError) return memoryToolError(new Error(targetError));
-            await editClawChatMemoryBody(root, targetFromParams(p), p.oldText, p.newText);
+            const target = targetFromParams(p);
+            const scope = await memoryScopeFor(ctx, root);
+            if (!canReadMemory(scope, target)) return jsonResponse(memoryScopeRefusal(scope, target));
+            await editClawChatMemoryBody(root, target, p.oldText, p.newText);
             return jsonResponse({ ok: true, targetType: p.targetType, targetId: p.targetId });
           } catch (err) {
             return memoryToolError(err);
@@ -818,12 +925,15 @@ export function registerOpenclawClawlingTools(
             if (!root) {
               return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
             }
-            const built = buildClient(accountId);
-            if (!built.ok) return built.error;
             try {
               const p = params as ClawchatMetadataSyncParams;
               const targetError = validateTarget(root, p);
               if (targetError) return memoryToolError(new Error(targetError));
+              const target = targetFromParams(p);
+              const scope = await memoryScopeFor(ctx, root);
+              if (!canReadMemory(scope, target)) return jsonResponse(memoryScopeRefusal(scope, target));
+              const built = buildClient(accountId);
+              if (!built.ok) return built.error;
               const account = resolveCurrent(accountId);
               if (p.direction === "push") {
                 if (!Array.isArray(p.fields) || p.fields.length === 0) {
@@ -899,14 +1009,17 @@ export function registerOpenclawClawlingTools(
             if (!root) {
               return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
             }
-            const built = buildClient(accountId);
-            if (!built.ok) return built.error;
             try {
               const p = params as ClawchatMetadataUpdateParams;
               const targetError = validateTarget(root, p);
               if (targetError) return memoryToolError(new Error(targetError));
               const patchError = validateMetadataUpdatePatch(p);
               if (patchError) return validationError(patchError);
+              const target = targetFromParams(p);
+              const scope = await memoryScopeFor(ctx, root);
+              if (!canReadMemory(scope, target)) return jsonResponse(memoryScopeRefusal(scope, target));
+              const built = buildClient(accountId);
+              if (!built.ok) return built.error;
               const account = resolveCurrent(accountId);
               if (p.targetType === "owner" && !account.agentId) {
                 return configError("clawchat-plugin-openclaw: agentId is required");
@@ -1376,7 +1489,7 @@ export function registerOpenclawClawlingTools(
         description: toolDescription(
           "React to a ClawChat message with a single quick emoji (the bubble long-press reaction), instead of sending a text message. " +
             "TRIGGER - invoke when a short acknowledgement or emotional beat (agreement, thanks, laughter, celebration, sympathy) reads more naturally as an emoji on the message than as a sentence, e.g. a simple 👍 to \"done\" or ❤️ to good news. " +
-            "Omit targetMessageId and chatId to react to the message that triggered the current turn; pass targetMessageId to react to an earlier message. " +
+            "In the owner's direct chat, omit targetMessageId and chatId to react to the message that triggered the current turn; pass targetMessageId to react to an earlier message. In group chats and other direct chats, always pass this chat's chatId. " +
             "Set remove:true to take back your reaction. " +
             "Prefer the quick set 👍 ❤️ 😂 😮 😢 🙏 🎉 👏 🔥 😍 🤔. " +
             "When a reaction is all you want to send, do not also send a normal text reply.",

package/src/turn-boundary.ts

@@ -0,0 +1,61 @@
+// Who started this turn? The owner's turns are exactly the ones in the owner's
+// activation direct chat (whoever the sender is — plugin-started turns there
+// count). Every group turn and every other direct chat is someone else's.
+// Anything we cannot place is treated as someone else's (fail closed).
+import { CHANNEL_ID, normalizeOpenclawClawlingAccountId } from "./config.ts";
+
+export type TurnClass = "owner" | "non-owner";
+export type ParsedClawChatSession = { kind: "direct" | "group"; chatId: string } | null;
+
+/** Tools a turn the owner did not start may still see and call. */
+export const NON_OWNER_TOOL_ALLOWLIST: readonly string[] = Object.freeze([
+  "clawchat_memory_search", "clawchat_memory_read", "clawchat_memory_write", "clawchat_memory_edit",
+  "clawchat_mention_message", "clawchat_react_message", "clawchat_get_user_profile", "clawchat_metadata_sync",
+  "web_search",
+]);
+
+const norm = (v: string | undefined | null) => (typeof v === "string" ? v.trim().toLowerCase() : "");
+
+/**
+ * Host session keys (dmScope per-account-channel-peer):
+ *   agent:<agent>:<channel>:<account>:direct:<chat>
+ *   agent:<agent>:<channel>:group:<chat>
+ */
+export function parseClawChatSessionKey(sessionKey: string | undefined | null): ParsedClawChatSession {
+  const parts = norm(sessionKey).split(":");
+  if (parts.length < 5 || parts[0] !== "agent" || parts[2] !== CHANNEL_ID) return null;
+  if (parts[3] === "group" && parts.length === 5 && parts[4]) return { kind: "group", chatId: parts[4] };
+  if (parts[4] === "direct" && parts.length === 6 && parts[5]) return { kind: "direct", chatId: parts[5] };
+  return null;
+}
+
+/**
+ * Account id carried by a ClawChat direct session key, normalized exactly once
+ * with the plugin's account-id normalizer. Group keys carry no account
+ * segment, and a blank segment is missing (never silently "default").
+ */
+export function clawChatSessionAccountId(sessionKey: string | undefined | null): string | undefined {
+  if (parseClawChatSessionKey(sessionKey)?.kind !== "direct") return undefined;
+  const segment = (sessionKey ?? "").trim().split(":")[3]?.trim();
+  return segment ? normalizeOpenclawClawlingAccountId(segment) : undefined;
+}
+
+export function classifyChat(input: {
+  kind: "direct" | "group" | string;
+  chatId?: string | undefined | null;
+  ownerDirectConversationId?: string | undefined | null;
+}): TurnClass {
+  const owner = norm(input.ownerDirectConversationId);
+  const chat = norm(input.chatId);
+  if (input.kind !== "direct" || !owner || !chat) return "non-owner";
+  return chat === owner ? "owner" : "non-owner";
+}
+
+export function classifyTurn(input: {
+  sessionKey?: string | null;
+  ownerDirectConversationId?: string | null;
+}): TurnClass {
+  const parsed = parseClawChatSessionKey(input.sessionKey);
+  if (!parsed) return "non-owner";
+  return classifyChat({ ...parsed, ownerDirectConversationId: input.ownerDirectConversationId });
+}