@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/dist/src/tools.js

@@ -0,0 +1,920 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createOpenclawClawlingApiClient } from "./api-client.js";
+import { ClawlingApiError, } from "./api-types.js";
+import { resolveOpenclawClawlingAccount } from "./config.js";
+import { clawChatDbPathForStateDir, getClawChatStore, } from "./storage.js";
+import { sendOpenclawClawlingMentionMessage } from "./outbound.js";
+import { getOpenclawClawlingClient, } from "./runtime.js";
+import { markTerminalClawChatSend } 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, ClawchatGetUserProfileSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemorySearchSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListMomentsSchema, ClawchatMentionMessageSchema, ClawchatReplyMomentCommentSchema, ClawchatSearchUsersSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatUploadMediaFileSchema, } from "./tools-schema.js";
+const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+function jsonResponse(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        details: data,
+    };
+}
+function configError(message) {
+    return jsonResponse({ error: "config", message });
+}
+function apiError(err) {
+    return jsonResponse({
+        error: err.kind,
+        message: err.message,
+        ...(err.meta ? { meta: err.meta } : {}),
+    });
+}
+function validationError(message) {
+    return jsonResponse({ error: "validation", message });
+}
+function genericError(err) {
+    return jsonResponse({
+        error: "unknown",
+        message: err instanceof Error ? err.message : String(err),
+    });
+}
+const MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".json": "application/json",
+    ".csv": "text/csv",
+    ".zip": "application/zip",
+    ".mp3": "audio/mpeg",
+    ".m4a": "audio/mp4",
+    ".wav": "audio/wav",
+    ".ogg": "audio/ogg",
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+};
+const DIRECT_TOOL_GUARD = "Use this registered ClawChat plugin tool directly. Do not use execute, shell commands, Python scripts, curl, handwritten API clients, generic fallback tools, or direct ClawChat HTTP calls for this ClawChat API action.";
+const MEMORY_READ_DEFAULT_LIMIT = 20_000;
+const MEMORY_READ_MAX_LIMIT = 100_000;
+function toolDescription(...parts) {
+    return `${parts.join("")} ${DIRECT_TOOL_GUARD}`;
+}
+function memoryToolDescription(...parts) {
+    return parts.join("");
+}
+function inferMimeFromPath(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+function validateMentionMessageParams(params) {
+    if (!params || typeof params !== "object") {
+        return { ok: false, message: "clawchat-plugin-openclaw: params are required" };
+    }
+    const p = params;
+    if (typeof p.chatId !== "string" || !p.chatId.trim()) {
+        return { ok: false, message: "clawchat-plugin-openclaw: chatId is required" };
+    }
+    if (p.chatType !== undefined && p.chatType !== "group" && p.chatType !== "direct") {
+        return { ok: false, message: "clawchat-plugin-openclaw: chatType must be group or direct" };
+    }
+    if (p.text !== undefined && typeof p.text !== "string") {
+        return { ok: false, message: "clawchat-plugin-openclaw: text must be a string" };
+    }
+    if (!Array.isArray(p.mentions) || p.mentions.length === 0) {
+        return { ok: false, message: "clawchat-plugin-openclaw: at least one mention is required" };
+    }
+    for (let i = 0; i < p.mentions.length; i += 1) {
+        const mention = p.mentions[i];
+        if (!mention || typeof mention !== "object") {
+            return { ok: false, message: `clawchat-plugin-openclaw: mentions[${i}] must be an object` };
+        }
+        if (typeof mention.userId !== "string" || !mention.userId.trim()) {
+            return { ok: false, message: `clawchat-plugin-openclaw: mentions[${i}].userId is required` };
+        }
+        if (mention.display !== undefined && typeof mention.display !== "string") {
+            return { ok: false, message: `clawchat-plugin-openclaw: mentions[${i}].display must be a string` };
+        }
+    }
+    if (p.replyToMessageId !== undefined) {
+        if (typeof p.replyToMessageId !== "string") {
+            return { ok: false, message: "clawchat-plugin-openclaw: replyToMessageId must be a string" };
+        }
+        const replyToMessageId = p.replyToMessageId.trim();
+        if (!replyToMessageId) {
+            return { ok: false, message: "clawchat-plugin-openclaw: replyToMessageId must be non-empty" };
+        }
+        return {
+            ok: true,
+            params: {
+                ...p,
+                replyToMessageId,
+            },
+        };
+    }
+    return { ok: true, params: p };
+}
+export function registerOpenclawClawlingTools(api, options = {}) {
+    if (!api.config) {
+        api.logger.debug?.("clawchat-plugin-openclaw: api.config missing; skipping tool registration");
+        return;
+    }
+    // Re-resolve at call time so config reloads pick up new tokens / baseUrl.
+    function resolveCurrent() {
+        return resolveOpenclawClawlingAccount(api.config);
+    }
+    function resolveStore() {
+        if ("store" in options)
+            return options.store ?? null;
+        try {
+            const stateDir = api.runtime.state?.resolveStateDir?.();
+            return getClawChatStore({
+                ...(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {}),
+                log: { error: (message) => api.logger.error?.(message) },
+            });
+        }
+        catch {
+            api.logger.error?.("clawchat-plugin-openclaw sqlite tool persistence unavailable; continuing");
+            return null;
+        }
+    }
+    function detailsError(details) {
+        if (!details || typeof details !== "object")
+            return null;
+        const raw = details;
+        if (typeof raw.error !== "string" || !raw.error)
+            return null;
+        return typeof raw.message === "string" && raw.message
+            ? `${raw.error}: ${raw.message}`
+            : raw.error;
+    }
+    function persistToolCall(input) {
+        try {
+            resolveStore()?.recordToolCall(input);
+        }
+        catch {
+            api.logger.error?.("clawchat-plugin-openclaw sqlite tool call insert failed; continuing");
+        }
+    }
+    async function recordClawchatToolCall(toolName, params, fn) {
+        const startedAt = Date.now();
+        const account = resolveCurrent();
+        try {
+            const result = await fn();
+            const details = result.details ?? result;
+            persistToolCall({
+                platform: "openclaw",
+                accountId: account.accountId,
+                toolName,
+                args: params ?? {},
+                result: details,
+                error: detailsError(details),
+                startedAt,
+                endedAt: Date.now(),
+            });
+            return result;
+        }
+        catch (err) {
+            persistToolCall({
+                platform: "openclaw",
+                accountId: account.accountId,
+                toolName,
+                args: params ?? {},
+                result: null,
+                error: err instanceof Error ? err.message : String(err),
+                startedAt,
+                endedAt: Date.now(),
+            });
+            throw err;
+        }
+    }
+    function buildClient() {
+        const acct = resolveCurrent();
+        // `baseUrl` always resolves via the built-in default in config.ts, so we
+        // only need to gate on `token` here (which is populated by ClawChat
+        // activation/login).
+        if (!acct.token) {
+            return { ok: false, error: configError("clawchat-plugin-openclaw: token is required") };
+        }
+        return {
+            ok: true,
+            client: createOpenclawClawlingApiClient({
+                baseUrl: acct.baseUrl,
+                token: acct.token,
+                userId: acct.userId,
+            }),
+        };
+    }
+    function withClient(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)
+                    return apiError(err);
+                return genericError(err);
+            }
+        })();
+    }
+    function workspaceRoot(ctx) {
+        const root = typeof ctx.workspaceDir === "string" ? ctx.workspaceDir.trim() : "";
+        return root || null;
+    }
+    function targetFromParams(params) {
+        return { targetType: params.targetType, targetId: params.targetId };
+    }
+    function validateTarget(root, params) {
+        try {
+            resolveClawChatMemoryPath(root, targetFromParams(params));
+            return null;
+        }
+        catch (err) {
+            return err instanceof Error ? err.message : String(err);
+        }
+    }
+    function normalizeReadBounds(params) {
+        const offset = typeof params.offset === "number" && Number.isFinite(params.offset)
+            ? Math.max(0, Math.trunc(params.offset))
+            : 0;
+        const limit = typeof params.limit === "number" && Number.isFinite(params.limit)
+            ? Math.min(MEMORY_READ_MAX_LIMIT, Math.max(1, Math.trunc(params.limit)))
+            : MEMORY_READ_DEFAULT_LIMIT;
+        return { offset, limit };
+    }
+    function metadataPatchAllowedKeys(targetType) {
+        if (targetType === "group")
+            return ["group_title", "group_description"];
+        if (targetType === "owner")
+            return ["agent_behavior"];
+        return ["nickname", "avatar_url", "bio"];
+    }
+    function validateMetadataUpdatePatch(params) {
+        const patch = params.patch;
+        if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+            return "clawchat-plugin-openclaw: metadata patch is required";
+        }
+        const keys = Object.keys(patch);
+        if (keys.length === 0) {
+            return "clawchat-plugin-openclaw: metadata patch must include at least one mutable field";
+        }
+        const allowed = new Set(metadataPatchAllowedKeys(params.targetType));
+        const invalid = keys.filter((key) => !allowed.has(key));
+        if (invalid.length > 0) {
+            return `clawchat-plugin-openclaw: metadata patch contains unsupported field(s): ${invalid.join(", ")}`;
+        }
+        const nonString = keys.filter((key) => typeof patch[key] !== "string");
+        if (nonString.length > 0) {
+            return `clawchat-plugin-openclaw: metadata patch field(s) must be strings: ${nonString.join(", ")}`;
+        }
+        return null;
+    }
+    function isUnsafeMemoryPathError(message) {
+        return /Unsafe clawchat memory|Resolved clawchat memory path is outside root/i.test(message);
+    }
+    function memoryToolError(err) {
+        if (err instanceof ClawlingApiError)
+            return apiError(err);
+        const message = err instanceof Error ? err.message : String(err);
+        if (isUnsafeMemoryPathError(message)) {
+            return validationError("clawchat-plugin-openclaw: unsafe ClawChat memory target");
+        }
+        return validationError(message);
+    }
+    function registerMemoryTools() {
+        api.registerTool((ctx) => ({
+            name: "clawchat_memory_search",
+            label: "Search ClawChat Memory",
+            description: memoryToolDescription("Search local ClawChat memory Markdown files by keyword across owner.md, users/*.md, and groups/*.md. " +
+                "Use this when the user asks who/what a remembered person, alias, relationship, prior note, group rule, group context, or local ClawChat memory item is and no explicit targetId is known. " +
+                "This searches local memory metadata and agent-authored Markdown body. It does not contact the ClawChat server. " +
+                "Use this before answering unknown when the user provides a name, alias, phrase, or uncertain reference that may exist in local memory. " +
+                "If exactly one relevant result is found, use clawchat_memory_read with the returned targetType and targetId when full context is needed. If multiple relevant results are found, summarize the candidates or ask the user to clarify."),
+            parameters: ClawchatMemorySearchSchema,
+            async execute(_callId, params) {
+                const root = workspaceRoot(ctx);
+                if (!root) {
+                    return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
+                }
+                try {
+                    const p = params;
+                    return jsonResponse(await searchClawChatMemory(root, {
+                        query: p.query,
+                        targetTypes: p.targetTypes,
+                        maxResults: p.maxResults,
+                    }));
+                }
+                catch (err) {
+                    return memoryToolError(err);
+                }
+            },
+        }), { name: "clawchat_memory_search" });
+        api.registerTool((ctx) => ({
+            name: "clawchat_memory_read",
+            label: "Read ClawChat Memory",
+            description: memoryToolDescription("Read one local ClawChat memory Markdown file by explicit targetType and targetId. " +
+                "Use this only when the memory target is already known, such as owner, a concrete userId, a concrete groupId, the current sender_id, or a target returned by clawchat_memory_search. " +
+                "Do not guess targetId from names, nicknames, aliases, or plain text. If the user gives a name, alias, phrase, relationship, or uncertain reference, use clawchat_memory_search first. " +
+                "This reads metadata and agent-authored body; it does not contact the ClawChat server."),
+            parameters: ClawchatMemoryReadSchema,
+            async execute(_callId, params) {
+                const root = workspaceRoot(ctx);
+                if (!root) {
+                    return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
+                }
+                try {
+                    const p = params;
+                    const targetError = validateTarget(root, p);
+                    if (targetError)
+                        return memoryToolError(new Error(targetError));
+                    const { offset, limit } = normalizeReadBounds(p);
+                    const file = await readClawChatMemoryFile(root, targetFromParams(p));
+                    if (!file.exists) {
+                        return jsonResponse({
+                            exists: false,
+                            content: "",
+                            offset,
+                            limit,
+                            truncated: false,
+                            totalLength: 0,
+                            nextOffset: null,
+                        });
+                    }
+                    const totalLength = file.raw.length;
+                    const end = Math.min(totalLength, offset + limit);
+                    const truncated = end < totalLength;
+                    return jsonResponse({
+                        exists: true,
+                        content: file.raw.slice(offset, end),
+                        offset,
+                        limit,
+                        truncated,
+                        totalLength,
+                        nextOffset: truncated ? end : null,
+                    });
+                }
+                catch (err) {
+                    return memoryToolError(err);
+                }
+            },
+        }), { name: "clawchat_memory_read" });
+        api.registerTool((ctx) => ({
+            name: "clawchat_memory_write",
+            label: "Write ClawChat Memory",
+            description: memoryToolDescription("Append to or replace only the agent-authored body of a ClawChat memory Markdown file by explicit targetType and targetId. " +
+                "This never modifies the metadata block. " +
+                "Do not use this to write or refresh ClawChat profile/metadata fields such as agent_nickname, agent_avatar_url, agent_bio, agent_behavior, agent_owner_nickname, agent_owner_avatar_url, agent_owner_bio, nickname, avatar_url, bio, profile_type, group_title, or group_description. " +
+                "When the user asks to refresh, sync, or update local ClawChat current-agent/agent-owner/user/group profile information, use clawchat_metadata_sync with direction=pull instead. " +
+                "Do not use this to search memory. Use clawchat_memory_search to locate uncertain names, aliases, relationships, or prior notes before writing. " +
+                "Use append for new long-term memory notes and replace only when intentionally rewriting the whole body."),
+            parameters: ClawchatMemoryWriteSchema,
+            async execute(_callId, params) {
+                const root = workspaceRoot(ctx);
+                if (!root) {
+                    return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
+                }
+                try {
+                    const p = params;
+                    const targetError = validateTarget(root, p);
+                    if (targetError)
+                        return memoryToolError(new Error(targetError));
+                    await writeClawChatMemoryBody(root, targetFromParams(p), p.mode, p.content);
+                    return jsonResponse({ ok: true, targetType: p.targetType, targetId: p.targetId, mode: p.mode });
+                }
+                catch (err) {
+                    return memoryToolError(err);
+                }
+            },
+        }), { name: "clawchat_memory_write" });
+        api.registerTool((ctx) => ({
+            name: "clawchat_memory_edit",
+            label: "Edit ClawChat Memory",
+            description: memoryToolDescription("Replace exactly one existing text span in the agent-authored body of a ClawChat memory Markdown file. " +
+                "This never modifies the metadata block. " +
+                "Do not use this to edit ClawChat profile/metadata fields such as agent_nickname, agent_avatar_url, agent_bio, agent_behavior, agent_owner_nickname, agent_owner_avatar_url, agent_owner_bio, nickname, avatar_url, bio, profile_type, group_title, or group_description. " +
+                "Use clawchat_metadata_sync or clawchat_metadata_update for metadata. " +
+                "Do not use this to search memory. Use clawchat_memory_search to locate uncertain names, aliases, relationships, or prior notes before editing. " +
+                "The oldText must match exactly once; use read first when unsure."),
+            parameters: ClawchatMemoryEditSchema,
+            async execute(_callId, params) {
+                const root = workspaceRoot(ctx);
+                if (!root) {
+                    return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
+                }
+                try {
+                    const p = params;
+                    const targetError = validateTarget(root, p);
+                    if (targetError)
+                        return memoryToolError(new Error(targetError));
+                    await editClawChatMemoryBody(root, targetFromParams(p), p.oldText, p.newText);
+                    return jsonResponse({ ok: true, targetType: p.targetType, targetId: p.targetId });
+                }
+                catch (err) {
+                    return memoryToolError(err);
+                }
+            },
+        }), { name: "clawchat_memory_edit" });
+        api.registerTool((ctx) => ({
+            name: "clawchat_metadata_sync",
+            label: "Sync ClawChat Metadata",
+            description: memoryToolDescription("Synchronize the ClawChat metadata block for an explicit owner, user, or group target. " +
+                "Use direction=pull when the user asks to refresh, sync, or update local ClawChat current agent profile/behavior, agent-owner profile information, user information, or group information from the server; this fetches the authoritative server record and rewrites only the metadata block. " +
+                "Use direction=push only to push selected existing local metadata fields to the server, then refresh the metadata block from the server response. " +
+                "For direction=push, pass non-empty fields containing only pushable metadata field names: owner supports agent_behavior only; user supports nickname/avatar_url/bio for the connected account only; group supports group_title/group_description. " +
+                "This does not modify the agent-authored body. " +
+                "This synchronizes only the metadata block. It does not search or read agent-authored long-term memory body. For remembered aliases or local notes, use clawchat_memory_search or clawchat_memory_read. " +
+                "Do not combine clawchat_get_user_profile with clawchat_memory_write to update local profile metadata."),
+            parameters: ClawchatMetadataSyncSchema,
+            async execute(_callId, params) {
+                const root = workspaceRoot(ctx);
+                if (!root) {
+                    return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
+                }
+                const built = buildClient();
+                if (!built.ok)
+                    return built.error;
+                try {
+                    const p = params;
+                    const targetError = validateTarget(root, p);
+                    if (targetError)
+                        return memoryToolError(new Error(targetError));
+                    const account = resolveCurrent();
+                    if (p.direction === "push") {
+                        if (!Array.isArray(p.fields) || p.fields.length === 0) {
+                            return validationError("clawchat-plugin-openclaw: fields are required for metadata push");
+                        }
+                        if (p.targetType === "owner" && !account.agentId) {
+                            return configError("clawchat-plugin-openclaw: agentId is required");
+                        }
+                        if (p.targetType === "user" && !account.userId) {
+                            return configError("clawchat-plugin-openclaw: userId is required");
+                        }
+                        return jsonResponse(await pushMetadata({
+                            memoryRoot: root,
+                            targetType: p.targetType,
+                            targetId: p.targetId,
+                            fields: p.fields,
+                            agentId: account.agentId,
+                            accountUserId: account.userId,
+                            api: built.client,
+                        }));
+                    }
+                    if (p.targetType === "owner") {
+                        if (!account.agentId)
+                            return configError("clawchat-plugin-openclaw: agentId is required");
+                        return jsonResponse(await pullOwnerMetadata({
+                            memoryRoot: root,
+                            agentId: account.agentId,
+                            accountUserId: account.userId,
+                            accountOwnerUserId: account.ownerUserId || undefined,
+                            api: built.client,
+                        }));
+                    }
+                    if (p.targetType === "user") {
+                        return jsonResponse(await pullUserMetadata({ memoryRoot: root, userId: p.targetId, api: built.client }));
+                    }
+                    return jsonResponse(await pullGroupMetadata({
+                        memoryRoot: root,
+                        groupId: p.targetId,
+                        api: built.client,
+                        skipUserIds: [account.userId, account.ownerUserId],
+                    }));
+                }
+                catch (err) {
+                    return memoryToolError(err);
+                }
+            },
+        }), { name: "clawchat_metadata_sync" });
+        api.registerTool((ctx) => ({
+            name: "clawchat_metadata_update",
+            label: "Update ClawChat Metadata",
+            description: memoryToolDescription("Update ClawChat server metadata for an explicit owner, connected user account, or group target, then refresh the local metadata block from the server response. " +
+                "Use this only when the user wants to change server-side metadata fields: current agent behavior via owner target agent_behavior, connected-user nickname/avatar_url/bio, or group group_title/group_description. " +
+                "To refresh local metadata from the server without changing the server, use clawchat_metadata_sync with direction=pull. " +
+                "This always pushes to the server first and does not modify the agent-authored body."),
+            parameters: ClawchatMetadataUpdateSchema,
+            async execute(_callId, params) {
+                const root = workspaceRoot(ctx);
+                if (!root) {
+                    return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
+                }
+                const built = buildClient();
+                if (!built.ok)
+                    return built.error;
+                try {
+                    const p = params;
+                    const targetError = validateTarget(root, p);
+                    if (targetError)
+                        return memoryToolError(new Error(targetError));
+                    const patchError = validateMetadataUpdatePatch(p);
+                    if (patchError)
+                        return validationError(patchError);
+                    const account = resolveCurrent();
+                    if (p.targetType === "owner" && !account.agentId) {
+                        return configError("clawchat-plugin-openclaw: agentId is required");
+                    }
+                    if (p.targetType === "user" && !account.userId) {
+                        return configError("clawchat-plugin-openclaw: userId is required");
+                    }
+                    return jsonResponse(await updateMetadata({
+                        memoryRoot: root,
+                        targetType: p.targetType,
+                        targetId: p.targetId,
+                        agentId: account.agentId,
+                        accountUserId: account.userId,
+                        patch: p.patch,
+                        api: built.client,
+                    }));
+                }
+                catch (err) {
+                    return memoryToolError(err);
+                }
+            },
+        }), { name: "clawchat_metadata_update" });
+    }
+    registerMemoryTools();
+    api.registerTool({
+        name: "clawchat_get_account_profile",
+        label: "Get ClawChat Account Profile",
+        description: toolDescription("Fetch the agent's connected ClawChat account profile (the configured ClawChat account: user id, nickname/display name, avatar, bio). " +
+            "This profile is the platform-side mirror of the local assistant identity; if fields are missing, report them as unset instead of inventing values. " +
+            "TRIGGER — invoke when the user asks for the ClawChat account/profile connected to this agent, " +
+            "such as 'show my ClawChat profile', 'what is the configured ClawChat account?', " +
+            "'当前 ClawChat 账号资料', or 'ClawChat 昵称头像简介'. " +
+            "Do not frame this as a human user's personal account."),
+        parameters: ClawchatGetAccountProfileSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_get_account_profile", params, async () => withClient((c) => c.getMyProfile()));
+        },
+    }, { name: "clawchat_get_account_profile" });
+    api.registerTool({
+        name: "clawchat_get_user_profile",
+        label: "Get ClawChat User Profile",
+        description: toolDescription("Fetch a ClawChat user's server-side public profile by explicit userId. " +
+            "TRIGGER — invoke when the user asks to view or inspect a specific ClawChat user's public profile and provides a concrete userId, or after clawchat_search_users returns a userId. " +
+            "Do not guess or infer userId from nickname, display name, alias, or local memory text. " +
+            "This is a read-only lookup and server lookup. It does not read local ClawChat memory files and does not update local metadata. " +
+            "When the user asks to refresh, sync, or update that user's local profile information, call clawchat_metadata_sync with targetType=user, that targetId, and direction=pull. " +
+            "Use `clawchat_get_account_profile` for the agent's own connected ClawChat account unless an explicit userId is provided."),
+        parameters: ClawchatGetUserProfileSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_get_user_profile", params, async () => {
+                const p = params;
+                return await withClient((c) => c.getUserInfo(p.userId));
+            });
+        },
+    }, { name: "clawchat_get_user_profile" });
+    api.registerTool({
+        name: "clawchat_list_account_friends",
+        label: "List ClawChat Account Friends",
+        description: toolDescription("List friends/contacts of the agent's connected ClawChat account (the configured ClawChat account). " +
+            "These are the agent's ClawChat-platform contacts. " +
+            "TRIGGER — invoke when the user asks for this ClawChat account's friends, contacts, or friend list."),
+        parameters: ClawchatListAccountFriendsSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_list_account_friends", params, async () => withClient((c) => c.listFriends()));
+        },
+    }, { name: "clawchat_list_account_friends" });
+    api.registerTool({
+        name: "clawchat_search_users",
+        label: "Search ClawChat Users",
+        description: toolDescription("Search ClawChat users by username or nickname. Search server-side ClawChat users in the ClawChat user directory. " +
+            "TRIGGER - invoke when the user asks to search, find, or look up ClawChat users in the server directory by a typed query, username, or public nickname, such as \"search ClawChat users named Alice\", \"查找用户 Alice\", or \"搜一下昵称 Alice\". " +
+            "This does not search local ClawChat memory files, aliases, known_as notes, relationship notes, group notes, or agent-authored Markdown memory. For remembered aliases, local notes, relationships, or prior ClawChat memory, use clawchat_memory_search. " +
+            "Empty q returns no users. Use this tool before fetching a public profile when the user only provides a server-side nickname or search term; do not guess a userId from query text."),
+        parameters: ClawchatSearchUsersSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_search_users", params, async () => {
+                const p = (params ?? {});
+                return await withClient((c) => c.searchUsers({
+                    ...(typeof p.q === "string" ? { q: p.q } : {}),
+                    ...(typeof p.limit === "number" ? { limit: p.limit } : {}),
+                }));
+            });
+        },
+    }, { name: "clawchat_search_users" });
+    api.registerTool({
+        name: "clawchat_get_conversation",
+        label: "Get ClawChat Conversation",
+        description: toolDescription("Fetch read-only ClawChat conversation details, including group membership when returned by the API. " +
+            "TRIGGER - invoke when the user asks to inspect a specific ClawChat conversation or group and provides a concrete conversationId. " +
+            "This is read-only and does not create, update, leave, dissolve, or administer conversations."),
+        parameters: ClawchatGetConversationSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_get_conversation", params, async () => {
+                const p = params;
+                const built = buildClient();
+                if (!built.ok)
+                    return built.error;
+                try {
+                    const data = await built.client.getConversation(p.conversationId);
+                    return jsonResponse(data);
+                }
+                catch (err) {
+                    if (err instanceof ClawlingApiError) {
+                        return apiError(err);
+                    }
+                    return genericError(err);
+                }
+            });
+        },
+    }, { name: "clawchat_get_conversation" });
+    api.registerTool({
+        name: "clawchat_mention_message",
+        label: "Send ClawChat Mention Message",
+        description: toolDescription("Send a real ClawChat mention message to a direct or group conversation. " +
+            "TRIGGER - invoke when the user asks to @, mention, notify, or address ClawChat users. " +
+            "Use `mentioned_users` or `sender_id` from current `[message]` blocks as `mentions[].userId` when present. " +
+            "Use `clawchat_search_users` only when no explicit or locally available id exists. " +
+            "Never guess userId from names, nicknames, or plain @name text. Plain @name is not a real mention. " +
+            "Pass the visible label as `mentions[].display` when known. Do not copy the visible @mention into `text`; put only the message body in `text`. If display is unknown but a concrete userId is available and a human-readable label matters, call clawchat_get_user_profile first and use the returned nickname. " +
+            "After this tool succeeds, the mention message has already been sent; output only <clawchat:no-reply/> and do not send a normal follow-up reply."),
+        parameters: ClawchatMentionMessageSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_mention_message", params, async () => {
+                const validated = validateMentionMessageParams(params);
+                if (!validated.ok)
+                    return validationError(validated.message);
+                const account = resolveCurrent();
+                if (!account.configured) {
+                    return configError("clawchat-plugin-openclaw: account is not configured");
+                }
+                try {
+                    const p = validated.params;
+                    const client = getOpenclawClawlingClient(account.accountId);
+                    if (!client) {
+                        return configError("ClawChat websocket client is not ready");
+                    }
+                    const result = await sendOpenclawClawlingMentionMessage({
+                        client,
+                        account,
+                        to: {
+                            chatId: p.chatId.trim(),
+                            chatType: p.chatType ?? "group",
+                        },
+                        ...(p.text !== undefined ? { text: p.text } : {}),
+                        mentions: p.mentions,
+                        ...(p.replyToMessageId
+                            ? {
+                                replyCtx: {
+                                    replyToMessageId: p.replyToMessageId,
+                                },
+                            }
+                            : {}),
+                        log: api.logger,
+                    });
+                    if (!result)
+                        return jsonResponse(result);
+                    markTerminalClawChatSend({
+                        accountId: account.accountId,
+                        chatId: p.chatId.trim(),
+                        messageId: result.messageId,
+                    });
+                    return jsonResponse({
+                        sent: true,
+                        terminal: true,
+                        noFollowupReply: true,
+                        instruction: "The mention message has already been sent to ClawChat. If a follow-up response is required, output only <clawchat:no-reply/> and do not send a normal follow-up reply.",
+                        ...result,
+                    });
+                }
+                catch (err) {
+                    return genericError(err);
+                }
+            });
+        },
+    }, { name: "clawchat_mention_message" });
+    api.registerTool({
+        name: "clawchat_list_moments",
+        label: "List ClawChat Moments",
+        description: toolDescription("List the configured ClawChat account's visible moments feed, including moments from the account and its friends. " +
+            "TRIGGER - invoke when the user asks to view, browse, refresh, or paginate ClawChat moments/dynamics/feed, such as \"show my ClawChat moments\", \"查看动态\", \"朋友圈动态\", or \"more moments\". " +
+            "Use before/comment/reaction/delete actions when the user needs to choose a moment id. This is a friends-only feed endpoint, not a global public timeline."),
+        parameters: ClawchatListMomentsSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_list_moments", params, async () => {
+                const p = (params ?? {});
+                return await withClient((c) => c.listMoments({
+                    ...(typeof p.before === "number" ? { before: p.before } : {}),
+                    ...(typeof p.limit === "number" ? { limit: p.limit } : {}),
+                }));
+            });
+        },
+    }, { name: "clawchat_list_moments" });
+    api.registerTool({
+        name: "clawchat_create_moment",
+        label: "Create ClawChat Moment",
+        description: toolDescription("Create a new ClawChat moment/dynamic for the configured ClawChat account. " +
+            "TRIGGER - invoke when the user asks to publish, post, or send a ClawChat moment/dynamic, such as \"post a ClawChat moment saying ...\", \"发布动态 ...\", or \"发朋友圈 ...\". " +
+            "At least one of text or images must be present. For local image files, upload first with the appropriate media upload tool and pass the returned URLs in images; do not pass local file paths as images."),
+        parameters: ClawchatCreateMomentSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_create_moment", params, async () => {
+                const p = (params ?? {});
+                const text = typeof p.text === "string" ? p.text : undefined;
+                const images = Array.isArray(p.images) ? p.images : undefined;
+                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({
+                    ...(text !== undefined ? { text } : {}),
+                    ...(images !== undefined ? { images } : {}),
+                }));
+            });
+        },
+    }, { name: "clawchat_create_moment" });
+    api.registerTool({
+        name: "clawchat_delete_moment",
+        label: "Delete ClawChat Moment",
+        description: toolDescription("Delete a ClawChat moment by moment id. " +
+            "TRIGGER - invoke when the user asks to delete/remove one of the configured account's ClawChat moments/dynamics and provides or selects a concrete moment id. " +
+            "Only the moment author can delete it. Do not guess the id; list moments first if the user refers to a moment ambiguously."),
+        parameters: ClawchatDeleteMomentSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_delete_moment", params, async () => {
+                const p = params;
+                return await withClient((c) => c.deleteMoment(p.momentId));
+            });
+        },
+    }, { name: "clawchat_delete_moment" });
+    api.registerTool({
+        name: "clawchat_toggle_moment_reaction",
+        label: "Toggle ClawChat Moment Reaction",
+        description: toolDescription("Toggle an emoji reaction on a ClawChat moment. " +
+            "TRIGGER - invoke when the user asks to react, like, unlike, emoji-react, or remove the same emoji reaction on a specific ClawChat moment, such as \"like moment 123 with 👍\", \"给动态 123 点赞\", or \"取消这个 👍 反应\". " +
+            "The API adds the reaction if missing and removes it if already present. Require a concrete moment id and emoji."),
+        parameters: ClawchatToggleMomentReactionSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_toggle_moment_reaction", params, async () => {
+                const p = params;
+                if (!p.emoji?.trim()) {
+                    return validationError("clawchat-plugin-openclaw: emoji is required");
+                }
+                return await withClient((c) => c.toggleMomentReaction({ momentId: p.momentId, emoji: p.emoji }));
+            });
+        },
+    }, { name: "clawchat_toggle_moment_reaction" });
+    api.registerTool({
+        name: "clawchat_create_moment_comment",
+        label: "Create ClawChat Moment Comment",
+        description: toolDescription("Create a top-level comment on a ClawChat moment. " +
+            "TRIGGER - invoke when the user asks to comment/reply directly to a moment/dynamic, not to another comment, such as \"comment on moment 123: ...\", \"评论动态 123 ...\", or \"在这条动态下留言 ...\". " +
+            "Require a concrete moment id and non-empty text. Use clawchat_reply_moment_comment when the user is replying to another user's comment."),
+        parameters: ClawchatCreateMomentCommentSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_create_moment_comment", params, async () => {
+                const p = params;
+                if (!p.text?.trim()) {
+                    return validationError("clawchat-plugin-openclaw: text is required");
+                }
+                return await withClient((c) => c.createMomentComment({ momentId: p.momentId, text: p.text }));
+            });
+        },
+    }, { name: "clawchat_create_moment_comment" });
+    api.registerTool({
+        name: "clawchat_reply_moment_comment",
+        label: "Reply To ClawChat Moment Comment",
+        description: toolDescription("Reply to an existing ClawChat moment comment with a single-level reply. " +
+            "TRIGGER - invoke when the user asks to reply to another user's comment on a moment/dynamic, such as \"reply to comment 456 on moment 123: ...\", \"回复评论 456 ...\", or \"回复他那条评论 ...\". " +
+            "Require concrete moment and comment ids; do not use this for top-level comments."),
+        parameters: ClawchatReplyMomentCommentSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_reply_moment_comment", params, async () => {
+                const p = params;
+                if (!p.text?.trim()) {
+                    return validationError("clawchat-plugin-openclaw: text is required");
+                }
+                return await withClient((c) => c.replyMomentComment({
+                    momentId: p.momentId,
+                    replyToCommentId: p.replyToCommentId,
+                    text: p.text,
+                }));
+            });
+        },
+    }, { name: "clawchat_reply_moment_comment" });
+    api.registerTool({
+        name: "clawchat_delete_moment_comment",
+        label: "Delete ClawChat Moment Comment",
+        description: toolDescription("Delete a comment on a ClawChat moment. " +
+            "TRIGGER - invoke when the user asks to delete/remove a specific comment or reply from a ClawChat moment/dynamic and provides concrete moment and comment ids. " +
+            "The caller may delete comments they authored or comments on moments they authored. Do not guess ids; list moments first if needed."),
+        parameters: ClawchatDeleteMomentCommentSchema,
+        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 }));
+            });
+        },
+    }, { name: "clawchat_delete_moment_comment" });
+    api.registerTool({
+        name: "clawchat_update_account_profile",
+        label: "Update ClawChat Account Profile",
+        description: toolDescription("Update nickname/avatar_url/bio on the agent's connected ClawChat account (the configured ClawChat account), which mirrors the local assistant identity. " +
+            "TRIGGER — invoke this tool whenever the user's message asks to change the ClawChat account profile or local assistant name/profile while ClawChat is connected: " +
+            "(1) ClawChat account nickname/name change: 'change the ClawChat account nickname to X', " +
+            "'set this assistant name to X', 'ClawChat 昵称改为 X', '账号昵称改成 X', '账号名字叫 X' " +
+            "→ call with `nickname = X`; " +
+            "(2) ClawChat account avatar/profile-picture change: 'change the ClawChat account avatar', " +
+            "'use this image as the assistant profile picture', 'ClawChat 头像改为 …', '账号头像换成 …' " +
+            "→ first obtain the avatar URL (upload via `clawchat_upload_avatar_image`, OR use a provided URL directly), " +
+            "then call this tool with `avatar_url = <url>`; " +
+            "(3) ClawChat account bio/self-introduction change: 'update the ClawChat bio', " +
+            "'set the assistant self-introduction to X', 'ClawChat 简介改成 X', '账号简介改为 X', '个人简介改为 X' " +
+            "→ call with `bio = X`. " +
+            "You can pass `nickname`, `avatar_url`, and `bio` together in one call, or just one of them. " +
+            "At least one of the three must be present. Do not frame this as updating a human user's personal account."),
+        parameters: ClawchatUpdateAccountProfileSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_update_account_profile", params, async () => {
+                const p = (params ?? {});
+                const patch = {};
+                if (typeof p.nickname === "string")
+                    patch.nickname = p.nickname;
+                if (typeof p.avatar_url === "string")
+                    patch.avatar_url = p.avatar_url;
+                if (typeof p.bio === "string")
+                    patch.bio = p.bio;
+                if (Object.keys(patch).length === 0) {
+                    return validationError("clawchat-plugin-openclaw: at least one of nickname / avatar / bio is required");
+                }
+                return await withClient((c) => c.updateMyProfile(patch));
+            });
+        },
+    }, { name: "clawchat_update_account_profile" });
+    api.registerTool({
+        name: "clawchat_upload_avatar_image",
+        label: "Upload ClawChat Avatar Image",
+        description: toolDescription("Upload an absolute local image path for use as the agent's connected ClawChat account avatar (max 20MB), returning a hosted avatar URL. " +
+            "TRIGGER — invoke when the user provides an absolute local image path and asks to upload it for the ClawChat account avatar/profile picture. " +
+            "This tool does not update or set the account avatar by itself; when the user asked to set or sync the avatar, call `clawchat_update_account_profile` with `avatar_url` after this tool returns a URL."),
+        parameters: ClawchatUploadAvatarImageSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_upload_avatar_image", params, async () => {
+                const p = params;
+                if (!p.filePath || !path.isAbsolute(p.filePath)) {
+                    return validationError("clawchat-plugin-openclaw: filePath must be an absolute local path");
+                }
+                let stat;
+                try {
+                    stat = fs.statSync(p.filePath);
+                }
+                catch (err) {
+                    return validationError(`clawchat-plugin-openclaw: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (!stat.isFile()) {
+                    return validationError(`clawchat-plugin-openclaw: ${p.filePath} is not a regular file`);
+                }
+                if (stat.size > MAX_UPLOAD_BYTES) {
+                    return validationError(`clawchat-plugin-openclaw: file too large (${stat.size} bytes; max 20MB)`);
+                }
+                const buffer = fs.readFileSync(p.filePath);
+                const filename = path.basename(p.filePath);
+                const mime = inferMimeFromPath(p.filePath);
+                return await withClient((c) => c.uploadAvatar({ buffer, filename, mime }));
+            });
+        },
+    }, { name: "clawchat_upload_avatar_image" });
+    api.registerTool({
+        name: "clawchat_upload_media_file",
+        label: "Upload ClawChat Media File",
+        description: toolDescription("Upload an absolute local file/media path to ClawChat media storage (max 20MB) and return a ClawChat-accessible public/shareable URL. " +
+            "TRIGGER — invoke when the user provides an absolute local file path and asks to upload, share, or create a ClawChat-accessible link for that file. " +
+            "Do not use this tool to send an attachment in the current chat; use the current runtime's native media-send mechanism instead (for example, MEDIA:/absolute/local/path where supported). " +
+            "Do not use this for account avatar changes; use `clawchat_upload_avatar_image` for avatar images. Do not use this just to mirror local assistant identity."),
+        parameters: ClawchatUploadMediaFileSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_upload_media_file", params, async () => {
+                const p = params;
+                if (!p.filePath || !path.isAbsolute(p.filePath)) {
+                    return validationError("clawchat-plugin-openclaw: filePath must be an absolute local path");
+                }
+                let stat;
+                try {
+                    stat = fs.statSync(p.filePath);
+                }
+                catch (err) {
+                    return validationError(`clawchat-plugin-openclaw: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (!stat.isFile()) {
+                    return validationError(`clawchat-plugin-openclaw: ${p.filePath} is not a regular file`);
+                }
+                if (stat.size > MAX_UPLOAD_BYTES) {
+                    return validationError(`clawchat-plugin-openclaw: file too large (${stat.size} bytes; max 20MB)`);
+                }
+                const buffer = fs.readFileSync(p.filePath);
+                const filename = path.basename(p.filePath);
+                const mime = inferMimeFromPath(p.filePath);
+                return await withClient((c) => c.uploadMedia({ buffer, filename, mime }));
+            });
+        },
+    }, { name: "clawchat_upload_media_file" });
+    api.logger.debug?.("clawchat-plugin-openclaw: registered 22 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, search_users, get_conversation, mention_message, list_moments, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, upload_media_file, memory_search, memory_read, memory_write, memory_edit, metadata_sync, metadata_update)");
+}