@openclaw/qqbot 2026.5.1-beta.1

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

@@ -0,0 +1,113 @@
+/**
+ * Quote stage — resolve the quoted-reply (`refMsgIdx`) if any.
+ *
+ * Three-level fallback mirrors the standalone build:
+ *   1. RefIndex cache hit → rich ReplyToInfo
+ *   2. `msg_elements[0]` present → re-process the quoted body
+ *   3. Otherwise → id-only placeholder so the pipeline still knows it's a reply
+ */
+
+import {
+  formatMessageReferenceForAgent,
+  type AttachmentProcessor,
+} from "../../ref/format-message-ref.js";
+import { formatRefEntryForAgent, getRefIndex } from "../../ref/store.js";
+import { MSG_TYPE_QUOTE } from "../../utils/text-parsing.js";
+import { formatVoiceText } from "../../utils/voice-text.js";
+import { processAttachments } from "../inbound-attachments.js";
+import type { InboundPipelineDeps, ReplyToInfo } from "../inbound-context.js";
+import type { QueuedMessage } from "../message-queue.js";
+
+/**
+ * Resolve the quote metadata for an inbound event.
+ *
+ * Returns `undefined` when the event is not a reply at all.
+ */
+export async function resolveQuote(
+  event: QueuedMessage,
+  deps: InboundPipelineDeps,
+): Promise<ReplyToInfo | undefined> {
+  if (!event.refMsgIdx) {
+    return undefined;
+  }
+
+  const { account, log } = deps;
+
+  // ---- Layer 1: cache hit ----
+  const refEntry = getRefIndex(event.refMsgIdx);
+  if (refEntry) {
+    log?.debug?.(
+      `Quote detected via refMsgIdx cache: refMsgIdx=${event.refMsgIdx}, sender=${refEntry.senderName ?? refEntry.senderId}`,
+    );
+    return {
+      id: event.refMsgIdx,
+      body: formatRefEntryForAgent(refEntry),
+      sender: refEntry.senderName ?? refEntry.senderId,
+      isQuote: true,
+    };
+  }
+
+  // ---- Layer 2: fall back to msg_elements[0] if this is a quote type ----
+  if (event.msgType === MSG_TYPE_QUOTE && event.msgElements?.[0]) {
+    try {
+      const refElement = event.msgElements[0];
+      const refData = {
+        content: refElement.content ?? "",
+        attachments: refElement.attachments,
+      };
+      const attachmentProcessor: AttachmentProcessor = {
+        processAttachments: async (atts, refCtx) => {
+          const result = await processAttachments(
+            atts as Array<{
+              content_type: string;
+              url: string;
+              filename?: string;
+              voice_wav_url?: string;
+              asr_refer_text?: string;
+            }>,
+            {
+              accountId: account.accountId,
+              cfg: refCtx.cfg,
+              audioConvert: deps.adapters.audioConvert,
+              log: refCtx.log,
+            },
+          );
+          return {
+            attachmentInfo: result.attachmentInfo,
+            voiceTranscripts: result.voiceTranscripts,
+            voiceTranscriptSources: result.voiceTranscriptSources,
+            attachmentLocalPaths: result.attachmentLocalPaths,
+          };
+        },
+        formatVoiceText: (transcripts) => formatVoiceText(transcripts),
+      };
+      const refPeerId =
+        event.type === "group" && event.groupOpenid ? event.groupOpenid : event.senderId;
+      const refBody = await formatMessageReferenceForAgent(
+        refData,
+        { appId: account.appId, peerId: refPeerId, cfg: account.config, log },
+        attachmentProcessor,
+      );
+      log?.debug?.(
+        `Quote detected via msg_elements[0] (cache miss): id=${event.refMsgIdx}, content="${(refBody ?? "").slice(0, 80)}..."`,
+      );
+      return {
+        id: event.refMsgIdx,
+        body: refBody || undefined,
+        isQuote: true,
+      };
+    } catch (refErr) {
+      log?.error(`Failed to format quoted message from msg_elements: ${String(refErr)}`);
+    }
+  } else {
+    log?.debug?.(
+      `Quote detected but no cache and msgType=${event.msgType}: refMsgIdx=${event.refMsgIdx}`,
+    );
+  }
+
+  // ---- Layer 3: id-only placeholder ----
+  return {
+    id: event.refMsgIdx,
+    isQuote: true,
+  };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * RefIdx persistence stage — writes the current message into the shared
+ * `refIndex` cache so future quote resolutions can find it.
+ *
+ * The stage also attaches voice transcripts (and their source) onto the
+ * cached attachment summaries so replies-to-this-message can render the
+ * original audio content inline instead of just a file handle.
+ *
+ * Pure data pipeline (no network I/O). Sync return value.
+ */
+
+import { setRefIndex } from "../../ref/store.js";
+import { buildAttachmentSummaries } from "../../utils/text-parsing.js";
+import type { ProcessedAttachments } from "../inbound-attachments.js";
+import type { QueuedMessage } from "../message-queue.js";
+
+/**
+ * Cache the current message under `msgIdx` (or the fallback `refIdx`
+ * returned by the typing-indicator call) so later quotes resolve.
+ *
+ * No-op when neither id is available.
+ */
+export function writeRefIndex(params: {
+  event: QueuedMessage;
+  parsedContent: string;
+  processed: ProcessedAttachments;
+  /** Optional refIdx returned by `InputNotify` — used when `msgIdx` is missing. */
+  inputNotifyRefIdx?: string;
+}): void {
+  const { event, parsedContent, processed, inputNotifyRefIdx } = params;
+
+  const currentMsgIdx = event.msgIdx ?? inputNotifyRefIdx;
+  if (!currentMsgIdx) {
+    return;
+  }
+
+  const attSummaries = buildAttachmentSummaries(event.attachments, processed.attachmentLocalPaths);
+  if (attSummaries && processed.voiceTranscripts.length > 0) {
+    let voiceIdx = 0;
+    for (const att of attSummaries) {
+      if (att.type === "voice" && voiceIdx < processed.voiceTranscripts.length) {
+        att.transcript = processed.voiceTranscripts[voiceIdx];
+        if (voiceIdx < processed.voiceTranscriptSources.length) {
+          att.transcriptSource = processed.voiceTranscriptSources[voiceIdx] as
+            | "stt"
+            | "asr"
+            | "tts"
+            | "fallback";
+        }
+        voiceIdx++;
+      }
+    }
+  }
+
+  setRefIndex(currentMsgIdx, {
+    content: parsedContent,
+    senderId: event.senderId,
+    senderName: event.senderName,
+    timestamp: new Date(event.timestamp).getTime(),
+    attachments: attSummaries,
+  });
+}

package/src/engine/gateway/stages/stub-contexts.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared `InboundContext` stub builders for early-return paths.
+ *
+ * Both the access-control "blocked" path and the group-gate "skipped"
+ * path need to return a fully populated {@link InboundContext} that the
+ * upstream handler can inspect without crashing on undefined fields.
+ * Centralising the stubs here prevents the two paths from drifting.
+ */
+
+import type { QQBotAccessResult } from "../../access/index.js";
+import type { InboundContext, InboundGroupInfo } from "../inbound-context.js";
+import type { QueuedMessage } from "../message-queue.js";
+import type { TypingKeepAlive } from "../typing-keepalive.js";
+
+/** Shared fields every stub context needs. */
+interface BaseStubFields {
+  event: QueuedMessage;
+  route: { sessionKey: string; accountId: string; agentId?: string };
+  isGroupChat: boolean;
+  peerId: string;
+  qualifiedTarget: string;
+  fromAddress: string;
+}
+
+/** Build an {@link InboundContext} with all non-routing fields cleared. */
+function emptyInboundContext(fields: BaseStubFields): InboundContext {
+  return {
+    event: fields.event,
+    route: fields.route,
+    isGroupChat: fields.isGroupChat,
+    peerId: fields.peerId,
+    qualifiedTarget: fields.qualifiedTarget,
+    fromAddress: fields.fromAddress,
+    parsedContent: "",
+    userContent: "",
+    quotePart: "",
+    dynamicCtx: "",
+    userMessage: "",
+    agentBody: "",
+    body: "",
+    systemPrompts: [],
+    groupSystemPrompt: undefined,
+    attachments: {
+      attachmentInfo: "",
+      imageUrls: [],
+      imageMediaTypes: [],
+      voiceAttachmentPaths: [],
+      voiceAttachmentUrls: [],
+      voiceAsrReferTexts: [],
+      voiceTranscripts: [],
+      voiceTranscriptSources: [],
+      attachmentLocalPaths: [],
+    },
+    localMediaPaths: [],
+    localMediaTypes: [],
+    remoteMediaUrls: [],
+    remoteMediaTypes: [],
+    uniqueVoicePaths: [],
+    uniqueVoiceUrls: [],
+    uniqueVoiceAsrReferTexts: [],
+    voiceMediaTypes: [],
+    hasAsrReferFallback: false,
+    voiceTranscriptSources: [],
+    replyTo: undefined,
+    commandAuthorized: false,
+    group: undefined,
+    blocked: false,
+    skipped: false,
+    typing: { keepAlive: null },
+    inputNotifyRefIdx: undefined,
+  };
+}
+
+/**
+ * Build an {@link InboundContext} that represents a message blocked by
+ * access control (policy denial, allowlist mismatch, etc.).
+ */
+export function buildBlockedInboundContext(
+  params: BaseStubFields & {
+    access: QQBotAccessResult;
+  },
+): InboundContext {
+  return {
+    ...emptyInboundContext(params),
+    blocked: true,
+    blockReason: params.access.reason,
+    blockReasonCode: params.access.reasonCode,
+    accessDecision: params.access.decision,
+  };
+}
+
+/**
+ * Build an {@link InboundContext} that represents a message stopped by
+ * the group gate (drop_other_mention, block_unauthorized_command,
+ * skip_no_mention). Any history side-effects have already been applied
+ * by the gate stage.
+ */
+export function buildSkippedInboundContext(
+  params: BaseStubFields & {
+    group: InboundGroupInfo;
+    skipReason: NonNullable<InboundContext["skipReason"]>;
+    access: QQBotAccessResult;
+    typing: { keepAlive: TypingKeepAlive | null };
+    inputNotifyRefIdx?: string;
+  },
+): InboundContext {
+  return {
+    ...emptyInboundContext(params),
+    group: params.group,
+    skipped: true,
+    skipReason: params.skipReason,
+    accessDecision: params.access.decision,
+    typing: params.typing,
+    inputNotifyRefIdx: params.inputNotifyRefIdx,
+  };
+}

package/src/engine/gateway/types.ts

@@ -0,0 +1,264 @@
+/**
+ * Gateway types.
+ *
+ * core/gateway/gateway.ts now imports all dependencies directly (both
+ * core/ modules and upper-layer files). The only injected dependency
+ * is `runtime` (PluginRuntime), which is a framework-provided object.
+ */
+
+// ============ Logger ============
+import type { EngineLogger } from "../types.js";
+export type { EngineLogger };
+
+// ============ Account ============
+
+/** Re-export GatewayAccount from engine/types.ts (single source of truth). */
+import type { GatewayAccount as _GatewayAccount } from "../types.js";
+export type GatewayAccount = _GatewayAccount;
+
+// ============ PluginRuntime subset ============
+
+/**
+ * Subset of PluginRuntime used by the gateway.
+ *
+ * This is NOT a custom adapter — it's the exact same object shape that
+ * the framework injects. We define it here so core/ doesn't need to
+ * depend on the plugin-sdk root barrel.
+ */
+export interface GatewayPluginRuntime {
+  channel: {
+    activity: {
+      record: (params: {
+        channel: string;
+        accountId: string;
+        direction: "inbound" | "outbound";
+      }) => void;
+    };
+    routing: {
+      resolveAgentRoute: (params: {
+        cfg: unknown;
+        channel: string;
+        accountId: string;
+        peer: { kind: "group" | "direct"; id: string };
+      }) => { sessionKey: string; accountId: string; agentId?: string };
+    };
+    reply: {
+      dispatchReplyWithBufferedBlockDispatcher: (params: unknown) => Promise<unknown>;
+      resolveEffectiveMessagesConfig: (
+        cfg: unknown,
+        agentId?: string,
+      ) => { responsePrefix?: string };
+      finalizeInboundContext: (fields: Record<string, unknown>) => unknown;
+      formatInboundEnvelope: (params: unknown) => string;
+      resolveEnvelopeFormatOptions: (cfg: unknown) => unknown;
+    };
+    session: {
+      resolveStorePath: (store: unknown, params: { agentId: string }) => string;
+      recordInboundSession: (params: unknown) => Promise<unknown>;
+    };
+    turn: {
+      run: (params: unknown) => Promise<unknown>;
+    };
+    text: {
+      chunkMarkdownText: (text: string, limit: number) => string[];
+    };
+  };
+  tts: {
+    textToSpeech: (params: {
+      text: string;
+      cfg: unknown;
+      channel: string;
+      accountId?: string;
+    }) => Promise<{
+      success: boolean;
+      audioPath?: string;
+      provider?: string;
+      outputFormat?: string;
+      error?: string;
+    }>;
+  };
+  /**
+   * Config API for reading/writing the framework configuration.
+   *
+   * Used by the interaction handler (config query/update) directly
+   * within the engine layer. Optional because not all runtime
+   * environments provide config write capability.
+   */
+  config?: {
+    current: () => Record<string, unknown>;
+    replaceConfigFile: (params: {
+      nextConfig: unknown;
+      afterWrite: { mode: "auto" };
+    }) => Promise<unknown>;
+  };
+}
+
+// ============ Shared result types ============
+
+/** Re-export ProcessedAttachments from inbound-attachments (single source of truth). */
+export type { ProcessedAttachments } from "./inbound-attachments.js";
+
+/** Outbound result from media sends. */
+export interface OutboundResult {
+  channel: string;
+  messageId?: string;
+  timestamp?: string | number;
+  error?: string;
+}
+
+/** Re-export RefAttachmentSummary for convenience. */
+export type { RefAttachmentSummary } from "../ref/types.js";
+
+// ============ WebSocket Event Types ============
+
+/** Raw WebSocket payload structure. */
+export interface WSPayload {
+  op: number;
+  d: unknown;
+  s?: number;
+  t?: string;
+}
+
+/** Attachment shape shared by all message event types. */
+interface RawMessageAttachment {
+  content_type: string;
+  url: string;
+  filename?: string;
+  voice_wav_url?: string;
+  asr_refer_text?: string;
+}
+
+/** Referenced message element (used for quote messages). */
+interface RawMsgElement {
+  msg_idx?: string;
+  content?: string;
+  attachments?: Array<
+    RawMessageAttachment & {
+      height?: number;
+      width?: number;
+      size?: number;
+    }
+  >;
+}
+
+export interface C2CMessageEvent {
+  id: string;
+  content: string;
+  timestamp: string;
+  author: { user_openid: string };
+  attachments?: RawMessageAttachment[];
+  message_scene?: { ext?: string[] };
+  message_type?: number;
+  msg_elements?: RawMsgElement[];
+}
+
+export interface GuildMessageEvent {
+  id: string;
+  content: string;
+  timestamp: string;
+  author: { id: string; username?: string };
+  channel_id: string;
+  guild_id: string;
+  attachments?: RawMessageAttachment[];
+  message_scene?: { ext?: string[] };
+}
+
+export interface GroupMessageEvent {
+  id: string;
+  content: string;
+  timestamp: string;
+  author: {
+    member_openid: string;
+    username?: string;
+    /** True when the sender is itself a bot. */
+    bot?: boolean;
+  };
+  group_openid: string;
+  attachments?: RawMessageAttachment[];
+  /** Optional @mentions list with per-entry is_you / member_openid / nickname. */
+  mentions?: Array<{
+    scope?: "all" | "single";
+    id?: string;
+    user_openid?: string;
+    member_openid?: string;
+    nickname?: string;
+    username?: string;
+    bot?: boolean;
+    /** `true` when this mention targets the bot itself. */
+    is_you?: boolean;
+  }>;
+  message_scene?: { source?: string; ext?: string[] };
+  message_type?: number;
+  msg_elements?: RawMsgElement[];
+}
+
+// ============ Gateway Context ============
+
+import type { EngineAdapters } from "../adapter/index.js";
+
+/**
+ * Group-chat behaviour options.
+ *
+ * Grouped under a dedicated sub-object on {@link CoreGatewayContext} so
+ * future additions (admin lookup, proactive push, per-group toggles)
+ * don't keep polluting the top-level context type.
+ */
+interface GatewayGroupOptions {
+  /**
+   * Whether group-chat gating is enabled. Defaults to `true`; set to
+   * `false` to disable all group processing (e.g. for a DM-only smoke
+   * test). When disabled, the engine does not allocate a history
+   * buffer and does not instantiate the session-store reader.
+   */
+  enabled?: boolean;
+  /**
+   * Whether the framework has text-based control commands enabled. When
+   * `false`, the group gate skips the "unauthorized command" check and
+   * the command-bypass path.
+   */
+  allowTextCommands?: boolean;
+  /**
+   * Optional probe that returns true when `content` is a recognised
+   * control command. Injected to avoid hard-coding a command list in
+   * the engine. When omitted, no message is treated as a control
+   * command and the bypass path never activates.
+   */
+  isControlCommand?: (content: string) => boolean;
+  /**
+   * Platform hook that contributes a channel-level group intro hint
+   * (e.g. "当前群: 开发讨论组"). Invoked per-group when building the
+   * system prompt.
+   */
+  resolveIntroHint?: (params: {
+    cfg: unknown;
+    accountId: string;
+    groupId: string;
+  }) => string | undefined;
+  /**
+   * Session-store reader for the `/activation` command override. When
+   * omitted, the engine loads a default node-based reader lazily.
+   */
+  sessionStoreReader?: import("../group/activation.js").SessionStoreReader;
+}
+
+/** Full gateway startup context. */
+export interface CoreGatewayContext {
+  account: GatewayAccount;
+  abortSignal: AbortSignal;
+  cfg: unknown;
+  onReady?: (data: unknown) => void;
+  /**
+   * Invoked when a RESUMED event is received after reconnect.
+   * Falls back to `onReady` when not provided so existing callers
+   * keep their current behaviour.
+   */
+  onResumed?: (data: unknown) => void;
+  onError?: (error: Error) => void;
+  log?: EngineLogger;
+  /** PluginRuntime injected by the framework — same object in both versions. */
+  runtime: GatewayPluginRuntime;
+  /** Group-chat tuning options. */
+  group?: GatewayGroupOptions;
+  /** Adapter ports — delegates audio, history, mention gating, commands to bridge implementations. */
+  adapters: EngineAdapters;
+}

package/src/engine/gateway/typing-keepalive.ts

@@ -0,0 +1,79 @@
+/**
+ * Periodically refresh C2C typing state while a response is in progress.
+ *
+ * All I/O operations are injected via constructor parameters so this
+ * module has zero external dependencies and can run in both plugin versions.
+ */
+
+import { formatErrorMessage } from "../utils/format.js";
+
+/** Function that sends a typing indicator to one user. */
+type SendInputNotifyFn = (
+  token: string,
+  openid: string,
+  msgId: string | undefined,
+  inputSecond: number,
+) => Promise<unknown>;
+
+/** Refresh every 50s for the QQ API's 60s input-notify window. */
+const TYPING_INTERVAL_MS = 50_000;
+export const TYPING_INPUT_SECOND = 60;
+
+export class TypingKeepAlive {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private stopped = false;
+
+  constructor(
+    private readonly getToken: () => Promise<string>,
+    private readonly clearCache: () => void,
+    private readonly sendInputNotify: SendInputNotifyFn,
+    private readonly openid: string,
+    private readonly msgId: string | undefined,
+    private readonly log?: {
+      info: (msg: string) => void;
+      error: (msg: string) => void;
+      debug?: (msg: string) => void;
+    },
+  ) {}
+
+  /** Start periodic keep-alive sends. */
+  start(): void {
+    if (this.stopped) {
+      return;
+    }
+    this.timer = setInterval(() => {
+      if (this.stopped) {
+        this.stop();
+        return;
+      }
+      this.send().catch(() => {});
+    }, TYPING_INTERVAL_MS);
+  }
+
+  /** Stop periodic keep-alive sends. */
+  stop(): void {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  private async send(): Promise<void> {
+    try {
+      const token = await this.getToken();
+      await this.sendInputNotify(token, this.openid, this.msgId, TYPING_INPUT_SECOND);
+      this.log?.debug?.(`Typing keep-alive sent to ${this.openid}`);
+    } catch (err) {
+      try {
+        this.clearCache();
+        const token = await this.getToken();
+        await this.sendInputNotify(token, this.openid, this.msgId, TYPING_INPUT_SECOND);
+      } catch {
+        this.log?.debug?.(
+          `Typing keep-alive failed for ${this.openid}: ${formatErrorMessage(err)}`,
+        );
+      }
+    }
+  }
+}