@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/gateway/reconnect.ts

@@ -0,0 +1,199 @@
+/**
+ * WebSocket reconnection state machine and close-code handler.
+ *
+ * Encapsulates the reconnect delay scheduling, quick-disconnect detection,
+ * and close-code interpretation that both plugin versions share.
+ *
+ * Zero external dependencies — uses only the constants from `./constants.ts`.
+ */
+
+import type { EngineLogger } from "../types.js";
+import {
+  RECONNECT_DELAYS,
+  RATE_LIMIT_DELAY,
+  MAX_RECONNECT_ATTEMPTS,
+  MAX_QUICK_DISCONNECT_COUNT,
+  QUICK_DISCONNECT_THRESHOLD,
+  GatewayCloseCode,
+} from "./constants.js";
+
+/** Actions the caller should take after processing a close event. */
+interface CloseAction {
+  /** Whether to schedule a reconnect. */
+  shouldReconnect: boolean;
+  /** Custom delay override (ms), or undefined to use the default backoff. */
+  reconnectDelay?: number;
+  /** Whether the session is invalidated and should be cleared. */
+  clearSession: boolean;
+  /** Whether the token should be refreshed before reconnecting. */
+  refreshToken: boolean;
+  /** Whether the bot is fatally blocked (offline/banned) and should stop. */
+  fatal: boolean;
+  /** Human-readable description of the close reason. */
+  reason: string;
+}
+
+/**
+ * Reconnection state machine.
+ *
+ * Usage:
+ * ```ts
+ * const rs = new ReconnectState('account-1', log);
+ * // On successful connect:
+ * rs.onConnected();
+ * // On close:
+ * const action = rs.handleClose(code);
+ * if (action.shouldReconnect) {
+ *   const delay = rs.getNextDelay(action.reconnectDelay);
+ *   setTimeout(connect, delay);
+ * }
+ * ```
+ */
+export class ReconnectState {
+  private attempts = 0;
+  private lastConnectTime = 0;
+  private quickDisconnectCount = 0;
+
+  constructor(
+    private readonly accountId: string,
+    private readonly log?: EngineLogger,
+  ) {}
+
+  /** Call when a WebSocket connection is successfully established. */
+  onConnected(): void {
+    this.attempts = 0;
+    this.lastConnectTime = Date.now();
+  }
+
+  /** Whether reconnection attempts are exhausted. */
+  isExhausted(): boolean {
+    return this.attempts >= MAX_RECONNECT_ATTEMPTS;
+  }
+
+  /**
+   * Compute the next reconnect delay and increment the attempt counter.
+   *
+   * @param customDelay Override from `CloseAction.reconnectDelay`.
+   * @returns Delay in milliseconds.
+   */
+  getNextDelay(customDelay?: number): number {
+    const delay =
+      customDelay ?? RECONNECT_DELAYS[Math.min(this.attempts, RECONNECT_DELAYS.length - 1)];
+    this.attempts++;
+    this.log?.debug?.(`Reconnecting in ${delay}ms (attempt ${this.attempts})`);
+    return delay;
+  }
+
+  /**
+   * Interpret a WebSocket close code and return the appropriate action.
+   */
+  handleClose(code: number, isAborted: boolean): CloseAction {
+    // Fatal: bot offline or banned.
+    if (
+      code === GatewayCloseCode.INSUFFICIENT_INTENTS ||
+      code === GatewayCloseCode.DISALLOWED_INTENTS
+    ) {
+      const reason =
+        code === GatewayCloseCode.INSUFFICIENT_INTENTS ? "offline/sandbox-only" : "banned";
+      this.log?.error(`Bot is ${reason}. Please contact QQ platform.`);
+      return {
+        shouldReconnect: false,
+        clearSession: false,
+        refreshToken: false,
+        fatal: true,
+        reason,
+      };
+    }
+
+    // Invalid token.
+    if (code === GatewayCloseCode.AUTH_FAILED) {
+      this.log?.info(`Invalid token (4004), will refresh token and reconnect`);
+      return {
+        shouldReconnect: !isAborted,
+        clearSession: false,
+        refreshToken: true,
+        fatal: false,
+        reason: "invalid token (4004)",
+      };
+    }
+
+    // Rate limited.
+    if (code === GatewayCloseCode.RATE_LIMITED) {
+      this.log?.info(`Rate limited (4008), waiting ${RATE_LIMIT_DELAY}ms`);
+      return {
+        shouldReconnect: !isAborted,
+        reconnectDelay: RATE_LIMIT_DELAY,
+        clearSession: false,
+        refreshToken: false,
+        fatal: false,
+        reason: "rate limited (4008)",
+      };
+    }
+
+    // Session invalid / seq invalid / session timeout.
+    if (
+      code === GatewayCloseCode.INVALID_SESSION ||
+      code === GatewayCloseCode.SEQ_OUT_OF_RANGE ||
+      code === GatewayCloseCode.SESSION_TIMEOUT
+    ) {
+      const codeDesc: Record<number, string> = {
+        [GatewayCloseCode.INVALID_SESSION]: "session no longer valid",
+        [GatewayCloseCode.SEQ_OUT_OF_RANGE]: "invalid seq on resume",
+        [GatewayCloseCode.SESSION_TIMEOUT]: "session timed out",
+      };
+      this.log?.info(`Error ${code} (${codeDesc[code]}), will re-identify`);
+      return {
+        shouldReconnect: !isAborted,
+        clearSession: true,
+        refreshToken: true,
+        fatal: false,
+        reason: codeDesc[code],
+      };
+    }
+
+    // Internal server errors.
+    if (code >= GatewayCloseCode.SERVER_ERROR_START && code <= GatewayCloseCode.SERVER_ERROR_END) {
+      this.log?.info(`Internal error (${code}), will re-identify`);
+      return {
+        shouldReconnect: !isAborted && code !== GatewayCloseCode.NORMAL,
+        clearSession: true,
+        refreshToken: true,
+        fatal: false,
+        reason: `internal error (${code})`,
+      };
+    }
+
+    // Quick disconnect detection.
+    const connectionDuration = Date.now() - this.lastConnectTime;
+    if (connectionDuration < QUICK_DISCONNECT_THRESHOLD && this.lastConnectTime > 0) {
+      this.quickDisconnectCount++;
+      this.log?.debug?.(
+        `Quick disconnect detected (${connectionDuration}ms), count: ${this.quickDisconnectCount}`,
+      );
+
+      if (this.quickDisconnectCount >= MAX_QUICK_DISCONNECT_COUNT) {
+        this.log?.error(`Too many quick disconnects. This may indicate a permission issue.`);
+        this.quickDisconnectCount = 0;
+        return {
+          shouldReconnect: !isAborted && code !== 1000,
+          reconnectDelay: RATE_LIMIT_DELAY,
+          clearSession: false,
+          refreshToken: false,
+          fatal: false,
+          reason: "too many quick disconnects",
+        };
+      }
+    } else {
+      this.quickDisconnectCount = 0;
+    }
+
+    // Default: reconnect with backoff.
+    return {
+      shouldReconnect: !isAborted && code !== GatewayCloseCode.NORMAL,
+      clearSession: false,
+      refreshToken: false,
+      fatal: false,
+      reason: `close code ${code}`,
+    };
+  }
+}

package/src/engine/gateway/stages/access-stage.ts

@@ -0,0 +1,132 @@
+/**
+ * Access stage — resolves routing target + runs access control.
+ *
+ * Split from the pipeline so it is trivially unit-testable: given a raw
+ * event and the runtime's routing info, the stage returns either:
+ *   - `{ kind: "allow", ... }` — proceed through the rest of the pipeline
+ *   - `{ kind: "block", context }` — short-circuit; the caller returns
+ *     `context` directly to its own caller.
+ */
+
+import { resolveQQBotAccess, type QQBotAccessResult } from "../../access/index.js";
+import type { InboundContext, InboundPipelineDeps } from "../inbound-context.js";
+import type { QueuedMessage } from "../message-queue.js";
+import { buildBlockedInboundContext } from "./stub-contexts.js";
+
+// ─────────────────────────── Types ───────────────────────────
+
+interface AccessStageAllow {
+  kind: "allow";
+  isGroupChat: boolean;
+  peerId: string;
+  qualifiedTarget: string;
+  fromAddress: string;
+  route: { sessionKey: string; accountId: string; agentId?: string };
+  access: QQBotAccessResult;
+}
+
+interface AccessStageBlock {
+  kind: "block";
+  context: InboundContext;
+}
+
+type AccessStageResult = AccessStageAllow | AccessStageBlock;
+
+// ─────────────────────────── Stage ───────────────────────────
+
+/**
+ * Resolve the routing target, walk the access policy, and decide whether
+ * the inbound message should proceed to the rest of the pipeline.
+ */
+export function runAccessStage(event: QueuedMessage, deps: InboundPipelineDeps): AccessStageResult {
+  const { account, cfg, runtime, log } = deps;
+
+  const isGroupChat = event.type === "guild" || event.type === "group";
+  const peerId = resolvePeerId(event, isGroupChat);
+  const qualifiedTarget = buildQualifiedTarget(event, isGroupChat);
+
+  const route = runtime.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: "qqbot",
+    accountId: account.accountId,
+    peer: { kind: isGroupChat ? "group" : "direct", id: peerId },
+  });
+
+  const access = resolveQQBotAccess({
+    isGroup: isGroupChat,
+    senderId: event.senderId,
+    allowFrom: account.config?.allowFrom,
+    groupAllowFrom: account.config?.groupAllowFrom,
+    dmPolicy: account.config?.dmPolicy,
+    groupPolicy: account.config?.groupPolicy,
+  });
+
+  if (access.decision !== "allow") {
+    log?.info(
+      `Blocked qqbot inbound: decision=${access.decision} reasonCode=${access.reasonCode} ` +
+        `reason=${access.reason} senderId=${event.senderId} ` +
+        `accountId=${account.accountId} isGroup=${isGroupChat}`,
+    );
+    return {
+      kind: "block",
+      context: buildBlockedInboundContext({
+        event,
+        route,
+        isGroupChat,
+        peerId,
+        qualifiedTarget,
+        fromAddress: qualifiedTarget,
+        access,
+      }),
+    };
+  }
+
+  return {
+    kind: "allow",
+    isGroupChat,
+    peerId,
+    qualifiedTarget,
+    fromAddress: qualifiedTarget,
+    route,
+    access,
+  };
+}
+
+// ─────────────────────────── Internal helpers ───────────────────────────
+
+function resolvePeerId(event: QueuedMessage, isGroupChat: boolean): string {
+  if (event.type === "guild") {
+    return event.channelId ?? "unknown";
+  }
+  if (event.type === "group") {
+    return event.groupOpenid ?? "unknown";
+  }
+  if (isGroupChat) {
+    return "unknown";
+  } // defensive, should never hit
+  return event.senderId;
+}
+
+function buildQualifiedTarget(event: QueuedMessage, isGroupChat: boolean): string {
+  if (isGroupChat) {
+    return event.type === "guild"
+      ? `qqbot:channel:${event.channelId}`
+      : `qqbot:group:${event.groupOpenid}`;
+  }
+  return event.type === "dm" ? `qqbot:dm:${event.guildId}` : `qqbot:c2c:${event.senderId}`;
+}
+
+/**
+ * Decide whether the access decision permits running text-based control
+ * commands. Placed in the access stage because the rule is an
+ * access-policy derivative, not a gate derivative.
+ */
+export function resolveCommandAuthorized(access: QQBotAccessResult): boolean {
+  return (
+    access.reasonCode === "dm_policy_open" ||
+    access.reasonCode === "dm_policy_allowlisted" ||
+    (access.reasonCode === "group_policy_allowed" &&
+      access.effectiveGroupAllowFrom.length > 0 &&
+      access.groupPolicy === "allowlist")
+  );
+}

package/src/engine/gateway/stages/assembly-stage.ts

@@ -0,0 +1,156 @@
+/**
+ * Assembly stage — build the user-turn string the AI sees.
+ *
+ * Responsible for:
+ *   - Rendering merged turns (preceding messages in a begin/end block
+ *     + a "current" message).
+ *   - Attaching the sender label + (@you) suffix for group chat.
+ *   - Prepending the group's buffered history via
+ *     {@link buildPendingHistoryContext} when the current turn is
+ *     `@`-activated.
+ *   - Handing out the plain `agentBody` for DM-style turns.
+ *
+ * The envelope rendering (Web UI body + dynamic ctx block) lives in
+ * `envelope-stage.ts`; this stage only produces text that the model
+ * sees directly.
+ */
+
+import {
+  buildMergedMessageContext,
+  formatAttachmentTags,
+  formatMessageContent,
+  type HistoryEntry,
+} from "../../group/history.js";
+import type { InboundGroupInfo, InboundPipelineDeps } from "../inbound-context.js";
+import type { QueuedMessage } from "../message-queue.js";
+
+// ─────────────────────────── buildUserMessage ───────────────────────────
+
+interface BuildUserMessageInput {
+  event: QueuedMessage;
+  userContent: string;
+  quotePart: string;
+  isGroupChat: boolean;
+  groupInfo?: InboundGroupInfo;
+}
+
+/**
+ * Compose the user-turn string. For merged group turns, renders a
+ * preceding block and a current-message suffix; for single turns,
+ * prefixes the sender label and (@you) suffix as appropriate.
+ */
+export function buildUserMessage(input: BuildUserMessageInput): string {
+  const { event, userContent, quotePart, isGroupChat, groupInfo } = input;
+
+  // ---- Merged group turn ----
+  if (groupInfo?.isMerged && groupInfo.mergedMessages?.length) {
+    const preceding = groupInfo.mergedMessages.slice(0, -1);
+    const lastMsg = groupInfo.mergedMessages[groupInfo.mergedMessages.length - 1];
+    const atYouTag = groupInfo.gate.effectiveWasMentioned ? " (@you)" : "";
+
+    const envelopeParts = preceding.map((m) => `[${formatSenderLabel(m)}] ${formatSub(m)}`);
+    const lastPart = `[${formatSenderLabel(lastMsg)}] ${formatSub(lastMsg)}${atYouTag}`;
+
+    return buildMergedMessageContext({
+      precedingParts: envelopeParts,
+      currentMessage: lastPart,
+    });
+  }
+
+  // ---- Single-message turn ----
+  const isAtYouTag = isGroupChat ? (groupInfo?.gate.effectiveWasMentioned ? " (@you)" : "") : "";
+  const senderPrefix =
+    event.type === "group" ? `[${formatSenderLabelFrom(event.senderName, event.senderId)}] ` : "";
+
+  return senderPrefix
+    ? `${senderPrefix}${quotePart}${userContent}${isAtYouTag}`
+    : `${quotePart}${userContent}`;
+}
+
+// ─────────────────────────── buildAgentBody ───────────────────────────
+
+interface BuildAgentBodyInput {
+  event: QueuedMessage;
+  userContent: string;
+  userMessage: string;
+  dynamicCtx: string;
+  isGroupChat: boolean;
+  groupInfo?: InboundGroupInfo;
+  deps: InboundPipelineDeps;
+}
+
+/**
+ * Compose the final `agentBody` the AI receives.
+ *
+ * Prepends buffered non-@ chatter via
+ * {@link buildPendingHistoryContext} when the current turn is
+ * `@`-activated in a group. Slash-commands bypass all decoration so
+ * the command parser sees verbatim input.
+ */
+export function buildAgentBody(input: BuildAgentBodyInput): string {
+  const { event, userContent, userMessage, dynamicCtx, groupInfo, deps } = input;
+
+  // Slash commands: strip all decoration so the command parser sees raw input.
+  if (userContent.startsWith("/")) {
+    return userContent;
+  }
+
+  const base = `${dynamicCtx}${userMessage}`;
+
+  // Non-group or group-without-history: no mixing in.
+  if (event.type !== "group" || !event.groupOpenid || !deps.groupHistories || !groupInfo) {
+    return base;
+  }
+
+  const envelopeOpts = deps.runtime.channel.reply.resolveEnvelopeFormatOptions(deps.cfg);
+  return deps.adapters.history.buildPendingHistoryContext({
+    historyMap: deps.groupHistories,
+    historyKey: event.groupOpenid,
+    limit: groupInfo.historyLimit,
+    currentMessage: base,
+    formatEntry: (entry) => formatHistoryEntry(entry as HistoryEntry, deps, envelopeOpts),
+  });
+}
+
+// ─────────────────────────── Internal ───────────────────────────
+
+function formatSub(m: QueuedMessage): string {
+  return formatMessageContent({
+    content: m.content ?? "",
+    chatType: m.type,
+    mentions: m.mentions as never,
+    attachments: m.attachments,
+  });
+}
+
+function formatSenderLabel(m: QueuedMessage): string {
+  return formatSenderLabelFrom(m.senderName, m.senderId);
+}
+
+/**
+ * Render a "Nick (openid)" label. When `name` already includes `id`
+ * (e.g. the label was pre-formatted upstream), avoid double-wrapping.
+ */
+function formatSenderLabelFrom(name: string | undefined, id: string): string {
+  if (!name) {
+    return id;
+  }
+  return name.includes(id) ? name : `${name} (${id})`;
+}
+
+function formatHistoryEntry(
+  entry: HistoryEntry,
+  deps: InboundPipelineDeps,
+  envelopeOpts: unknown,
+): string {
+  const attachmentDesc = formatAttachmentTags(entry.attachments);
+  const bodyWithAttachments = attachmentDesc ? `${entry.body} ${attachmentDesc}` : entry.body;
+  return deps.runtime.channel.reply.formatInboundEnvelope({
+    channel: "qqbot",
+    from: entry.sender,
+    timestamp: entry.timestamp,
+    body: bodyWithAttachments,
+    chatType: "group",
+    envelope: envelopeOpts,
+  });
+}

package/src/engine/gateway/stages/content-stage.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import type { QueuedMessage } from "../message-queue.js";
+import { buildUserContent } from "./content-stage.js";
+
+function makeEvent(partial: Partial<QueuedMessage> = {}): QueuedMessage {
+  return {
+    type: "group",
+    senderId: "U1",
+    content: "hello",
+    messageId: "M1",
+    timestamp: "2025-01-01T00:00:00.000Z",
+    groupOpenid: "G1",
+    ...partial,
+  };
+}
+
+describe("content-stage", () => {
+  describe("buildUserContent", () => {
+    it("returns plain content when no voice / no mentions", () => {
+      const out = buildUserContent({
+        event: makeEvent({ content: "plain" }),
+        attachmentInfo: "",
+        voiceTranscripts: [],
+      });
+      expect(out.parsedContent).toBe("plain");
+      expect(out.userContent).toBe("plain");
+    });
+
+    it("appends attachmentInfo after content", () => {
+      const out = buildUserContent({
+        event: makeEvent({ content: "see" }),
+        attachmentInfo: " [img]",
+        voiceTranscripts: [],
+      });
+      expect(out.userContent).toBe("see [img]");
+    });
+
+    it("interleaves voice transcripts on their own line", () => {
+      const out = buildUserContent({
+        event: makeEvent({ content: "hi" }),
+        attachmentInfo: "",
+        voiceTranscripts: ["hello world"],
+      });
+      // formatVoiceText renders "[Voice message] …" or "[Voice N] …" — the
+      // important assertion is that voice text ends up in userContent.
+      expect(out.userContent).toContain("hi");
+      expect(out.userContent).toContain("hello world");
+      expect(out.userContent.length).toBeGreaterThan(out.parsedContent.length);
+    });
+
+    it("strips <@bot> mention tags in group chats", () => {
+      const out = buildUserContent({
+        event: makeEvent({
+          type: "group",
+          content: "<@BOT> help",
+          mentions: [{ member_openid: "BOT", is_you: true }],
+        }),
+        attachmentInfo: "",
+        voiceTranscripts: [],
+      });
+      expect(out.userContent.trim()).toBe("help");
+    });
+
+    it("replaces <@user> with @nickname in DMs", () => {
+      const out = buildUserContent({
+        event: makeEvent({
+          type: "c2c",
+          content: "hi <@U2> there",
+          mentions: [{ member_openid: "U2", username: "Alice" }],
+        }),
+        attachmentInfo: "",
+        voiceTranscripts: [],
+      });
+      expect(out.userContent).toBe("hi @Alice there");
+    });
+  });
+});

package/src/engine/gateway/stages/content-stage.ts

@@ -0,0 +1,77 @@
+/**
+ * Content stage — build the user-visible message body.
+ *
+ * Responsible for:
+ *   1. Parsing QQ emoji tags (`<faceType=...>` → `[Emoji: name]`)
+ *   2. Appending attachment info + voice transcripts
+ *   3. Stripping `<@openid>` mention tags in group messages
+ *   4. Replacing `<@openid>` → `@nickname` in DMs (best-effort)
+ *
+ * Pure function: same input → same output, no I/O.
+ */
+
+import { stripMentionText } from "../../group/mention.js";
+import { parseFaceTags } from "../../utils/text-parsing.js";
+import { formatVoiceText } from "../../utils/voice-text.js";
+import type { QueuedMention, QueuedMessage } from "../message-queue.js";
+
+// ─────────────────────────── Types ───────────────────────────
+
+/** Input for {@link buildUserContent}. */
+interface ContentStageInput {
+  event: QueuedMessage;
+  /** `attachmentInfo` from the attachment stage — appended verbatim. */
+  attachmentInfo: string;
+  /** Voice transcripts collected from the attachment stage. */
+  voiceTranscripts: string[];
+}
+
+/** Output of {@link buildUserContent}. */
+interface ContentStageOutput {
+  /** `parseFaceTags(event.content)`. */
+  parsedContent: string;
+  /** Full user-visible content (parsed + voice + attachments + mention cleanup). */
+  userContent: string;
+}
+
+// ─────────────────────────── Stage ───────────────────────────
+
+/**
+ * Build both the raw-parsed content and the fully composed user-visible
+ * body that downstream stages feed to the AI and to the envelope.
+ */
+export function buildUserContent(input: ContentStageInput): ContentStageOutput {
+  const { event, attachmentInfo, voiceTranscripts } = input;
+
+  const parsedContent = parseFaceTags(event.content);
+  const voiceText = formatVoiceText(voiceTranscripts);
+
+  let userContent = voiceText
+    ? (parsedContent.trim() ? `${parsedContent}\n${voiceText}` : voiceText) + attachmentInfo
+    : parsedContent + attachmentInfo;
+
+  // Mention cleanup — only for events with mentions attached.
+  if (event.type === "group" && event.mentions?.length) {
+    userContent = stripMentionText(userContent, event.mentions as never) ?? userContent;
+  } else if (event.mentions?.length) {
+    userContent = replaceMentionsWithNicknames(userContent, event.mentions);
+  }
+
+  return { parsedContent, userContent };
+}
+
+// ─────────────────────────── Internal ───────────────────────────
+
+function replaceMentionsWithNicknames(text: string, mentions: QueuedMention[]): string {
+  let out = text;
+  for (const m of mentions) {
+    if (m.member_openid && m.username) {
+      out = out.replace(new RegExp(`<@${escapeRegex(m.member_openid)}>`, "g"), `@${m.username}`);
+    }
+  }
+  return out;
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}