minimal-agent 0.18.10 → 0.18.12

package/src/loop/messages.ts

@@ -0,0 +1,166 @@
+import crypto from 'node:crypto';
+import { buildUserContent } from '../multimodal.js';
+import type { Message, ToolCall, ToolResult, Provider } from '../types.js';
+// ---------------- 辅助函数 ----------------
+
+/**
+ * 易变上下文只存在于 provider 请求副本中，不会进入会话历史。
+ */
+export const SYSTEM_REMINDER_OPEN = '<system-reminder>';
+export const SYSTEM_REMINDER_CLOSE = '</system-reminder>';
+
+/**
+ * Attach transient context to the current turn's user message in a model-only
+ * clone. Later tool-loop requests reuse the same decorated message, making each
+ * serialized request a strict prefix extension of the previous one.
+ */
+export function buildModelMessages(
+  history: Message[],
+  transientContext?: string,
+  currentUserMessageId?: string,
+): Message[] {
+  history = history.filter((message) => !(message.role === 'system' && message._ephemeral));
+  const transient = transientContext?.trim();
+  if (!transient) return history;
+  let index = currentUserMessageId
+    ? history.findIndex((message) => message.role === 'user' && message.id === currentUserMessageId)
+    : -1;
+  if (index < 0) {
+    for (let cursor = history.length - 1; cursor >= 0; cursor--) {
+      if (history[cursor]?.role === 'user') {
+        index = cursor;
+        break;
+      }
+    }
+  }
+  if (index < 0) return history;
+  const target = history[index];
+  if (target.role !== 'user') return history;
+  const reminder = `${SYSTEM_REMINDER_OPEN}\n${transient}\n${SYSTEM_REMINDER_CLOSE}`;
+  const content =
+    typeof target.content === 'string'
+      ? `${target.content}\n\n${reminder}`
+      : [...target.content, { type: 'text' as const, text: reminder }];
+  const next = [...history];
+  next[index] = { ...target, content };
+  return next;
+}
+
+// 关键节点图像核验的合成消息标记：既是给模型的提示前缀，也是 evictPriorVisionShots 识别旧图消息的锚。
+export const VISION_SHOT_MARKER = '【实况图像】';
+
+/**
+ * 历史标记。这套机制最初只有 WebBrowser 用得上，文案写死了「浏览器」；
+ * 现在 Bash 的 ATTACH_IMAGE sentinel 也能产图（屏幕截图 / 生成的产物），文案必须中性。
+ * 但**持久化会话里仍存着旧前缀的消息**，淘汰逻辑必须继续认它 ——
+ * 否则老会话里的旧截图永远不会被降级，图片一路累积撑爆上下文。
+ */
+const LEGACY_VISION_SHOT_MARKERS = ['【浏览器实况截图】'] as const;
+
+const VISION_SHOT_PROMPT = `${VISION_SHOT_MARKER}上面是刚才工具执行后附带的真实图像（浏览器页面 / 屏幕截图 / 生成的产物）。请仔细看图核对：是否真的到达/呈现了你预期的状态？若与预期不符（空白/报错/弹窗遮挡/验证拦截/内容不对），不要假设成功，如实说明并调整下一步。`;
+
+/** 一条 user 消息的文本是否是「实况图像」合成消息（含历史前缀）。 */
+function isVisionShotText(text: string): boolean {
+  return text.startsWith(VISION_SHOT_MARKER) || LEGACY_VISION_SHOT_MARKERS.some((marker) => text.startsWith(marker));
+}
+
+/**
+ * 把本轮工具附带的实况截图（ToolResult.visionImages）组装成一条带图 user 消息喂给模型自我核验。
+ * - 仅在模型明确支持识图时注入（provider.supportsVision === true）；否则丢弃（不假装核验、也不给非视觉端点发图触发 400）。
+ * - 注入前先把历史里旧的截图消息降级为纯文字占位（evictPriorVisionShots），保证上下文里最多一张实况图，
+ *   避免图片累积撑爆上下文（呼应浏览器 ADR「高频帧只存内存、只持久化最终结果」）。
+ * - **失败的工具结果同样回填**：出错现场那张图往往比成功时更有信息量（权限弹窗、
+ *   验证拦截、意外的前台窗口）。此前这里要求 `ok === true`，逼得想附图的工具只能
+ *   把失败伪装成成功——见 types.ts 里 ToolResult 那段注释。
+ */
+export async function injectVisionFollowups(
+  history: Message[],
+  settled: { result: ToolResult }[],
+  provider: Provider,
+): Promise<Message | null> {
+  if (provider.supportsVision === false) return null;
+  const images = settled.flatMap((s) => s.result.visionImages ?? []);
+  if (images.length === 0) return null;
+  evictPriorVisionShots(history);
+  // 工具可以给自己这批图配一句说明（visionNote）。内核只负责把它拼在通用提示之后，
+  // 不解读内容——「这是一组 1Hz 连续帧」这类语义只有产图的工具知道。
+  const notes = settled
+    .flatMap((s) => (s.result.visionNote ? [s.result.visionNote] : []))
+    .filter((note, index, all) => all.indexOf(note) === index);
+  const text = notes.length > 0 ? `${VISION_SHOT_PROMPT}\n\n${notes.join('\n\n')}` : VISION_SHOT_PROMPT;
+  const content = await buildUserContent({ text, images });
+  const msg: Message = {
+    role: 'user',
+    content,
+    timestamp: Date.now(),
+    id: crypto.randomUUID(),
+  };
+  history.push(msg);
+  return msg;
+}
+
+/** 把历史里旧的实况图像 user 消息降级为纯文字占位、剔除其图片，释放上下文（只保留最近一张真图）。 */
+export function evictPriorVisionShots(history: Message[]): void {
+  for (const msg of history) {
+    if (msg.role !== 'user' || !Array.isArray(msg.content)) continue;
+    const textPart = msg.content.find((p) => p.type === 'text');
+    if (textPart?.type === 'text' && isVisionShotText(textPart.text)) {
+      msg.content = `${VISION_SHOT_MARKER}（此前的实况图像已从上下文移除以节省空间。）`;
+    }
+  }
+}
+
+/**
+ * 用户按ESC手动中断
+ */
+export function pushManualInterruptMarker(history: Message[]): void {
+  history.push({
+    role: 'user',
+    content: '(用户按下了 ESC/Ctrl+C 中断了任务。等待用户新指令。)',
+    timestamp: Date.now(),
+    id: crypto.randomUUID(),
+  });
+}
+
+/**
+ * 有新的用户输入在队列中，当前安全停靠
+ */
+export function pushQueuedInputMarker(history: Message[]): void {
+  history.push({
+    role: 'user',
+    content: [
+      '(系统提示：用户在工作过程中发送了新的消息。',
+      '你现在看到的是上一轮工作在被打断前已完成的部分。',
+      '请阅读用户的新消息，判断：',
+      '1. 如果是不相关的新任务：简要确认已收到，转向新任务，可在新任务完成后询问是否回到之前工作',
+      '2. 如果是补充信息或前置依赖：把新信息纳入考虑，判断是否需要调整已做的工作，然后继续',
+      '3. 如果是改变方向或取消：评估已完成的部分，说明你对变更的理解，按新方向推进)',
+    ].join('\n'),
+    timestamp: Date.now(),
+    id: crypto.randomUUID(),
+  });
+}
+
+/** 把一条 tool_call_delta 合并到累积数组上 */
+export function mergeToolCallDelta(
+  acc: ToolCall[],
+  ev: {
+    index: number;
+    id?: string;
+    name?: string;
+    argumentsDelta?: string;
+  },
+): void {
+  let slot = acc[ev.index];
+  if (!slot) {
+    slot = {
+      id: '',
+      type: 'function',
+      function: { name: '', arguments: '' },
+    };
+    acc[ev.index] = slot;
+  }
+  if (ev.id) slot.id = ev.id;
+  if (ev.name) slot.function.name += ev.name;
+  if (ev.argumentsDelta) slot.function.arguments += ev.argumentsDelta;
+}

package/src/loop/options.js

@@ -0,0 +1 @@
+export {};

package/src/loop/options.ts

@@ -0,0 +1,155 @@
+import type { ContextBundle } from '../context/contextBundle.js';
+import type { chat as defaultChat } from '../llm/client.js';
+import type { AgentRuntimeContext } from '../runtime/agentRuntimeContext.js';
+import type { InvocationPolicy } from '../runtime/invocationPolicy.js';
+import type { SessionState } from '../session/sessionState.js';
+import type { ToolGate } from '../toolGate.js';
+import type {
+  DeliverableManifest,
+  ImageDetail,
+  ImageInputSpec,
+  Message,
+  Provider,
+  Tool,
+  ToolCallContext,
+  ToolResult,
+} from '../types.js';
+export interface RunQueryOptions {
+  agentHandoff?: ToolCallContext['agentHandoff'];
+  /** Generic embedded-task policy; omitted for ordinary conversation turns. */
+  invocationPolicy?: InvocationPolicy;
+  executionServices?: ToolCallContext['executionServices'];
+  provider: Provider;
+  /** Canonical host-issued trust context. Legacy fields below remain adapters. */
+  runtimeContext?: AgentRuntimeContext;
+  /** 历史会被 mutate（追加新消息、压缩时整体替换内容）；调用方持同一引用 */
+  history: Message[];
+  /** Host mailbox: consume at model boundaries, never mutate an in-flight request. */
+  takePendingMessages?: () => Message[];
+  /** 最多多少轮（防止失控调工具） */
+  maxTurns?: number;
+  /**
+   * 工作流 agent/llm 步的工具白名单：只把这些工具下发给模型并允许执行。
+   * 缺省 = 当前宿主工具全集；空数组 = 无工具。
+   */
+  allowedTools?: string[];
+  /** 调用方工具边界名称，仅用于准确解释越界调用；缺省表示宿主能力边界。 */
+  toolBoundaryLabel?: string;
+  /** Disable Advisor checkpoints for an explicitly read-only embedded node. */
+  advisorCheckpoints?: boolean;
+  /** Tools the host/workflow explicitly requires; emergency schema reduction preserves them. */
+  requiredTools?: string[];
+  /**
+   * provider 原生结构化输出（`response_format.json_schema`），原样透传给 `chat()`。
+   *
+   * ⚠️ **只在本轮没有工具时才该传**：response_format 会强制**每一条** assistant
+   * 消息都是 JSON，而工具调用轮的 assistant 消息带的是 tool_calls —— 两者互斥，
+   * 同时给会让带工具的循环直接崩。工作流引擎因此只在 `llm()`（零工具）和
+   * schema 修复轮（零工具）上传它；`agent()` 的结构化输出走「跑完再修复」那条路。
+   *
+   * Anthropic 格式的 provider 不支持，`chat()` 会在发请求前抛错 —— 所以它是
+   * **加成**而不是地基，地基是引擎侧的「校验 + 有界修复」。
+   */
+  responseFormat?: {
+    type: 'json_schema';
+    json_schema: {
+      name: string;
+      schema: Record<string, unknown>;
+      strict?: boolean;
+    };
+  };
+  /**
+   * Host-provided tool catalog. Production hosts normally omit this and use ALL_TOOLS;
+   * tests and embedders with custom executors must provide matching schemas so the
+   * model-visible catalog and execution boundary remain identical.
+   */
+  availableTools?: readonly Tool[];
+  /** 用户取消 */
+  signal?: AbortSignal;
+  /**
+   * 回调：宿主检查是否有排队输入需要在安全点处理。
+   * loop只在安全检查点调用：每轮while开始时、工具全部执行完成后。
+   * 返回true表示应该结束当前turn（自然return，不抛异常）。
+   */
+  hasQueuedInput?: () => boolean;
+  /** Concurrent-safe tool throughput; defaults to the safe segment size, host may tune upward. */
+  toolConcurrency?: number;
+  /**
+   * 回调：工具开始/结束执行，用于宿主跟踪运行中工具状态。
+   */
+  onToolStart?: (toolName: string, toolCallId: string) => void;
+  onToolEnd?: (toolCallId: string, wasAborted: boolean) => void;
+  /**
+   * 多租户场景下注入隔离的 session 级状态；缺省走模块单例。
+   * TUI / print（单进程单 session）不传即可；HTTP server per-request 必须传。
+   */
+  sessionState?: SessionState;
+  /**
+   * 注入 chat 实现（仅测试用）。
+   *
+   * 之前用 bun:test 的 mock.module 替换 llm/client.js 会进程全局污染所有跨文件
+   * import；改用显式 DI 后，测试传 stub 进来即可，零污染。生产代码不需要传。
+   */
+  chat?: typeof defaultChat;
+  /**
+   * 注入 executeTool 实现（仅测试用）。同上，DI 而非 mock.module，零污染。
+   */
+  executeTool?: (name: string, rawArgsJson: string, signal?: AbortSignal, ctx?: ToolCallContext) => Promise<ToolResult>;
+  /**
+   * Trusted host persistence boundary for formal results. It runs after
+   * PresentResult validates the files but before tool_end is published or the
+   * result is appended to history. Throwing turns the tool call into a failure,
+   * so a UI can never display an uncommitted delivery as durable.
+   */
+  commitFormalDelivery?: (input: {
+    toolCallId: string;
+    turnId: string;
+    manifest: DeliverableManifest;
+  }) => Promise<void>;
+  /**
+   * 工具执行闸门（通用机制，见 src/toolGate.ts）：loop 在执行每个工具前
+   * await 它拿放行/拒绝；拒绝时把 reason 当 tool_result 回填。内核零策略——审批语义
+   * 全在宿主（如 gateway 跨机指令同意闸门）。缺省不传 = 全放行，行为不变。
+   */
+  toolGate?: ToolGate;
+  /**
+   * 仅对本次回合可见的系统上下文。它会随每次模型调用注入，但不会写入 history、
+   * 会话文件或压缩摘要，适合项目事实、远程委托和附件概要等外部上下文。
+   *
+   * 注入到本轮用户消息的模型副本，不改变 UI 或持久化历史。
+   */
+  transientContext?: string;
+  /** Structured transient fragments allow deterministic request-time degradation. */
+  transientBundle?: ContextBundle;
+  /** Provider cache routing for this conversation; never persisted. */
+  promptCache?: import('../types.js').PromptCacheContext;
+  /** 仅供宿主 UI 恢复附件卡片；不会发送给 LLM。 */
+  userAttachments?: import('../types.js').MessageAttachmentRef[];
+  /** Host-authorized files for typed workflow inputs; runtime-only paths. */
+  inputResources?: readonly import('../types.js').InvocationResource[];
+  /** Stable host-provided identity for the user message of this turn. */
+  userMessageId?: string;
+  /** Trusted local origin for every message created by this run. */
+  messageProvenance?: import('../types.js').ConversationProvenance;
+  /** Browser element chips are persisted for UI but stripped before provider calls. */
+  userBrowserReferences?: import('../types.js').MessageBrowserReference[];
+  /** 显式传入的图片附件（-p --image / stream-json images）。 */
+  imageInputs?: ImageInputSpec[];
+  /** 是否解析用户文本里的 @./image.png / 图片 URL。TUI 默认开启。 */
+  parseInlineImages?: boolean;
+  /** 图片 detail 默认值：low/default/high。 */
+  imageDetail?: ImageDetail;
+  /** OpenAI 兼容扩展：图片最长边像素。 */
+  imageMaxLongSidePixel?: number;
+  /** Host-provided browser ownership scope; never exposed to the model. */
+  browserRun?: ToolCallContext['browserRun'];
+  /** Host-provided native desktop-control scope; absent means ComputerUse is not exposed. */
+  computerRun?: ToolCallContext['computerRun'];
+  /** Trusted host-only human handoff bridge for native Computer Use. */
+  computerIntervention?: ToolCallContext['computerIntervention'];
+  memoryContext?: {
+    access: import('../runtime/agentRuntimeContext.js').MemoryAccessInput;
+    workspaceId?: string;
+    sessionId?: string;
+  };
+}

package/src/loop/progressStream.js

@@ -0,0 +1,40 @@
+/** Bridge callback progress to a generator, draining events before returning or throwing. */
+export async function* progressStream(run) {
+    const queue = [];
+    let wake;
+    let finished = false;
+    const notify = () => {
+        wake?.();
+        wake = undefined;
+    };
+    const result = Promise.resolve().then(() => run((event) => {
+        queue.push(event);
+        notify();
+    }));
+    const settled = result
+        .then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }))
+        .then((outcome) => {
+        finished = true;
+        notify();
+        return outcome;
+    });
+    try {
+        while (!finished || queue.length) {
+            while (queue.length)
+                yield queue.shift();
+            if (!finished)
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+        }
+        const outcome = await settled;
+        if (!outcome.ok)
+            throw outcome.error;
+        return outcome.value;
+    }
+    finally {
+        // Generator disposal must not orphan a still-running tool. Cancellation is
+        // owned by the caller's AbortSignal; this boundary only drains settlement.
+        await settled;
+    }
+}

package/src/loop/progressStream.ts

@@ -0,0 +1,44 @@
+/** Bridge callback progress to a generator, draining events before returning or throwing. */
+export async function* progressStream<Event, Result>(
+  run: (emit: (event: Event) => void) => Promise<Result>,
+): AsyncGenerator<Event, Result> {
+  const queue: Event[] = [];
+  let wake: (() => void) | undefined;
+  let finished = false;
+  const notify = () => {
+    wake?.();
+    wake = undefined;
+  };
+  const result = Promise.resolve().then(() =>
+    run((event) => {
+      queue.push(event);
+      notify();
+    }),
+  );
+  const settled = result
+    .then(
+      (value) => ({ ok: true as const, value }),
+      (error) => ({ ok: false as const, error }),
+    )
+    .then((outcome) => {
+      finished = true;
+      notify();
+      return outcome;
+    });
+  try {
+    while (!finished || queue.length) {
+      while (queue.length) yield queue.shift()!;
+      if (!finished)
+        await new Promise<void>((resolve) => {
+          wake = resolve;
+        });
+    }
+    const outcome = await settled;
+    if (!outcome.ok) throw outcome.error;
+    return outcome.value;
+  } finally {
+    // Generator disposal must not orphan a still-running tool. Cancellation is
+    // owned by the caller's AbortSignal; this boundary only drains settlement.
+    await settled;
+  }
+}

package/src/loop/publication.js

@@ -0,0 +1,94 @@
+import { buildContextBudgetPlan } from '../context/budgetPlan.js';
+import { finalAnswerMessages } from '../runtime/finalAnswer.js';
+/** A one-way visibility boundary: never retract or regenerate visible text. */
+export async function* publishFinalAnswer(input) {
+    const { provider, messages, candidate, candidateFinishReason, output, chatFn, options, signal, conversationMode, turnUsage, } = input;
+    let lastFinishReason = candidateFinishReason;
+    let publicationError;
+    let publicationInterrupted = false;
+    let streamed = false;
+    let publishedText = '';
+    let publicationDone = false;
+    yield { type: 'stage_change', stage: 'streaming' };
+    try {
+        const publicationMessages = finalAnswerMessages(messages, candidate, output);
+        const publicationPlan = buildContextBudgetPlan({
+            provider,
+            history: publicationMessages,
+            tools: [],
+        });
+        if (publicationPlan.overBudget)
+            throw new Error('最终表达上下文超过模型输入上限，未发送请求。');
+        if (signal?.aborted || options.hasQueuedInput?.()) {
+            publicationInterrupted = true;
+            throw new Error('最终发布已取消。');
+        }
+        turnUsage.totalCalls += 1;
+        for await (const event of chatFn({
+            provider,
+            messages: publicationMessages,
+            tools: [],
+            signal,
+            conversationMode: conversationMode,
+            promptCache: options.promptCache,
+        })) {
+            if (event.type === 'done' && !publicationDone) {
+                publicationDone = true;
+                if (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number') {
+                    turnUsage.reportedCalls += 1;
+                    turnUsage.inputTokens += event.promptTokens ?? 0;
+                    turnUsage.outputTokens += event.outputTokens ?? 0;
+                }
+            }
+            if (signal?.aborted || options.hasQueuedInput?.()) {
+                publicationInterrupted = true;
+                break;
+            }
+            if (event.type === 'text_delta') {
+                // Final expression is live generation, not an exact-copy replay.
+                // Once visible, text is never replaced or joined with a different draft.
+                publishedText += event.delta;
+                streamed = true;
+                yield { type: 'text', delta: event.delta };
+            }
+            else if (event.type === 'tool_call_delta') {
+                throw new Error('最终表达阶段返回了非预期工具调用，未执行该工具。');
+            }
+            else if (event.type === 'done') {
+                publicationDone = true;
+                lastFinishReason = event.stopReason;
+                if (event.stopReason === 'aborted')
+                    publicationInterrupted = true;
+            }
+        }
+        if (!publicationDone && !publicationInterrupted)
+            throw new Error('最终答案流未正常结束。');
+        if (!publicationInterrupted && lastFinishReason !== 'stop' && lastFinishReason !== 'length')
+            throw new Error('最终答案流缺少有效的结束状态。');
+        if (!publishedText.trim() && !publicationInterrupted)
+            throw new Error('最终表达未返回正文。');
+    }
+    catch (error) {
+        publicationInterrupted ||=
+            signal?.aborted === true || options.hasQueuedInput?.() === true || error?.name === 'AbortError';
+        publicationError = error;
+    }
+    if (publicationError && !publicationInterrupted && !publishedText) {
+        yield {
+            type: 'warning',
+            message: '最终回答流未能开始，已一次性显示内部准备的答案；未进行新的事实核验。',
+        };
+        yield { type: 'text', delta: candidate };
+        streamed = true;
+        publishedText = candidate;
+        lastFinishReason = candidateFinishReason;
+        publicationError = undefined;
+    }
+    return {
+        text: publishedText,
+        lastFinishReason,
+        publicationError,
+        publicationInterrupted,
+        streamed,
+    };
+}

package/src/loop/publication.ts

@@ -0,0 +1,124 @@
+import { buildContextBudgetPlan } from '../context/budgetPlan.js';
+import { finalAnswerMessages } from '../runtime/finalAnswer.js';
+import type { OutputContract } from '../runtime/outputContract.js';
+import type { LoopEvent, Message, Provider, TurnResourceUsage } from '../types.js';
+import type { RunQueryOptions } from './options.js';
+
+type FinishReason = 'stop' | 'tool_calls' | 'length' | 'unknown' | 'aborted';
+/** A one-way visibility boundary: never retract or regenerate visible text. */
+export async function* publishFinalAnswer(input: {
+  provider: Provider;
+  messages: Message[];
+  candidate: string;
+  candidateFinishReason: FinishReason;
+  output: OutputContract;
+  chatFn: NonNullable<RunQueryOptions['chat']>;
+  options: Pick<RunQueryOptions, 'hasQueuedInput' | 'promptCache'>;
+  signal?: AbortSignal;
+  conversationMode: 'private' | 'group';
+  turnUsage: Omit<TurnResourceUsage, 'trustworthy'>;
+}): AsyncGenerator<
+  LoopEvent,
+  {
+    text: string;
+    lastFinishReason: FinishReason;
+    publicationError: unknown;
+    publicationInterrupted: boolean;
+    streamed: boolean;
+  }
+> {
+  const {
+    provider,
+    messages,
+    candidate,
+    candidateFinishReason,
+    output,
+    chatFn,
+    options,
+    signal,
+    conversationMode,
+    turnUsage,
+  } = input;
+  let lastFinishReason = candidateFinishReason;
+  let publicationError: unknown;
+  let publicationInterrupted = false;
+  let streamed = false;
+  let publishedText = '';
+  let publicationDone = false;
+  yield { type: 'stage_change', stage: 'streaming' };
+  try {
+    const publicationMessages = finalAnswerMessages(messages, candidate, output);
+    const publicationPlan = buildContextBudgetPlan({
+      provider,
+      history: publicationMessages,
+      tools: [],
+    });
+    if (publicationPlan.overBudget) throw new Error('最终表达上下文超过模型输入上限，未发送请求。');
+    if (signal?.aborted || options.hasQueuedInput?.()) {
+      publicationInterrupted = true;
+      throw new Error('最终发布已取消。');
+    }
+    turnUsage.totalCalls += 1;
+    for await (const event of chatFn({
+      provider,
+      messages: publicationMessages,
+      tools: [],
+      signal,
+      conversationMode: conversationMode,
+      promptCache: options.promptCache,
+    })) {
+      if (event.type === 'done' && !publicationDone) {
+        publicationDone = true;
+        if (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number') {
+          turnUsage.reportedCalls += 1;
+          turnUsage.inputTokens += event.promptTokens ?? 0;
+          turnUsage.outputTokens += event.outputTokens ?? 0;
+        }
+      }
+      if (signal?.aborted || options.hasQueuedInput?.()) {
+        publicationInterrupted = true;
+        break;
+      }
+      if (event.type === 'text_delta') {
+        // Final expression is live generation, not an exact-copy replay.
+        // Once visible, text is never replaced or joined with a different draft.
+        publishedText += event.delta;
+        streamed = true;
+        yield { type: 'text', delta: event.delta };
+      } else if (event.type === 'tool_call_delta') {
+        throw new Error('最终表达阶段返回了非预期工具调用，未执行该工具。');
+      } else if (event.type === 'done') {
+        publicationDone = true;
+        lastFinishReason = event.stopReason;
+        if (event.stopReason === 'aborted') publicationInterrupted = true;
+      }
+    }
+    if (!publicationDone && !publicationInterrupted) throw new Error('最终答案流未正常结束。');
+    if (!publicationInterrupted && lastFinishReason !== 'stop' && lastFinishReason !== 'length')
+      throw new Error('最终答案流缺少有效的结束状态。');
+    if (!publishedText.trim() && !publicationInterrupted) throw new Error('最终表达未返回正文。');
+  } catch (error) {
+    publicationInterrupted ||=
+      signal?.aborted === true || options.hasQueuedInput?.() === true || (error as Error)?.name === 'AbortError';
+    publicationError = error;
+  }
+  if (publicationError && !publicationInterrupted && !publishedText) {
+    yield {
+      type: 'warning',
+      message: '最终回答流未能开始，已一次性显示内部准备的答案；未进行新的事实核验。',
+    };
+    yield { type: 'text', delta: candidate };
+    streamed = true;
+    publishedText = candidate;
+    lastFinishReason = candidateFinishReason;
+    publicationError = undefined;
+  }
+
+  return {
+    text: publishedText,
+    lastFinishReason,
+    publicationError,
+    publicationInterrupted,
+    streamed,
+  };
+}