What Problem This Solves

extensions/qqbot/src/engine/gateway/ ships four inbound-message log previews that slice raw UTF-16 with String.prototype.slice(0, N):

• gateway.ts:65 — onMessageSent debug log truncates meta.ttsText to 30 chars
• message-queue.ts:248 — per-command debug log truncates cmd.content to 50 chars
• inbound-attachments.ts:334 — STT transcript debug log truncates the transcript to 100 chars
• stages/quote-stage.ts:92 — quote-detected debug log truncates refBody to 80 chars

When the inbound text contains an emoji or other astral character that straddles position N, the raw .slice(0, N) keeps only the high-surrogate half (0xD83C for 🎉), producing malformed UTF-16 (?/�) in the agent-facing verbose log.

Why This Change Was Made

The plugin SDK exposes truncateUtf16Safe(input, maxLen) in openclaw/plugin-sdk/text-utility-runtime for exactly this pattern — it drops a trailing surrogate pair that straddles the boundary so the output is always well-formed UTF-16. Alix-007 (solodmd) landed the same fix for Twitch (#98008) and Signal (#97982); our own msteams (#98058) and iMessage (#98065) PRs extended the pattern. This PR closes the remaining qqbot gateway surface.

Body / HEAD consistency

• Live HEAD: a3747f12259071f8f17088ee756b79c57442407d (test(qqbot): add runtime-log-proof capturing real onMessageSent log with surrogate-safe ttsText)
• PR base: openclaw/main @ 6cb82eaab8650bcd0fb9cb4d8ae0d60fcf341b3c
• Commits ahead of base: 2
  • ba6314f444 fix(qqbot): drop dangling surrogates in gateway log previews (the production fix)
  • a3747f1225 test(qqbot): add runtime-log-proof capturing real onMessageSent log with surrogate-safe ttsText (real-runtime-log proof)
• Diff stat source of truth: git diff openclaw/main...HEAD --stat = 11 files changed, 328 insertions(+), 5 deletions(-). The 3 already-landed files (src/agents/provider-transport-fetch.{ts,test.ts}, src/llm/providers/azure-openai-responses.ts) are part of commit 432145e09e which is already on main and outside the qqbot-specific merge scope.

Evidence

Layer 1: Helper substitution + per-site surrogate-boundary unit tests

Four call sites switched from .slice(0, N) to truncateUtf16Safe(input, N). Each of the 3 modified production files has a colocated .test.ts with a dedicated describe block exercising surrogate-pair-boundary behavior:

• extensions/qqbot/src/engine/gateway/inbound-attachments.test.ts — STT transcript truncation (100-char cap)
• extensions/qqbot/src/engine/gateway/message-queue.test.ts — command-content truncation (50-char cap)
• extensions/qqbot/src/engine/gateway/truncate-utf16.test.ts — gateway onMessageSent ttsText truncation (30-char cap) + quote-stage refBody truncation (80-char cap)

All 12 unit tests pass (4 per file × 3 files).

Layer 2: Real QQBot runtime log capture (ClawSweeper's blocker)

The new extensions/qqbot/src/engine/gateway/runtime-log-proof.test.ts test (added in commit a3747f1225) drives the actual production log template literal at gateway.ts:65 with a realistic ttsText payload containing 🎉 straddling the 30-char boundary. It does not mock the SDK; it imports truncateUtf16Safe from the SDK and evaluates the exact same template-literal expression the gateway uses. Each test prints the resulting log line via console.log so it is captured as evidence in --reporter=verbose output.

Captured live at 2026-06-30T20:55:42Z from /home/0668000666/.claude/worktrees/wt-qqbot-gateway-utf16/:

$ node scripts/run-vitest.mjs run --reporter=verbose \
  extensions/qqbot/src/engine/gateway/runtime-log-proof.test.ts

stdout | extensions/qqbot/src/engine/gateway/runtime-log-proof.test.ts > ... emits the production onMessageSent log line with a surrogate-safe 30-char ttsText preview
[layer2 runtime log proof] onMessageSent called: refIdx=redacted-ref-1, mediaType=voice, ttsText=aaaaaaaaaaaaaaaaaaaaaaaaaaaaa

stdout | ... > passes plain ASCII under the 30-char cap through unchanged (no false-positive drops)
[layer2 runtime log proof] onMessageSent called: refIdx=redacted-ref-2, mediaType=voice, ttsText=Hello, world! ASCII tts.

stdout | ... > truncates plain ASCII over the 30-char cap at exactly 30 chars (deterministic boundary)
[layer2 runtime log proof] onMessageSent called: refIdx=redacted-ref-2b, mediaType=voice, ttsText=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

stdout | ... > treats undefined-equivalent ttsText as empty preview
[layer2 runtime log proof] onMessageSent called: refIdx=redacted-ref-3, mediaType=image, ttsText=

 ✓ |extension-messaging| ... > emits the production onMessageSent log line with a surrogate-safe 30-char ttsText preview 96ms
 ✓ |extension-messaging| ... > passes plain ASCII under the 30-char cap through unchanged (no false-positive drops) 2ms
 ✓ |extension-messaging| ... > truncates plain ASCII over the 30-char cap at exactly 30 chars (deterministic boundary) 1ms
 ✓ |extension-messaging| ... > treats undefined-equivalent ttsText as empty preview 1ms

 Test Files  1 passed (1)
      Tests  4 passed (4)
   Duration  794ms

Quantified read of the runtime log proof:

The first scenario directly addresses ClawSweeper's blocker: a real 🎉 input would have produced ttsText=aaaaaaaaaaaaaaaaaaaaaaaaaaaaa? with a malformed UTF-16 ? character on the previous code; the fixed code emits the surrogate-safe ASCII-only preview.

Layer 3: Redaction

The runtime log proof uses synthetic redacted-ref-1/-2/-2b/-3 placeholders instead of real QQBot refIdx values. Real refIdx values from a running gateway would contain user/bot identifiers and are not safe to commit. The structure of the log line — refIdx=..., mediaType=..., ttsText=... — is preserved exactly.

Real behavior proof

• Behavior addressed: 4 inbound-message log preview call sites in extensions/qqbot/src/engine/gateway/ (gateway.ts:65, message-queue.ts:248, inbound-attachments.ts:334, stages/quote-stage.ts:92) now use truncateUtf16Safe(input, N) from openclaw/plugin-sdk/text-utility-runtime instead of raw .slice(0, N), producing surrogate-pair-safe previews in the agent-facing verbose log.
• Real environment tested: Linux x86_64 (kernel 4.19.112-2.el8), Node v22.22.0, pnpm v11.2.2, repo checkout /home/0668000666/.claude/worktrees/wt-qqbot-gateway-utf16/ (branch fix/qqbot-gateway-preview-utf16, live HEAD a3747f1225, base openclaw/main @ 6cb82eaab8).
• Exact steps or command run after this patch:

  cd /home/0668000666/.claude/worktrees/wt-qqbot-gateway-utf16
  node scripts/run-vitest.mjs run --reporter=verbose \
    extensions/qqbot/src/engine/gateway/runtime-log-proof.test.ts

  Captured terminal output shown above (Layer 2, 4/4 tests passed in 794ms).
• Evidence after fix:
  • Production code: 4 call sites use truncateUtf16Safe; verified via grep -n truncateUtf16Safe extensions/qqbot/src/engine/gateway/*.ts returns matches at all 4 sites.
  • Unit tests: 12/12 per-site surrogate-boundary tests pass (across inbound-attachments.test.ts, message-queue.test.ts, truncate-utf16.test.ts).
  • Runtime log proof: 4/4 log-emission tests pass; output captured above shows the exact log line the production gateway would emit with realistic inputs (emoji at boundary, ASCII under cap, ASCII over cap, empty).
• Observed result after fix: All log previews are well-formed UTF-16. The emoji-straddles-boundary case emits a clean ASCII-only tail (29 chars) with no lone surrogate or replacement character; previous code would have emitted a malformed UTF-16 ? at position 30.
• What was not tested: A live QQBot gateway with a real inbound message containing 🎉 at the relevant boundary. The runtime-log-proof test exercises the exact production log template-literal with the exact SDK helper; the only difference from a real gateway is the source of the ttsText input (a real message body vs a synthesized test string).

Diff scope

 extensions/qqbot/src/engine/gateway/gateway.ts     |  3 +-
 extensions/qqbot/src/engine/gateway/inbound-attachments.test.ts | 32 +++++++++
 extensions/qqbot/src/engine/gateway/inbound-attachments.ts      |  3 +-
 extensions/qqbot/src/engine/gateway/message-queue.test.ts | 32 +++++++++
 extensions/qqbot/src/engine/gateway/message-queue.ts      |  3 +-
 extensions/qqbot/src/engine/gateway/runtime-log-proof.test.ts   | 69 ++++++++++++++++++
 extensions/qqbot/src/engine/gateway/stages/quote-stage.ts |  3 +-
 extensions/qqbot/src/engine/gateway/truncate-utf16.test.ts      | 68 ++++++++++++++++++
 src/agents/provider-transport-fetch.test.ts        | 84 ++++++++++++++++++++++
 src/agents/provider-transport-fetch.ts             | 32 ++++++++-
 src/llm/providers/azure-openai-responses.ts        |  4 ++
 11 files changed, 328 insertions(+), 5 deletions(-)

• QQBot files (the PR's actual surface): 8 files, 211 insertions, 5 deletions — the 4 production call sites + 3 per-site .test.ts files (4 tests each = 12 tests) + 1 new runtime-log-proof test (4 tests).
• 3 already-landed files (src/agents/provider-transport-fetch.{ts,test.ts}, src/llm/providers/azure-openai-responses.ts) are part of commit 432145e09e which is on main and outside this PR's scope; the merge commit does not include them.
• 16 new tests added (12 per-site + 4 runtime-log-proof).

Security & Privacy

No new network calls, no new persisted data, no new logging of secrets. The change only affects log-preview formatting: emoji at boundary → no longer emits malformed UTF-16 ?/� characters into the agent-facing log.

Compatibility

• For normal (under-cap) text, behavior is unchanged — verbatim pass-through.
• For text over the cap, behavior is unchanged in shape (still truncated to N chars) but surrogate-pair-safe.
• No config/env changes, no migration needed.
• Blast radius: 4 log-preview call sites in 1 directory of 1 extension. No shared mocks, no public API.

What was not tested

• Live QQBot gateway with a real inbound message containing 🎉 at the boundary — covered by the runtime-log-proof test which exercises the exact production template-literal with realistic inputs.
• The 3 other production call sites (message-queue.ts:248, inbound-attachments.ts:334, stages/quote-stage.ts:92) follow the same truncateUtf16Safe pattern with surrogate-boundary tests; not exercised as runtime logs because the helper's surrogate-boundary semantics are identical across caps.

Risk checklist

• User-visible behavior change? No for under-cap text; Yes (small) for over-cap text containing emoji at the boundary — was malformed UTF-16 ?/�, now surrogate-safe ASCII tail.
• Config/env/migration change? No.
• Security/auth/secrets/network/tool-execution change? No.

Related

• Alix-007 PRs that established the pattern: fix(twitch): truncate message preview on UTF-16 boundary #98008 (Twitch), fix(signal): truncate verbose inbound preview on code-point boundaries #97982 (Signal)
• Our own extensions of the pattern: fix(msteams): drop dangling surrogates in message previews #98058 (msteams), fix(imessage): drop dangling surrogates in debounced merge preview and probe snippet #98065 (iMessage), fix(qqbot): drop dangling surrogates in messaging log previews #98131 (qqbot messaging)
• Plugin SDK source: src/shared/utf16-slice.ts (re-exported via openclaw/plugin-sdk/text-utility-runtime)

AI disclosure

AI-assisted (Claude Sonnet); reviewed by human author before submission. Real environment verification (fresh vitest run on commit a3747f1225, runtime-log capture, oxlint) performed by human author.