@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/tools.test.ts

@@ -0,0 +1,933 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { EventEmitter } from "node:events";
+import { Value } from "@sinclair/typebox/value";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { registerOpenclawClawlingTools } from "./tools.ts";
+import * as toolSchemas from "./tools-schema.ts";
+import * as runtime from "./runtime.ts";
+import {
+  clearTerminalClawChatSendsForTest,
+  consumeTerminalClawChatSend,
+  runWithTerminalClawChatSendScope,
+} from "./terminal-send.ts";
+
+const schemas = toolSchemas as Record<string, unknown>;
+
+interface RegisteredTool {
+  name: string;
+  description?: string;
+  parameters?: unknown;
+  execute: (callId: string, params: unknown) => Promise<unknown>;
+}
+
+const ALWAYS_VISIBLE_TOOL_NAMES = [
+  "clawchat_create_moment",
+  "clawchat_create_moment_comment",
+  "clawchat_delete_moment",
+  "clawchat_delete_moment_comment",
+  "clawchat_get_account_profile",
+  "clawchat_get_conversation",
+  "clawchat_get_user_profile",
+  "clawchat_list_account_friends",
+  "clawchat_list_moments",
+  "clawchat_memory_edit",
+  "clawchat_memory_read",
+  "clawchat_memory_search",
+  "clawchat_memory_write",
+  "clawchat_mention_message",
+  "clawchat_metadata_sync",
+  "clawchat_metadata_update",
+  "clawchat_reply_moment_comment",
+  "clawchat_search_users",
+  "clawchat_toggle_moment_reaction",
+  "clawchat_update_account_profile",
+  "clawchat_upload_avatar_image",
+  "clawchat_upload_media_file",
+];
+
+const tempRoots: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempRoots.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  vi.restoreAllMocks();
+  clearTerminalClawChatSendsForTest();
+});
+
+function mockMentionClient() {
+  let trace = 0;
+  const sent: Array<{ event: string; trace_id: string; payload: { message_id?: string } }> = [];
+  const client = Object.assign(new EventEmitter(), {
+    sent,
+    state: "connected",
+    nextTraceId: vi.fn(() => `trace-${++trace}`),
+    sendWire: vi.fn((wire: string) => {
+      const env = JSON.parse(wire) as {
+        event: string;
+        trace_id: string;
+        payload: { message_id?: string };
+      };
+      sent.push(env);
+      queueMicrotask(() => {
+        client.emit("raw", {
+          version: "2",
+          event: "message.ack",
+          trace_id: env.trace_id,
+          emitted_at: Date.now(),
+          payload: {
+            message_id: env.payload.message_id ?? "msg-mention",
+            accepted_at: 1234,
+          },
+        });
+      });
+    }),
+    typing: vi.fn(),
+    emitRaw: vi.fn(),
+    sendRawEnvelope: vi.fn(),
+  });
+  Object.defineProperty(client, "transportState", { get: () => "open" });
+  return client;
+}
+
+function buildApi(opts: {
+  configChannel?: Record<string, unknown> | null;
+  configTools?: Record<string, unknown>;
+  workspaceDir?: string;
+  registerTool?: (tool: { name: string }, options?: { name: string }) => void;
+}) {
+  const registered: RegisteredTool[] = [];
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "clawchat-plugin-openclaw-tools-"));
+  const workspaceDir =
+    opts.workspaceDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "clawchat-plugin-openclaw-workspace-"));
+  tempRoots.push(stateDir);
+  tempRoots.push(workspaceDir);
+  const api = {
+    config:
+      opts.configChannel === null
+        ? undefined
+        : {
+            channels: { "clawchat-plugin-openclaw": opts.configChannel ?? {} },
+            ...(opts.configTools ? { tools: opts.configTools } : {}),
+          },
+    logger: {
+      info: vi.fn(),
+      debug: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+    runtime: {
+      state: {
+        resolveStateDir: () => stateDir,
+      },
+      config: {
+        mutateConfigFile: vi.fn(),
+      },
+    },
+    registerTool: (tool: RegisteredTool | ((ctx: unknown) => RegisteredTool | RegisteredTool[] | null | undefined), _options?: { name: string }) => {
+      const resolved =
+        typeof tool === "function"
+          ? tool({
+              workspaceDir,
+              agentId: "agent-default",
+              runtimeConfig: {
+                channels: { "clawchat-plugin-openclaw": opts.configChannel ?? {} },
+              },
+              getRuntimeConfig: () => ({
+                channels: { "clawchat-plugin-openclaw": opts.configChannel ?? {} },
+              }),
+            })
+          : tool;
+      if (Array.isArray(resolved)) {
+        registered.push(...resolved);
+      } else if (resolved) {
+        registered.push(resolved);
+      }
+    },
+  } as unknown as Parameters<typeof registerOpenclawClawlingTools>[0];
+  return { api, registered };
+}
+
+function configuredChannel(extra: Record<string, unknown> = {}) {
+  return {
+    websocketUrl: "wss://w",
+    token: "tk",
+    agentId: "agt-1",
+    userId: "u",
+    ownerUserId: "owner-u",
+    ...extra,
+  };
+}
+
+describe("registerOpenclawClawlingTools", () => {
+  it("uses OpenClaw SDK tool result types instead of direct pi-agent-core imports", () => {
+    const source = fs.readFileSync(new URL("./tools.ts", import.meta.url), "utf8");
+    expect(source).not.toMatch(/@mariozechner\/pi-agent-core/);
+    expect(source).toMatch(/openclaw\/plugin-sdk\/agent-harness-runtime/);
+  });
+
+  it("registers all ClawChat tools even when account.configured is false", () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+    });
+    registerOpenclawClawlingTools(api);
+    expect(registered.map((t) => t.name).sort()).toEqual(ALWAYS_VISIBLE_TOOL_NAMES);
+  });
+
+  it("does not mutate tool policy during registration before account activation", () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+      configTools: { profile: "coding", allow: [] },
+    });
+
+    registerOpenclawClawlingTools(api);
+
+    expect(registered.map((t) => t.name).sort()).toEqual(ALWAYS_VISIBLE_TOOL_NAMES);
+    expect(api.config?.tools).toEqual({
+      profile: "coding",
+      allow: [],
+    });
+  });
+
+  it("does not register invite-code activation as an agent tool", () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+    });
+
+    registerOpenclawClawlingTools(api);
+
+    expect(registered.some((t) => t.name === "clawchat_activate")).toBe(false);
+  });
+
+  it("registers only read-only conversation tools", () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel(),
+    });
+
+    registerOpenclawClawlingTools(api);
+
+    const names = registered.map((t) => t.name);
+    expect(names).toContain("clawchat_get_conversation");
+    expect(names).not.toContain("clawchat_create_group_conversation");
+    expect(names).not.toContain("clawchat_update_conversation");
+    expect(names).not.toContain("clawchat_leave_conversation");
+    expect(names).not.toContain("clawchat_dissolve_conversation");
+    expect(names).not.toContain("clawchat_add_conversation_member");
+    expect(names).not.toContain("clawchat_remove_conversation_member");
+    expect(names).not.toContain("clawchat_list_conversation_users");
+  });
+
+  it("skips registration when api.config is undefined", () => {
+    const { api, registered } = buildApi({ configChannel: null });
+    registerOpenclawClawlingTools(api);
+    expect(registered).toHaveLength(0);
+  });
+
+  it("registers all account/media/search/moment ClawChat tools when configured (regardless of baseUrl)", () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel(/* no baseUrl */),
+    });
+    registerOpenclawClawlingTools(api);
+    const names = registered.map((t) => t.name).sort();
+    expect(names).toEqual(ALWAYS_VISIBLE_TOOL_NAMES);
+  });
+
+  it("logs configured tool registration at debug level only", () => {
+    const { api } = buildApi({
+      configChannel: configuredChannel(),
+    });
+    const logger = api.logger as {
+      info: ReturnType<typeof vi.fn>;
+      debug: ReturnType<typeof vi.fn>;
+    };
+
+    registerOpenclawClawlingTools(api);
+
+    expect(logger.info).not.toHaveBeenCalled();
+    expect(logger.debug).toHaveBeenCalledWith(
+      "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)",
+    );
+  });
+
+  it("registers clawchat_mention_message with mention target schema", () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel(),
+    });
+
+    registerOpenclawClawlingTools(api);
+
+    const mention = registered.find((t) => t.name === "clawchat_mention_message");
+    expect(mention).toBeDefined();
+    expect(mention?.description).toMatch(/@|mention|notify|address/i);
+    expect(mention?.description).toContain("Use `mentioned_users` or `sender_id` from current `[message]` blocks as `mentions[].userId`");
+    expect(mention?.description).toContain("Do not copy the visible @mention into `text`; put only the message body in `text`");
+    const parameters = mention?.parameters as { properties?: Record<string, unknown> } | undefined;
+    const properties = parameters?.properties ?? {};
+    expect(properties).toHaveProperty("mentions");
+    expect(JSON.stringify(properties.mentions)).toMatch(/userId/);
+  });
+
+  it("registers exactly the six ClawChat memory and metadata tools without old-prefix aliases", () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel({ ownerUserId: "owner" }),
+    });
+
+    registerOpenclawClawlingTools(api);
+
+    const names = registered.map((t) => t.name).sort();
+    expect(names.filter((name) => /memory|metadata/.test(name))).toEqual([
+      "clawchat_memory_edit",
+      "clawchat_memory_read",
+      "clawchat_memory_search",
+      "clawchat_memory_write",
+      "clawchat_metadata_sync",
+      "clawchat_metadata_update",
+    ]);
+    expect(names).not.toContain("cc_memory_read");
+    expect(names).not.toContain("cc_metadata_sync");
+  });
+
+  it("keeps old ClawChat tools registered and guarded against direct HTTP or shell fallbacks", () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel({ ownerUserId: "owner" }),
+    });
+
+    registerOpenclawClawlingTools(api);
+
+    const oldTools = registered.filter((tool) => !/memory|metadata/.test(tool.name));
+    expect(oldTools.map((tool) => tool.name).sort()).toEqual(
+      ALWAYS_VISIBLE_TOOL_NAMES.filter((name) => !/memory|metadata/.test(name)),
+    );
+    for (const tool of oldTools) {
+      expect(tool.description).toMatch(/Do not use execute/);
+      expect(tool.description).toMatch(/shell commands/);
+      expect(tool.description).toMatch(/curl/);
+      expect(tool.description).toMatch(/direct ClawChat HTTP calls/);
+      expect(tool.description).toMatch(/generic fallback tools/);
+    }
+  });
+
+  it("memory and metadata schemas require explicit targets and bounded modes", () => {
+    const readSchema = schemas.ClawchatMemoryReadSchema;
+    const searchSchema = schemas.ClawchatMemorySearchSchema;
+    const writeSchema = schemas.ClawchatMemoryWriteSchema;
+    const editSchema = schemas.ClawchatMemoryEditSchema;
+    const syncSchema = schemas.ClawchatMetadataSyncSchema;
+    const updateSchema = schemas.ClawchatMetadataUpdateSchema;
+    expect(readSchema).toBeDefined();
+    expect(searchSchema).toBeDefined();
+    expect(writeSchema).toBeDefined();
+    expect(editSchema).toBeDefined();
+    expect(syncSchema).toBeDefined();
+    expect(updateSchema).toBeDefined();
+
+    for (const schema of [searchSchema, readSchema, writeSchema, editSchema, syncSchema, updateSchema]) {
+      expect((schema as { type?: unknown }).type).toBe("object");
+      expect(schema).not.toHaveProperty("anyOf");
+      expect(schema).not.toHaveProperty("oneOf");
+    }
+    expect(Value.Check(searchSchema, { query: "才哥" })).toBe(true);
+    expect(Value.Check(searchSchema, { query: "才哥", targetTypes: ["user"], maxResults: 5 })).toBe(true);
+    expect(Value.Check(searchSchema, { query: "" })).toBe(false);
+    expect(Value.Check(searchSchema, { query: "才哥", targetTypes: ["profile"] })).toBe(false);
+
+    for (const targetType of ["owner", "user", "group"] as const) {
+      expect(Value.Check(readSchema, { targetType, targetId: targetType === "owner" ? "owner" : "id_1" })).toBe(true);
+    }
+    expect(Value.Check(readSchema, { targetType: "profile", targetId: "id_1" })).toBe(false);
+    expect(Value.Check(readSchema, { targetType: "user" })).toBe(false);
+    expect(Value.Check(readSchema, { targetType: "user", targetId: "id_1", filePath: "users/id_1.md" })).toBe(false);
+
+    expect(Value.Check(writeSchema, { targetType: "user", targetId: "usr_1", mode: "append", content: "note" })).toBe(true);
+    expect(Value.Check(writeSchema, { targetType: "user", targetId: "usr_1", mode: "replace", content: "" })).toBe(true);
+    expect(Value.Check(writeSchema, { targetType: "user", targetId: "usr_1", mode: "merge", content: "note" })).toBe(false);
+
+    expect(Value.Check(syncSchema, { targetType: "owner", targetId: "owner", direction: "pull" })).toBe(true);
+    expect(Value.Check(syncSchema, { targetType: "group", targetId: "grp_1", direction: "push" })).toBe(true);
+    expect(Value.Check(syncSchema, { targetType: "group", targetId: "grp_1", direction: "refresh" })).toBe(false);
+  });
+
+  it("metadata update schema requires a non-empty whitelisted patch", () => {
+    const schema = schemas.ClawchatMetadataUpdateSchema;
+    expect(schema).toBeDefined();
+
+    expect(Value.Check(schema, {
+      targetType: "owner",
+      targetId: "owner",
+      patch: { agent_behavior: "Answer concisely." },
+    })).toBe(true);
+    expect(Value.Check(schema, {
+      targetType: "user",
+      targetId: "usr_1",
+      patch: { avatar_url: "https://cdn/avatar.png", bio: "" },
+    })).toBe(true);
+    expect(Value.Check(schema, {
+      targetType: "group",
+      targetId: "grp_1",
+      patch: { group_title: "Team", group_description: "Planning" },
+    })).toBe(true);
+    expect(Value.Check(schema, { targetType: "owner", targetId: "owner" })).toBe(false);
+    expect(Value.Check(schema, { targetType: "owner", targetId: "owner", patch: {} })).toBe(false);
+    for (const key of ["visibility", "status", "platform", "raw", "kind"]) {
+      expect(Value.Check(schema, {
+        targetType: "owner",
+        targetId: "owner",
+        patch: { [key]: "not allowed" },
+      })).toBe(false);
+      expect(Value.Check(schema, {
+        targetType: "group",
+        targetId: "grp_1",
+        patch: { [key]: "not allowed" },
+      })).toBe(false);
+    }
+  });
+
+  it("memory tool safety errors do not expose workspace paths", async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), "clawchat-plugin-openclaw-workspace-"));
+    tempRoots.push(workspaceDir);
+    fs.symlinkSync(os.tmpdir(), path.join(workspaceDir, "users"));
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel({ ownerUserId: "owner" }),
+      workspaceDir,
+    });
+
+    registerOpenclawClawlingTools(api);
+    const tool = registered.find((t) => t.name === "clawchat_memory_read")!;
+    const result = await tool.execute("call-1", { targetType: "user", targetId: "usr_1" });
+
+    const parsed = JSON.parse((result as { content: { text: string }[] }).content[0]!.text) as {
+      error?: string;
+      message?: string;
+    };
+    expect(parsed).toMatchObject({
+      error: "validation",
+      message: "clawchat-plugin-openclaw: unsafe ClawChat memory target",
+    });
+    expect(parsed.message).not.toContain(workspaceDir);
+    expect(parsed.message).not.toContain(os.tmpdir());
+  });
+
+  it("clawchat_mention_message validates empty mentions before waiting for a client", async () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel(),
+    });
+    registerOpenclawClawlingTools(api);
+    const tool = registered.find((t) => t.name === "clawchat_mention_message")!;
+
+    const result = await Promise.race([
+      tool.execute("call-1", { chatId: "group-1", mentions: [] }),
+      new Promise((resolve) => setTimeout(() => resolve("timeout"), 100)),
+    ]);
+
+    expect(result).not.toBe("timeout");
+    const text = (result as { content: { text: string }[] }).content[0]!.text;
+    const parsed = JSON.parse(text) as { error?: string; message?: string };
+    expect(parsed.error).toBe("validation");
+    expect(parsed.message).toMatch(/mention/i);
+  });
+
+  it("clawchat_mention_message success returns terminal send result and marks reply suppression", async () => {
+    const client = mockMentionClient();
+    vi.spyOn(runtime, "getOpenclawClawlingClient").mockReturnValue(client as never);
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel(),
+    });
+    registerOpenclawClawlingTools(api);
+    const tool = registered.find((t) => t.name === "clawchat_mention_message")!;
+
+    const result = await runWithTerminalClawChatSendScope("scope-1", () =>
+      tool.execute("call-1", {
+        chatId: "group-1",
+        mentions: [{ userId: "user-1", display: "Alice" }],
+        text: "please check",
+      }),
+    );
+
+    const parsed = JSON.parse((result as { content: { text: string }[] }).content[0]!.text) as {
+      sent?: boolean;
+      terminal?: boolean;
+      noFollowupReply?: boolean;
+      instruction?: string;
+      messageId?: string;
+      mentions?: string[];
+    };
+    expect(parsed).toMatchObject({
+      sent: true,
+      terminal: true,
+      noFollowupReply: true,
+      messageId: "msg-mention",
+      mentions: ["user-1"],
+    });
+    expect(parsed.instruction).toContain("output only <clawchat:no-reply/>");
+    expect(consumeTerminalClawChatSend({
+      accountId: "default",
+      chatId: "group-1",
+      scopeId: "scope-1",
+    })?.messageId).toBe("msg-mention");
+  });
+
+  it("clawchat_mention_message returns config error for token-only unconfigured account", async () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w", token: "tk" },
+    });
+    registerOpenclawClawlingTools(api);
+    const tool = registered.find((t) => t.name === "clawchat_mention_message")!;
+
+    const result = await Promise.race([
+      tool.execute("call-1", {
+        chatId: "group-1",
+        mentions: [{ userId: "user-1" }],
+      }),
+      new Promise((resolve) => setTimeout(() => resolve("timeout"), 100)),
+    ]);
+
+    expect(result).not.toBe("timeout");
+    const text = (result as { content: { text: string }[] }).content[0]!.text;
+    const parsed = JSON.parse(text) as { error?: string; message?: string };
+    expect(parsed.error).toBe("config");
+  });
+
+  it("clawchat_mention_message returns validation error for non-string replyToMessageId", async () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel(),
+    });
+    registerOpenclawClawlingTools(api);
+    const tool = registered.find((t) => t.name === "clawchat_mention_message")!;
+
+    const result = await tool.execute("call-1", {
+      chatId: "group-1",
+      mentions: [{ userId: "user-1" }],
+      replyToMessageId: null,
+    });
+
+    const text = (result as { content: { text: string }[] }).content[0]!.text;
+    const parsed = JSON.parse(text) as { error?: string; message?: string };
+    expect(parsed.error).toBe("validation");
+    expect(parsed.message).toMatch(/replyToMessageId/i);
+  });
+
+  it("clawchat_mention_message accepts padded replyToMessageId before config guard", async () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w", token: "tk" },
+    });
+    registerOpenclawClawlingTools(api);
+    const tool = registered.find((t) => t.name === "clawchat_mention_message")!;
+
+    const result = await tool.execute("call-1", {
+      chatId: "group-1",
+      mentions: [{ userId: "user-1" }],
+      replyToMessageId: " msg-1 ",
+    });
+
+    const text = (result as { content: { text: string }[] }).content[0]!.text;
+    const parsed = JSON.parse(text) as { error?: string; message?: string };
+    expect(parsed.error).toBe("config");
+  });
+
+  it("clawchat_mention_message returns config error when websocket client is not ready", async () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel(),
+    });
+    registerOpenclawClawlingTools(api);
+    const tool = registered.find((t) => t.name === "clawchat_mention_message")!;
+
+    const result = await Promise.race([
+      tool.execute("call-1", {
+        chatId: "group-1",
+        mentions: [{ userId: "user-1" }],
+      }),
+      new Promise((resolve) => setTimeout(() => resolve("timeout"), 100)),
+    ]);
+
+    expect(result).not.toBe("timeout");
+    const text = (result as { content: { text: string }[] }).content[0]!.text;
+    const parsed = JSON.parse(text) as { error?: string; message?: string };
+    expect(parsed).toEqual({
+      error: "config",
+      message: "ClawChat websocket client is not ready",
+    });
+  });
+
+  it("account tools return a config error before activation instead of disappearing", async () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+    });
+
+    registerOpenclawClawlingTools(api);
+    const tool = registered.find((t) => t.name === "clawchat_get_account_profile")!;
+    const result = await tool.execute("call-1", {});
+
+    const text = (result as { content: { text: string }[] }).content[0]!.text;
+    const parsed = JSON.parse(text) as { error?: string; message?: string };
+    expect(parsed.error).toBe("config");
+    expect(parsed.message).toMatch(/token is required/i);
+  });
+
+  it("records successful clawchat tool calls without changing the returned result", async () => {
+    const store = { recordToolCall: vi.fn() };
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          code: 0,
+          msg: "ok",
+          data: { user_id: "u", nickname: "Bot", avatar_url: "", bio: "" },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      ),
+    );
+    try {
+      const { api, registered } = buildApi({
+        configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
+      });
+      registerOpenclawClawlingTools(api, { store });
+      const tool = registered.find((t) => t.name === "clawchat_get_account_profile")!;
+
+      const result = await tool.execute("call-1", {});
+
+      expect((result as { details: unknown }).details).toEqual({
+        user_id: "u",
+        nickname: "Bot",
+        avatar_url: "",
+        bio: "",
+      });
+      expect(store.recordToolCall).toHaveBeenCalledTimes(1);
+      expect(store.recordToolCall).toHaveBeenCalledWith(
+        expect.objectContaining({
+          platform: "openclaw",
+          accountId: "default",
+          toolName: "clawchat_get_account_profile",
+          args: {},
+          result: { user_id: "u", nickname: "Bot", avatar_url: "", bio: "" },
+          error: null,
+          startedAt: expect.any(Number),
+          endedAt: expect.any(Number),
+        }),
+      );
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("gets a conversation without writing SQLite conversation state", async () => {
+    const store = {
+      recordToolCall: vi.fn(),
+    };
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          code: 0,
+          msg: "ok",
+          data: {
+            conversation: {
+              id: "group_1",
+              type: "group",
+              title: "Project Group",
+              creator_id: "owner",
+              created_at: "2026-05-01T00:00:00Z",
+              updated_at: "2026-05-02T00:00:00Z",
+              participants: [
+                { conversation_id: "group_1", user_id: "owner", role: "owner", joined_at: "2026-05-01T00:00:00Z" },
+              ],
+            },
+          },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      ),
+    );
+    try {
+      const { api, registered } = buildApi({
+        configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
+      });
+      registerOpenclawClawlingTools(api, { store });
+      const tool = registered.find((t) => t.name === "clawchat_get_conversation")!;
+
+      await tool.execute("call-1", { conversationId: "group_1" });
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(fetchMock.mock.calls[0]?.[0]).toBe("https://api.example.com/v1/conversations/group_1");
+      expect(store.recordToolCall).toHaveBeenCalledWith(expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        toolName: "clawchat_get_conversation",
+      }));
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("returns the standard error result when get conversation is not found", async () => {
+    const store = {
+      recordToolCall: vi.fn(),
+    };
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ code: 40401, msg: "conversation not found", data: null }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    try {
+      const { api, registered } = buildApi({
+        configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
+      });
+      registerOpenclawClawlingTools(api, { store });
+      const tool = registered.find((t) => t.name === "clawchat_get_conversation")!;
+
+      const result = await tool.execute("call-1", { conversationId: "missing" });
+
+      const parsed = JSON.parse((result as { content: { text: string }[] }).content[0]!.text) as {
+        error?: string;
+        message?: string;
+        meta?: { code?: number };
+      };
+      expect(parsed).toMatchObject({
+        error: "api",
+        message: "conversation not found",
+        meta: { code: 40401 },
+      });
+      expect(store.recordToolCall).toHaveBeenCalledWith(expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        toolName: "clawchat_get_conversation",
+        error: "api: conversation not found",
+      }));
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("does not require SQLite conversation state methods from account, user, friend, search, avatar, or media tools", async () => {
+    const store = {
+      recordToolCall: vi.fn(),
+    };
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          code: 0,
+          msg: "ok",
+          data: { id: "u", nickname: "Bot", avatar_url: "", bio: "" },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      ),
+    );
+    try {
+      const { api, registered } = buildApi({
+        configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
+      });
+      registerOpenclawClawlingTools(api, { store });
+      const tool = registered.find((t) => t.name === "clawchat_get_account_profile")!;
+
+      await tool.execute("call-1", {});
+
+      expect(store.recordToolCall).toHaveBeenCalledWith(expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        toolName: "clawchat_get_account_profile",
+      }));
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("records clawchat tool failures while preserving the returned error result", async () => {
+    const store = { recordToolCall: vi.fn() };
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+    });
+    registerOpenclawClawlingTools(api, { store });
+    const tool = registered.find((t) => t.name === "clawchat_get_account_profile")!;
+
+    const result = await tool.execute("call-1", {});
+
+    const parsed = JSON.parse((result as { content: { text: string }[] }).content[0]!.text) as {
+      error?: string;
+      message?: string;
+    };
+    expect(parsed).toMatchObject({ error: "config" });
+    expect(store.recordToolCall).toHaveBeenCalledWith(
+      expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        toolName: "clawchat_get_account_profile",
+        args: {},
+        result: parsed,
+        error: expect.stringContaining("config"),
+      }),
+    );
+    expect(registered.every((tool) => tool.name.startsWith("clawchat_"))).toBe(true);
+  });
+
+  it("clawchat_update_account_profile description names account profile triggers (EN + ZH)", () => {
+    const { api } = buildApi({ configChannel: configuredChannel() });
+    const fullTools: Array<{ name: string; description?: string }> = [];
+    api.registerTool = (tool: { name: string; description?: string }) => {
+      fullTools.push(tool);
+    };
+    registerOpenclawClawlingTools(api);
+    const update = fullTools.find((t) => t.name === "clawchat_update_account_profile")!;
+    expect(update).toBeDefined();
+    expect(update.description).toMatch(/configured ClawChat account|logged-in ClawChat account/i);
+    expect(update.description).toMatch(/ClawChat (account )?(nickname|name)/i);
+    expect(update.description).toMatch(/ClawChat 昵称|账号昵称|账号名字/);
+    expect(update.description).toMatch(/avatar|profile picture/i);
+    expect(update.description).toMatch(/ClawChat 头像|账号头像/);
+    expect(update.description).toMatch(/clawchat_upload_avatar_image/);
+    expect(update.description).toMatch(/bio|self-introduction/i);
+    expect(update.description).toMatch(/ClawChat 简介|账号简介|个人简介/);
+    expect(update.description).not.toMatch(
+      new RegExp(["agent's own", "rename " + "yourself", "this agent's own"].join("|"), "i"),
+    );
+  });
+
+  it("account query and upload tool descriptions include precise trigger semantics", () => {
+    const { api, registered: fullTools } = buildApi({ configChannel: configuredChannel() });
+    registerOpenclawClawlingTools(api);
+
+    const accountProfile = fullTools.find((t) => t.name === "clawchat_get_account_profile")!;
+    const userProfile = fullTools.find((t) => t.name === "clawchat_get_user_profile")!;
+    const memoryWrite = fullTools.find((t) => t.name === "clawchat_memory_write")!;
+    const metadataSync = fullTools.find((t) => t.name === "clawchat_metadata_sync")!;
+    const friends = fullTools.find((t) => t.name === "clawchat_list_account_friends")!;
+    const avatar = fullTools.find((t) => t.name === "clawchat_upload_avatar_image")!;
+    const media = fullTools.find((t) => t.name === "clawchat_upload_media_file")!;
+
+    expect(accountProfile.description).toMatch(/configured ClawChat account|logged-in ClawChat account/i);
+    expect(accountProfile.description).toMatch(/profile|nickname|avatar|bio/i);
+    expect(accountProfile.description).not.toMatch(/agent's own|this agent's/i);
+
+    expect(userProfile.description).toMatch(/userId/);
+    expect(userProfile.description).toMatch(/public profile/i);
+    expect(userProfile.description).toMatch(/do not guess|do not infer/i);
+    expect(userProfile.description).toMatch(/read-only lookup/i);
+    expect(userProfile.description).toMatch(/clawchat_metadata_sync.*direction=pull/i);
+
+    expect(memoryWrite.description).toMatch(/agent-authored body/i);
+    expect(memoryWrite.description).toMatch(/never modifies the metadata block/i);
+    expect(memoryWrite.description).toMatch(/Do not use.*nickname.*avatar_url.*bio.*profile_type/i);
+    expect(memoryWrite.description).toMatch(/refresh.*local ClawChat.*profile.*clawchat_metadata_sync.*direction=pull/i);
+
+    expect(metadataSync.description).toMatch(/refresh, sync, or update local ClawChat current agent profile\/behavior, agent-owner profile information/i);
+    expect(metadataSync.description).toMatch(/rewrites only the metadata block/i);
+    expect(metadataSync.description).toMatch(/Do not combine clawchat_get_user_profile with clawchat_memory_write/i);
+
+    expect(friends.description).toMatch(/configured ClawChat account|logged-in ClawChat account/i);
+    expect(friends.description).toMatch(/friends|contacts/i);
+    expect(friends.description).not.toMatch(/paginated|page=1|pageSize=20/i);
+    expect(friends.parameters?.properties ?? {}).toEqual({});
+
+    expect(avatar.description).toMatch(/local image/i);
+    expect(avatar.description).toMatch(/avatar URL|hosted avatar URL|public URL/i);
+    expect(avatar.description).toMatch(/clawchat_update_account_profile/);
+    expect(avatar.description).toMatch(/does not update|does not set/i);
+
+    expect(media.description).toMatch(/local file|media file/i);
+    expect(media.description).toMatch(/public URL|shareable URL/i);
+    expect(media.description).toMatch(/not.*avatar|do not use.*avatar/i);
+  });
+
+  it("search and moment tool descriptions match reviewed trigger semantics", () => {
+    const { api, registered: fullTools } = buildApi({ configChannel: configuredChannel() });
+    registerOpenclawClawlingTools(api);
+
+    const search = fullTools.find((t) => t.name === "clawchat_search_users")!;
+    const memorySearch = fullTools.find((t) => t.name === "clawchat_memory_search")!;
+    const memoryRead = fullTools.find((t) => t.name === "clawchat_memory_read")!;
+    const listMoments = fullTools.find((t) => t.name === "clawchat_list_moments")!;
+    const createMoment = fullTools.find((t) => t.name === "clawchat_create_moment")!;
+    const deleteMoment = fullTools.find((t) => t.name === "clawchat_delete_moment")!;
+    const reaction = fullTools.find((t) => t.name === "clawchat_toggle_moment_reaction")!;
+    const comment = fullTools.find((t) => t.name === "clawchat_create_moment_comment")!;
+    const reply = fullTools.find((t) => t.name === "clawchat_reply_moment_comment")!;
+    const deleteComment = fullTools.find((t) => t.name === "clawchat_delete_moment_comment")!;
+
+    for (const tool of [
+      search,
+      listMoments,
+      createMoment,
+      deleteMoment,
+      reaction,
+      comment,
+      reply,
+      deleteComment,
+    ]) {
+      expect(tool.description).toMatch(/Do not use execute/);
+      expect(tool.description).toMatch(/direct ClawChat HTTP calls/);
+    }
+
+    expect(search.description).toMatch(/Search ClawChat users by username or nickname/);
+    expect(search.description).toMatch(/server-side ClawChat users/i);
+    expect(search.description).toMatch(/does not search local ClawChat memory/i);
+    expect(search.description).toMatch(/clawchat_memory_search/);
+    expect(search.description).toMatch(/do not guess a userId/);
+    expect(memorySearch.description).toMatch(/Search local ClawChat memory Markdown files/i);
+    expect(memorySearch.description).toMatch(/owner\.md, users\/\*\.md, and groups\/\*\.md/);
+    expect(memorySearch.description).toMatch(/remembered person, alias, relationship, prior note, group rule/i);
+    expect(memorySearch.description).toMatch(/does not contact the ClawChat server/i);
+    expect(memoryRead.description).toMatch(/target returned by clawchat_memory_search/i);
+    expect(memoryRead.description).toMatch(/use clawchat_memory_search first/i);
+    expect(listMoments.description).toMatch(/moments\/dynamics\/feed/);
+    expect(listMoments.description).toMatch(/friends-only feed endpoint/);
+    expect(createMoment.description).toMatch(/At least one of text or images/);
+    expect(createMoment.description).toMatch(/do not pass local file paths as images/);
+    expect(deleteMoment.description).toMatch(/Do not guess the id/);
+    expect(reaction.description).toMatch(/adds the reaction if missing and removes it/);
+    expect(comment.description).toMatch(/top-level comment/);
+    expect(comment.description).toMatch(/Use clawchat_reply_moment_comment/);
+    expect(reply.description).toMatch(/single-level reply/);
+    expect(reply.description).toMatch(/do not use this for top-level comments/);
+    expect(deleteComment.description).toMatch(/moment and comment ids/);
+  });
+
+  it("clawchat_upload_avatar_image rejects oversized files before upload", async () => {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const os = await import("node:os");
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "clawchat-plugin-openclaw-"));
+    const big = path.join(tmp, "avatar-big.bin");
+    const handle = await fs.open(big, "w");
+    await handle.truncate(21 * 1024 * 1024);
+    await handle.close();
+    try {
+      const { api, registered } = buildApi({
+        configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
+      });
+      registerOpenclawClawlingTools(api);
+      const tool = registered.find((t) => t.name === "clawchat_upload_avatar_image")!;
+      const result = await tool.execute("call-1", { filePath: big });
+      const text = (result as { content: { text: string }[] }).content[0]!.text;
+      const parsed = JSON.parse(text) as { error?: string; message?: string };
+      expect(parsed.error).toBe("validation");
+      expect(parsed.message).toMatch(/20 ?MB|too large/i);
+    } finally {
+      await fs.rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+
+  it("clawchat_upload_media_file rejects oversized files before upload", async () => {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const os = await import("node:os");
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "clawchat-plugin-openclaw-"));
+    const big = path.join(tmp, "big.bin");
+    // create a sparse 21MB file (we never read it; size check fires first)
+    const handle = await fs.open(big, "w");
+    await handle.truncate(21 * 1024 * 1024);
+    await handle.close();
+    try {
+      const { api, registered } = buildApi({
+        configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
+      });
+      registerOpenclawClawlingTools(api);
+      const tool = registered.find((t) => t.name === "clawchat_upload_media_file")!;
+      const result = await tool.execute("call-1", { filePath: big });
+      const text = (result as { content: { text: string }[] }).content[0]!.text;
+      const parsed = JSON.parse(text) as { error?: string; message?: string };
+      expect(parsed.error).toBe("validation");
+      expect(parsed.message).toMatch(/20 ?MB|too large/i);
+    } finally {
+      await fs.rm(tmp, { recursive: true, force: true });
+    }
+  });
+});