@newbase-clawchat/openclaw-clawchat 2026.5.12-2 → 2026.5.12-21

package/dist/src/tools.js

@@ -1,9 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
-import { ClawlingApiError } from "./api-types.js";
+import { ClawlingApiError, } from "./api-types.js";
 import { resolveOpenclawClawlingAccount } from "./config.js";
-import { ClawchatGetAccountProfileSchema, ClawchatGetUserProfileSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListMomentsSchema, ClawchatReplyMomentCommentSchema, ClawchatSearchUsersSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatUploadMediaFileSchema, } from "./tools-schema.js";
+import { clawChatDbPathForStateDir, getClawChatStore, } from "./storage.js";
+import { editClawChatMemoryBody, readClawChatMemoryFile, resolveClawChatMemoryPath, writeClawChatMemoryBody, } from "./clawchat-memory.js";
+import { pullGroupMetadata, pullOwnerMetadata, pullUserMetadata, pushMetadata, updateMetadata, } from "./clawchat-metadata.js";
+import { ClawchatGetAccountProfileSchema, ClawchatGetConversationSchema, ClawchatGetUserProfileSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListConversationsSchema, ClawchatListMomentsSchema, ClawchatReplyMomentCommentSchema, ClawchatSearchUsersSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatUploadMediaFileSchema, } from "./tools-schema.js";
 const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
 function jsonResponse(data) {
     return {
@@ -53,14 +56,62 @@ const MIME_BY_EXT = {
     ".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";
 }
-export function registerOpenclawClawlingTools(api) {
+function parseTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function upsertConversationSummaryCache(store, accountId, conversation) {
+    if (!store?.upsertConversationSummary)
+        return;
+    store.upsertConversationSummary({
+        platform: "openclaw",
+        accountId,
+        conversationId: conversation.id,
+        conversationType: conversation.type,
+        lastSeenAt: parseTimestamp(conversation.updated_at),
+        lastRefreshedAt: Date.now(),
+        raw: conversation,
+    });
+}
+function upsertConversationDetailsCache(store, accountId, conversation) {
+    if (!store?.upsertConversationDetails)
+        return;
+    const refreshedAt = Date.now();
+    store.upsertConversationDetails({
+        platform: "openclaw",
+        accountId,
+        conversationId: conversation.id,
+        conversationType: conversation.type,
+        lastSeenAt: parseTimestamp(conversation.updated_at),
+        lastRefreshedAt: refreshedAt,
+        raw: conversation,
+        members: conversation.participants.map((participant) => ({
+            userId: participant.user_id,
+            role: participant.role,
+            raw: participant,
+            lastSeenAt: parseTimestamp(participant.joined_at),
+        })),
+        membersComplete: true,
+    });
+}
+function isConversationNotFound(err) {
+    return err.meta?.status === 404 || err.meta?.code === 404 || err.meta?.code === 40401;
+}
+export function registerOpenclawClawlingTools(api, options = {}) {
     if (!api.config) {
         api.logger.debug?.("openclaw-clawchat: api.config missing; skipping tool registration");
         return;
@@ -69,6 +120,81 @@ export function registerOpenclawClawlingTools(api) {
     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?.("openclaw-clawchat 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?.("openclaw-clawchat sqlite tool call insert failed; continuing");
+        }
+    }
+    function persistConversationCache(fn) {
+        try {
+            const store = resolveStore();
+            if (store)
+                fn(store);
+        }
+        catch {
+            api.logger.error?.("openclaw-clawchat sqlite conversation cache update 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
@@ -102,6 +228,287 @@ export function registerOpenclawClawlingTools(api) {
             }
         })();
     }
+    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 ["title", "description"];
+        if (targetType === "owner")
+            return ["nickname", "avatar_url", "bio", "behavior"];
+        return ["nickname", "avatar_url", "bio"];
+    }
+    function validateMetadataUpdatePatch(params) {
+        const patch = params.patch;
+        if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+            return "openclaw-clawchat: metadata patch is required";
+        }
+        const keys = Object.keys(patch);
+        if (keys.length === 0) {
+            return "openclaw-clawchat: 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 `openclaw-clawchat: metadata patch contains unsupported field(s): ${invalid.join(", ")}`;
+        }
+        const nonString = keys.filter((key) => typeof patch[key] !== "string");
+        if (nonString.length > 0) {
+            return `openclaw-clawchat: 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("openclaw-clawchat: unsafe ClawChat memory target");
+        }
+        return validationError(message);
+    }
+    function registerMemoryTools() {
+        api.registerTool((ctx) => ({
+            name: "clawchat_memory_read",
+            label: "Read ClawChat Memory",
+            description: memoryToolDescription("Read a ClawChat memory Markdown file by explicit targetType and targetId. " +
+                "Use this when you need existing owner, user, or group memory content. " +
+                "Do not guess ids from names. " +
+                "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("openclaw-clawchat: 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 nickname, avatar_url, bio, profile_type, title, description, or behavior. " +
+                "When the user asks to refresh, sync, or update local ClawChat owner/user/group profile information, use clawchat_metadata_sync with direction=pull instead. " +
+                "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("openclaw-clawchat: 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 nickname, avatar_url, bio, profile_type, title, description, or behavior. " +
+                "Use clawchat_metadata_sync or clawchat_metadata_update for metadata. " +
+                "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("openclaw-clawchat: 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 profile information, user information, group information, or owner behavior 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. " +
+                "This does not modify the agent-authored body. " +
+                "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("openclaw-clawchat: 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("openclaw-clawchat: fields are required for metadata push");
+                        }
+                        if (p.targetType === "owner" && !account.agentId) {
+                            return configError("openclaw-clawchat: agentId is required");
+                        }
+                        if (p.targetType === "user" && !account.userId) {
+                            return configError("openclaw-clawchat: 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("openclaw-clawchat: 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 }));
+                }
+                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. " +
+                "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("openclaw-clawchat: 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("openclaw-clawchat: agentId is required");
+                    }
+                    if (p.targetType === "user" && !account.userId) {
+                        return configError("openclaw-clawchat: 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",
@@ -112,8 +519,8 @@ export function registerOpenclawClawlingTools(api) {
             "'当前 ClawChat 账号资料', or 'ClawChat 昵称头像简介'. " +
             "Do not frame this as a human user's personal account."),
         parameters: ClawchatGetAccountProfileSchema,
-        async execute(_callId, _params) {
-            return await withClient((c) => c.getMyProfile());
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_get_account_profile", params, async () => withClient((c) => c.getMyProfile()));
         },
     }, { name: "clawchat_get_account_profile" });
     api.registerTool({
@@ -122,26 +529,26 @@ export function registerOpenclawClawlingTools(api) {
         description: toolDescription("Fetch a ClawChat user's public profile by userId. " +
             "TRIGGER — invoke when the user asks to look up, view, or inspect a specific ClawChat user's public profile " +
             "and provides a concrete userId. Do not guess or infer userId from a nickname/display name. " +
+            "This is a read-only lookup and does not update local ClawChat Memory files. " +
+            "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) {
-            const p = params;
-            return await withClient((c) => c.getUserInfo(p.userId));
+            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), paginated (page=1, pageSize=20 by default). " +
+        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, friend list, or asks to show more friends with pagination."),
+            "TRIGGER — invoke when the user asks for this ClawChat account's friends, contacts, or friend list."),
         parameters: ClawchatListAccountFriendsSchema,
         async execute(_callId, params) {
-            const p = (params ?? {});
-            return await withClient((c) => c.listFriends({
-                ...(p.page !== undefined ? { page: p.page } : { page: 1 }),
-                ...(p.pageSize !== undefined ? { pageSize: p.pageSize } : { pageSize: 20 }),
-            }));
+            return await recordClawchatToolCall("clawchat_list_account_friends", params, async () => withClient((c) => c.listFriends()));
         },
     }, { name: "clawchat_list_account_friends" });
     api.registerTool({
@@ -152,13 +559,74 @@ export function registerOpenclawClawlingTools(api) {
             "Empty q returns no users. Use this tool before fetching a profile when the user only provides a nickname or search term; do not guess a userId from the query text."),
         parameters: ClawchatSearchUsersSchema,
         async execute(_callId, params) {
-            const p = (params ?? {});
-            return await withClient((c) => c.searchUsers({
-                ...(typeof p.q === "string" ? { q: p.q } : {}),
-                ...(typeof p.limit === "number" ? { limit: p.limit } : {}),
-            }));
+            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_list_conversations",
+        label: "List ClawChat Conversations",
+        description: toolDescription("List ClawChat direct and group conversations visible to the configured account. " +
+            "TRIGGER - invoke when the user asks to list, browse, inspect, or paginate ClawChat conversations, chats, groups, or direct messages. " +
+            "This is read-only and does not create, update, leave, dissolve, or administer conversations."),
+        parameters: ClawchatListConversationsSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_list_conversations", params, async () => {
+                const p = (params ?? {});
+                const account = resolveCurrent();
+                return await withClient(async (c) => {
+                    const data = await c.listConversations({
+                        ...(typeof p.before === "string" ? { before: p.before } : {}),
+                        ...(typeof p.limit === "number" ? { limit: p.limit } : {}),
+                    });
+                    for (const conversation of data.conversations) {
+                        persistConversationCache((store) => upsertConversationSummaryCache(store, account.accountId, conversation));
+                    }
+                    return data;
+                });
+            });
+        },
+    }, { name: "clawchat_list_conversations" });
+    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 account = resolveCurrent();
+                const built = buildClient();
+                if (!built.ok)
+                    return built.error;
+                try {
+                    const data = await built.client.getConversation(p.conversationId);
+                    persistConversationCache((store) => upsertConversationDetailsCache(store, account.accountId, data.conversation));
+                    return jsonResponse(data);
+                }
+                catch (err) {
+                    if (err instanceof ClawlingApiError) {
+                        if (isConversationNotFound(err)) {
+                            persistConversationCache((store) => store.deleteConversationCache?.({
+                                platform: "openclaw",
+                                accountId: account.accountId,
+                                conversationId: p.conversationId,
+                            }));
+                        }
+                        return apiError(err);
+                    }
+                    return genericError(err);
+                }
+            });
+        },
+    }, { name: "clawchat_get_conversation" });
     api.registerTool({
         name: "clawchat_list_moments",
         label: "List ClawChat Moments",
@@ -167,11 +635,13 @@ export function registerOpenclawClawlingTools(api) {
             "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) {
-            const p = (params ?? {});
-            return await withClient((c) => c.listMoments({
-                ...(typeof p.before === "number" ? { before: p.before } : {}),
-                ...(typeof p.limit === "number" ? { limit: p.limit } : {}),
-            }));
+            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({
@@ -182,16 +652,18 @@ export function registerOpenclawClawlingTools(api) {
             "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) {
-            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("openclaw-clawchat: at least one of text or images is required");
-            }
-            return await withClient((c) => c.createMoment({
-                ...(text !== undefined ? { text } : {}),
-                ...(images !== undefined ? { images } : {}),
-            }));
+            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("openclaw-clawchat: 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({
@@ -202,8 +674,10 @@ export function registerOpenclawClawlingTools(api) {
             "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) {
-            const p = params;
-            return await withClient((c) => c.deleteMoment(p.momentId));
+            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({
@@ -214,11 +688,13 @@ export function registerOpenclawClawlingTools(api) {
             "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) {
-            const p = params;
-            if (!p.emoji?.trim()) {
-                return validationError("openclaw-clawchat: emoji is required");
-            }
-            return await withClient((c) => c.toggleMomentReaction({ momentId: p.momentId, emoji: p.emoji }));
+            return await recordClawchatToolCall("clawchat_toggle_moment_reaction", params, async () => {
+                const p = params;
+                if (!p.emoji?.trim()) {
+                    return validationError("openclaw-clawchat: emoji is required");
+                }
+                return await withClient((c) => c.toggleMomentReaction({ momentId: p.momentId, emoji: p.emoji }));
+            });
         },
     }, { name: "clawchat_toggle_moment_reaction" });
     api.registerTool({
@@ -229,11 +705,13 @@ export function registerOpenclawClawlingTools(api) {
             "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) {
-            const p = params;
-            if (!p.text?.trim()) {
-                return validationError("openclaw-clawchat: text is required");
-            }
-            return await withClient((c) => c.createMomentComment({ momentId: p.momentId, text: p.text }));
+            return await recordClawchatToolCall("clawchat_create_moment_comment", params, async () => {
+                const p = params;
+                if (!p.text?.trim()) {
+                    return validationError("openclaw-clawchat: text is required");
+                }
+                return await withClient((c) => c.createMomentComment({ momentId: p.momentId, text: p.text }));
+            });
         },
     }, { name: "clawchat_create_moment_comment" });
     api.registerTool({
@@ -244,15 +722,17 @@ export function registerOpenclawClawlingTools(api) {
             "Require concrete moment and comment ids; do not use this for top-level comments."),
         parameters: ClawchatReplyMomentCommentSchema,
         async execute(_callId, params) {
-            const p = params;
-            if (!p.text?.trim()) {
-                return validationError("openclaw-clawchat: text is required");
-            }
-            return await withClient((c) => c.replyMomentComment({
-                momentId: p.momentId,
-                replyToCommentId: p.replyToCommentId,
-                text: p.text,
-            }));
+            return await recordClawchatToolCall("clawchat_reply_moment_comment", params, async () => {
+                const p = params;
+                if (!p.text?.trim()) {
+                    return validationError("openclaw-clawchat: 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({
@@ -263,8 +743,10 @@ export function registerOpenclawClawlingTools(api) {
             "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) {
-            const p = params;
-            return await withClient((c) => c.deleteMomentComment({ momentId: p.momentId, commentId: p.commentId }));
+            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({
@@ -286,18 +768,20 @@ export function registerOpenclawClawlingTools(api) {
             "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) {
-            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("openclaw-clawchat: at least one of nickname / avatar / bio is required");
-            }
-            return await withClient((c) => c.updateMyProfile(patch));
+            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("openclaw-clawchat: at least one of nickname / avatar / bio is required");
+                }
+                return await withClient((c) => c.updateMyProfile(patch));
+            });
         },
     }, { name: "clawchat_update_account_profile" });
     api.registerTool({
@@ -308,27 +792,29 @@ export function registerOpenclawClawlingTools(api) {
             "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) {
-            const p = params;
-            if (!p.filePath || !path.isAbsolute(p.filePath)) {
-                return validationError("openclaw-clawchat: filePath must be an absolute local path");
-            }
-            let stat;
-            try {
-                stat = fs.statSync(p.filePath);
-            }
-            catch (err) {
-                return validationError(`openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            if (!stat.isFile()) {
-                return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
-            }
-            if (stat.size > MAX_UPLOAD_BYTES) {
-                return validationError(`openclaw-clawchat: 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 }));
+            return await recordClawchatToolCall("clawchat_upload_avatar_image", params, async () => {
+                const p = params;
+                if (!p.filePath || !path.isAbsolute(p.filePath)) {
+                    return validationError("openclaw-clawchat: filePath must be an absolute local path");
+                }
+                let stat;
+                try {
+                    stat = fs.statSync(p.filePath);
+                }
+                catch (err) {
+                    return validationError(`openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (!stat.isFile()) {
+                    return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
+                }
+                if (stat.size > MAX_UPLOAD_BYTES) {
+                    return validationError(`openclaw-clawchat: 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({
@@ -340,28 +826,30 @@ export function registerOpenclawClawlingTools(api) {
             "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) {
-            const p = params;
-            if (!p.filePath || !path.isAbsolute(p.filePath)) {
-                return validationError("openclaw-clawchat: filePath must be an absolute local path");
-            }
-            let stat;
-            try {
-                stat = fs.statSync(p.filePath);
-            }
-            catch (err) {
-                return validationError(`openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            if (!stat.isFile()) {
-                return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
-            }
-            if (stat.size > MAX_UPLOAD_BYTES) {
-                return validationError(`openclaw-clawchat: 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 }));
+            return await recordClawchatToolCall("clawchat_upload_media_file", params, async () => {
+                const p = params;
+                if (!p.filePath || !path.isAbsolute(p.filePath)) {
+                    return validationError("openclaw-clawchat: filePath must be an absolute local path");
+                }
+                let stat;
+                try {
+                    stat = fs.statSync(p.filePath);
+                }
+                catch (err) {
+                    return validationError(`openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (!stat.isFile()) {
+                    return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
+                }
+                if (stat.size > MAX_UPLOAD_BYTES) {
+                    return validationError(`openclaw-clawchat: 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?.("openclaw-clawchat: registered 14 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, search_users, 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)");
+    api.logger.debug?.("openclaw-clawchat: registered 21 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, search_users, list_conversations, get_conversation, 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_read, memory_write, memory_edit, metadata_sync, metadata_update)");
 }