@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.2

package/src/engine/gateway/constants.ts

@@ -1,117 +0,0 @@
-/**
- * QQ Bot WebSocket Gateway protocol constants.
- *
- * Extracted from `gateway.ts` to share between both plugin versions.
- * Zero external dependencies.
- */
-
-/** QQ Bot WebSocket intents grouped by permission level. */
-const INTENTS = {
-  GUILDS: 1 << 0,
-  GUILD_MEMBERS: 1 << 1,
-  PUBLIC_GUILD_MESSAGES: 1 << 30,
-  DIRECT_MESSAGE: 1 << 12,
-  GROUP_AND_C2C: 1 << 25,
-  /** Button interaction callbacks (INTERACTION_CREATE). */
-  INTERACTION: 1 << 26,
-} as const;
-
-/** Full intent mask: groups + DMs + channels + interaction. */
-export const FULL_INTENTS =
-  INTENTS.PUBLIC_GUILD_MESSAGES |
-  INTENTS.DIRECT_MESSAGE |
-  INTENTS.GROUP_AND_C2C |
-  INTENTS.INTERACTION;
-
-/** Exponential backoff delays for reconnection attempts (ms). */
-export const RECONNECT_DELAYS = [1000, 2000, 5000, 10000, 30000, 60000] as const;
-
-/** Delay after receiving a rate-limit close code (ms). */
-export const RATE_LIMIT_DELAY = 60000;
-
-/** Maximum reconnection attempts before giving up. */
-export const MAX_RECONNECT_ATTEMPTS = 100;
-
-/** How many quick disconnects before warning about permissions. */
-export const MAX_QUICK_DISCONNECT_COUNT = 3;
-
-/** A disconnect within this window (ms) counts as "quick". */
-export const QUICK_DISCONNECT_THRESHOLD = 5000;
-
-// ============ Opcode Constants ============
-
-/** Gateway opcodes used by the QQ Bot WebSocket protocol. */
-export const GatewayOp = {
-  /** Server → Client: Dispatch event (type + data). */
-  DISPATCH: 0,
-  /** Client → Server: Heartbeat. */
-  HEARTBEAT: 1,
-  /** Client → Server: Identify (initial auth). */
-  IDENTIFY: 2,
-  /** Client → Server: Resume a dropped session. */
-  RESUME: 6,
-  /** Server → Client: Request client to reconnect. */
-  RECONNECT: 7,
-  /** Server → Client: Invalid session. */
-  INVALID_SESSION: 9,
-  /** Server → Client: Hello (heartbeat interval). */
-  HELLO: 10,
-  /** Server → Client: Heartbeat ACK. */
-  HEARTBEAT_ACK: 11,
-} as const;
-
-// ============ Close Codes ============
-
-/** WebSocket close codes used by the QQ Gateway. */
-export const GatewayCloseCode = {
-  /** Normal closure — do not reconnect. */
-  NORMAL: 1000,
-  /** Authentication failed — refresh token then reconnect. */
-  AUTH_FAILED: 4004,
-  /** Session invalid — clear session, refresh token, reconnect. */
-  INVALID_SESSION: 4006,
-  /** Sequence number out of range — clear session, refresh token, reconnect. */
-  SEQ_OUT_OF_RANGE: 4007,
-  /** Rate limited — wait before reconnecting. */
-  RATE_LIMITED: 4008,
-  /** Session timed out — clear session, refresh token, reconnect. */
-  SESSION_TIMEOUT: 4009,
-  /** Server internal error (range start) — clear session, refresh token, reconnect. */
-  SERVER_ERROR_START: 4900,
-  /** Server internal error (range end). */
-  SERVER_ERROR_END: 4913,
-  /** Insufficient intents — fatal, do not reconnect. */
-  INSUFFICIENT_INTENTS: 4914,
-  /** Disallowed intents — fatal, do not reconnect. */
-  DISALLOWED_INTENTS: 4915,
-} as const;
-
-// ============ Dispatch Event Types ============
-
-/** Event type strings dispatched under opcode 0 (DISPATCH). */
-export const GatewayEvent = {
-  READY: "READY",
-  RESUMED: "RESUMED",
-  C2C_MESSAGE_CREATE: "C2C_MESSAGE_CREATE",
-  AT_MESSAGE_CREATE: "AT_MESSAGE_CREATE",
-  DIRECT_MESSAGE_CREATE: "DIRECT_MESSAGE_CREATE",
-  /** Group message that explicitly @-mentions the bot. */
-  GROUP_AT_MESSAGE_CREATE: "GROUP_AT_MESSAGE_CREATE",
-  /**
-   * Group message that does NOT mention the bot. Still dispatched to the
-   * pipeline so the group history buffer and the `requireMention=false`
-   * path can observe it.
-   */
-  GROUP_MESSAGE_CREATE: "GROUP_MESSAGE_CREATE",
-  INTERACTION_CREATE: "INTERACTION_CREATE",
-} as const;
-
-// ============ Interaction Type Constants ============
-
-/** Interaction sub-types carried in `InteractionEvent.data.type`. */
-export const InteractionType = {
-  /** Remote config query — bot reports its current claw_cfg snapshot. */
-  CONFIG_QUERY: 2001,
-  /** Remote config update — caller pushes new settings. */
-  CONFIG_UPDATE: 2002,
-} as const;

package/src/engine/gateway/event-dispatcher.ts

@@ -1,177 +0,0 @@
-/**
- * Event dispatcher — convert raw WebSocket op=0 events into QueuedMessage objects.
- *
- * Pure mapping logic with zero side effects (except known-user recording).
- * Independently testable.
- */
-
-import { recordKnownUser } from "../session/known-users.js";
-import type { InteractionEvent } from "../types.js";
-import { parseRefIndices } from "../utils/text-parsing.js";
-import { readOptionalMessageSceneExt } from "./codec.js";
-import { GatewayEvent } from "./constants.js";
-import type { QueuedMessage } from "./message-queue.js";
-import type {
-  C2CMessageEvent,
-  GuildMessageEvent,
-  GroupMessageEvent,
-  EngineLogger,
-} from "./types.js";
-
-// ============ Dispatch result ============
-
-type DispatchResult =
-  | { action: "ready"; data: unknown; sessionId: string }
-  | { action: "resumed"; data: unknown }
-  | { action: "message"; msg: QueuedMessage }
-  | { action: "interaction"; event: InteractionEvent }
-  | { action: "ignore" };
-
-// ============ dispatchEvent ============
-
-/**
- * Map a raw op=0 event into a structured dispatch result.
- *
- * Returns "message" for events that should be queued for processing,
- * "ready"/"resumed" for session lifecycle events, and "ignore" otherwise.
- */
-export function dispatchEvent(
-  eventType: string,
-  data: unknown,
-  accountId: string,
-  _log?: EngineLogger,
-): DispatchResult {
-  if (eventType === GatewayEvent.READY) {
-    const d = data as { session_id: string };
-    return { action: "ready", data, sessionId: d.session_id };
-  }
-
-  if (eventType === GatewayEvent.RESUMED) {
-    return { action: "resumed", data };
-  }
-
-  if (eventType === GatewayEvent.C2C_MESSAGE_CREATE) {
-    const ev = data as C2CMessageEvent;
-    recordKnownUser({
-      openid: ev.author.user_openid,
-      type: "c2c",
-      accountId,
-    });
-    const refs = parseRefIndices(ev.message_scene?.ext, ev.message_type, ev.msg_elements);
-    return {
-      action: "message",
-      msg: {
-        type: "c2c",
-        senderId: ev.author.user_openid,
-        content: ev.content,
-        messageId: ev.id,
-        timestamp: ev.timestamp,
-        attachments: ev.attachments,
-        refMsgIdx: refs.refMsgIdx,
-        msgIdx: refs.msgIdx,
-        msgType: ev.message_type,
-        msgElements: ev.msg_elements,
-      },
-    };
-  }
-
-  if (eventType === GatewayEvent.AT_MESSAGE_CREATE) {
-    const ev = data as GuildMessageEvent;
-    const refs = parseRefIndices(
-      readOptionalMessageSceneExt(ev as unknown as Record<string, unknown>),
-    );
-    return {
-      action: "message",
-      msg: {
-        type: "guild",
-        senderId: ev.author.id,
-        senderName: ev.author.username,
-        content: ev.content,
-        messageId: ev.id,
-        timestamp: ev.timestamp,
-        channelId: ev.channel_id,
-        guildId: ev.guild_id,
-        attachments: ev.attachments,
-        refMsgIdx: refs.refMsgIdx,
-        msgIdx: refs.msgIdx,
-      },
-    };
-  }
-
-  if (eventType === GatewayEvent.DIRECT_MESSAGE_CREATE) {
-    const ev = data as GuildMessageEvent;
-    const refs = parseRefIndices(
-      readOptionalMessageSceneExt(ev as unknown as Record<string, unknown>),
-    );
-    return {
-      action: "message",
-      msg: {
-        type: "dm",
-        senderId: ev.author.id,
-        senderName: ev.author.username,
-        content: ev.content,
-        messageId: ev.id,
-        timestamp: ev.timestamp,
-        guildId: ev.guild_id,
-        attachments: ev.attachments,
-        refMsgIdx: refs.refMsgIdx,
-        msgIdx: refs.msgIdx,
-      },
-    };
-  }
-
-  if (eventType === GatewayEvent.GROUP_AT_MESSAGE_CREATE) {
-    return { action: "message", msg: buildGroupQueuedMessage(data, accountId, eventType) };
-  }
-
-  if (eventType === GatewayEvent.GROUP_MESSAGE_CREATE) {
-    return { action: "message", msg: buildGroupQueuedMessage(data, accountId, eventType) };
-  }
-
-  if (eventType === GatewayEvent.INTERACTION_CREATE) {
-    return { action: "interaction", event: data as InteractionEvent };
-  }
-
-  return { action: "ignore" };
-}
-
-/**
- * Build a {@link QueuedMessage} from a raw QQ group event payload.
- *
- * Used for both `GROUP_AT_MESSAGE_CREATE` (bot was @-ed) and
- * `GROUP_MESSAGE_CREATE` (non-@ background chatter). The only difference
- * between the two is the carried `eventType` — downstream gating uses
- * that to decide whether to treat the message as a bot-directed turn.
- */
-function buildGroupQueuedMessage(
-  data: unknown,
-  accountId: string,
-  eventType: string,
-): QueuedMessage {
-  const ev = data as GroupMessageEvent;
-  recordKnownUser({
-    openid: ev.author.member_openid,
-    type: "group",
-    groupOpenid: ev.group_openid,
-    accountId,
-  });
-  const refs = parseRefIndices(ev.message_scene?.ext, ev.message_type, ev.msg_elements);
-  return {
-    type: "group",
-    senderId: ev.author.member_openid,
-    senderName: ev.author.username,
-    senderIsBot: ev.author.bot,
-    content: ev.content,
-    messageId: ev.id,
-    timestamp: ev.timestamp,
-    groupOpenid: ev.group_openid,
-    attachments: ev.attachments,
-    refMsgIdx: refs.refMsgIdx,
-    msgIdx: refs.msgIdx,
-    msgType: ev.message_type,
-    msgElements: ev.msg_elements,
-    eventType,
-    mentions: ev.mentions,
-    messageScene: ev.message_scene,
-  };
-}

package/src/engine/gateway/gateway-connection.ts

@@ -1,371 +0,0 @@
-/**
- * GatewayConnection — WebSocket lifecycle, heartbeat, reconnect, and session persistence.
- *
- * Encapsulates all connection state as class fields (replaces 11 closure variables).
- * Event handling and message processing are delegated to injected handlers.
- */
-
-import WebSocket from "ws";
-import {
-  trySlashCommand,
-  type SlashCommandHandlerContext,
-} from "../commands/slash-command-handler.js";
-import {
-  clearTokenCache,
-  getAccessToken,
-  getGatewayUrl,
-  getPluginUserAgent,
-  startBackgroundTokenRefresh,
-  stopBackgroundTokenRefresh,
-} from "../messaging/sender.js";
-import { flushRefIndex } from "../ref/store.js";
-import { flushKnownUsers } from "../session/known-users.js";
-import { clearSession, loadSession, saveSession } from "../session/session-store.js";
-import type { InteractionEvent } from "../types.js";
-import { decodeGatewayMessageData } from "./codec.js";
-import { FULL_INTENTS, RATE_LIMIT_DELAY, GatewayOp } from "./constants.js";
-import { dispatchEvent } from "./event-dispatcher.js";
-import { createMessageQueue, type QueuedMessage } from "./message-queue.js";
-import { ReconnectState } from "./reconnect.js";
-import type { GatewayAccount, EngineLogger, GatewayPluginRuntime, WSPayload } from "./types.js";
-
-// ============ Connection context ============
-
-interface GatewayConnectionContext {
-  account: GatewayAccount;
-  abortSignal: AbortSignal;
-  cfg: unknown;
-  log?: EngineLogger;
-  runtime: GatewayPluginRuntime;
-  onReady?: (data: unknown) => void;
-  /** Called when a RESUMED event is received (reconnect success). */
-  onResumed?: (data: unknown) => void;
-  onError?: (error: Error) => void;
-  /** Process a queued message (inbound pipeline → outbound dispatch). */
-  handleMessage: (event: QueuedMessage) => Promise<void>;
-  /** Called when an INTERACTION_CREATE event is received (e.g. approval button clicks). */
-  onInteraction?: (event: InteractionEvent) => void;
-}
-
-// ============ GatewayConnection ============
-
-export class GatewayConnection {
-  // ---- Connection state ----
-  private isAborted = false;
-  private currentWs: WebSocket | null = null;
-  private heartbeatInterval: ReturnType<typeof setInterval> | null = null;
-  private sessionId: string | null = null;
-  private lastSeq: number | null = null;
-  private isConnecting = false;
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-  private shouldRefreshToken = false;
-
-  private readonly reconnect: ReconnectState;
-  private readonly msgQueue;
-  private readonly ctx: GatewayConnectionContext;
-
-  constructor(ctx: GatewayConnectionContext) {
-    this.ctx = ctx;
-    this.reconnect = new ReconnectState(ctx.account.accountId, ctx.log);
-    this.msgQueue = createMessageQueue({
-      accountId: ctx.account.accountId,
-      log: ctx.log,
-      isAborted: () => this.isAborted,
-    });
-  }
-
-  /** Start the connection loop. Resolves when abortSignal fires. */
-  async start(): Promise<void> {
-    this.restoreSession();
-    this.registerAbortHandler();
-    await this.connect();
-    return new Promise<void>((resolve) => {
-      this.ctx.abortSignal.addEventListener("abort", () => resolve());
-    });
-  }
-
-  // ============ Session persistence ============
-
-  private restoreSession(): void {
-    const { account, log } = this.ctx;
-    const saved = loadSession(account.accountId, account.appId);
-    if (saved) {
-      this.sessionId = saved.sessionId;
-      this.lastSeq = saved.lastSeq;
-      log?.info(`Restored session: sessionId=${this.sessionId}, lastSeq=${this.lastSeq}`);
-    }
-  }
-
-  private saveCurrentSession(): void {
-    const { account } = this.ctx;
-    if (!this.sessionId) {
-      return;
-    }
-    saveSession({
-      sessionId: this.sessionId,
-      lastSeq: this.lastSeq,
-      lastConnectedAt: Date.now(),
-      intentLevelIndex: 0,
-      accountId: account.accountId,
-      savedAt: Date.now(),
-      appId: account.appId,
-    });
-  }
-
-  // ============ Abort + cleanup ============
-
-  private registerAbortHandler(): void {
-    const { account, abortSignal, log: _log } = this.ctx;
-    abortSignal.addEventListener("abort", () => {
-      this.isAborted = true;
-      if (this.reconnectTimer) {
-        clearTimeout(this.reconnectTimer);
-        this.reconnectTimer = null;
-      }
-      this.cleanup();
-      stopBackgroundTokenRefresh(account.appId);
-      flushKnownUsers();
-      flushRefIndex();
-    });
-  }
-
-  private cleanup(): void {
-    if (this.heartbeatInterval) {
-      clearInterval(this.heartbeatInterval);
-      this.heartbeatInterval = null;
-    }
-    if (
-      this.currentWs &&
-      (this.currentWs.readyState === WebSocket.OPEN ||
-        this.currentWs.readyState === WebSocket.CONNECTING)
-    ) {
-      this.currentWs.close();
-    }
-    this.currentWs = null;
-  }
-
-  // ============ Reconnect ============
-
-  private scheduleReconnect(customDelay?: number): void {
-    const { account: _account, log } = this.ctx;
-    if (this.isAborted || this.reconnect.isExhausted()) {
-      log?.error(`Max reconnect attempts reached or aborted`);
-      return;
-    }
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-    const delay = this.reconnect.getNextDelay(customDelay);
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      if (!this.isAborted) {
-        void this.connect();
-      }
-    }, delay);
-  }
-
-  // ============ Connect ============
-
-  private async connect(): Promise<void> {
-    const { account, log } = this.ctx;
-
-    if (this.isConnecting) {
-      log?.debug?.(`Already connecting, skip`);
-      return;
-    }
-    this.isConnecting = true;
-
-    try {
-      this.cleanup();
-      if (this.shouldRefreshToken) {
-        log?.debug?.(`Refreshing token...`);
-        clearTokenCache(account.appId);
-        this.shouldRefreshToken = false;
-      }
-
-      const accessToken = await getAccessToken(account.appId, account.clientSecret);
-      log?.info(`✅ Access token obtained successfully`);
-      const gatewayUrl = await getGatewayUrl(accessToken, account.appId);
-      log?.info(`Connecting to ${gatewayUrl}`);
-
-      const ws = new WebSocket(gatewayUrl, {
-        headers: { "User-Agent": getPluginUserAgent() },
-      });
-      this.currentWs = ws;
-
-      // ---- Slash command interception ----
-      const slashCtx: SlashCommandHandlerContext = {
-        account,
-        log,
-        getMessagePeerId: (msg) => this.msgQueue.getMessagePeerId(msg),
-        getQueueSnapshot: (peerId) => this.msgQueue.getSnapshot(peerId),
-      };
-
-      const trySlashCommandOrEnqueue = async (msg: QueuedMessage): Promise<void> => {
-        const result = await trySlashCommand(msg, slashCtx);
-        if (result === "enqueue") {
-          this.msgQueue.enqueue(msg);
-        } else if (result === "urgent") {
-          const peerId = this.msgQueue.getMessagePeerId(msg);
-          this.msgQueue.clearUserQueue(peerId);
-          this.msgQueue.executeImmediate(msg);
-        }
-        // "handled" — command executed, nothing to queue.
-      };
-
-      // ---- WebSocket: open ----
-      ws.on("open", () => {
-        log?.info(`WebSocket connected`);
-        this.isConnecting = false;
-        this.reconnect.onConnected();
-        this.msgQueue.startProcessor(this.ctx.handleMessage);
-        startBackgroundTokenRefresh(account.appId, account.clientSecret, { log });
-      });
-
-      // ---- WebSocket: message ----
-      ws.on("message", async (data) => {
-        try {
-          const rawData = decodeGatewayMessageData(data);
-          const payload = JSON.parse(rawData) as WSPayload;
-          const { op, d, s, t } = payload;
-
-          if (s) {
-            this.lastSeq = s;
-            this.saveCurrentSession();
-          }
-
-          switch (op) {
-            case GatewayOp.HELLO:
-              this.handleHello(ws, d, accessToken);
-              break;
-
-            case GatewayOp.DISPATCH: {
-              log?.debug?.(`Dispatch event: t=${t}, d=${JSON.stringify(d)}`);
-              const result = dispatchEvent(t ?? "", d, account.accountId, log);
-              if (result.action === "ready") {
-                this.sessionId = result.sessionId;
-                this.saveCurrentSession();
-                this.ctx.onReady?.(result.data);
-              } else if (result.action === "resumed") {
-                (this.ctx.onResumed ?? this.ctx.onReady)?.(result.data);
-                this.saveCurrentSession();
-              } else if (result.action === "interaction") {
-                this.ctx.onInteraction?.(result.event);
-              } else if (result.action === "message") {
-                void trySlashCommandOrEnqueue(result.msg);
-              }
-              break;
-            }
-
-            case GatewayOp.HEARTBEAT_ACK:
-              break;
-
-            case GatewayOp.RECONNECT:
-              this.cleanup();
-              this.scheduleReconnect();
-              break;
-
-            case GatewayOp.INVALID_SESSION: {
-              const canResume = d as boolean;
-              if (!canResume) {
-                this.sessionId = null;
-                this.lastSeq = null;
-                clearSession(account.accountId);
-                this.shouldRefreshToken = true;
-              }
-              this.cleanup();
-              this.scheduleReconnect(3000);
-              break;
-            }
-          }
-        } catch (err) {
-          log?.error(`Message parse error: ${err instanceof Error ? err.message : String(err)}`);
-        }
-      });
-
-      // ---- WebSocket: close ----
-      ws.on("close", (code, reason) => {
-        log?.info(`WebSocket closed: ${code} ${reason.toString()}`);
-        this.isConnecting = false;
-        this.handleClose(code);
-      });
-
-      // ---- WebSocket: error ----
-      ws.on("error", (err) => {
-        log?.error(`WebSocket error: ${err.message}`);
-        this.ctx.onError?.(err);
-      });
-    } catch (err) {
-      this.isConnecting = false;
-      const errMsg = err instanceof Error ? err.message : String(err);
-      log?.error(`Connection failed: ${errMsg}`);
-      if (errMsg.includes("Too many requests") || errMsg.includes("100001")) {
-        this.scheduleReconnect(RATE_LIMIT_DELAY);
-      } else {
-        this.scheduleReconnect();
-      }
-    }
-  }
-
-  // ============ Protocol handlers ============
-
-  private handleHello(ws: WebSocket, d: unknown, accessToken: string): void {
-    if (this.sessionId && this.lastSeq !== null) {
-      ws.send(
-        JSON.stringify({
-          op: GatewayOp.RESUME,
-          d: {
-            token: `QQBot ${accessToken}`,
-            session_id: this.sessionId,
-            seq: this.lastSeq,
-          },
-        }),
-      );
-    } else {
-      ws.send(
-        JSON.stringify({
-          op: GatewayOp.IDENTIFY,
-          d: {
-            token: `QQBot ${accessToken}`,
-            intents: FULL_INTENTS,
-            shard: [0, 1],
-          },
-        }),
-      );
-    }
-
-    const interval = (d as { heartbeat_interval: number }).heartbeat_interval;
-    if (this.heartbeatInterval) {
-      clearInterval(this.heartbeatInterval);
-    }
-    this.heartbeatInterval = setInterval(() => {
-      if (ws.readyState === WebSocket.OPEN) {
-        ws.send(JSON.stringify({ op: GatewayOp.HEARTBEAT, d: this.lastSeq }));
-      }
-    }, interval);
-  }
-
-  private handleClose(code: number): void {
-    const { account } = this.ctx;
-    const action = this.reconnect.handleClose(code, this.isAborted);
-
-    if (action.clearSession) {
-      this.sessionId = null;
-      this.lastSeq = null;
-      clearSession(account.accountId);
-    }
-    if (action.refreshToken) {
-      this.shouldRefreshToken = true;
-    }
-
-    this.cleanup();
-
-    if (action.fatal) {
-      return;
-    }
-    if (action.shouldReconnect) {
-      this.scheduleReconnect(action.reconnectDelay);
-    }
-  }
-}