@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.1

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

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

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

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

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

@@ -1,79 +0,0 @@
-/**
- * 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)}`,
-        );
-      }
-    }
-  }
-}