fix(gateway): keep command-list field clamping UTF-16 safe

MoerAI · MoerAI · commit 1a650b57ef65 · 2026-07-09T21:45:22.000+09:00
clampString truncated command names, descriptions, aliases, arg names/descriptions, and choice values/labels with a raw value.slice(0, maxLength). When an emoji (or other astral code point) straddles the clamp limit, the raw slice keeps a dangling high surrogate and emits a lone surrogate over the gateway commands.list protocol result. Route the clamp through the shared truncateUtf16Safe primitive so the boundary code point is dropped whole. Adds a regression test through buildCommandsListResult.
diff --git a/src/gateway/server-methods/commands-list-result.ts b/src/gateway/server-methods/commands-list-result.ts
@@ -1,6 +1,7 @@
 // Command list serialization gathers chat, skill, and plugin commands into the
 // gateway protocol result while clamping names, descriptions, aliases, and args.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
+import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 import type {
   CommandEntry,
   CommandsListResult,
@@ -36,7 +37,7 @@ type SerializedArg = NonNullable<CommandEntry["args"]>[number];
 type CommandNameSurface = "text" | "native";
 
 function clampString(value: string, maxLength: number): string {
-  return value.length > maxLength ? value.slice(0, maxLength) : value;
+  return value.length > maxLength ? truncateUtf16Safe(value, maxLength) : value;
 }
 
 function trimClampNonEmpty(value: string, maxLength: number): string | null {
diff --git a/src/gateway/server-methods/commands.test.ts b/src/gateway/server-methods/commands.test.ts
@@ -564,6 +564,33 @@ describe("commands.list handler", () => {
     }
   });
 
+  it("clamps a description without splitting a trailing surrogate pair", () => {
+    const originalCommands = [...mockChatCommands];
+    // U+1F600 is a surrogate pair; place it so it straddles the clamp limit.
+    const description = `${"d".repeat(COMMAND_DESCRIPTION_MAX_LENGTH - 1)}😀`;
+    try {
+      mockChatCommands.length = 0;
+      mockChatCommands.push({
+        key: "surrogate_boundary",
+        nativeName: "surrogate_boundary",
+        description,
+        textAliases: ["/surrogate_boundary"],
+        scope: "both",
+        category: "tools",
+      });
+
+      const clamped = requireCommand(listCommands(), "surrogate_boundary").description as string;
+
+      expect(clamped.length).toBeLessThanOrEqual(COMMAND_DESCRIPTION_MAX_LENGTH);
+      const lastUnit = clamped.charCodeAt(clamped.length - 1);
+      // A raw slice would leave a dangling high surrogate at the boundary.
+      expect(lastUnit >= 0xd800 && lastUnit <= 0xdbff).toBe(false);
+    } finally {
+      mockChatCommands.length = 0;
+      mockChatCommands.push(...originalCommands);
+    }
+  });
+
   it("rejects unknown agentId", () => {
     const { ok, error } = callHandler({ agentId: "nonexistent" });
     expect(ok).toBe(false);
