@clawling/clawchat-plugin-openclaw 2026.8.2-1 → 2026.8.4-2

package/dist/src/api-client.js

@@ -398,6 +398,16 @@ export function createOpenclawClawlingApiClient(opts) {
             assertNonBlankId(conversationId, "leaveConversation: conversationId");
             return await call("POST", `/v1/conversations/${encodeURIComponent(conversationId)}/leave`);
         },
+        async addConversationMember(conversationId, userId) {
+            assertNonBlankId(conversationId, "addConversationMember: conversationId");
+            assertNonBlankId(userId, "addConversationMember: userId");
+            const cid = conversationId.trim();
+            const uid = userId.trim();
+            return await call("POST", `/v1/conversations/${encodeURIComponent(cid)}/members`, {
+                body: JSON.stringify({ user_id: uid }),
+                headers: { "content-type": "application/json" },
+            });
+        },
         async patchConversation(conversationId, patch) {
             assertNonBlankId(conversationId, "patchConversation: conversationId");
             const body = pickPatch(patch, ["title", "description"], "patchConversation");

package/dist/src/liveware-sample.js

@@ -15,6 +15,35 @@ export const LIVEWARE_SAMPLE_APP_NAME = "Liveware Sample";
 export const MAX_SAMPLE_FILE_BYTES = 512 * 1024;
 /** Files the agent owns at runtime; preserved across sample upgrades. */
 const USER_DATA_FILES = ["state.json", "events.jsonl"];
+/**
+ * Windows refuses to unlink or rename a directory while ANY file inside it is
+ * still open, and reports it as a sharing violation (EPERM/EBUSY/EACCES) or a
+ * non-empty directory. A still-draining sample server, an antivirus scan or the
+ * search indexer is enough to trigger it, and all of those clear within
+ * milliseconds — so a short bounded retry turns a hard install failure into a
+ * brief pause. On POSIX these codes essentially never appear here and the first
+ * attempt always wins, so the retry costs nothing.
+ */
+const FS_SWAP_RETRY_DELAYS_MS = [50, 150, 400];
+const TRANSIENT_FS_CODES = new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY"]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function withFsSwapRetry(op) {
+    let lastError;
+    for (let attempt = 0; attempt <= FS_SWAP_RETRY_DELAYS_MS.length; attempt += 1) {
+        try {
+            return await op();
+        }
+        catch (err) {
+            lastError = err;
+            const code = err.code ?? "";
+            const delay = FS_SWAP_RETRY_DELAYS_MS[attempt];
+            if (!TRANSIENT_FS_CODES.has(code) || delay === undefined)
+                break;
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
 function livewaresBase(base, ref) {
     return `${(base ?? OFFICIAL_SKILLS_BASE).replace(/\/+$/, "")}/${ref}/livewares`;
 }
@@ -116,6 +145,14 @@ export async function downloadLivewareSample(opts) {
     if (await localInstallMatches(appDir, entry)) {
         return { version: entry.version, appDir, reused: true };
     }
+    // Sweep app.old-* left behind when a previous swap could not delete the old
+    // tree (a handle was still open then, but is not now). Best effort: a dir we
+    // still cannot remove is simply retried next run.
+    for (const name of await fs.promises.readdir(opts.sampleRoot).catch(() => [])) {
+        if (name.startsWith("app.old-")) {
+            await fs.promises.rm(path.join(opts.sampleRoot, name), { recursive: true, force: true }).catch(() => { });
+        }
+    }
     const tmpDir = path.join(opts.sampleRoot, `app.tmp-${process.pid}`);
     await fs.promises.rm(tmpDir, { recursive: true, force: true });
     await fs.promises.mkdir(tmpDir, { recursive: true });
@@ -138,8 +175,18 @@ export async function downloadLivewareSample(opts) {
                 await fs.promises.copyFile(prev, path.join(tmpDir, name));
             }
         }
-        await fs.promises.rm(appDir, { recursive: true, force: true });
-        await fs.promises.rename(tmpDir, appDir);
+        // Swap by moving the old tree ASIDE rather than deleting it first. On
+        // Windows the delete is the step most likely to lose a race with an open
+        // handle, and doing it first leaves no app/ at all when it fails. Renaming
+        // aside puts the new tree in place first and makes the delete best-effort:
+        // a leftover app.old-<pid> is swept on the next run, never a broken install.
+        const oldDir = path.join(opts.sampleRoot, `app.old-${process.pid}`);
+        await fs.promises.rm(oldDir, { recursive: true, force: true }).catch(() => { });
+        if (fs.existsSync(appDir)) {
+            await withFsSwapRetry(() => fs.promises.rename(appDir, oldDir));
+        }
+        await withFsSwapRetry(() => fs.promises.rename(tmpDir, appDir));
+        await fs.promises.rm(oldDir, { recursive: true, force: true }).catch(() => { });
         return { version: entry.version, appDir };
     }
     catch (err) {
@@ -147,6 +194,35 @@ export async function downloadLivewareSample(opts) {
         throw err;
     }
 }
+/**
+ * Terminate a child and everything it spawned.
+ *
+ * POSIX: `SIGTERM` to the child is what we want and what the child expects.
+ *
+ * Windows: there are no signals. `child.kill()` maps to TerminateProcess on
+ * that one process, so any grandchild the liveware agent spawned survives —
+ * orphaned, still holding the sample port, and invisible to the next boot,
+ * which then fails to bind. `taskkill /T /F` takes the whole tree down.
+ * Fire-and-forget: we never wait on it, and a failure (already dead, no such
+ * pid) falls through to the ordinary kill().
+ */
+export function killProcessTree(child, execFileFn = nodeExecFile) {
+    if (!child)
+        return;
+    if (process.platform === "win32" && typeof child.pid === "number") {
+        try {
+            execFileFn("taskkill", ["/pid", String(child.pid), "/T", "/F"], () => { });
+            return;
+        }
+        catch {
+            // taskkill missing or spawn refused — fall back to the plain kill below.
+        }
+    }
+    try {
+        child.kill("SIGTERM");
+    }
+    catch { /* already dead */ }
+}
 const SERVER_START_TIMEOUT_MS = 10_000;
 const TUNNEL_START_TIMEOUT_MS = 30_000;
 const CLI_TIMEOUT_MS = 30_000;
@@ -164,10 +240,7 @@ function waitForOutput(child, match, timeoutMs, label) {
             child.stderr?.removeListener("data", onData);
             child.removeListener("exit", onExit);
             if (err) {
-                try {
-                    child.kill("SIGTERM");
-                }
-                catch { /* already dead */ }
+                killProcessTree(child);
                 reject(err);
             }
             else {
@@ -535,10 +608,7 @@ export class LivewareSampleSupervisor {
     killChildren() {
         this.generation += 1; // invalidate pending exit handlers before killing
         for (const child of [this.serverChild, this.tunnelChild]) {
-            try {
-                child?.kill("SIGTERM");
-            }
-            catch { /* already dead */ }
+            killProcessTree(child, this.deps.execFileFn);
         }
         this.serverChild = null;
         this.tunnelChild = null;

package/dist/src/skill-update.js

@@ -38,9 +38,11 @@ import { fileURLToPath } from "node:url";
  * - All network IO goes through an injected `FetchLike`; tests never touch the
  *   real network.
  *
- * Cross-language contract / spec: see
- * `ops/agent-plugin/skill-dynamic-update-plan.md` (§2, §3 phase 4,
- * §4 #5, §6.4, §6.7, §7.2).
+ * Cross-language contract / spec: see `docs/clawchat-plugin-openclaw.md`
+ * §"Conversational skill hot-update" for this adapter's end of the flow,
+ * `docs/client-integration.md` for the `clawchat.skill.update.check` signal
+ * shape, and the install-cli repo's `skills/README.md` for the canonical skill
+ * source and `manifest.json` contract.
  */
 // ---------------------------------------------------------------------------
 // Constants — fixed contract (must match the install-cli `config.ts`).

package/dist/src/tools-schema.js

@@ -128,6 +128,16 @@ export const ClawchatLeaveGroupSchema = Type.Object({
         description: "Concrete ClawChat group conversation id to leave",
     }),
 });
+export const ClawchatAddGroupMemberSchema = Type.Object({
+    conversationId: Type.String({
+        minLength: 1,
+        description: "Concrete ClawChat group conversation id to add the user to",
+    }),
+    userId: Type.String({
+        minLength: 1,
+        description: "Concrete ClawChat user id (usr_...) to add to the group",
+    }),
+});
 export const ClawchatMentionMessageSchema = Type.Object({
     chatId: Type.String({
         minLength: 1,

package/dist/src/tools.js

@@ -12,7 +12,7 @@ import { getOpenclawClawlingClient, } from "./runtime.js";
 import { markTerminalClawChatSend, getCurrentTerminalSendScope } from "./terminal-send.js";
 import { editClawChatMemoryBody, readClawChatMemoryFile, resolveClawChatMemoryPath, searchClawChatMemory, writeClawChatMemoryBody, } from "./clawchat-memory.js";
 import { pullGroupMetadata, pullOwnerMetadata, pullUserMetadata, pushMetadata, updateMetadata, } from "./clawchat-metadata.js";
-import { ClawchatGetAccountProfileSchema, ClawchatGetConversationSchema, ClawchatGetMomentSchema, ClawchatGetUserProfileSchema, ClawchatLeaveGroupSchema, ClawchatAcceptFriendRequestSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemorySearchSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListFriendRequestsSchema, ClawchatListMomentsSchema, ClawchatMentionMessageSchema, ClawchatReactMessageSchema, ClawchatReplyMomentCommentSchema, ClawchatRejectFriendRequestSchema, ClawchatRemoveFriendSchema, ClawchatSearchUsersSchema, ClawchatSendFriendRequestSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatRegisterAppSchema, ClawchatListAppsSchema, ClawchatUnregisterAppSchema, ClawchatLivewareLoginSchema, } from "./tools-schema.js";
+import { ClawchatGetAccountProfileSchema, ClawchatGetConversationSchema, ClawchatGetMomentSchema, ClawchatGetUserProfileSchema, ClawchatLeaveGroupSchema, ClawchatAddGroupMemberSchema, ClawchatAcceptFriendRequestSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemorySearchSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListFriendRequestsSchema, ClawchatListMomentsSchema, ClawchatMentionMessageSchema, ClawchatReactMessageSchema, ClawchatReplyMomentCommentSchema, ClawchatRejectFriendRequestSchema, ClawchatRemoveFriendSchema, ClawchatSearchUsersSchema, ClawchatSendFriendRequestSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatRegisterAppSchema, ClawchatListAppsSchema, ClawchatUnregisterAppSchema, ClawchatLivewareLoginSchema, } from "./tools-schema.js";
 const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
 // Owner-approval gate business codes (must match the ClawChat backend's owner-approval codes).
 const CODE_PENDING_APPROVAL = 21001;
@@ -808,6 +808,34 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             });
         },
     }, { name: "clawchat_leave_group" });
+    api.registerTool({
+        name: "clawchat_add_group_member",
+        label: "Add ClawChat Group Member",
+        description: toolDescription("Add a specified ClawChat user to a group conversation the agent is a member of. " +
+            "TRIGGER - invoke only when the user explicitly asks the agent to add, invite, or pull a specific person into a specific ClawChat group, and both a concrete conversationId and a concrete userId are available. " +
+            "Never guess a userId from a name or nickname — use ids from ClawChat Group Message Metadata, clawchat_list_account_friends, or clawchat_search_users. " +
+            "Groups only: direct conversations are rejected by the server. " +
+            "The target must already be the agent's ClawChat friend, and the agent needs the group-management permission granted by its owner; if the call fails for either reason, explain that to the user and do not retry."),
+        parameters: ClawchatAddGroupMemberSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_add_group_member", params, async () => {
+                const p = params;
+                const built = buildClient();
+                if (!built.ok)
+                    return built.error;
+                try {
+                    const data = await built.client.addConversationMember(p.conversationId, p.userId);
+                    return jsonResponse(data);
+                }
+                catch (err) {
+                    if (err instanceof ClawlingApiError) {
+                        return apiError(err);
+                    }
+                    return genericError(err);
+                }
+            });
+        },
+    }, { name: "clawchat_add_group_member" });
     api.registerTool({
         name: "clawchat_mention_message",
         label: "Send ClawChat Mention Message",

package/openclaw.plugin.json

@@ -47,6 +47,7 @@
       "clawchat_react_message",
       "clawchat_get_conversation",
       "clawchat_leave_group",
+      "clawchat_add_group_member",
       "clawchat_list_moments",
       "clawchat_get_moment",
       "clawchat_create_moment",

package/package.json

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

package/src/api-client.ts

@@ -135,6 +135,10 @@ export interface OpenclawClawlingApiClient {
   deleteMomentComment(params: { momentId: number; commentId: number }): Promise<{ ok: boolean }>;
   getConversation(conversationId: string): Promise<{ conversation: ConversationDetails }>;
   leaveConversation(conversationId: string): Promise<{ ok: boolean }>;
+  addConversationMember(
+    conversationId: string,
+    userId: string,
+  ): Promise<{ conversation: ConversationDetails }>;
   patchConversation(
     conversationId: string,
     patch: ConversationMetadataPatch,
@@ -643,6 +647,23 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         `/v1/conversations/${encodeURIComponent(conversationId)}/leave`,
       );
     },
+    async addConversationMember(
+      conversationId,
+      userId,
+    ): Promise<{ conversation: ConversationDetails }> {
+      assertNonBlankId(conversationId, "addConversationMember: conversationId");
+      assertNonBlankId(userId, "addConversationMember: userId");
+      const cid = conversationId.trim();
+      const uid = userId.trim();
+      return await call<{ conversation: ConversationDetails }>(
+        "POST",
+        `/v1/conversations/${encodeURIComponent(cid)}/members`,
+        {
+          body: JSON.stringify({ user_id: uid }),
+          headers: { "content-type": "application/json" },
+        },
+      );
+    },
     async patchConversation(
       conversationId: string,
       patch: ConversationMetadataPatch,

package/src/liveware-sample.ts

@@ -20,6 +20,36 @@ export const MAX_SAMPLE_FILE_BYTES = 512 * 1024;
 /** Files the agent owns at runtime; preserved across sample upgrades. */
 const USER_DATA_FILES = ["state.json", "events.jsonl"];
 
+/**
+ * Windows refuses to unlink or rename a directory while ANY file inside it is
+ * still open, and reports it as a sharing violation (EPERM/EBUSY/EACCES) or a
+ * non-empty directory. A still-draining sample server, an antivirus scan or the
+ * search indexer is enough to trigger it, and all of those clear within
+ * milliseconds — so a short bounded retry turns a hard install failure into a
+ * brief pause. On POSIX these codes essentially never appear here and the first
+ * attempt always wins, so the retry costs nothing.
+ */
+const FS_SWAP_RETRY_DELAYS_MS = [50, 150, 400];
+const TRANSIENT_FS_CODES = new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY"]);
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+async function withFsSwapRetry<T>(op: () => Promise<T>): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= FS_SWAP_RETRY_DELAYS_MS.length; attempt += 1) {
+    try {
+      return await op();
+    } catch (err) {
+      lastError = err;
+      const code = (err as NodeJS.ErrnoException).code ?? "";
+      const delay = FS_SWAP_RETRY_DELAYS_MS[attempt];
+      if (!TRANSIENT_FS_CODES.has(code) || delay === undefined) break;
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+
 export interface LivewareSampleManifestFile {
   path: string;
   sha256: string;
@@ -151,6 +181,15 @@ export async function downloadLivewareSample(opts: {
   if (await localInstallMatches(appDir, entry)) {
     return { version: entry.version, appDir, reused: true };
   }
+  // Sweep app.old-* left behind when a previous swap could not delete the old
+  // tree (a handle was still open then, but is not now). Best effort: a dir we
+  // still cannot remove is simply retried next run.
+  for (const name of await fs.promises.readdir(opts.sampleRoot).catch(() => [])) {
+    if (name.startsWith("app.old-")) {
+      await fs.promises.rm(path.join(opts.sampleRoot, name), { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
   const tmpDir = path.join(opts.sampleRoot, `app.tmp-${process.pid}`);
   await fs.promises.rm(tmpDir, { recursive: true, force: true });
   await fs.promises.mkdir(tmpDir, { recursive: true });
@@ -173,8 +212,18 @@ export async function downloadLivewareSample(opts: {
         await fs.promises.copyFile(prev, path.join(tmpDir, name));
       }
     }
-    await fs.promises.rm(appDir, { recursive: true, force: true });
-    await fs.promises.rename(tmpDir, appDir);
+    // Swap by moving the old tree ASIDE rather than deleting it first. On
+    // Windows the delete is the step most likely to lose a race with an open
+    // handle, and doing it first leaves no app/ at all when it fails. Renaming
+    // aside puts the new tree in place first and makes the delete best-effort:
+    // a leftover app.old-<pid> is swept on the next run, never a broken install.
+    const oldDir = path.join(opts.sampleRoot, `app.old-${process.pid}`);
+    await fs.promises.rm(oldDir, { recursive: true, force: true }).catch(() => {});
+    if (fs.existsSync(appDir)) {
+      await withFsSwapRetry(() => fs.promises.rename(appDir, oldDir));
+    }
+    await withFsSwapRetry(() => fs.promises.rename(tmpDir, appDir));
+    await fs.promises.rm(oldDir, { recursive: true, force: true }).catch(() => {});
     return { version: entry.version, appDir };
   } catch (err) {
     await fs.promises.rm(tmpDir, { recursive: true, force: true });
@@ -185,6 +234,34 @@ export async function downloadLivewareSample(opts: {
 export type SpawnLike = typeof nodeSpawn;
 export type ExecFileLike = typeof nodeExecFile;
 
+/**
+ * Terminate a child and everything it spawned.
+ *
+ * POSIX: `SIGTERM` to the child is what we want and what the child expects.
+ *
+ * Windows: there are no signals. `child.kill()` maps to TerminateProcess on
+ * that one process, so any grandchild the liveware agent spawned survives —
+ * orphaned, still holding the sample port, and invisible to the next boot,
+ * which then fails to bind. `taskkill /T /F` takes the whole tree down.
+ * Fire-and-forget: we never wait on it, and a failure (already dead, no such
+ * pid) falls through to the ordinary kill().
+ */
+export function killProcessTree(
+  child: ChildProcess | null | undefined,
+  execFileFn: ExecFileLike = nodeExecFile,
+): void {
+  if (!child) return;
+  if (process.platform === "win32" && typeof child.pid === "number") {
+    try {
+      execFileFn("taskkill", ["/pid", String(child.pid), "/T", "/F"], () => {});
+      return;
+    } catch {
+      // taskkill missing or spawn refused — fall back to the plain kill below.
+    }
+  }
+  try { child.kill("SIGTERM"); } catch { /* already dead */ }
+}
+
 const SERVER_START_TIMEOUT_MS = 10_000;
 const TUNNEL_START_TIMEOUT_MS = 30_000;
 const CLI_TIMEOUT_MS = 30_000;
@@ -207,7 +284,7 @@ function waitForOutput(
       child.stderr?.removeListener("data", onData);
       child.removeListener("exit", onExit);
       if (err) {
-        try { child.kill("SIGTERM"); } catch { /* already dead */ }
+        killProcessTree(child);
         reject(err);
       } else {
         resolve(value as string);
@@ -670,7 +747,7 @@ export class LivewareSampleSupervisor {
   private killChildren(): void {
     this.generation += 1; // invalidate pending exit handlers before killing
     for (const child of [this.serverChild, this.tunnelChild]) {
-      try { child?.kill("SIGTERM"); } catch { /* already dead */ }
+      killProcessTree(child, this.deps.execFileFn);
     }
     this.serverChild = null;
     this.tunnelChild = null;

package/src/skill-update.ts

@@ -39,9 +39,11 @@ import { fileURLToPath } from "node:url";
  * - All network IO goes through an injected `FetchLike`; tests never touch the
  *   real network.
  *
- * Cross-language contract / spec: see
- * `ops/agent-plugin/skill-dynamic-update-plan.md` (§2, §3 phase 4,
- * §4 #5, §6.4, §6.7, §7.2).
+ * Cross-language contract / spec: see `docs/clawchat-plugin-openclaw.md`
+ * §"Conversational skill hot-update" for this adapter's end of the flow,
+ * `docs/client-integration.md` for the `clawchat.skill.update.check` signal
+ * shape, and the install-cli repo's `skills/README.md` for the canonical skill
+ * source and `manifest.json` contract.
  */
 
 // ---------------------------------------------------------------------------

package/src/tools-schema.ts

@@ -208,6 +208,18 @@ export const ClawchatLeaveGroupSchema = Type.Object({
 });
 export type ClawchatLeaveGroupParams = Static<typeof ClawchatLeaveGroupSchema>;
 
+export const ClawchatAddGroupMemberSchema = Type.Object({
+  conversationId: Type.String({
+    minLength: 1,
+    description: "Concrete ClawChat group conversation id to add the user to",
+  }),
+  userId: Type.String({
+    minLength: 1,
+    description: "Concrete ClawChat user id (usr_...) to add to the group",
+  }),
+});
+export type ClawchatAddGroupMemberParams = Static<typeof ClawchatAddGroupMemberSchema>;
+
 export const ClawchatMentionMessageSchema = Type.Object({
   chatId: Type.String({
     minLength: 1,

package/src/tools.ts

@@ -43,6 +43,7 @@ import {
   ClawchatGetMomentSchema,
   ClawchatGetUserProfileSchema,
   ClawchatLeaveGroupSchema,
+  ClawchatAddGroupMemberSchema,
   ClawchatAcceptFriendRequestSchema,
   ClawchatMemoryEditSchema,
   ClawchatMemoryReadSchema,
@@ -86,6 +87,7 @@ import {
   type ClawchatGetMomentParams,
   type ClawchatGetUserProfileParams,
   type ClawchatLeaveGroupParams,
+  type ClawchatAddGroupMemberParams,
   type ClawchatListFriendRequestsParams,
   type ClawchatListMomentsParams,
   type ClawchatMentionMessageParams,
@@ -1048,6 +1050,38 @@ export function registerOpenclawClawlingTools(
     { name: "clawchat_leave_group" },
   );
 
+  api.registerTool(
+    {
+      name: "clawchat_add_group_member",
+      label: "Add ClawChat Group Member",
+      description: toolDescription(
+        "Add a specified ClawChat user to a group conversation the agent is a member of. " +
+          "TRIGGER - invoke only when the user explicitly asks the agent to add, invite, or pull a specific person into a specific ClawChat group, and both a concrete conversationId and a concrete userId are available. " +
+          "Never guess a userId from a name or nickname — use ids from ClawChat Group Message Metadata, clawchat_list_account_friends, or clawchat_search_users. " +
+          "Groups only: direct conversations are rejected by the server. " +
+          "The target must already be the agent's ClawChat friend, and the agent needs the group-management permission granted by its owner; if the call fails for either reason, explain that to the user and do not retry.",
+      ),
+      parameters: ClawchatAddGroupMemberSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_add_group_member", params, async () => {
+          const p = params as ClawchatAddGroupMemberParams;
+          const built = buildClient();
+          if (!built.ok) return built.error;
+          try {
+            const data = await built.client.addConversationMember(p.conversationId, p.userId);
+            return jsonResponse(data);
+          } catch (err) {
+            if (err instanceof ClawlingApiError) {
+              return apiError(err);
+            }
+            return genericError(err);
+          }
+        });
+      },
+    },
+    { name: "clawchat_add_group_member" },
+  );
+
   api.registerTool(
     {
       name: "clawchat_mention_message",