@soimy/dingtalk 3.2.0 → 3.4.0

package/src/ack-reaction-classifier.ts

@@ -0,0 +1,75 @@
+type SentenceType = "夸奖" | "责怪" | "命令" | "叙事" | "请求" | "未知";
+
+type AckReactionClassifyResult = {
+  type: SentenceType;
+  emoji: string;
+};
+
+type EmojiMap = Record<SentenceType, readonly string[]>;
+
+const CATCHPHRASE = "叽 ";
+
+const KEYWORDS = {
+  praise: ["真棒", "太好了", "厉害", "优秀", "聪明", "好样的", "赞", "牛", "完美", "出色", "真行", "干得漂亮", "天才", "棒极了"],
+  blame: ["怎么又", "搞砸", "太差了", "烦死了", "讨厌", "笨", "蠢", "马虎", "不负责任", "乱来", "糟糕", "废物", "气死我了", "错了"],
+  command: ["必须", "立刻", "马上", "赶紧", "不准", "不要", "别动", "别说", "别做", "快去", "去做", "给我", "听着", "站住", "闭嘴"],
+  request: ["能不能", "可以吗", "好吗", "请", "麻烦", "帮个忙", "帮忙", "劳驾", "能否", "想请你", "能帮我", "借我", "方便吗"],
+} as const;
+
+const POLITE_EXCLUSIONS = ["别客气", "别介意", "别见怪", "别担心", "别着急"] as const;
+
+const EMOJIS: EmojiMap = {
+  // DingTalk `emotion/reply` does not accept every visually valid kaomoji.
+  // Keep only the strings that survived repeated direct API retests against
+  // the live endpoint using a real message target. Removed as unstable/bad:
+  // `٩(๑>◡<๑)۶`.
+  "夸奖": ["(๑•̀ㅂ•́)و✧", "(ﾉ≧∀≦)ﾉ", "(★▽★)", "(⌒▽⌒)☆", "(*≧ω≦)", "(ง •_•)ง", "ヾ(≧▽≦*)o"],
+  "责怪": ["(╬ Ò﹏Ó)", "(╯°□°）╯", "(▼皿▼#)", "(｡•́︿•̀｡)", "(╥﹏╥)", "ヽ(｀Д´)ﾉ", "(＃＞＜)", "(；′⌒`)"],
+  // Keep command kaomoji limited to strings that passed local
+  // DingTalk emotion/reply verification. Removed as unstable/bad after
+  // repeated direct API retests: `┌（┌ *｀д´）┐`, `(•̀へ •́ ╮ )`.
+  "命令": ["(¬_¬)", "(｀ε´)", "(＃｀Д´)", "(●｀∀´●)", "(｀д´)", "(￣ω￣;)"],
+  // Narrative kaomoji must also stay within the subset accepted by
+  // DingTalk emotion/reply. Removed as unstable/bad after repeated direct
+  // API retests: `(´• ω •`)`.
+  "叙事": ["(。・ω・。)", "(￣▽￣)", "(・・?)", "(。_。)", "(￣ω￣)", "(´▽`)", "(=_=)"],
+  // Request kaomoji must exclude strings that stayed unstable across
+  // repeated direct API retests. Removed as unstable/bad:
+  // `(づ｡◕‿‿◕｡)づ`, `(⁄ ⁄•⁄ω⁄•⁄ ⁄)`.
+  "请求": ["(っ´∀｀)っ", "(๑•̀ω•́๑)✧", "(p≧w≦q)", "(♡˙︶˙♡)", "(´;ω;｀)", "(人•ᴗ•✿)"],
+  "未知": ["(•̀_•́)", "(；一_一)", "(???)"],
+};
+
+function containsAny(text: string, words: readonly string[]): boolean {
+  return words.some(word => text.includes(word));
+}
+
+export function classifyAckReactionEmoji(sentence: unknown): AckReactionClassifyResult {
+  if (!sentence || typeof sentence !== "string") {
+    return { type: "未知", emoji: `${CATCHPHRASE}(•̀_•́)` };
+  }
+
+  const s = sentence.trim();
+  const isPolitePhrase = POLITE_EXCLUSIONS.some(phrase => s.includes(phrase));
+  const isQuestion = /吗|呢|？|\?/.test(s);
+  const startsWithPlease = s.startsWith("请");
+  const hasExclamation = /[!！]/.test(s);
+  const imperativeStart = !isPolitePhrase && /^(快|别|不要|不准|必须|马上|立刻)/.test(s);
+
+  let type: SentenceType;
+  if (containsAny(s, KEYWORDS.request) || (isQuestion && (startsWithPlease || /帮|麻烦/.test(s)))) {
+    type = "请求";
+  } else if (imperativeStart || containsAny(s, KEYWORDS.command)) {
+    type = "命令";
+  } else if (containsAny(s, KEYWORDS.praise)) {
+    type = "夸奖";
+  } else if (containsAny(s, KEYWORDS.blame) || (hasExclamation && /烦|讨厌|笨|蠢|差|气死/.test(s))) {
+    type = "责怪";
+  } else {
+    type = "叙事";
+  }
+
+  const emojiList = EMOJIS[type];
+  const emoji = emojiList[Math.floor(Math.random() * emojiList.length)];
+  return { type, emoji: `${CATCHPHRASE}${emoji}` };
+}

package/src/ack-reaction-service.ts

@@ -0,0 +1,182 @@
+import axios from "axios";
+import { getAccessToken } from "./auth";
+import type { DingTalkConfig } from "./types";
+import { formatDingTalkErrorPayloadLog, getErrorMessage, getProxyBypassOption } from "./utils";
+
+// DingTalk currently exposes a dedicated native "thinking" reaction flow rather than
+// a generic arbitrary-emoji reaction API for this plugin path.
+const DINGTALK_NATIVE_ACK_REACTION = "🤔思考中";
+const THINKING_EMOTION_ID = "2659900";
+const THINKING_EMOTION_BACKGROUND_ID = "im_bg_1";
+// DingTalk `emotion/reply` occasionally races with just-arrived inbound
+// messages or returns transient 5xx responses. Keep the first attempt
+// immediate, then retry twice with short backoff windows before giving up.
+const THINKING_REACTION_ATTACH_DELAYS_MS = [0, 400, 1200] as const;
+const THINKING_REACTION_RECALL_DELAYS_MS = [0, 1500, 5000] as const;
+
+type AckReactionLogger = {
+  debug?: (msg: string) => void;
+  info?: (msg: string) => void;
+  warn?: (msg: string) => void;
+};
+
+type AckReactionTarget = {
+  msgId: string;
+  conversationId: string;
+  robotCode?: string;
+  reactionName?: string;
+};
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
+}
+
+function formatAckReactionTarget(data: AckReactionTarget): string {
+  return `msgId=${data.msgId || "-"} conversationId=${data.conversationId || "-"} reactionName=${data.reactionName || DINGTALK_NATIVE_ACK_REACTION}`;
+}
+
+function resolveAckReactionPayload(config: DingTalkConfig, data: AckReactionTarget): {
+  robotCode: string;
+  reactionName: string;
+} | null {
+  const robotCode = (data.robotCode || config.robotCode || config.clientId || "").trim();
+  const reactionName =
+    (data.reactionName || DINGTALK_NATIVE_ACK_REACTION).trim() || DINGTALK_NATIVE_ACK_REACTION;
+  if (!robotCode || !data.msgId || !data.conversationId) {
+    return null;
+  }
+  return { robotCode, reactionName };
+}
+
+async function callEmotionApi(
+  config: DingTalkConfig,
+  data: AckReactionTarget,
+  endpoint: "reply" | "recall",
+  successLog: string,
+  errorLogPrefix: string,
+  errorPayloadKey: "inbound.ackReactionAttach" | "inbound.ackReactionRecall",
+  log?: AckReactionLogger,
+): Promise<{ ok: boolean; error?: unknown }> {
+  const payload = resolveAckReactionPayload(config, data);
+  if (!payload) {
+    return { ok: false };
+  }
+
+  try {
+    const token = await getAccessToken(config, log as any);
+    await axios.post(
+      `https://api.dingtalk.com/v1.0/robot/emotion/${endpoint}`,
+      {
+        robotCode: payload.robotCode,
+        openMsgId: data.msgId,
+        openConversationId: data.conversationId,
+        emotionType: 2,
+        emotionName: payload.reactionName,
+        textEmotion: {
+          emotionId: THINKING_EMOTION_ID,
+          emotionName: payload.reactionName,
+          text: payload.reactionName,
+          backgroundId: THINKING_EMOTION_BACKGROUND_ID,
+        },
+      },
+      {
+        headers: {
+          "x-acs-dingtalk-access-token": token,
+          "Content-Type": "application/json",
+        },
+        timeout: 5000,
+        ...getProxyBypassOption(config),
+      },
+    );
+    log?.info?.(successLog);
+    return { ok: true };
+  } catch (err: unknown) {
+    const response = asRecord(asRecord(err)?.response);
+    log?.warn?.(`${errorLogPrefix}: ${getErrorMessage(err)}`);
+    if (response?.data !== undefined) {
+      log?.warn?.(formatDingTalkErrorPayloadLog(errorPayloadKey, response.data));
+    }
+    return { ok: false, error: err };
+  }
+}
+
+function isRetryableEmotionApiError(err: unknown): boolean {
+  const response = asRecord(asRecord(err)?.response);
+  const data = asRecord(response?.data);
+  const status = Number(response?.status ?? 0);
+  const errorCode = String(data?.code || "").trim().toLowerCase();
+  if (!response) {
+    return true;
+  }
+  if (status >= 500) {
+    return true;
+  }
+  return errorCode === "system.err";
+}
+
+export async function attachNativeAckReaction(
+  config: DingTalkConfig,
+  data: AckReactionTarget,
+  log?: AckReactionLogger,
+): Promise<boolean> {
+  for (let index = 0; index < THINKING_REACTION_ATTACH_DELAYS_MS.length; index += 1) {
+    const delayMs = THINKING_REACTION_ATTACH_DELAYS_MS[index];
+    if (delayMs > 0) {
+      await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+    const attempt = index + 1;
+    const attemptLabel = `${attempt}/${THINKING_REACTION_ATTACH_DELAYS_MS.length}`;
+    const result = await callEmotionApi(
+      config,
+      data,
+      "reply",
+      `[DingTalk] Native ack reaction attach succeeded (${formatAckReactionTarget(data)} attempt=${attemptLabel})`,
+      `[DingTalk] Native ack reaction attach failed (${formatAckReactionTarget(data)} attempt=${attemptLabel})`,
+      "inbound.ackReactionAttach",
+      log,
+    );
+    if (result.ok) {
+      return true;
+    }
+    const shouldRetry = isRetryableEmotionApiError(result.error);
+    if (!shouldRetry || attempt === THINKING_REACTION_ATTACH_DELAYS_MS.length) {
+      break;
+    }
+    log?.debug?.(
+      `[DingTalk] Retrying native ack reaction attach (${formatAckReactionTarget(data)} nextAttempt=${attempt + 1}/${THINKING_REACTION_ATTACH_DELAYS_MS.length})`,
+    );
+  }
+  return false;
+}
+
+async function recallNativeAckReaction(
+  config: DingTalkConfig,
+  data: AckReactionTarget,
+  log?: AckReactionLogger,
+): Promise<boolean> {
+  const result = await callEmotionApi(
+    config,
+    data,
+    "recall",
+    "[DingTalk] Native ack reaction recall succeeded",
+    "[DingTalk] Native ack reaction recall failed",
+    "inbound.ackReactionRecall",
+    log,
+  );
+  return result.ok;
+}
+
+export async function recallNativeAckReactionWithRetry(
+  config: DingTalkConfig,
+  data: AckReactionTarget,
+  log?: AckReactionLogger,
+): Promise<void> {
+  for (const delayMs of THINKING_REACTION_RECALL_DELAYS_MS) {
+    if (delayMs > 0) {
+      await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+    if (await recallNativeAckReaction(config, data, log)) {
+      return;
+    }
+  }
+}

package/src/attachment-text-extractor.ts

@@ -0,0 +1,148 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { AttachmentTextSource } from "./types";
+
+const MAX_EXTRACTED_TEXT_CHARS = 6000;
+const MAX_ATTACHMENT_EXTRACT_BYTES = 2 * 1024 * 1024;
+
+export interface AttachmentTextExtractionInput {
+  path: string;
+  mimeType?: string;
+  fileName?: string;
+}
+
+export interface AttachmentTextExtractionResult {
+  text: string;
+  truncated: boolean;
+  sourceType: AttachmentTextSource;
+}
+
+async function isFileTooLarge(filePath: string): Promise<boolean> {
+  const stat = await fs.stat(filePath);
+  return stat.size > MAX_ATTACHMENT_EXTRACT_BYTES;
+}
+
+function isTextLikeMimeType(mimeType: string | undefined): boolean {
+  if (!mimeType) {
+    return false;
+  }
+  return (
+    mimeType.startsWith("text/") ||
+    mimeType === "application/json" ||
+    mimeType === "application/xml" ||
+    mimeType === "application/javascript"
+  );
+}
+
+function normalizeWhitespace(text: string): string {
+  return text
+    .replace(/\r\n/g, "\n")
+    .split("\u0000").join("")
+    .replace(/[ \t]{2,}/g, " ")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function limitExtractedText(text: string): AttachmentTextExtractionResult | null {
+  const normalized = normalizeWhitespace(text);
+  if (!normalized) {
+    return null;
+  }
+  const truncated = normalized.length > MAX_EXTRACTED_TEXT_CHARS;
+  const limited = truncated ? `${normalized.slice(0, MAX_EXTRACTED_TEXT_CHARS)}\n\n[内容已截断]` : normalized;
+  return {
+    text: limited,
+    truncated,
+    sourceType: "text",
+  };
+}
+
+function stripHtml(html: string): string {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&amp;/gi, "&")
+    .replace(/&#39;/gi, "'")
+    .replace(/&quot;/gi, "\"");
+}
+
+async function extractTextLikeFile(filePath: string): Promise<AttachmentTextExtractionResult | null> {
+  const raw = await fs.readFile(filePath, "utf8");
+  return limitExtractedText(raw);
+}
+
+async function extractPdf(filePath: string): Promise<AttachmentTextExtractionResult | null> {
+  const pdfParseModule = await import("pdf-parse");
+  const fileBuffer = await fs.readFile(filePath);
+  const parser = new pdfParseModule.PDFParse({ data: new Uint8Array(fileBuffer) });
+  try {
+    const result = await parser.getText();
+    const limited = limitExtractedText(result.text || "");
+    return limited ? { ...limited, sourceType: "pdf" } : null;
+  } finally {
+    await parser.destroy();
+  }
+}
+
+async function extractDocx(filePath: string): Promise<AttachmentTextExtractionResult | null> {
+  const mammothModule = await import("mammoth");
+  const result = await mammothModule.extractRawText({ path: filePath });
+  const limited = limitExtractedText(result.value || "");
+  return limited ? { ...limited, sourceType: "docx" } : null;
+}
+
+async function extractHtml(filePath: string): Promise<AttachmentTextExtractionResult | null> {
+  const raw = await fs.readFile(filePath, "utf8");
+  const limited = limitExtractedText(stripHtml(raw));
+  return limited ? { ...limited, sourceType: "html" } : null;
+}
+
+export async function extractAttachmentText(
+  input: AttachmentTextExtractionInput,
+): Promise<AttachmentTextExtractionResult | null> {
+  const mimeType = input.mimeType?.toLowerCase();
+  const fileName = (input.fileName || path.basename(input.path)).toLowerCase();
+
+  if (mimeType?.startsWith("image/") || mimeType?.startsWith("audio/") || mimeType?.startsWith("video/")) {
+    return null;
+  }
+
+  if (await isFileTooLarge(input.path)) {
+    return null;
+  }
+
+  if (
+    mimeType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ||
+    fileName.endsWith(".docx")
+  ) {
+    return extractDocx(input.path);
+  }
+
+  if (mimeType === "application/pdf" || fileName.endsWith(".pdf")) {
+    return extractPdf(input.path);
+  }
+
+  if (mimeType === "text/html" || mimeType === "application/xhtml+xml" || fileName.endsWith(".html") || fileName.endsWith(".htm")) {
+    return extractHtml(input.path);
+  }
+
+  if (
+    isTextLikeMimeType(mimeType) ||
+    fileName.endsWith(".txt") ||
+    fileName.endsWith(".md") ||
+    fileName.endsWith(".markdown") ||
+    fileName.endsWith(".csv") ||
+    fileName.endsWith(".json") ||
+    fileName.endsWith(".xml") ||
+    fileName.endsWith(".log")
+  ) {
+    return extractTextLikeFile(input.path);
+  }
+
+  return null;
+}

package/src/card-callback-service.ts

@@ -0,0 +1,119 @@
+export interface CardCallbackAnalysis {
+  summary: string;
+  actionId?: string;
+  feedbackTarget?: string;
+  feedbackAckText?: string;
+  userId?: string;
+  processQueryKey?: string;
+}
+
+function stringifyCandidate(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseEmbeddedJson(value: unknown): unknown {
+  if (typeof value !== "string") {
+    return value;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+export function extractCardActionSummary(data: unknown): string {
+  const record = asRecord(data);
+  const candidates = [
+    record?.action,
+    record?.actionType,
+    record?.actionValue,
+    record?.value,
+    record?.eventType,
+    record?.operate,
+    record?.callbackType,
+    record?.cardPrivateData,
+    record?.privateData,
+  ].filter((value) => value !== undefined && value !== null);
+
+  if (candidates.length === 0) {
+    return "(no action field found)";
+  }
+
+  return candidates.map(stringifyCandidate).join(" | ");
+}
+
+export function extractCardActionId(data: unknown): string | undefined {
+  const record = asRecord(data);
+  const embeddedValue = parseEmbeddedJson(record?.value);
+  const embeddedContent = parseEmbeddedJson(record?.content);
+
+  for (const source of [embeddedValue, embeddedContent, record].filter(Boolean)) {
+    const sourceRecord = asRecord(source);
+    const cardPrivateData = asRecord(sourceRecord?.cardPrivateData);
+    const actionIds = cardPrivateData?.actionIds;
+    if (Array.isArray(actionIds) && actionIds.length > 0 && typeof actionIds[0] === "string") {
+      return actionIds[0];
+    }
+    if (typeof sourceRecord?.actionValue === "string" && sourceRecord.actionValue.trim()) {
+      return sourceRecord.actionValue.trim();
+    }
+    if (typeof sourceRecord?.eventKey === "string" && sourceRecord.eventKey.trim()) {
+      return sourceRecord.eventKey.trim();
+    }
+    if (typeof sourceRecord?.value === "string" && sourceRecord.value.trim()) {
+      return sourceRecord.value.trim();
+    }
+  }
+
+  return undefined;
+}
+
+export function analyzeCardCallback(data: unknown): CardCallbackAnalysis {
+  const record = asRecord(data);
+  const summary = extractCardActionSummary(data);
+  const actionId = extractCardActionId(data);
+  const embeddedValue = asRecord(parseEmbeddedJson(record?.value));
+  const embeddedContent = asRecord(parseEmbeddedJson(record?.content));
+  const processQueryKey =
+    (typeof record?.processQueryKey === "string" && record.processQueryKey.trim()) ||
+    (typeof embeddedValue?.processQueryKey === "string" && embeddedValue.processQueryKey.trim()) ||
+    (typeof embeddedContent?.processQueryKey === "string" && embeddedContent.processQueryKey.trim()) ||
+    undefined;
+
+  if (actionId !== "feedback_up" && actionId !== "feedback_down") {
+    return { summary, actionId, processQueryKey };
+  }
+
+  const spaceType = typeof record?.spaceType === "string" ? record.spaceType.trim().toLowerCase() : "";
+  const spaceId = typeof record?.spaceId === "string" ? record.spaceId.trim() : "";
+  const userId = typeof record?.userId === "string" ? record.userId.trim() : "";
+  const feedbackTarget = spaceType === "im" ? userId : spaceId;
+  const feedbackAckText =
+    actionId === "feedback_up"
+      ? "✅ 已收到你的点赞（反馈已记录）"
+      : "⚠️ 已收到你的点踩（反馈已记录，我会改进）";
+
+  return {
+    summary,
+    actionId,
+    feedbackTarget: feedbackTarget || undefined,
+    feedbackAckText,
+    userId: userId || undefined,
+    processQueryKey,
+  };
+}

package/src/card-draft-controller.ts

@@ -0,0 +1,114 @@
+/**
+ * Card draft controller for throttled AI Card streaming updates.
+ *
+ * Wraps {@link createDraftStreamLoop} with a phase-based state machine
+ * (idle → reasoning → answer) that manages what content is sent to the
+ * DingTalk AI Card during the reply lifecycle.
+ *
+ * Responsibilities (and non-responsibilities):
+ * - DOES manage throttled card preview updates via streamAICard
+ * - DOES enforce single-flight, latest-wins, phase-gated semantics
+ * - Does NOT handle tool append, finalize, or markdown fallback —
+ *   those stay in inbound-handler's deliver callback.
+ */
+
+import { formatContentForCard, streamAICard } from "./card-service";
+import { createDraftStreamLoop } from "./draft-stream-loop";
+import type { AICardInstance, Logger } from "./types";
+
+export type CardDraftPhase = "idle" | "reasoning" | "answer";
+
+export interface CardDraftController {
+    updateAnswer: (text: string) => void;
+    updateReasoning: (text: string) => void;
+    /** Signal that a new assistant turn has started (e.g. after a tool call). */
+    notifyNewAssistantTurn: () => void;
+    flush: () => Promise<void>;
+    waitForInFlight: () => Promise<void>;
+    stop: () => void;
+    isFailed: () => boolean;
+    /** Last content sent to card (reasoning or answer). */
+    getLastContent: () => string;
+    /** Last content sent to card during answer phase only. */
+    getLastAnswerContent: () => string;
+}
+
+export function createCardDraftController(params: {
+    card: AICardInstance;
+    throttleMs?: number;
+    log?: Logger;
+}): CardDraftController {
+    let phase: CardDraftPhase = "idle";
+    let failed = false;
+    let stopped = false;
+    let lastSentContent = "";
+    let lastAnswerContent = "";
+    let answerPrefix = "";
+    let turnBoundaryPending = false;
+
+    const loop = createDraftStreamLoop({
+        throttleMs: params.throttleMs ?? 300,
+        isStopped: () => stopped || failed,
+        sendOrEditStreamMessage: async (content: string) => {
+            try {
+                await streamAICard(params.card, content, false, params.log);
+                lastSentContent = content;
+                if (phase === "answer") {
+                    lastAnswerContent = content;
+                }
+            } catch (err: unknown) {
+                failed = true;
+                const message = err instanceof Error ? err.message : String(err);
+                params.log?.warn?.(`[DingTalk][AICard] Stream failed: ${message}`);
+            }
+        },
+    });
+
+    return {
+        updateReasoning: (text: string) => {
+            if (stopped || failed || phase === "answer") { return; }
+            phase = "reasoning";
+            const formatted = formatContentForCard(text, "thinking");
+            if (formatted) {
+                loop.update(formatted);
+            }
+        },
+
+        updateAnswer: (text: string) => {
+            if (stopped || failed) { return; }
+            if (phase !== "answer") {
+                params.log?.debug?.(`[DingTalk][Draft] phase ${phase} → answer`);
+                phase = "answer";
+                if (turnBoundaryPending && lastAnswerContent) {
+                    answerPrefix = lastAnswerContent + "\n\n";
+                }
+                turnBoundaryPending = false;
+            }
+            const trimmed = text?.trimStart();
+            if (trimmed) {
+                loop.update(answerPrefix + trimmed);
+            }
+        },
+
+        notifyNewAssistantTurn: () => {
+            if (stopped || failed) { return; }
+            turnBoundaryPending = true;
+            if (phase === "reasoning") {
+                loop.resetPending();
+            }
+            phase = "idle";
+        },
+
+        flush: () => loop.flush(),
+        waitForInFlight: () => loop.waitForInFlight(),
+
+        stop: () => {
+            stopped = true;
+            loop.stop();
+        },
+
+        isFailed: () => failed,
+        getLastContent: () => lastSentContent,
+        getLastAnswerContent: () => lastAnswerContent,
+    };
+}