@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.2

package/src/engine/types.ts

@@ -1,313 +0,0 @@
-/**
- * Core API layer public types.
- *
- * These types are independent of the root `src/types.ts` and only define
- * what the `core/api/` modules need.  The old `src/types.ts` remains
- * untouched for backward compatibility.
- */
-
-// ============ Structured API Error ============
-
-/**
- * Structured API error with HTTP status, path, and optional business error code.
- *
- * Compared to the old `api.ts` which throws plain `Error`, this carries
- * machine-readable fields for downstream retry/fallback decisions.
- */
-export class ApiError extends Error {
-  override readonly name = "ApiError";
-
-  constructor(
-    message: string,
-    /** HTTP status code returned by the QQ Open Platform. */
-    public readonly httpStatus: number,
-    /** API path that produced the error (e.g. `/v2/users/{id}/messages`). */
-    public readonly path: string,
-    /** Business error code from the response body (`code` or `err_code`). */
-    public readonly bizCode?: number,
-    /** Original error message from the response body. */
-    public readonly bizMessage?: string,
-  ) {
-    super(message);
-  }
-}
-
-// ============ Logger ============
-
-/**
- * Unified logger interface used across all engine/ modules.
- *
- * Replaces the previously fragmented ApiLogger, GatewayLogger, ReconnectLogger,
- * MessageRefLogger, PathLogger, and SenderLogger interfaces.
- *
- * `info` and `error` are required; `warn` and `debug` are optional because
- * some callers (e.g. the framework-injected `ctx.log`) may not provide them.
- */
-export interface EngineLogger {
-  info: (msg: string, meta?: Record<string, unknown>) => void;
-  error: (msg: string, meta?: Record<string, unknown>) => void;
-  warn?: (msg: string, meta?: Record<string, unknown>) => void;
-  debug?: (msg: string, meta?: Record<string, unknown>) => void;
-}
-
-// ============ Chat Scope ============
-
-/** Chat scope used to unify C2C/Group path construction. */
-export type ChatScope = "c2c" | "group";
-
-// ============ Message Response ============
-
-/** Standard message send response from the QQ Open Platform. */
-export interface MessageResponse {
-  id: string;
-  timestamp: number | string;
-  /** Reference index for future quoting. */
-  ext_info?: {
-    ref_idx?: string;
-  };
-}
-
-// ============ Media Types ============
-
-/** QQ Open Platform media file type codes. */
-export enum MediaFileType {
-  IMAGE = 1,
-  VIDEO = 2,
-  VOICE = 3,
-  FILE = 4,
-}
-
-/** Media upload response from the QQ Open Platform. */
-export interface UploadMediaResponse {
-  file_uuid: string;
-  file_info: string;
-  ttl: number;
-  id?: string;
-}
-
-/** Structured metadata recorded for outbound messages. */
-export interface OutboundMeta {
-  /** Message text content. */
-  text?: string;
-  /** Media type tag. */
-  mediaType?: "image" | "voice" | "video" | "file";
-  /** Remote URL of the media source. */
-  mediaUrl?: string;
-  /** Local file path of the media source. */
-  mediaLocalPath?: string;
-  /** Original TTS text (voice messages only). */
-  ttsText?: string;
-}
-
-// ============ API Client Config ============
-
-/** Configuration for the core HTTP client. */
-export interface ApiClientConfig {
-  /** Base URL for the QQ Open Platform REST API. */
-  baseUrl?: string;
-  /** Default request timeout in milliseconds. */
-  defaultTimeoutMs?: number;
-  /** File upload request timeout in milliseconds. */
-  fileUploadTimeoutMs?: number;
-  /** Logger instance. */
-  logger?: EngineLogger;
-  /** User-Agent header value, or a getter function for dynamic resolution. */
-  userAgent?: string | (() => string);
-}
-
-// ============ Chunked Upload Types ============
-
-/** Individual upload part metadata. */
-export interface UploadPart {
-  /** Part index (1-based). */
-  index: number;
-  /** Pre-signed upload URL. */
-  presigned_url: string;
-}
-
-/** Response from the upload_prepare endpoint. */
-export interface UploadPrepareResponse {
-  /** Upload task identifier. */
-  upload_id: string;
-  /** Block size in bytes. */
-  block_size: number;
-  /** Pre-signed upload parts. */
-  parts: UploadPart[];
-  /** Server-suggested upload concurrency. */
-  concurrency?: number;
-  /** Server-suggested retry timeout for upload_part_finish (seconds). */
-  retry_timeout?: number;
-}
-
-/** File hash information for upload_prepare. */
-export interface UploadPrepareHashes {
-  /** Whole-file MD5 (hex). */
-  md5: string;
-  /** Whole-file SHA1 (hex). */
-  sha1: string;
-  /** MD5 of the first 10,002,432 bytes (hex). */
-  md5_10m: string;
-}
-
-// ============ Stream Message Types ============
-
-/** Stream message input mode (C2C stream_messages API). */
-export const StreamInputMode = {
-  /** Each chunk replaces full message content. */
-  REPLACE: "replace",
-} as const;
-export type StreamInputMode = (typeof StreamInputMode)[keyof typeof StreamInputMode];
-
-/** Stream message input state (numeric per QQ Open Platform). */
-export const StreamInputState = {
-  GENERATING: 1,
-  DONE: 10,
-} as const;
-export type StreamInputState = (typeof StreamInputState)[keyof typeof StreamInputState];
-
-/** Stream message content type. */
-export const StreamContentType = {
-  MARKDOWN: "markdown",
-} as const;
-export type StreamContentType = (typeof StreamContentType)[keyof typeof StreamContentType];
-
-/** Stream message request body for `/v2/users/{openid}/stream_messages`. */
-export interface StreamMessageRequest {
-  input_mode: StreamInputMode;
-  input_state: StreamInputState;
-  content_type: StreamContentType;
-  content_raw: string;
-  event_id: string;
-  msg_id: string;
-  stream_msg_id?: string;
-  msg_seq: number;
-  index: number;
-}
-
-// ============ Inline Keyboard Types ============
-
-/** Inline keyboard button for approval/interaction flows. */
-export interface KeyboardButton {
-  id: string;
-  render_data: {
-    label: string;
-    visited_label: string;
-    style: number;
-  };
-  action: {
-    type: number;
-    permission: { type: number };
-    data: string;
-    click_limit?: number;
-  };
-  group_id?: string;
-}
-
-/**
- * Inline keyboard structure attached to messages.
- * Sent as the `keyboard` field in the message body:
- * `{ "keyboard": { "content": { "rows": [...] } } }`
- */
-export interface InlineKeyboard {
-  content: {
-    rows: Array<{ buttons: KeyboardButton[] }>;
-  };
-}
-
-// ============ Interaction Event Types ============
-
-/** Button interaction event (INTERACTION_CREATE). */
-export interface InteractionEvent {
-  /** Event ID — used to acknowledge the interaction (PUT /interactions/{id}). */
-  id: string;
-  /** Event sub-type: 11=message button, 12=c2c quick menu. */
-  type: number;
-  /** Scene identifier: c2c / group / guild. */
-  scene?: string;
-  /** Chat type: 0=guild, 1=group, 2=c2c. */
-  chat_type?: number;
-  timestamp?: string;
-  guild_id?: string;
-  channel_id?: string;
-  /** C2C user openid (c2c scene only). */
-  user_openid?: string;
-  /** Group openid (group scene only). */
-  group_openid?: string;
-  /** Group member openid (group scene only). */
-  group_member_openid?: string;
-  version: number;
-  data: {
-    type: number;
-    resolved: {
-      button_data?: string;
-      button_id?: string;
-      user_id?: string;
-      feature_id?: string;
-      message_id?: string;
-    };
-  };
-}
-
-// ============ Account Config View ============
-
-import type { QQBotDmPolicy, QQBotGroupPolicy } from "./access/types.js";
-
-/**
- * Typed view of known per-account configuration fields.
- *
- * Used for `as QQBotAccountConfigView` casts when reading fields from
- * the raw `Record<string, unknown>` config. The actual config type
- * stays `Record<string, unknown>` to avoid schema incompatibility.
- */
-export interface QQBotAccountConfigView {
-  allowFrom?: Array<string | number>;
-  groupAllowFrom?: Array<string | number>;
-  dmPolicy?: QQBotDmPolicy;
-  groupPolicy?: QQBotGroupPolicy;
-  groups?: Record<string, Record<string, unknown>>;
-  streaming?:
-    | boolean
-    | {
-        mode?: string;
-        c2cStreamApi?: boolean;
-      };
-  audioFormatPolicy?: {
-    uploadDirectFormats?: string[];
-    transcodeEnabled?: boolean;
-  };
-  voiceDirectUploadFormats?: string[];
-}
-
-// ============ Gateway Account ============
-
-/**
- * Resolved account configuration — shared across gateway/ and messaging/ layers.
- *
- * Lifted here from gateway/types.ts to eliminate the circular type dependency
- * where messaging/ had to import from gateway/.
- */
-export interface GatewayAccount {
-  accountId: string;
-  appId: string;
-  clientSecret: string;
-  markdownSupport: boolean;
-  systemPrompt?: string;
-  config: Record<string, unknown> & {
-    allowFrom?: Array<string | number>;
-    groupAllowFrom?: Array<string | number>;
-    dmPolicy?: "open" | "allowlist" | "disabled";
-    groupPolicy?: "open" | "allowlist" | "disabled";
-    streaming?:
-      | boolean
-      | {
-          mode?: string;
-          /** When true, use QQ C2C `stream_messages` for DMs. Boolean `true` is equivalent. */
-          c2cStreamApi?: boolean;
-        };
-    audioFormatPolicy?: {
-      uploadDirectFormats?: string[];
-      transcodeEnabled?: boolean;
-    };
-    voiceDirectUploadFormats?: string[];
-  };
-}

package/src/engine/utils/attachment-tags.test.ts

@@ -1,186 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  formatAttachmentTags,
-  renderAttachmentTags,
-  TRANSCRIPT_SOURCE_LABELS,
-  type AttachmentSummary,
-} from "./attachment-tags.js";
-
-describe("engine/utils/attachment-tags", () => {
-  // ────────────────────────── shared body (mode-agnostic) ──────────────────────────
-
-  describe("shared tag body", () => {
-    it("returns empty string for missing/empty input", () => {
-      expect(formatAttachmentTags()).toBe("");
-      expect(formatAttachmentTags([])).toBe("");
-    });
-
-    it("collapses to MEDIA:{source} when a path/url is present", () => {
-      expect(formatAttachmentTags([{ type: "image", localPath: "/tmp/a.png" }])).toBe(
-        "MEDIA:/tmp/a.png",
-      );
-      expect(formatAttachmentTags([{ type: "file", url: "https://x/y.pdf" }])).toBe(
-        "MEDIA:https://x/y.pdf",
-      );
-    });
-
-    it("inlines voice transcript only for voice attachments", () => {
-      expect(
-        formatAttachmentTags([{ type: "voice", localPath: "/tmp/v.wav", transcript: "hi" }]),
-      ).toBe('MEDIA:/tmp/v.wav (transcript: "hi")');
-      // Non-voice attachments never get the transcript suffix even if one
-      // is present on the summary.
-      expect(
-        formatAttachmentTags([
-          { type: "image", localPath: "/tmp/i.png", transcript: "unused" } as AttachmentSummary,
-        ]),
-      ).toBe("MEDIA:/tmp/i.png");
-    });
-
-    it("falls back to bracketed tags when no source is available", () => {
-      expect(formatAttachmentTags([{ type: "image" }])).toBe("[image]");
-      expect(formatAttachmentTags([{ type: "image", filename: "a.png" }])).toBe("[image: a.png]");
-      expect(formatAttachmentTags([{ type: "voice" }])).toBe("[voice]");
-      expect(formatAttachmentTags([{ type: "voice", transcript: "t" }])).toBe(
-        '[voice (transcript: "t")]',
-      );
-      expect(formatAttachmentTags([{ type: "video" }])).toBe("[video]");
-      expect(formatAttachmentTags([{ type: "file", filename: "b.pdf" }])).toBe("[file: b.pdf]");
-      expect(formatAttachmentTags([{ type: "unknown" }])).toBe("[attachment]");
-    });
-
-    it("joins multiple entries with newline in inline mode", () => {
-      expect(
-        formatAttachmentTags([
-          { type: "image", localPath: "/tmp/a.png" },
-          { type: "voice", transcript: "hi" },
-        ]),
-      ).toBe('MEDIA:/tmp/a.png\n[voice (transcript: "hi")]');
-    });
-  });
-
-  // ────────────────────────── ref mode = body + source suffix ──────────────────────────
-
-  describe("ref mode consistency with inline", () => {
-    it("produces the same body as inline for non-voice attachments", () => {
-      const att: AttachmentSummary[] = [
-        { type: "image", localPath: "/tmp/a.png" },
-        { type: "file", filename: "b.pdf" },
-      ];
-      // Rendered one at a time so separator differences don't matter.
-      for (const a of att) {
-        expect(renderAttachmentTags([a], { mode: "inline" })).toBe(
-          renderAttachmentTags([a], { mode: "ref" }),
-        );
-      }
-    });
-
-    it("produces the same body as inline for voice without transcriptSource", () => {
-      const cases: AttachmentSummary[] = [
-        { type: "voice" },
-        { type: "voice", transcript: "hi" },
-        { type: "voice", localPath: "/tmp/v.wav", transcript: "hi" },
-      ];
-      for (const a of cases) {
-        expect(renderAttachmentTags([a], { mode: "inline" })).toBe(
-          renderAttachmentTags([a], { mode: "ref" }),
-        );
-      }
-    });
-
-    it("appends ' [source: …]' ONLY for voice + transcript + transcriptSource in ref mode", () => {
-      // ref mode: suffix appears.
-      expect(
-        renderAttachmentTags(
-          [{ type: "voice", localPath: "/tmp/v.wav", transcript: "hi", transcriptSource: "stt" }],
-          { mode: "ref" },
-        ),
-      ).toBe('MEDIA:/tmp/v.wav (transcript: "hi") [source: local STT]');
-
-      // inline mode: suffix NEVER appears, even with transcriptSource set.
-      expect(
-        renderAttachmentTags(
-          [{ type: "voice", localPath: "/tmp/v.wav", transcript: "hi", transcriptSource: "stt" }],
-          { mode: "inline" },
-        ),
-      ).toBe('MEDIA:/tmp/v.wav (transcript: "hi")');
-    });
-
-    it("omits the source suffix when transcriptSource is missing (both modes identical)", () => {
-      const att: AttachmentSummary = { type: "voice", transcript: "hi" };
-      expect(renderAttachmentTags([att], { mode: "ref" })).toBe(
-        renderAttachmentTags([att], { mode: "inline" }),
-      );
-    });
-
-    it("joins with space in ref mode", () => {
-      expect(
-        renderAttachmentTags(
-          [
-            { type: "image", filename: "a.png" },
-            { type: "voice", transcript: "hi" },
-          ],
-          { mode: "ref" },
-        ),
-      ).toBe('[image: a.png] [voice (transcript: "hi")]');
-    });
-  });
-
-  // ────────────────────────── Prompt-contract regression guards ──────────────────────────
-
-  describe("prompt contract", () => {
-    it("exposes the transcript-source labels table", () => {
-      expect(TRANSCRIPT_SOURCE_LABELS.stt).toBe("local STT");
-      expect(TRANSCRIPT_SOURCE_LABELS.asr).toBe("platform ASR");
-      expect(TRANSCRIPT_SOURCE_LABELS.tts).toBe("TTS source");
-      expect(TRANSCRIPT_SOURCE_LABELS.fallback).toBe("fallback text");
-    });
-
-    it("uses the single canonical keyword 'transcript:' (never 'content:')", () => {
-      // If anyone reintroduces 'content:' the regex below will match and fail the test.
-      const samples = [
-        formatAttachmentTags([{ type: "voice", transcript: "t" }]),
-        renderAttachmentTags([{ type: "voice", transcript: "t", transcriptSource: "asr" }], {
-          mode: "ref",
-        }),
-      ];
-      for (const s of samples) {
-        expect(s).toMatch(/transcript:/);
-        expect(s).not.toMatch(/content:/);
-      }
-    });
-
-    it("uses the single canonical type label 'voice' (never 'voice message')", () => {
-      const samples = [
-        renderAttachmentTags([{ type: "voice" }], { mode: "inline" }),
-        renderAttachmentTags([{ type: "voice", transcript: "hi" }], { mode: "ref" }),
-      ];
-      for (const s of samples) {
-        expect(s).not.toMatch(/voice message/);
-      }
-    });
-  });
-
-  // ────────────────────────── Options ──────────────────────────
-
-  describe("options", () => {
-    it("respects a custom separator", () => {
-      expect(
-        renderAttachmentTags(
-          [
-            { type: "image", filename: "a" },
-            { type: "video", filename: "b" },
-          ],
-          { mode: "inline", separator: " | " },
-        ),
-      ).toBe("[image: a] | [video: b]");
-    });
-
-    it("returns the emptyFallback when input is empty", () => {
-      expect(renderAttachmentTags(undefined, { mode: "ref", emptyFallback: "(none)" })).toBe(
-        "(none)",
-      );
-      expect(renderAttachmentTags([], { mode: "inline", emptyFallback: "" })).toBe("");
-    });
-  });
-});

package/src/engine/utils/attachment-tags.ts

@@ -1,174 +0,0 @@
-/**
- * Single source of truth for rendering attachment summaries as
- * human-readable tags that the LLM sees.
- *
- * There is exactly ONE vocabulary shared by every consumer:
- *
- *   • Type labels: `image` / `voice` / `video` / `file` / `attachment`
- *   • Keyword for voice text: `transcript:` (never `content:`)
- *   • With source: `MEDIA:{source}` (no bracketed alias)
- *   • Without source: `[{type}]` or `[{type}: {filename}]`
- *
- * Both consumers (group history / current inbound turn, and the ref-index
- * quoted-message block) call the same function with the same vocabulary.
- * They differ only on two orthogonal dimensions:
- *
- *   1. `transcriptSource` — ref mode appends `[source: local STT]` (or
- *      similar) after a voice transcript so the model knows where the
- *      text came from. Inline mode omits this (the current turn knows
- *      its own STT provenance).
- *
- *   2. Separator — inline joins with `\n` (history replay is multi-line),
- *      ref joins with a space (quoted block is rendered inline).
- *
- * These are the ONLY permitted differences between modes. Any new
- * decoration must be added in both modes or behind an explicit option
- * documented here, otherwise the model ends up learning two dialects.
- *
- * Zero external dependencies — pure string formatting.
- */
-
-import type { RefAttachmentSummary } from "../ref/types.js";
-
-// ============ Types ============
-
-/** Canonical attachment shape shared by history entries and ref entries. */
-export type AttachmentSummary = RefAttachmentSummary;
-
-/**
- * Rendering mode.
- *
- * - `"inline"`: current turn + history replay. No transcript-source tag.
- *   Tags are separated by newlines.
- * - `"ref"`: quoted-message block. Appends `[source: …]` to voice
- *   transcripts when `transcriptSource` is present. Tags are separated
- *   by spaces so the block fits on one line.
- */
-type RenderMode = "inline" | "ref";
-
-/** Human-readable labels for transcript provenance (prompt contract). */
-export const TRANSCRIPT_SOURCE_LABELS: Record<
-  NonNullable<RefAttachmentSummary["transcriptSource"]>,
-  string
-> = {
-  stt: "local STT",
-  asr: "platform ASR",
-  tts: "TTS source",
-  fallback: "fallback text",
-};
-
-/** Options controlling how the tag list is rendered. */
-interface RenderOptions {
-  mode: RenderMode;
-  /** Separator between tags. Defaults per mode: inline=`\n`, ref=` `. */
-  separator?: string;
-  /** Returned when `attachments` is empty/undefined. Defaults to `""`. */
-  emptyFallback?: string;
-}
-
-// ============ Public API ============
-
-/**
- * Render a list of attachments into an LLM-facing tag string.
- *
- * Shared grammar (both modes):
- *
- * ```
- * attachment_with_source  := "MEDIA:" SOURCE [voice_suffix]
- * voice_suffix            := ' (transcript: "' TEXT '")' [source_suffix]
- * attachment_no_source    := "[" TYPE_LABEL [": " FILENAME] [voice_suffix_bare] "]" [source_suffix_bare]
- * voice_suffix_bare       := ' (transcript: "' TEXT '")'
- * source_suffix           := " [source: " LABEL "]"   ← ref mode only
- * source_suffix_bare      := " [source: " LABEL "]"   ← ref mode only
- * TYPE_LABEL              := "image" | "voice" | "video" | "file" | "attachment"
- * ```
- *
- * The **only** mode-dependent decoration is the `source_suffix` (present
- * in `ref`, absent in `inline`). Every other token is identical.
- */
-export function renderAttachmentTags(
-  attachments: readonly AttachmentSummary[] | undefined,
-  options: RenderOptions,
-): string {
-  if (!attachments?.length) {
-    return options.emptyFallback ?? "";
-  }
-
-  const parts: string[] = [];
-  for (const att of attachments) {
-    parts.push(renderOne(att, options.mode));
-  }
-
-  const separator = options.separator ?? (options.mode === "ref" ? " " : "\n");
-  return parts.join(separator);
-}
-
-/**
- * Shorthand for `renderAttachmentTags(attachments, { mode: "inline" })`.
- *
- * Kept as the primary entry point for group history / current-turn
- * rendering where the terse inline form is always wanted.
- */
-export function formatAttachmentTags(attachments?: readonly AttachmentSummary[]): string {
-  return renderAttachmentTags(attachments, { mode: "inline" });
-}
-
-// ============ Internal ============
-
-/**
- * Render a single attachment.
- *
- * The function is split into two orthogonal concerns:
- *   - `renderBody`: the shared "MEDIA:{source}…" or "[type…]" string.
- *   - `renderSourceSuffix`: ref-mode-only `" [source: …]"` tail.
- *
- * Both consumers produce the same body; only the suffix differs.
- */
-function renderOne(att: AttachmentSummary, mode: RenderMode): string {
-  const body = renderBody(att);
-  const suffix = mode === "ref" ? renderSourceSuffix(att) : "";
-  return body + suffix;
-}
-
-/** Shared, mode-agnostic body of the tag. */
-function renderBody(att: AttachmentSummary): string {
-  const source = att.localPath || att.url;
-  const voiceSuffix =
-    att.type === "voice" && att.transcript ? ` (transcript: "${att.transcript}")` : "";
-
-  if (source) {
-    return `MEDIA:${source}${voiceSuffix}`;
-  }
-
-  const label = labelForType(att.type);
-  const namePart = att.filename ? `: ${att.filename}` : "";
-  return `[${label}${namePart}${voiceSuffix}]`;
-}
-
-/**
- * Ref-mode-only tail that records where a voice transcript came from.
- * Empty string when the attachment isn't a transcribed voice message.
- */
-function renderSourceSuffix(att: AttachmentSummary): string {
-  if (att.type !== "voice" || !att.transcript || !att.transcriptSource) {
-    return "";
-  }
-  const label = TRANSCRIPT_SOURCE_LABELS[att.transcriptSource] ?? att.transcriptSource;
-  return ` [source: ${label}]`;
-}
-
-/** Canonical single-word label for each attachment type. */
-function labelForType(type: AttachmentSummary["type"]): string {
-  switch (type) {
-    case "image":
-      return "image";
-    case "voice":
-      return "voice";
-    case "video":
-      return "video";
-    case "file":
-      return "file";
-    default:
-      return "attachment";
-  }
-}