@gakr-gakr/qqbot 0.1.0

package/src/engine/gateway/reconnect.ts

@@ -0,0 +1,199 @@
+/**
+ * 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 ${this.accountId} 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

@@ -0,0 +1,99 @@
+import type { QQBotInboundAccess } from "../../adapter/index.js";
+import type { InboundContext, InboundPipelineDeps } from "../inbound-context.js";
+import type { QueuedMessage } from "../message-queue.js";
+import { buildBlockedInboundContext } from "./stub-contexts.js";
+
+type AccessStageResult =
+  | {
+      kind: "allow";
+      isGroupChat: boolean;
+      peerId: string;
+      qualifiedTarget: string;
+      fromAddress: string;
+      route: { sessionKey: string; accountId: string; agentId?: string };
+      access: QQBotInboundAccess;
+    }
+  | { kind: "block"; context: InboundContext };
+
+export async function runAccessStage(
+  event: QueuedMessage,
+  deps: InboundPipelineDeps,
+): Promise<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 = await deps.adapters.access.resolveInboundAccess({
+    cfg,
+    accountId: account.accountId,
+    isGroup: isGroupChat,
+    senderId: event.senderId,
+    conversationId: peerId,
+    allowFrom: account.config?.allowFrom,
+    groupAllowFrom: account.config?.groupAllowFrom,
+    dmPolicy: account.config?.dmPolicy,
+    groupPolicy: account.config?.groupPolicy,
+  });
+
+  if (access.senderAccess.decision !== "allow") {
+    log?.info(
+      `Blocked qqbot inbound: decision=${access.senderAccess.decision} reasonCode=${access.senderAccess.reasonCode} ` +
+        `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";
+  }
+  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}`;
+}

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

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

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

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

@@ -0,0 +1,144 @@
+/**
+ * Envelope stage — render the Web UI body, the dynamic-context block,
+ * the final group system prompt, and the media classification arrays.
+ *
+ * All logic here is presentation-layer glue: it combines fields built by
+ * earlier stages into the display-friendly strings the outbound
+ * dispatcher needs. No decisions / gating.
+ */
+
+import type { ProcessedAttachments } from "../inbound-attachments.js";
+import type { InboundGroupInfo, InboundPipelineDeps, ReplyToInfo } from "../inbound-context.js";
+import type { QueuedMessage } from "../message-queue.js";
+
+// ─────────────────────────── Envelope body ───────────────────────────
+
+interface BuildBodyInput {
+  event: QueuedMessage;
+  deps: InboundPipelineDeps;
+  userContent: string;
+  isGroupChat: boolean;
+  imageUrls: string[];
+}
+
+/** Format the inbound envelope (Web UI body). */
+export function buildBody(input: BuildBodyInput): string {
+  const { event, deps, userContent, isGroupChat, imageUrls } = input;
+  const envelopeOptions = deps.runtime.channel.reply.resolveEnvelopeFormatOptions(deps.cfg);
+  return deps.runtime.channel.reply.formatInboundEnvelope({
+    channel: "qqbot",
+    from: event.senderName ?? event.senderId,
+    timestamp: new Date(event.timestamp).getTime(),
+    body: userContent,
+    chatType: isGroupChat ? "group" : "direct",
+    sender: { id: event.senderId, name: event.senderName },
+    envelope: envelopeOptions,
+    ...(imageUrls.length > 0 ? { imageUrls } : {}),
+  });
+}
+
+// ─────────────────────────── Quote / dynamic ctx ───────────────────────────
+
+/** Render the `[Quoted message begins]...[ends]` block (empty if no reply-to). */
+export function buildQuotePart(replyTo?: ReplyToInfo): string {
+  if (!replyTo) {
+    return "";
+  }
+  return replyTo.body
+    ? `[Quoted message begins]\n${replyTo.body}\n[Quoted message ends]\n`
+    : `[Quoted message begins]\nOriginal content unavailable\n[Quoted message ends]\n`;
+}
+
+interface BuildDynamicCtxInput {
+  imageUrls: string[];
+  uniqueVoicePaths: string[];
+  uniqueVoiceUrls: string[];
+  uniqueVoiceAsrReferTexts: string[];
+}
+
+/** Render the per-message dynamic metadata block (images / voice / ASR). */
+export function buildDynamicCtx(input: BuildDynamicCtxInput): string {
+  const lines: string[] = [];
+  if (input.imageUrls.length > 0) {
+    lines.push(`- Images: ${input.imageUrls.join(", ")}`);
+  }
+  if (input.uniqueVoicePaths.length > 0 || input.uniqueVoiceUrls.length > 0) {
+    lines.push(`- Voice: ${[...input.uniqueVoicePaths, ...input.uniqueVoiceUrls].join(", ")}`);
+  }
+  if (input.uniqueVoiceAsrReferTexts.length > 0) {
+    lines.push(`- ASR: ${input.uniqueVoiceAsrReferTexts.join(" | ")}`);
+  }
+  return lines.length > 0 ? lines.join("\n") + "\n\n" : "";
+}
+
+// ─────────────────────────── System prompt ───────────────────────────
+
+/** Combine account-level system prompt with group-specific prompts. */
+export function buildGroupSystemPrompt(
+  accountSystemInstruction: string,
+  groupInfo: InboundGroupInfo | undefined,
+): string | undefined {
+  const parts: string[] = [];
+  if (accountSystemInstruction) {
+    parts.push(accountSystemInstruction);
+  }
+  if (groupInfo?.display.introHint) {
+    parts.push(groupInfo.display.introHint);
+  }
+  if (groupInfo?.display.behaviorPrompt) {
+    parts.push(groupInfo.display.behaviorPrompt);
+  }
+  const combined = parts.filter(Boolean).join("\n");
+  return combined || undefined;
+}
+
+// ─────────────────────────── Media classification ───────────────────────────
+
+interface MediaClassification {
+  localMediaPaths: string[];
+  localMediaTypes: string[];
+  remoteMediaUrls: string[];
+  remoteMediaTypes: string[];
+  uniqueVoicePaths: string[];
+  uniqueVoiceUrls: string[];
+  uniqueVoiceAsrReferTexts: string[];
+  voiceMediaTypes: string[];
+  hasAsrReferFallback: boolean;
+  voiceTranscriptSources: string[];
+}
+
+/** Classify image URLs into local vs remote and de-duplicate voice arrays. */
+export function classifyMedia(processed: ProcessedAttachments): MediaClassification {
+  const localMediaPaths: string[] = [];
+  const localMediaTypes: string[] = [];
+  const remoteMediaUrls: string[] = [];
+  const remoteMediaTypes: string[] = [];
+  for (let i = 0; i < processed.imageUrls.length; i++) {
+    const u = processed.imageUrls[i];
+    const t = processed.imageMediaTypes[i] ?? "image/png";
+    if (u.startsWith("http://") || u.startsWith("https://")) {
+      remoteMediaUrls.push(u);
+      remoteMediaTypes.push(t);
+    } else {
+      localMediaPaths.push(u);
+      localMediaTypes.push(t);
+    }
+  }
+
+  const uniqueVoicePaths = [...new Set(processed.voiceAttachmentPaths)];
+  const uniqueVoiceUrls = [...new Set(processed.voiceAttachmentUrls)];
+  const voiceMediaTypes = [...uniqueVoicePaths, ...uniqueVoiceUrls].map(() => "audio/wav");
+
+  return {
+    localMediaPaths,
+    localMediaTypes,
+    remoteMediaUrls,
+    remoteMediaTypes,
+    uniqueVoicePaths,
+    uniqueVoiceUrls,
+    uniqueVoiceAsrReferTexts: [...new Set(processed.voiceAsrReferTexts)].filter(Boolean),
+    voiceMediaTypes,
+    hasAsrReferFallback: processed.voiceTranscriptSources.includes("asr"),
+    voiceTranscriptSources: processed.voiceTranscriptSources,
+  };
+}