@newbase-clawchat/openclaw-clawchat 2026.4.24 → 2026.4.29

package/src/login.runtime.test.ts

@@ -95,7 +95,7 @@ describe("runOpenclawClawlingLogin", () => {
     });
 
     expect(agentsConnect).toHaveBeenCalledWith({
-      inviteCode: "INV-ABC",
+      code: "INV-ABC",
       platform: "openclaw",
       type: "clawbot",
     });
@@ -112,6 +112,109 @@ describe("runOpenclawClawlingLogin", () => {
     expect(log).toHaveBeenCalledWith(expect.stringContaining("login succeeded"));
   });
 
+  it("preserves other configured channels when persisting ClawChat credentials", async () => {
+    const cfg = {
+      channels: {
+        telegram: {
+          enabled: true,
+          token: "telegram-token",
+        },
+        [CHANNEL_ID]: {
+          baseUrl: "https://api.example.com",
+          websocketUrl: "wss://ws.example.com/v2/client",
+        },
+      },
+    } as unknown as OpenClawConfig;
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "agent-123" },
+      access_token: "access-tok",
+      refresh_token: "refresh-tok",
+    });
+    const persistConfig = vi.fn();
+
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log: vi.fn() },
+      readInviteCode: async () => "INV-ABC",
+      apiClientFactory: () => makeApiClient({ agentsConnect }),
+      persistConfig,
+    });
+
+    const savedCfg = persistConfig.mock.calls[0]![0] as OpenClawConfig;
+    expect(savedCfg.channels?.telegram).toEqual({
+      enabled: true,
+      token: "telegram-token",
+    });
+    expect(savedCfg.channels?.[CHANNEL_ID]).toMatchObject({
+      baseUrl: "https://api.example.com",
+      websocketUrl: "wss://ws.example.com/v2/client",
+      token: "access-tok",
+      userId: "agent-123",
+      refreshToken: "refresh-tok",
+    });
+  });
+
+  it("enables the channel when login fills a pre-activation disabled skeleton", async () => {
+    const cfg = buildCfg({
+      enabled: false,
+      baseUrl: "https://api.example.com",
+    });
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "agent-123" },
+      access_token: "access-tok",
+      refresh_token: "refresh-tok",
+    });
+    const persistConfig = vi.fn();
+
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log: vi.fn() },
+      readInviteCode: async () => "INV-ABC",
+      apiClientFactory: () => makeApiClient({ agentsConnect }),
+      persistConfig,
+    });
+
+    const savedCfg = persistConfig.mock.calls[0]![0] as OpenClawConfig;
+    const section = (savedCfg.channels as Record<string, Record<string, unknown>>)[CHANNEL_ID]!;
+    expect(section.enabled).toBe(true);
+    expect(section.token).toBe("access-tok");
+    expect(section.userId).toBe("agent-123");
+  });
+
+  it("allows openclaw-clawchat plugin tools after successful login without replacing policy", async () => {
+    const cfg = {
+      ...buildCfg({ baseUrl: "https://api.example.com" }),
+      tools: {
+        profile: "coding",
+        allow: [],
+        deny: ["exec"],
+        alsoAllow: ["browser"],
+      },
+    } as unknown as OpenClawConfig;
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "agent-123" },
+      access_token: "access-tok",
+      refresh_token: "refresh-tok",
+    });
+    const persistConfig = vi.fn();
+
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log: vi.fn() },
+      readInviteCode: async () => "INV-ABC",
+      apiClientFactory: () => makeApiClient({ agentsConnect }),
+      persistConfig,
+    });
+
+    const savedCfg = persistConfig.mock.calls[0]![0] as OpenClawConfig;
+    expect(savedCfg.tools).toMatchObject({
+      profile: "coding",
+      allow: [],
+      deny: ["exec"],
+      alsoAllow: ["browser", "openclaw-clawchat"],
+    });
+  });
+
   it("surfaces agents/connect API errors with the kind and message", async () => {
     const cfg = buildCfg({ baseUrl: "https://api.example.com" });
     const agentsConnect = vi.fn().mockRejectedValue(
@@ -219,7 +322,7 @@ describe("runOpenclawClawlingLogin", () => {
       persistConfig: vi.fn(),
     });
     expect(agentsConnect).toHaveBeenCalledWith({
-      inviteCode: "INV-TRIM",
+      code: "INV-TRIM",
       platform: "openclaw",
       type: "clawbot",
     });
@@ -243,7 +346,7 @@ describe("runOpenclawClawlingLogin (non-interactive via readInviteCode)", () =>
       persistConfig,
     });
     expect(agentsConnect).toHaveBeenCalledWith({
-      inviteCode: "INV-PROGRAMMATIC",
+      code: "INV-PROGRAMMATIC",
       platform: "openclaw",
       type: "clawbot",
     });

package/src/login.runtime.ts

@@ -3,7 +3,11 @@ import { writeConfigFile } from "openclaw/plugin-sdk/config-runtime";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { ClawlingApiError } from "./api-types.ts";
-import { CHANNEL_ID, resolveOpenclawClawlingAccount } from "./config.ts";
+import {
+  CHANNEL_ID,
+  mergeOpenclawClawchatToolAllow,
+  resolveOpenclawClawlingAccount,
+} from "./config.ts";
 
 /**
  * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
@@ -120,16 +124,17 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
   const existing = (channels[CHANNEL_ID] ?? {}) as Record<string, unknown>;
   const nextSection: Record<string, unknown> = {
     ...existing,
+    enabled: true,
     token: result.access_token,
     userId: result.agent.user_id,
   };
   if (result.refresh_token) {
     nextSection.refreshToken = result.refresh_token;
   }
-  const nextCfg: OpenClawConfig = {
+  const nextCfg: OpenClawConfig = mergeOpenclawClawchatToolAllow({
     ...cfg,
     channels: { ...channels, [CHANNEL_ID]: nextSection },
-  };
+  });
 
   const tokenPreview = redactToken(result.access_token);
   runtime.log(

package/src/manifest.test.ts

@@ -1,11 +1,15 @@
+import fs from "node:fs";
 import { describe, expect, it } from "vitest";
 import pluginManifest from "../openclaw.plugin.json" with { type: "json" };
 import packageJson from "../package.json" with { type: "json" };
 
 interface PackageJsonWithOpenclaw {
   name: string;
+  files: string[];
   openclaw: {
-    channel: { id: string };
+    extensions: string[];
+    setupEntry?: string;
+    channel?: { id: string; aliases?: string[]; cliAddOptions?: Array<{ flags: string }> };
     install: { npmSpec: string };
   };
 }
@@ -14,9 +18,107 @@ describe("openclaw-clawchat manifest", () => {
   it("keeps plugin id / channel id / package name aligned", () => {
     expect(pluginManifest.id).toBe("openclaw-clawchat");
     expect(pluginManifest.channels).toContain("openclaw-clawchat");
-    expect(packageJson.name).toBe("openclaw-clawchat");
+    expect(pluginManifest.skills).toContain("./skills");
+    expect(pluginManifest.channelConfigs?.["openclaw-clawchat"]?.label).toBe(
+      "Clawling Chat",
+    );
+    expect(pluginManifest.channelConfigs?.["openclaw-clawchat"]?.schema?.properties).toHaveProperty(
+      "token",
+    );
+    expect(packageJson.name).toBe("@newbase-clawchat/openclaw-clawchat");
     const pkg = packageJson as PackageJsonWithOpenclaw;
-    expect(pkg.openclaw.channel.id).toBe("openclaw-clawchat");
-    expect(pkg.openclaw.install.npmSpec).toBe("openclaw-clawchat");
+    expect(pkg.openclaw.extensions).toContain("./index.ts");
+    expect(pkg.openclaw.install.npmSpec).toBe("@newbase-clawchat/openclaw-clawchat");
+  });
+
+  it("declares supported channel/command activation hints for plugin loading", () => {
+    expect(pluginManifest.activation).toEqual({
+      onChannels: ["openclaw-clawchat"],
+      onCommands: ["clawchat-login"],
+    });
+    expect(pluginManifest.activation).not.toHaveProperty("onStartup");
+    expect(pluginManifest.commandAliases).toEqual([
+      { name: "clawchat-login", kind: "runtime-slash" },
+    ]);
+  });
+
+  it("does not publish setup migration or setup-runtime channel metadata", () => {
+    const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pkg.files).not.toContain("setup-api.ts");
+    expect(pkg.files).not.toContain("setup-entry.ts");
+    expect(pkg.openclaw.setupEntry).toBeUndefined();
+    expect(pkg.openclaw.channel).toBeUndefined();
+    expect(fs.existsSync(new URL("../setup-api.ts", import.meta.url))).toBe(false);
+    expect(fs.existsSync(new URL("../setup-entry.ts", import.meta.url))).toBe(false);
+  });
+
+  it("does not document channels add as an activation path", () => {
+    const readme = fs.readFileSync(new URL("../README.md", import.meta.url), "utf8");
+    const docs = fs.readFileSync(new URL("../docs/openclaw-clawchat.md", import.meta.url), "utf8");
+    expect(readme).not.toMatch(/channels add --channel openclaw-clawchat/i);
+    expect(docs).not.toMatch(/channels add --channel openclaw-clawchat/i);
+  });
+
+  it("publishes a ClawChat account tools skill for non-activation workflows", () => {
+    const skill = fs.readFileSync(new URL("../skills/clawchat-account-tools/SKILL.md", import.meta.url), "utf8");
+    expect(skill).toMatch(/^---\nname: clawchat-account-tools\n/m);
+    expect(skill).toMatch(/description: .*Use when/i);
+    expect(skill).toMatch(/clawchat_get_account_profile/);
+    expect(skill).toMatch(/clawchat_get_user_profile/);
+    expect(skill).toMatch(/clawchat_list_account_friends/);
+    expect(skill).toMatch(/clawchat_update_account_profile/);
+    expect(skill).toMatch(/clawchat_upload_avatar_image/);
+    expect(skill).toMatch(/clawchat_upload_media_file/);
+    expect(skill).toMatch(/configured ClawChat account/i);
+    expect(skill).not.toMatch(/clawchat_activate/);
+  });
+
+  it("keeps the activation skill on channel login without tool or slash-command dispatch", () => {
+    const skill = fs.readFileSync(new URL("../skills/clawchat-activate/SKILL.md", import.meta.url), "utf8");
+    expect(skill).toMatch(/name:\s*clawchat-activate/);
+    expect(skill).not.toMatch(/clawchat_activate/);
+    expect(skill).not.toMatch(/command-dispatch:\s*tool/);
+    expect(skill).not.toMatch(/command-tool:/);
+    expect(skill).not.toMatch(/command-dispatch:/);
+    expect(skill).not.toMatch(/command-command:/);
+    expect(skill).not.toMatch(/command-arg-mode:/);
+    expect(skill).not.toMatch(/user-invocable:/);
+    expect(skill).not.toMatch(/`clawchat\s+A1B2C3`/i);
+    expect(skill).not.toMatch(/`clawchat\s*<code>`/i);
+    expect(skill).not.toMatch(/\/clawchat_activate A1B2C3/);
+    expect(skill).not.toMatch(/\/clawchat-activate A1B2C3/);
+    expect(skill).not.toMatch(/\/clawchat-login A1B2C3/);
+    expect(skill).toMatch(/openclaw channels login --channel openclaw-clawchat/);
+    expect(skill).toMatch(/do not append/i);
+    expect(skill).toMatch(/prompt[^\n]+invite code[^\n]+provide/i);
+    expect(skill).toMatch(/channel login/i);
+    expect(skill).toMatch(/openclaw gateway restart/);
+    expect(skill).not.toMatch(/ask the user to send/i);
+    expect(skill).not.toMatch(/give the exact/i);
+    expect(skill).toMatch(/execute[^\n]+openclaw channels login --channel openclaw-clawchat/i);
+    expect(skill).toMatch(/execute[^\n]+openclaw gateway restart/i);
+  });
+
+  it("documents channel login as the natural-language activation path", () => {
+    const readme = fs.readFileSync(new URL("../README.md", import.meta.url), "utf8");
+    const docs = fs.readFileSync(new URL("../docs/openclaw-clawchat.md", import.meta.url), "utf8");
+    expect(readme).toMatch(/openclaw channels login --channel openclaw-clawchat/i);
+    expect(docs).toMatch(/openclaw channels login --channel openclaw-clawchat/i);
+    expect(readme).toMatch(/openclaw gateway restart/i);
+    expect(docs).toMatch(/openclaw gateway restart/i);
+    expect(readme).not.toMatch(/activation skill[^.]+\/clawchat-login/i);
+    expect(docs).not.toMatch(/natural-language activation requests[^.]+\/clawchat-login/i);
+    expect(readme).not.toMatch(/\/clawchat-activate\s+A1B2C3/i);
+    expect(docs).not.toMatch(/\/clawchat-activate\s+A1B2C3/i);
+    expect(readme).not.toMatch(/clawchat_activate/);
+    expect(docs).not.toMatch(/clawchat_activate/);
+    expect(readme).not.toMatch(/\/clawchat_activate\s+A1B2C3/i);
+    expect(docs).not.toMatch(/\/clawchat_activate\s+A1B2C3/i);
+    expect(readme).not.toMatch(/direct users to/i);
+    expect(docs).not.toMatch(/direct the\s+user/i);
+    expect(docs).not.toMatch(/call the tool with the extracted code/i);
+    expect(docs).not.toMatch(/AGT->>PLG: clawchat_activate/);
+    expect(readme).toMatch(/activation skill[^.]+execute/i);
+    expect(docs).toMatch(/natural-language activation requests[^.]+execute/i);
   });
 });

package/src/outbound.test.ts

@@ -64,7 +64,8 @@ describe("openclaw-clawchat outbound", () => {
       text: "hello",
     });
     expect((client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).toMatchObject({
-      to: { id: "user-1", type: "direct" },
+      chat_id: "user-1",
+      chat_type: "direct",
       body: { fragments: [{ kind: "text", text: "hello" }] },
     });
     expect(client.replyMessage).not.toHaveBeenCalled();
@@ -82,16 +83,17 @@ describe("openclaw-clawchat outbound", () => {
       replyCtx: {
         replyToMessageId: "m-orig",
         replyPreviewSenderId: "user-2",
-        replyPreviewDisplayName: "Sender",
+        replyPreviewNickName: "Sender",
         replyPreviewText: "original",
       },
     });
     expect((client.replyMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).toMatchObject({
-      to: { id: "user-1", type: "direct" },
+      chat_id: "user-1",
+      chat_type: "direct",
       replyTo: {
         msgId: "m-orig",
         senderId: "user-2",
-        displayName: "Sender",
+        nickName: "Sender",
         fragments: [{ kind: "text", text: "original" }],
       },
       body: { fragments: [{ kind: "text", text: "reply" }] },
@@ -168,7 +170,7 @@ describe("openclaw-clawchat outbound", () => {
       replyCtx: {
         replyToMessageId: "m-orig",
         replyPreviewSenderId: "user-2",
-        replyPreviewDisplayName: "Sender",
+        replyPreviewNickName: "Sender",
         replyPreviewText: "original",
       },
       mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],

package/src/plugin-entry.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from "vitest";
+import pluginEntry from "../index.ts";
+
+describe("openclaw-clawchat plugin entry", () => {
+  it("registers the channel/tools and native activation command without bootstrap migration", () => {
+    const api = {
+      config: {},
+      runtime: {},
+      logger: { debug: vi.fn(), info: vi.fn(), error: vi.fn() },
+      registerChannel: vi.fn(),
+      registerCommand: vi.fn(),
+      registerConfigMigration: vi.fn(),
+      registerTool: vi.fn(),
+    } as never;
+
+    pluginEntry.register(api);
+
+    expect(api.registerChannel).toHaveBeenCalledTimes(1);
+    expect(api.registerConfigMigration).not.toHaveBeenCalled();
+    expect(api.registerCommand).toHaveBeenCalledTimes(1);
+    expect(api.registerCommand).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: "clawchat-login",
+      }),
+    );
+  });
+});

package/src/protocol.ts

@@ -40,3 +40,8 @@ export function hasRenderableText(message: {
           (f as { url: string }).url.trim().length > 0)),
   );
 }
+
+export function isGroupSender(sender: unknown): boolean {
+  if (!sender || typeof sender !== "object") return false;
+  return (sender as { type?: unknown }).type === "group";
+}

package/src/reply-dispatcher.test.ts

@@ -185,7 +185,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
 
     expect(client.sendMessage).toHaveBeenCalledWith(
       expect.objectContaining({
-        to: { id: "chat-1", type: "direct" },
+        chat_id: "chat-1",
+        chat_type: "direct",
         body: { fragments: [{ kind: "text", text: "Error: boom" }] },
       }),
     );
@@ -244,7 +245,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
 
     expect(client.sendMessage).toHaveBeenCalledWith(
       expect.objectContaining({
-        to: { id: "chat-1", type: "direct" },
+        chat_id: "chat-1",
+        chat_type: "direct",
         body: { fragments: [{ kind: "text", text: "Error: boom" }] },
       }),
     );

package/src/runtime.test.ts

@@ -56,15 +56,19 @@ describe("openclaw-clawchat runtime media ingest", () => {
       capturedCtx = ctx;
       return ctx;
     });
+    const resolveAgentRoute = vi.fn(() => ({
+      agentId: "u",
+      accountId: "default",
+      sessionKey: "s",
+    }));
+    const cfg = {
+      session: { store: "/tmp/sessions.json", dmScope: "main" },
+    } as unknown as OpenClawConfig;
 
     const runtime = {
       channel: {
         routing: {
-          resolveAgentRoute: vi.fn(() => ({
-            agentId: "u",
-            accountId: "default",
-            sessionKey: "s",
-          })),
+          resolveAgentRoute,
         },
         session: {
           resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
@@ -108,7 +112,7 @@ describe("openclaw-clawchat runtime media ingest", () => {
     const abortController = new AbortController();
 
     const startPromise = startOpenclawClawlingGateway({
-      cfg: {} as import("openclaw/plugin-sdk/core").OpenClawConfig,
+      cfg,
       account: {
         accountId: "default",
         name: "openclaw-clawchat",
@@ -203,6 +207,18 @@ describe("openclaw-clawchat runtime media ingest", () => {
     expect(capturedCtx?.From).toBe("openclaw-clawchat:chat-1");
     expect(capturedCtx?.ConversationLabel).toBe("chat-1");
     expect(capturedCtx?.SenderId).toBe("user-1");
+    expect(resolveAgentRoute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cfg: expect.objectContaining({
+          session: expect.objectContaining({
+            dmScope: "per-account-channel-peer",
+            store: "/tmp/sessions.json",
+          }),
+        }),
+        peer: { kind: "direct", id: "chat-1" },
+      }),
+    );
+    expect(cfg.session?.dmScope).toBe("main");
   });
 
   it("uses group chat_id as the canonical conversation identity", async () => {
@@ -494,7 +510,7 @@ describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
     expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
     expect(markDispatchIdle).toHaveBeenCalledTimes(1);
     expect(logError).toHaveBeenCalledWith(
-      expect.stringContaining("openclaw-clawchat message handler error:"),
+      expect.stringContaining("openclaw-clawchat dispatch failed msg=m-fail"),
     );
   });
 });

package/src/runtime.ts

@@ -107,6 +107,16 @@ function formatConversationSubject(peer: { kind: "direct" | "group"; id: string
   return peer.kind === "group" ? `group:${peer.id}` : peer.id;
 }
 
+function withClawChatSessionScope(cfg: OpenClawConfig): OpenClawConfig {
+  return {
+    ...cfg,
+    session: {
+      ...(cfg.session ?? {}),
+      dmScope: "per-account-channel-peer",
+    },
+  };
+}
+
 export interface StartGatewayParams {
   cfg: OpenClawConfig;
   account: ResolvedOpenclawClawlingAccount;
@@ -172,8 +182,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       ingest: async (turn) => {
         const rt = runtime.channel;
         const storePath = rt.session.resolveStorePath(cfg.session?.store);
+        const routeCfg = withClawChatSessionScope(cfg);
         const route = rt.routing.resolveAgentRoute({
-          cfg,
+          cfg: routeCfg,
           channel: CHANNEL_ID,
           accountId,
           peer: turn.peer,

package/src/streaming.test.ts

@@ -37,8 +37,8 @@ describe("openclaw-clawchat streaming", () => {
       "message.done",
     ]);
     expect((client.typing as ReturnType<typeof vi.fn>).mock.calls).toEqual([
-      [{ id: "u1", type: "direct" }, true],
-      [{ id: "u1", type: "direct" }, false],
+      ["u1", true, "direct"],
+      ["u1", false, "direct"],
     ]);
   });
 
@@ -110,7 +110,7 @@ describe("openclaw-clawchat streaming", () => {
     expect(sent[0]!.payload.sequence).toBe(3);
     expect(sent[0]!.payload.reason).toBe("boom");
     expect((client.typing as ReturnType<typeof vi.fn>).mock.calls).toEqual([
-      [{ id: "u1", type: "direct" }, false],
+      ["u1", false, "direct"],
     ]);
   });
 });

package/src/streaming.ts

@@ -10,7 +10,8 @@ import {
 
 export interface StreamingSendParams {
   client: ClawlingChatClient;
-  routing: EnvelopeRouting;
+  routing?: EnvelopeRouting;
+  to?: { id: string; type: "direct" | "group" };
   sender: StreamSender;
   /**
    * Pre-chunked text. Use `chunkMarkdownText` from
@@ -22,6 +23,12 @@ export interface StreamingSendParams {
   emitTyping?: boolean;
 }
 
+function resolveRouting(params: { routing?: EnvelopeRouting; to?: { id: string; type: "direct" | "group" } }): EnvelopeRouting {
+  if (params.routing) return params.routing;
+  if (params.to) return { chatId: params.to.id, chatType: params.to.type };
+  throw new Error("openclaw-clawchat streaming requires routing");
+}
+
 /**
  * Emit one full streaming lifecycle for a pre-chunked reply.
  *
@@ -35,13 +42,14 @@ export interface StreamingSendParams {
  * With zero chunks: typing(true) -> created -> done -> typing(false).
  */
 export async function sendStreamingText(params: StreamingSendParams): Promise<void> {
+  const routing = resolveRouting(params);
   const emitTyping = params.emitTyping !== false;
   if (emitTyping) {
-    params.client.typing(params.routing.chatId, true, params.routing.chatType);
+    params.client.typing(routing.chatId, true, routing.chatType);
   }
   emitStreamCreated(params.client, {
     messageId: params.messageId,
-    routing: params.routing,
+    routing,
   });
   let sequence = 0;
   let fullText = "";
@@ -50,7 +58,7 @@ export async function sendStreamingText(params: StreamingSendParams): Promise<vo
     fullText += chunk;
     emitStreamAdd(params.client, {
       messageId: params.messageId,
-      routing: params.routing,
+      routing,
       sequence,
       fullText,
       textDelta: chunk,
@@ -58,18 +66,19 @@ export async function sendStreamingText(params: StreamingSendParams): Promise<vo
   }
   emitStreamDone(params.client, {
     messageId: params.messageId,
-    routing: params.routing,
+    routing,
     finalSequence: sequence,
     finalText: fullText,
   });
   if (emitTyping) {
-    params.client.typing(params.routing.chatId, false, params.routing.chatType);
+    params.client.typing(routing.chatId, false, routing.chatType);
   }
 }
 
 export interface StreamingFailureParams {
   client: ClawlingChatClient;
-  routing: EnvelopeRouting;
+  routing?: EnvelopeRouting;
+  to?: { id: string; type: "direct" | "group" };
   messageId: string;
   currentSequence: number;
   reason?: string;
@@ -77,13 +86,14 @@ export interface StreamingFailureParams {
 }
 
 export async function sendStreamingFailure(params: StreamingFailureParams): Promise<void> {
+  const routing = resolveRouting(params);
   emitStreamFailed(params.client, {
     messageId: params.messageId,
-    routing: params.routing,
+    routing,
     sequence: params.currentSequence + 1,
     reason: params.reason,
   });
   if (params.emitTyping !== false) {
-    params.client.typing(params.routing.chatId, false, params.routing.chatType);
+    params.client.typing(routing.chatId, false, routing.chatType);
   }
 }

package/src/tools-schema.ts

@@ -1,14 +1,16 @@
 import { Type, type Static } from "@sinclair/typebox";
 
-export const ClawchatGetMyProfileSchema = Type.Object({});
-export type ClawchatGetMyProfileParams = Static<typeof ClawchatGetMyProfileSchema>;
+export const ClawchatGetAccountProfileSchema = Type.Object({});
+export type ClawchatGetAccountProfileParams = Static<typeof ClawchatGetAccountProfileSchema>;
 
-export const ClawchatGetUserInfoSchema = Type.Object({
-  userId: Type.String({ description: "Target user id (required)" }),
+export const ClawchatGetUserProfileSchema = Type.Object({
+  userId: Type.String({
+    description: "Target ClawChat user id (required). Do not infer this from a nickname.",
+  }),
 });
-export type ClawchatGetUserInfoParams = Static<typeof ClawchatGetUserInfoSchema>;
+export type ClawchatGetUserProfileParams = Static<typeof ClawchatGetUserProfileSchema>;
 
-export const ClawchatListFriendsSchema = Type.Object({
+export const ClawchatListAccountFriendsSchema = Type.Object({
   page: Type.Optional(Type.Integer({ minimum: 1, description: "1-based page number (default 1)" })),
   pageSize: Type.Optional(
     Type.Integer({
@@ -18,35 +20,42 @@ export const ClawchatListFriendsSchema = Type.Object({
     }),
   ),
 });
-export type ClawchatListFriendsParams = Static<typeof ClawchatListFriendsSchema>;
+export type ClawchatListAccountFriendsParams = Static<typeof ClawchatListAccountFriendsSchema>;
 
-export const ClawchatUpdateMyProfileSchema = Type.Object({
-  nickname: Type.Optional(Type.String({ description: "New Nick Name" })),
+export const ClawchatUpdateAccountProfileSchema = Type.Object({
+  nickname: Type.Optional(Type.String({ description: "New ClawChat account nickname" })),
   avatar_url: Type.Optional(
-    Type.String({ description: "Avatar URL (use clawchat_upload_avatar first to obtain)" }),
+    Type.String({
+      description:
+        "Avatar URL for the ClawChat account profile (use clawchat_upload_avatar_image first to obtain one from a local image)",
+    }),
+  ),
+  bio: Type.Optional(
+    Type.String({ description: "New ClawChat account self-introduction / bio text" }),
   ),
-  bio: Type.Optional(Type.String({ description: "New self-introduction / bio text" })),
 });
-export type ClawchatUpdateMyProfileParams = Static<typeof ClawchatUpdateMyProfileSchema>;
+export type ClawchatUpdateAccountProfileParams = Static<
+  typeof ClawchatUpdateAccountProfileSchema
+>;
 
-export const ClawchatUploadFileSchema = Type.Object({
+export const ClawchatUploadMediaFileSchema = Type.Object({
   filePath: Type.String({
-    description: "Absolute local path of the file to upload (max 20MB)",
+    description: "Absolute local path of the media/file to upload to ClawChat (max 20MB)",
   }),
 });
-export type ClawchatUploadFileParams = Static<typeof ClawchatUploadFileSchema>;
+export type ClawchatUploadMediaFileParams = Static<typeof ClawchatUploadMediaFileSchema>;
 
-export const ClawchatUploadAvatarSchema = Type.Object({
+export const ClawchatUploadAvatarImageSchema = Type.Object({
   filePath: Type.String({
-    description: "Absolute local path of the avatar image to upload (max 20MB)",
+    description: "Absolute local path of the avatar image to upload to ClawChat (max 20MB)",
   }),
 });
-export type ClawchatUploadAvatarParams = Static<typeof ClawchatUploadAvatarSchema>;
+export type ClawchatUploadAvatarImageParams = Static<typeof ClawchatUploadAvatarImageSchema>;
 
 export const ClawchatActivateSchema = Type.Object({
   code: Type.String({
     description:
-      "The invite code (e.g. 'INV-ABC123') extracted from the user's message. " +
+      "The invite code (six uppercase letters/digits, e.g. 'A1B2C3') extracted from the user's message. " +
       "Whitespace is trimmed automatically.",
   }),
 });