@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.2

package/src/engine/gateway/reconnect.ts

@@ -1,199 +0,0 @@
-/**
- * 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

@@ -1,132 +0,0 @@
-/**
- * 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

@@ -1,156 +0,0 @@
-/**
- * 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

@@ -1,77 +0,0 @@
-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

@@ -1,77 +0,0 @@
-/**
- * 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, "\\$&");
-}