@xgspz/cli-ui 0.0.0-stage → 0.6.15

package/src/core/conversation.ts

@@ -0,0 +1,581 @@
+/**
+ * 一个对话的前端状态，以及把 center 实时流的事件应用上去的纯函数（无 React，可单测）。
+ *
+ * 数据来自两层：
+ *   · 中枢轮次（turn）：每条消息一轮，排队 → 执行中 → 成功 / 失败 / 取消（或被合并进别的轮次）。
+ *   · 节点转录（transcript + node 事件）：Agent 实际的对话过程，规则与 Operator 的 useTaskStream 一致。
+ * 界面以节点转录为主；转录还没有（没派发、节点连不上）时用轮次的 input / reply 兜底。
+ */
+import { isBatchSnapshot, type AskAnswers, type AskQuestion, type BatchStreamSnapshot, type BatchStreamTask, type CenterTurn, type ConversationClosedCallback, type ConversationTurnCallback, type JobStatus, type Message, type Msg, type NodeEvent, type StreamItem, type StreamSnapshot, type StreamTask, type ToolData, type TurnUsage } from "./types";
+import { indexFromEnd, mergeSnapshot, prependOlder, toolDataOf } from "../ui/transcriptModel";
+import { formatAnswersText } from "../ui/format";
+
+export const TERMINAL_TURN = new Set(["succeeded", "failed", "cancelled", "merged"]);
+export const ACTIVE_TURN = new Set(["queued", "dispatching", "running"]);
+export const TERMINAL_JOB = new Set(["succeeded", "failed", "cancelled"]);
+/** 一次性任务的子任务：结束了的、正在节点上跑的。 */
+export const TERMINAL_TASK = TERMINAL_JOB;
+const ACTIVE_TASK = new Set(["dispatching", "running", "verifying"]);
+
+// ── 对话键 ─────────────────────────────────────────────
+//
+// 一个对话任务（job）里可以有几个对话（几个子任务，各自一个 Agent 会话，共用节点和工作区）。
+// 组件里「一个对话」用对话键标识：
+//   · "job_x"            对话任务的第一个对话（只有一个对话时就是它，和以前一样）；
+//   · "job_x#task_y"     对话任务里的某个对话；
+//   · "job_x#new"        在这个对话任务里新开一个对话（还没发第一条消息）。
+
+/** 「在这个对话任务里新开一个对话」的子任务占位。 */
+export const NEW_TASK = "new";
+
+export function convKey(jobId: string, taskId?: string | null): string {
+  return taskId ? `${jobId}#${taskId}` : jobId;
+}
+
+export function parseConvKey(key: string): { jobId: string; taskId: string | null } {
+  const at = key.indexOf("#");
+  return at < 0 ? { jobId: key, taskId: null } : { jobId: key.slice(0, at), taskId: key.slice(at + 1) || null };
+}
+
+/** 对话键里的真实子任务（「新开」的占位不算）。 */
+export function taskOfKey(key: string): string | null {
+  const { taskId } = parseConvKey(key);
+  return taskId && taskId !== NEW_TASK ? taskId : null;
+}
+
+export const isNewInJob = (key: string | null | undefined) => !!key && parseConvKey(key).taskId === NEW_TASK;
+/** Operator 首轮固定的启动语句：正文其实在任务描述里（= 中枢第 1 轮的 input）。 */
+export const OPERATOR_INITIAL_PROMPT = "Start working on the task described in the task context.";
+
+export interface ConvJob {
+  status: JobStatus;
+  closed_reason: string | null;
+  node_id: string | null;
+  title?: string;
+}
+
+export interface ConvState {
+  /** 对话键（见 convKey）。 */
+  key: string;
+  jobId: string;
+  /** 对话键里指定的子任务；只有 job_id 时为 null（看第一个对话）。 */
+  taskId: string | null;
+  job: ConvJob | null;
+  /** 实时流看的这个对话（子任务）的状态；关闭了 closed=true。旧版 center 没有。 */
+  task: StreamTask | null;
+  /** 中枢轮次，按 seq 升序。 */
+  turns: CenterTurn[];
+  /** 节点转录（Operator 消息）。 */
+  msgs: Msg[];
+  hasTranscript: boolean;
+  /** 中枢说这段对话记录暂时读不到（transcript_unavailable）；读到转录后清掉。 */
+  transcriptError: string | null;
+  /** 节点转录里比 msgs 更早、还没取的条数（实时流只给最新一段；往上翻时 store.loadOlder 分页取）。 */
+  older: number;
+  nodeRunning: boolean;
+  /**
+   * 收尾计数：一轮在节点上结束（中枢把这一轮标成结束；没有轮次的一次性任务看节点 turn_end）、对话结束、
+   * 断线重连后补齐时 +1。首次连上不算。看板的「改动」据此重读 diff。
+   */
+  settled: number;
+  resolvedModel: string | null;
+  /** 上次刷新任务详情之后，实时流里累计的用量（usage 事件）。 */
+  liveUsage: { fresh: number; cacheRead: number };
+  /** offline：自动重连用完、已停下，等网络恢复 / 页面回到前台 / 获得焦点 / 发消息 / store.reconnect() 时再连。 */
+  stream: "idle" | "connecting" | "live" | "reconnecting" | "offline" | "ended" | "error";
+  streamError: string | null;
+  endReason: string | null;
+  /** 接续这个对话的新对话的键（对话任务结束后再发消息开出来的）。 */
+  continuedBy: string | null;
+  /** 本页提交过的提问回答（askId → 答案）。节点上那一轮已被中枢结束，不会回 ask_answered，只能本地记。 */
+  localAnswers: Record<string, AskAnswers>;
+  /**
+   * 一次性任务（含续派，不是对话任务）：只读查看其中一个子任务。没有轮次，task 是那个子任务，
+   * batchTask 是它的原样（状态、错误、原文），remoteTaskId 是它在节点上的对话（流里只认这个对话的转录）。
+   */
+  batch: boolean;
+  batchTask: BatchStreamTask | null;
+  remoteTaskId: string | null;
+}
+
+export const emptyConv = (key: string): ConvState => ({
+  key, ...parseConvKey(key), job: null, task: null, turns: [], msgs: [], hasTranscript: false, transcriptError: null, older: 0, nodeRunning: false, settled: 0, resolvedModel: null,
+  liveUsage: { fresh: 0, cacheRead: 0 }, stream: "idle", streamError: null, endReason: null, continuedBy: null, localAnswers: {},
+  batch: false, batchTask: null, remoteTaskId: null,
+});
+
+export function upsertTurns(turns: CenterTurn[], incoming: CenterTurn[]): CenterTurn[] {
+  if (!incoming.length) return turns;
+  const byId = new Map(turns.map((turn) => [turn.turn_id, turn]));
+  for (const turn of incoming) byId.set(turn.turn_id, { ...byId.get(turn.turn_id), ...turn });
+  return [...byId.values()].sort((a, b) => a.seq - b.seq);
+}
+
+/**
+ * 只补上还不认识的轮次（发消息 / 撤回的接口响应用）。接口响应是请求那一刻的快照，可能比实时流晚到：
+ * 实时流已经报了「执行中 / 已结束」，再拿响应里的「排队中」去盖，这一轮就会一直显示排队（之后也不会再有更新）。
+ * 已有的轮次只认实时流——状态可能合法地往回走（节点忙时中枢会把派发中的轮次放回队列），不能按状态大小判断新旧。
+ */
+export function addTurnsIfAbsent(turns: CenterTurn[], incoming: CenterTurn[]): CenterTurn[] {
+  const known = new Set(turns.map((turn) => turn.turn_id));
+  const fresh = incoming.filter((turn) => !known.has(turn.turn_id));
+  return fresh.length ? upsertTurns(turns, fresh) : turns;
+}
+
+export function applySnapshot(conv: ConvState, snapshot: StreamSnapshot | BatchStreamSnapshot): ConvState {
+  if (isBatchSnapshot(snapshot)) return applyBatchSnapshot(conv, snapshot);
+  const { job } = snapshot;
+  return {
+    ...conv,
+    job: { status: job.status, closed_reason: job.closed_reason, node_id: job.node_id, title: job.title },
+    task: snapshot.task ?? conv.task,
+    turns: upsertTurns([], Array.isArray(snapshot.turns) ? snapshot.turns : []),
+    resolvedModel: conv.resolvedModel ?? job.conversation?.last_turn?.resolved_model ?? null,
+  };
+}
+
+// ── 一次性任务（含续派）：只读查看其中一个子任务 ─────────
+//
+// 指定了子任务就看它；没指定看最近一个派发过的（续派开出新的子任务时跟过去）。
+// 流里可能同时有几个节点对话的事件（带 remote_task_id），只认看的这个子任务所在的那个。
+
+const batchStreamTask = (task: BatchStreamTask): StreamTask => ({
+  // 对话式子任务跑完一条不算结束：还能接着聊。
+  id: task.id, seq: task.seq, title: task.title, status: task.status, closed: !task.conversation && TERMINAL_TASK.has(task.status),
+  remote_task_id: task.remote_task_id, continue_from_task_id: task.continue_from_task_id,
+  awaiting_input: task.awaiting_input, awaiting_input_observed_at: task.awaiting_input_observed_at,
+});
+
+/** 没指定子任务时看哪个：最近一个派发过的，都没派发过就是最后一个。 */
+export const latestBatchTask = (tasks: BatchStreamTask[]) =>
+  [...tasks].sort((a, b) => a.seq - b.seq).reverse().find((task) => task.remote_task_id) ?? tasks.reduce<BatchStreamTask | null>((last, task) => (!last || task.seq > last.seq ? task : last), null);
+
+/** 对话式子任务（续派时 mode=conversation）：可以接着聊，发消息 = 续派一条接着它的对话。 */
+export const isChatTask = (conv: Pick<ConvState, "batch" | "batchTask"> | null | undefined) => !!conv?.batch && !!conv.batchTask?.conversation;
+
+/** 换成看另一个子任务（或同一个子任务换了节点对话，例如重试）：节点转录清掉，等新对话的转录。 */
+function focusBatchTask(conv: ConvState, task: BatchStreamTask | null): ConvState {
+  // 对话式的对话里最新那条可能还没派发：节点对话用它们共用的那个。
+  const remote = task?.conversation_remote_task_id ?? task?.remote_task_id ?? null;
+  const sameRemote = remote === conv.remoteTaskId;
+  // 状态变化事件不一定带原文（没指定子任务时）：沿用已有的。
+  const kept = conv.batchTask && task && conv.batchTask.id === task.id ? { prompt: conv.batchTask.prompt, opener_prompt: conv.batchTask.opener_prompt } : {};
+  const batchTask = task ? { ...kept, ...task } : null;
+  return {
+    ...conv, batch: true, batchTask, task: batchTask ? batchStreamTask(batchTask) : null, remoteTaskId: remote,
+    ...(sameRemote ? {} : { msgs: [], hasTranscript: false, transcriptError: null, older: 0, nodeRunning: false }),
+  };
+}
+
+function applyBatchSnapshot(conv: ConvState, snapshot: BatchStreamSnapshot): ConvState {
+  const { job } = snapshot;
+  const tasks = Array.isArray(snapshot.tasks) ? snapshot.tasks : [];
+  // 流给的那个优先：指定了子任务就是它（对话式的是它所在对话里最新的那条）；没指定是最近一个派发过的。旧版中枢不给时自己挑。
+  const shown = snapshot.task ?? (conv.taskId ? tasks.find((task) => task.id === conv.taskId) ?? null : latestBatchTask(tasks));
+  return focusBatchTask({ ...conv, job: { status: job.status, closed_reason: null, node_id: job.node_id, title: job.title }, turns: [] }, shown);
+}
+
+/** 一次性任务里的子任务状态变化。 */
+function applyBatchTask(conv: ConvState, task: BatchStreamTask): ConvState {
+  if (conv.batchTask?.id === task.id) return focusBatchTask(conv, task);
+  // 对话式的对话：接着聊的新消息成了最新那条（流只发这个对话的）。
+  if (conv.taskId && task.conversation) return focusBatchTask(conv, task);
+  // 没指定子任务：续派开出了更新的子任务（已经派发到节点），跟过去。
+  if (!conv.taskId && task.remote_task_id && (!conv.batchTask || task.seq > conv.batchTask.seq)) return focusBatchTask(conv, task);
+  return conv;
+}
+
+// 缺字段时兜底：generation 缺省 1（按它分会话，缺了会把顺序排乱）；时间缺就不显示。
+export const toMsg = (m: Message): Msg => ({ id: m.id, role: m.role, content: m.content, generation: typeof m.generation === "number" ? m.generation : 1, ...(typeof m.created_at === "number" ? { ts: m.created_at } : {}) });
+
+export function applyItems(conv: ConvState, items: StreamItem[]): ConvState {
+  let next = conv;
+  for (const item of items) {
+    // 一次性任务：只认看的这个子任务所在的节点对话。
+    if (next.batch && (item.type === "transcript" || item.type === "node" || item.type === "transcript_unavailable") && item.remote_task_id && item.remote_task_id !== next.remoteTaskId) continue;
+    if (item.type === "transcript") {
+      // 节点转录全量（连上 / 重连节点时各一次）：整体替换，没变的消息保留对象引用。
+      const messages = Array.isArray(item.messages) ? item.messages.map(toMsg) : [];
+      const merged = mergeSnapshot(next.msgs, messages, typeof item.older === "number" ? item.older : 0);
+      next = { ...next, msgs: merged.msgs, older: merged.older, hasTranscript: true, transcriptError: null, nodeRunning: item.running === true };
+    } else if (item.type === "transcript_unavailable") {
+      if (!next.hasTranscript) next = { ...next, transcriptError: typeof item.error === "string" && item.error ? item.error : "暂时读不到这段对话记录" };
+    } else if (item.type === "node") {
+      next = applyNodeEvent(next, item.event);
+    } else if (item.type === "turn") {
+      const turns = upsertTurns(next.turns, [item.turn]);
+      // 中枢只在节点上的回合真的停下后才把执行过的一轮收尾，所以一轮结束、又没有别的轮次在排队或执行时，
+      // 节点一定没在跑了——不只靠节点的 turn_end 事件（重连的空档里可能错过，界面就会一直显示「运行中」）。
+      const settled = TERMINAL_TURN.has(item.turn.status) && !turns.some((turn) => ACTIVE_TURN.has(turn.status));
+      next = { ...next, turns, resolvedModel: item.turn.resolved_model ?? next.resolvedModel, ...(settled ? { nodeRunning: false } : {}) };
+    } else if (item.type === "job") {
+      next = { ...next, job: { ...next.job, status: item.job.status, closed_reason: item.job.closed_reason ?? null, node_id: item.job.node_id } };
+    } else if (item.type === "task") {
+      next = next.batch ? applyBatchTask(next, item.task as BatchStreamTask) : { ...next, task: item.task as StreamTask };
+    }
+  }
+  return next;
+}
+
+function upsertMsg(msgs: Msg[], m: Msg): Msg[] {
+  const i = indexFromEnd(msgs, m.id);
+  if (i === -1) return [...msgs, m];
+  const next = msgs.slice();
+  next[i] = { ...msgs[i], ...m };
+  return next;
+}
+
+let synthetic = 0;
+const localId = (prefix: string) => `${prefix}-${Date.now()}-${++synthetic}`;
+
+/** 节点的一个回合事件。与 Operator 的 handleStreamEvent 同一套规则。 */
+export function applyNodeEvent(conv: ConvState, ev: NodeEvent): ConvState {
+  const e = ev as Record<string, any>;
+  const gen = typeof e.generation === "number" ? e.generation : 1;
+  const set = (msgs: Msg[]) => ({ ...conv, msgs });
+  switch (ev.type) {
+    case "user":
+      return { ...set(upsertMsg(conv.msgs, { id: e.msgId, role: "user", content: e.content, generation: gen, ts: e.ts })), nodeRunning: true };
+    case "assistant":
+      return set(upsertMsg(conv.msgs, { id: e.msgId ?? localId("a"), role: "assistant", content: e.content, generation: gen, ts: e.ts }));
+    case "tool": {
+      const data: ToolData = { title: e.title, detail: e.detail, peek: e.peek, diff: e.diff, subagent: e.subagent, subagentMessage: e.subagentMessage };
+      return set(upsertMsg(conv.msgs, { id: e.msgId ?? localId("t"), role: "tool", content: JSON.stringify(data), generation: gen, toolId: e.id, ts: e.ts }));
+    }
+    case "tool_result": {
+      // 先按消息 id 找（快照加载的消息也能对上），找不到再按 tool_use id。结果多在末尾，从后往前找。
+      const arr = conv.msgs;
+      let i = arr.length - 1;
+      while (i >= 0 && (arr[i].role !== "tool" || (arr[i].id !== e.msgId && arr[i].toolId !== e.id))) i--;
+      if (i < 0) {
+        if (!e.msgId || (!e.subagent && !e.subagentMessage)) return conv;
+        const data: ToolData = { title: e.subagent?.title ?? e.subagentMessage?.tool?.title ?? "子代理消息", subagent: e.subagent, subagentMessage: e.subagentMessage };
+        return set(upsertMsg(arr, { id: e.msgId, role: "tool", content: JSON.stringify(data), generation: gen, toolId: e.id, ts: e.ts }));
+      }
+      try {
+        const d = JSON.parse(arr[i].content) as ToolData;
+        d.result = e.content;
+        d.isError = e.isError;
+        if (e.subagent) d.subagent = e.subagent;
+        if (e.subagentMessage) d.subagentMessage = e.subagentMessage;
+        if (e.peek) d.peek = e.peek;
+        const next = arr.slice();
+        next[i] = { ...arr[i], content: JSON.stringify(d) };
+        return set(next);
+      } catch {
+        return conv;
+      }
+    }
+    case "ask": {
+      const data: ToolData = { title: "有问题需要你回答", ask: { id: e.id, questions: e.questions } };
+      return set(upsertMsg(conv.msgs, { id: e.msgId ?? `ask-${e.id}`, role: "tool", content: JSON.stringify(data), generation: gen, toolId: e.id }));
+    }
+    case "ask_answered":
+      return set(conv.msgs.map((m) => {
+        if (m.role !== "tool") return m;
+        try {
+          const d = JSON.parse(m.content) as ToolData;
+          if (m.toolId !== e.id && d.ask?.id !== e.id) return m;
+          d.ask = { id: d.ask?.id ?? e.id, questions: d.ask?.questions ?? [], answers: e.answers };
+          return { ...m, content: JSON.stringify(d) };
+        } catch {
+          return m;
+        }
+      }));
+    case "input": {
+      const data: ToolData = { title: "需要你提供信息", input: e.input };
+      return set(upsertMsg(conv.msgs, { id: e.msgId ?? `in-${e.input?.id}`, role: "tool", content: JSON.stringify(data), generation: gen }));
+    }
+    case "notice":
+      return set(upsertMsg(conv.msgs, { id: e.msgId ?? localId("n"), role: "system", content: e.content, generation: gen }));
+    case "error":
+      return set(upsertMsg(conv.msgs, { id: e.msgId ?? localId("e"), role: "system", content: e.content, generation: gen }));
+    case "model":
+      return { ...conv, resolvedModel: e.model };
+    case "usage": {
+      const u = e.usage as TurnUsage;
+      const fresh = (u.input_tokens ?? 0) + (u.output_tokens ?? 0) + (u.cache_creation_tokens ?? 0);
+      return { ...conv, liveUsage: { fresh: conv.liveUsage.fresh + fresh, cacheRead: conv.liveUsage.cacheRead + (u.cache_read_tokens ?? 0) } };
+    }
+    case "turn_end":
+      return { ...conv, nodeRunning: false };
+    default:
+      // queued / dequeued 是 Operator 自己的排队；对话任务的排队在中枢（轮次），这里不用。
+      return conv;
+  }
+}
+
+/** 往上翻取到的一页更早的节点消息（旧的在前）。older：再往前还剩几条。 */
+export function applyOlderPage(conv: ConvState, page: Message[], older: number): ConvState {
+  return { ...conv, msgs: prependOlder(conv.msgs, page.map(toMsg)), older: Math.max(0, older) };
+}
+
+/** 这个对话结束了：整个对话任务结束，或者只是这一个对话被关闭。 */
+export const convEnded = (conv: Pick<ConvState, "job" | "task">) => !!conv.task?.closed || (!!conv.job && TERMINAL_JOB.has(conv.job.status));
+
+/** 正在执行的那一轮（派发中或执行中）。 */
+export const runningTurn = (conv: ConvState) => conv.turns.find((turn) => turn.status === "running" || turn.status === "dispatching") ?? null;
+
+export const isRunning = (conv: ConvState) => conv.nodeRunning || !!runningTurn(conv) || (conv.batch && ACTIVE_TASK.has(conv.batchTask?.status ?? ""));
+
+/**
+ * 界面上的转录：
+ *   1. 节点转录（首轮的固定启动语句换成真正的第一条消息）；没有转录时用轮次兜底；
+ *   2. 没送到节点就失败 / 取消的轮次，补一行说明（否则用户只看到消息石沉大海）；
+ *   3. 还在中枢排队的消息，作为「排队中」气泡（可撤回），由界面钉在最下面。
+ */
+export function viewMessages(conv: ConvState): Msg[] {
+  if (conv.batch) return batchViewMessages(conv);
+  let out: Msg[] = [];
+  // 有节点消息就以节点为准：通常先收到全量转录，但新对话可能先来增量事件（user / assistant / tool），也算。
+  if (conv.msgs.length) {
+    // 节点转录只有当前这个 Operator 会话：它的开场是固定的启动语句，正文其实是开出这个会话的那一轮——
+    // 这个对话的第一轮，或者节点会话重建过（context_reset）时最近重建的那一轮。
+    // 轮次号在整个对话任务里统一编号：对话任务里后开的对话，第一轮不是 1，取这个对话最早的那一轮。
+    const opener = [...conv.turns].reverse().find((turn) => turn.context_reset && turn.started_at) ?? conv.turns[0];
+    // 认开场语句：Operator 一个会话的第一条用户消息总是固定的启动语句（忽略请求正文），所以按位置认——
+    // 转录里的第一条用户消息、内容又不是开出会话那一轮的原文，就是它；措辞以后变了也认得出。
+    // 之后的消息里再出现这句固定语句（例如会话被重启），按原文匹配。
+    const openerText = opener ? opener.sent_input ?? opener.input : null;
+    // 更早的消息还没取（older > 0）时，手里的第一条用户消息不是会话的开场：不按位置认。
+    let replaced = conv.older > 0;
+    for (const m of conv.msgs) {
+      const firstUser = !replaced && m.role === "user";
+      if (firstUser) replaced = true;
+      if (openerText && m.role === "user" && m.content.trim() !== openerText.trim()
+        && ((firstUser && m.id === conv.msgs.find((x) => x.role === "user")?.id) || m.content.trim() === OPERATOR_INITIAL_PROMPT)) {
+        out.push({ ...m, content: openerText });
+      } else out.push(m);
+    }
+  } else {
+    for (const turn of conv.turns) {
+      if (turn.status === "queued" || turn.status === "merged") continue;
+      if (turn.status !== "running" && !turn.started_at) continue;
+      const ts = new Date(turn.started_at ?? turn.created_at).getTime();
+      out.push({ id: `turn-in-${turn.turn_id}`, role: "user", content: turn.sent_input ?? turn.input, generation: 1, ts });
+      if (turn.reply) out.push({ id: `turn-out-${turn.turn_id}`, role: "assistant", content: turn.reply, generation: 1, ts: new Date(turn.ended_at ?? turn.created_at).getTime() });
+    }
+  }
+  out = settleAsks(out, conv.localAnswers);
+  const generation = out.length ? out[out.length - 1].generation : 1;
+  // 中枢判定的结果，节点转录里看不到，补一行说明，按时间插到对应位置：
+  //   · 没送到节点就失败 / 被撤回的消息（否则用户只看到消息石沉大海）；
+  //   · 执行了但被中枢判为失败的（超时中止、读不到执行记录、节点会话丢失、没有输出）。
+  // 用户自己按停止取消的不补：Operator 里停止也不写提示。
+  const notices: Msg[] = [];
+  for (const turn of conv.turns) {
+    const ts = new Date(turn.ended_at ?? turn.created_at).getTime();
+    const reason = turn.last_error ? `：${describeTurnError(turn.last_error)}` : "";
+    if ((turn.status === "failed" || turn.status === "cancelled") && !turn.started_at) {
+      // 用户自己撤回的不用再写原因（「已撤回：已取消」是同一件事）；中枢取消的（例如对话结束时还在排队）写明原因。
+      const byCaller = turn.status === "cancelled" && /cancelled by caller/i.test(turn.last_error ?? "");
+      notices.push({ id: `turn-fail-${turn.turn_id}`, role: "system", content: `⚠ 第 ${turn.seq} 条消息${turn.status === "cancelled" ? "已撤回" : "没有执行"}${byCaller ? "" : reason}`, generation, ts });
+    } else if (turn.status === "failed") {
+      notices.push({ id: `turn-fail-${turn.turn_id}`, role: "system", content: `⚠ 这一轮没有完成${reason}`, generation, ts });
+    }
+  }
+  out = insertByTime(out, notices);
+  const queuedHeads = new Set(conv.turns.filter((turn) => turn.status === "queued").map((turn) => turn.turn_id));
+  for (const turn of conv.turns) {
+    const waiting = turn.status === "queued" || (turn.status === "merged" && turn.merged_into_turn_id && queuedHeads.has(turn.merged_into_turn_id));
+    if (waiting) {
+      // 排在最前面、而且中枢记了等待原因的（节点连不上、没有可用节点、节点上还有回合没结束），把原因显示出来。
+      const note = turn.status === "queued" && turn.last_error ? describeTurnError(turn.last_error) : undefined;
+      out.push({ id: `turn-q-${turn.turn_id}`, role: "queued", content: turn.input, generation, ts: new Date(turn.created_at).getTime(), turnId: turn.turn_id, ...(note ? { note } : {}) });
+    }
+  }
+  return out;
+}
+
+// 中枢派发一次性任务时加在正文前的标记行，和完成后的自动核对（见 center scheduler.ts）。
+const CENTER_MARKER_LINES = /^(?:\[CENTER-(?:ATTEMPT|TERMINAL-REVISION):[^\]\n]*\][ \t]*(?:\r?\n|$))+/;
+const CONFIRM_MARK = "[CENTER-CONFIRM]";
+const BATCH_TASK_ERROR: Record<string, string> = { failed: "子任务失败", cancelled: "子任务已取消" };
+const CHAT_TASK_ERROR: Record<string, string> = { failed: "这一轮没有完成", cancelled: "这条消息已取消" };
+
+/**
+ * 一次性任务（含续派）的转录，只读：
+ *   1. 第一条用户消息是 Operator 固定的启动语句，换成开出这个节点对话的子任务原文（流里给了才换）；
+ *   2. 去掉中枢加在正文前的标记行（[CENTER-ATTEMPT:…]、[CENTER-TERMINAL-REVISION:…]）；
+ *   3. 中枢的完成核对（[CENTER-CONFIRM] 追问 + Agent 回的 TASK_COMPLETE / TASK_INCOMPLETE）合成一行说明；
+ *   4. 还没派发、拿不到执行记录、失败 / 取消时补一行说明。
+ */
+function batchViewMessages(conv: ConvState): Msg[] {
+  const out: Msg[] = [];
+  const task = conv.batchTask;
+  const opener = task?.opener_prompt ?? null;
+  // 更早的消息还没取时，手里的第一条用户消息不是开场语句。
+  const firstUserId = conv.older > 0 ? undefined : conv.msgs.find((m) => m.role === "user")?.id;
+  for (let i = 0; i < conv.msgs.length; i++) {
+    const m = conv.msgs[i];
+    if (m.role === "user" && m.content.includes(CONFIRM_MARK)) {
+      const reply = conv.msgs[i + 1]?.role === "assistant" ? conv.msgs[++i] : null;
+      const content = !reply ? "中枢正在核对任务是否完成…" : /^\s*TASK_COMPLETE\b/.test(reply.content) ? "✓ 中枢核对：任务已完成" : "⚠ 中枢核对：任务没有完成";
+      out.push({ id: `confirm-${m.id}`, role: "system", content, generation: m.generation, ...(m.ts !== undefined ? { ts: m.ts } : {}) });
+      continue;
+    }
+    if (m.role !== "user") { out.push(m); continue; }
+    const content = m.id === firstUserId && opener ? opener : m.content.replace(CENTER_MARKER_LINES, "");
+    out.push(content === m.content ? m : { ...m, content });
+  }
+  const generation = out.length ? out[out.length - 1].generation : 1;
+  const note = (id: string, content: string) => out.push({ id: `batch-${id}`, role: "system", content, generation });
+  for (const q of task?.queued ?? []) out.push({ id: `batch-q-${q.id}`, role: "queued", content: q.prompt, generation, ...(q.created_at ? { ts: new Date(q.created_at).getTime() } : {}) });
+  if (task?.conversation) {
+    // 对话式：像对话一样显示——还没派发的消息是「排队中」气泡，没有「子任务」字样。
+    if (CHAT_TASK_ERROR[task.status]) note(`err-${task.id}-${task.attempt}`, `⚠ ${CHAT_TASK_ERROR[task.status]}${task.last_error ? `：${describeTurnError(task.last_error)}` : ""}`);
+    return out;
+  }
+  if (!task) {
+    if (conv.job) note("none", "这个任务里还没有子任务");
+  } else if (!conv.msgs.length && !task.remote_task_id && !TERMINAL_TASK.has(task.status)) {
+    note("waiting", "子任务还没派发到执行节点，派发后这里会实时显示执行过程");
+  } else if (!conv.msgs.length && conv.stream === "ended") {
+    note("empty", "没有拿到这个子任务的执行记录（执行节点上的会话可能已经清理）");
+  }
+  if (task && BATCH_TASK_ERROR[task.status]) note(`err-${task.id}-${task.attempt}`, `⚠ ${BATCH_TASK_ERROR[task.status]}${task.last_error ? `：${describeTurnError(task.last_error)}` : ""}`);
+  return out;
+}
+
+/** 把说明行按时间插进转录：放在时间不晚于它的最后一条消息之后（没有时间的消息沿用前一条的时间）。 */
+function insertByTime(msgs: Msg[], notices: Msg[]): Msg[] {
+  if (!notices.length) return msgs;
+  const out = msgs.slice();
+  for (const notice of [...notices].sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0))) {
+    let at = out.length;
+    let lastTs = -Infinity;
+    for (let i = 0; i < out.length; i++) {
+      lastTs = out[i].ts ?? lastTs;
+      if (lastTs > (notice.ts ?? Infinity)) { at = i; break; }
+    }
+    out.splice(at, 0, notice);
+  }
+  return out;
+}
+
+/** 中枢的等待 / 失败原因（英文内部描述）翻成中文。 */
+export function describeTurnError(raw: string): string {
+  const text = raw.trim();
+  const rules: Array<[RegExp, string]> = [
+    [/no healthy node available/i, "当前产品线没有可用的执行节点，等待超时"],
+    [/produced no output/i, "智能体没有产生任何输出，会话可能没能启动"],
+    [/transcript could not be read/i, "这一轮结束了，但一直读不到它的执行记录"],
+    [/remote task confirmed missing|remote task.*missing/i, "执行节点上的会话已丢失，下一条消息会开一个新会话"],
+    [/still running .* after abort/i, "已请求中止，但节点上的回合长时间没有停下"],
+    [/node unreachable/i, "执行节点暂时连不上，恢复后会继续"],
+    [/turn cancelled|cancel requested|cancelled by caller/i, "已取消"],
+    // 超时的原文也带 "aborted"，要先于下面那条匹配。
+    [/timed? ?out|timeout/i, "执行超时，已中止"],
+    [/aborted|abort requested/i, "已中止"],
+    [/already running on the node/i, "节点上还有一轮没结束，等它结束后发送"],
+    [/center restarted/i, "中枢重启过，这条消息会重新发送"],
+    [/conversation (closed|expired)/i, "对话已结束"],
+  ];
+  for (const [re, label] of rules) if (re.test(text)) return label;
+  return text;
+}
+
+// ── 提问卡片（AskUserQuestion） ────────────────────────
+//
+// Operator 里 Agent 提问时回合停在提问上，界面把回答 POST 给节点的 /answer。对话任务里中枢一看到
+// 提问（awaiting_input）就结束这一轮（asked=true），节点上的提问随之作废，回答走「下一条消息」——
+// 这正是 Operator 自己在「没有在等的回合」（resolved=false）时的做法：formatAnswersText 组成回复发出，
+// 卡片立刻显示「你的回答」。节点不会再回 ask_answered，所以卡片的已答状态由这里推出来：
+//   · 本页刚提交的：localAnswers；
+//   · 刷新 / 别处打开的：提问之后的第一条用户消息如果是回答格式，就按它解析回答案。
+
+/** formatAnswersText 的反解：不是这几个问题的回答返回 null。 */
+export function parseAnswersText(text: string, questions: AskQuestion[]): AskAnswers | null {
+  const body = text.trim();
+  if (!body.startsWith("回答你的问题：")) return null;
+  const lines = body.split("\n").slice(1).map((line) => line.trim()).filter(Boolean);
+  if (lines.length !== questions.length) return null;
+  const answers: AskAnswers = [];
+  for (let i = 0; i < questions.length; i++) {
+    const prefix = `- ${questions[i].header || questions[i].question}：`;
+    if (!lines[i].startsWith(prefix)) return null;
+    const picked = lines[i].slice(prefix.length);
+    answers.push(picked === "（未选择）" ? [] : picked.split("、"));
+  }
+  // 再拼一遍要完全一致，免得把普通消息误认成回答。
+  return formatAnswersText(questions, answers).trim() === body ? answers : null;
+}
+
+const settledCache = new WeakMap<Msg, { key: string; msg: Msg }>();
+
+function settleAsks(msgs: Msg[], local: Record<string, AskAnswers>): Msg[] {
+  let changed = false;
+  const out = msgs.map((m, i) => {
+    if (m.role !== "tool") return m;
+    const data = toolDataOf(m);
+    if (!data.ask || data.ask.answers) return m;
+    let answers: AskAnswers | undefined = local[data.ask.id] ?? local[m.toolId ?? ""];
+    if (!answers) {
+      const next = msgs.slice(i + 1).find((x) => x.role === "user");
+      answers = (next && parseAnswersText(next.content, data.ask.questions)) || undefined;
+    }
+    if (!answers) return m;
+    // 同一条消息、同一份答案复用同一个对象：消息行是 memo 的，不要每次都重渲染。
+    const key = JSON.stringify(answers);
+    const hit = settledCache.get(m);
+    if (hit?.key === key) { changed = true; return hit.msg; }
+    const msg = { ...m, content: JSON.stringify({ ...data, ask: { ...data.ask, answers } }) };
+    settledCache.set(m, { key, msg });
+    changed = true;
+    return msg;
+  });
+  return changed ? out : msgs;
+}
+
+// ── 回调体 ───────────────────────────────────────────
+
+/** 一轮结束 → 与中枢 conversation_turn 回调同样字段的载荷。 */
+export function turnCallback(conv: ConvState, turn: CenterTurn, continuedFrom: string | null): ConversationTurnCallback {
+  const group = [turn, ...conv.turns.filter((t) => t.status === "merged" && t.merged_into_turn_id === turn.turn_id)].sort((a, b) => a.seq - b.seq);
+  return {
+    type: "conversation_turn",
+    callback_seq: turn.seq,
+    job_id: turn.job_id,
+    task_id: turn.task_id,
+    turn_id: turn.turn_id,
+    seq: turn.seq,
+    business_id: turn.business_id,
+    status: turn.status,
+    occurred_at: turn.ended_at ?? new Date().toISOString(),
+    input: turn.sent_input ?? turn.input,
+    messages: group.map((t) => ({ turn_id: t.turn_id, seq: t.seq, business_id: t.business_id, input: t.input })),
+    reply: turn.reply,
+    asked: turn.asked,
+    message: turn.last_error,
+    continued_from_job_id: continuedFrom,
+    context_reset: turn.context_reset,
+    merged: !!turn.merged,
+    merge_error: turn.merge_error ?? null,
+    ...(turn.saved !== undefined ? { saved: turn.saved, saved_at: turn.saved_at ?? null, save_error: turn.save_error ?? null } : {}),
+    agent: turn.agent,
+    resolved_model: turn.resolved_model,
+    total_tokens: turn.total_tokens, input_tokens: turn.input_tokens, output_tokens: turn.output_tokens,
+    cache_read_tokens: turn.cache_read_tokens, cache_creation_tokens: turn.cache_creation_tokens,
+    started_at: turn.started_at,
+    ended_at: turn.ended_at,
+  };
+}
+
+/** 对话结束 → 与中枢 conversation_closed 回调同样字段的载荷。 */
+export function closedCallback(conv: ConvState): ConversationClosedCallback {
+  // 与 center 一致：turns = 最大的 seq（被合并的消息也算），callback_seq = turns + 1。
+  const turns = conv.turns.reduce((max, t) => Math.max(max, t.seq), 0);
+  return {
+    type: "conversation_closed",
+    mode: "conversation",
+    callback_seq: turns + 1,
+    job_id: conv.jobId,
+    // 只关掉了这一个对话（对话任务还开着）：带上是哪个，原因写 conversation_closed。
+    ...(conv.task?.closed && !TERMINAL_JOB.has(conv.job?.status ?? "") ? { task_id: conv.task.id } : {}),
+    status: conv.task?.closed && !TERMINAL_JOB.has(conv.job?.status ?? "") ? "succeeded" : conv.job?.status ?? "succeeded",
+    closed_reason: conv.task?.closed && !TERMINAL_JOB.has(conv.job?.status ?? "") ? "conversation_closed" : conv.job?.closed_reason ?? null,
+    turns,
+    continued_by_job_id: conv.continuedBy,
+    occurred_at: new Date().toISOString(),
+  };
+}