@spzxg/cli-ui 0.0.0-stage → 0.1.0

package/src/core/config.ts

@@ -0,0 +1,220 @@
+/**
+ * 组件的界面配置：哪些模块显示、文案怎么写。全部可选，不给就是缺省（全部显示、默认文案）。
+ *
+ *   <CliChat config={{ header: { export: false, close: false }, composer: { placeholder: "问点什么…", fileUpload: false } }} />
+ *   <CliMsgList config={{ header: { refresh: false }, card: { turns: false } }} />
+ *
+ * 开关类的模块写 false 就整块隐藏，写对象就逐项开关；文案里可以用 {title}（对话标题）、{agent}（智能体名）。
+ */
+
+// ── cli-chat ─────────────────────────────────────────
+
+export interface CliChatConfig {
+  /** 顶部栏。false = 整栏隐藏；对象 = 逐项开关。 */
+  header?: boolean | {
+    /** 面包屑：色块 + 名称 / 对话。 */
+    crumb?: boolean;
+    /** 「导出执行过程」按钮。 */
+    export?: boolean;
+    /** 对话标题。 */
+    title?: boolean;
+    /** 智能体标签（Codex / Claude Code）。 */
+    agent?: boolean;
+    /** token 用量。 */
+    usage?: boolean;
+    /** 模型（默认 + 实际模型）。 */
+    model?: boolean;
+    /** 对话状态（运行中 / 需要你处理 / 已结束）。 */
+    status?: boolean;
+    /** 「结束对话」按钮。 */
+    close?: boolean;
+  };
+  /** 底部输入框。false = 不显示输入框（只读）；对象 = 逐项配置。 */
+  composer?: boolean | {
+    /** 回复时的占位文案，可用 {title} {agent}。 */
+    placeholder?: string;
+    /** 新对话（还没有 jobId）时的占位文案。 */
+    placeholderNew?: string;
+    /** 智能体正在执行、发的消息会排队时的占位文案。 */
+    placeholderRunning?: string;
+    /** 不能发送时（对话已结束、只读）的占位文案。 */
+    placeholderDisabled?: string;
+    /** 底部「⏎ 发送 / ⇧⏎ 换行」提示。 */
+    hints?: boolean;
+    /** 底部字数统计。 */
+    charCount?: boolean;
+    /** 文件上传（按钮、拖拽、粘贴文件）。只收 TXT / Markdown / Word。 */
+    fileUpload?: boolean;
+    /** 「文件」按钮的文字。 */
+    fileButtonText?: string;
+    /** 运行中的停止按钮。 */
+    stop?: boolean;
+    /** 运行中允许发消息排队；false = 运行中不能发。 */
+    queue?: boolean;
+  };
+  /** 对话区。 */
+  transcript?: {
+    /** 右下角的上一条 / 下一条 / 跳到最新按钮。 */
+    nav?: boolean;
+    /** 「第 1 次会话 · 当前」分隔线。 */
+    sessionLabel?: boolean;
+    /** 消息时间。 */
+    timestamps?: boolean;
+    /** 首条消息上的「初始提示」「已随项目上下文发送」标记。 */
+    initialBadge?: boolean;
+    /** 工具调用卡片（命令、读写文件……）；false 只留文字往来（提问卡片照常显示）。 */
+    tools?: boolean;
+    /** 「智能体 · 运行中 0:12」那一行。 */
+    runningIndicator?: boolean;
+  };
+  /** 消息头上的称呼。 */
+  labels?: { user?: string; agent?: string };
+  /** 新对话的空白页。false = 不显示。 */
+  empty?: boolean | { title?: string; description?: string };
+}
+
+export interface ResolvedChatConfig {
+  header: { show: boolean; crumb: boolean; export: boolean; title: boolean; agent: boolean; usage: boolean; model: boolean; status: boolean; close: boolean };
+  composer: {
+    show: boolean; placeholder: string; placeholderNew: string; placeholderRunning: string; placeholderDisabled: string | null;
+    hints: boolean; charCount: boolean; fileUpload: boolean; fileButtonText: string; stop: boolean; queue: boolean;
+  };
+  transcript: { nav: boolean; sessionLabel: boolean; timestamps: boolean; initialBadge: boolean; tools: boolean; runningIndicator: boolean };
+  labels: { user: string; agent: string };
+  empty: { show: boolean; title: string; description: string };
+}
+
+export const DEFAULT_CHAT_CONFIG: ResolvedChatConfig = {
+  header: { show: true, crumb: true, export: true, title: true, agent: true, usage: true, model: true, status: true, close: true },
+  composer: {
+    show: true,
+    placeholder: "在“{title}”中回复 {agent}…（可拖入 TXT / Markdown / Word 文件）",
+    placeholderNew: "输入第一条消息，开始新对话…（可拖入 TXT / Markdown / Word 文件）",
+    placeholderRunning: "排队一条后续消息…（本轮结束后发送）",
+    placeholderDisabled: null,
+    hints: true, charCount: true, fileUpload: true, fileButtonText: "文件", stop: true, queue: true,
+  },
+  transcript: { nav: true, sessionLabel: true, timestamps: true, initialBadge: true, tools: true, runningIndicator: true },
+  labels: { user: "你", agent: "智能体" },
+  empty: { show: true, title: "开始一个新对话", description: "在下面输入第一条消息。可以附上 TXT、Markdown 或 Word 文件，内容会转成文字一起发送。" },
+};
+
+export function resolveChatConfig(config: CliChatConfig = {}): ResolvedChatConfig {
+  const d = DEFAULT_CHAT_CONFIG;
+  const header = toggle(config.header, d.header);
+  const composer = toggle(config.composer, d.composer);
+  const empty = toggle(config.empty, d.empty);
+  // 没有文件上传时，缺省文案里的「可拖入文件」提示也去掉。
+  if (!composer.fileUpload) {
+    const strip = (text: string) => text.replace(/（可拖入 TXT \/ Markdown \/ Word 文件）$/, "");
+    if (!isObj(config.composer) || config.composer.placeholder === undefined) composer.placeholder = strip(composer.placeholder);
+    if (!isObj(config.composer) || config.composer.placeholderNew === undefined) composer.placeholderNew = strip(composer.placeholderNew);
+  }
+  return {
+    header,
+    composer,
+    transcript: { ...d.transcript, ...defined(config.transcript) },
+    labels: { ...d.labels, ...defined(config.labels) },
+    empty,
+  };
+}
+
+// ── cli-msglist ──────────────────────────────────────
+
+export interface CliMsgListConfig {
+  /** 顶部栏。false = 整栏隐藏；对象 = 逐项开关。 */
+  header?: boolean | {
+    /** 色块 + 名称。 */
+    title?: boolean;
+    /** 「+ 对话」按钮。 */
+    newButton?: boolean;
+    /** 「+ 对话」按钮的文字。 */
+    newButtonText?: string;
+    /** 刷新按钮。 */
+    refresh?: boolean;
+    /** 上下文说明框（需同时给 context 或 onEditContext）。 */
+    context?: boolean;
+  };
+  /** 搜索框：true 总是显示，false 不显示，"auto"（缺省）对话数 ≥ 6 时显示。 */
+  search?: boolean | "auto";
+  searchPlaceholder?: string;
+  /** 卡片上显示哪些内容。 */
+  card?: {
+    /** 状态点和状态文字。 */
+    status?: boolean;
+    /** 智能体标签。 */
+    agent?: boolean;
+    /** 第一条消息摘要。 */
+    description?: boolean;
+    /** 底部活动（运行中 · 3 分钟前……）。 */
+    activity?: boolean;
+    /** 「N 轮对话」。 */
+    turns?: boolean;
+  };
+  /** 分组标题；写 false 隐藏这一组。 */
+  groups?: { needs?: string | false; active?: string | false; done?: string | false; cancelled?: string | false };
+  /** 没有对话时的提示。 */
+  emptyTitle?: string;
+  emptyDescription?: string;
+}
+
+export interface ResolvedMsgListConfig {
+  header: { show: boolean; title: boolean; newButton: boolean; newButtonText: string; refresh: boolean; context: boolean };
+  search: boolean | "auto";
+  searchPlaceholder: string;
+  card: { status: boolean; agent: boolean; description: boolean; activity: boolean; turns: boolean };
+  groups: { needs: string | false; active: string | false; done: string | false; cancelled: string | false };
+  emptyTitle: string;
+  emptyDescription: string;
+}
+
+export const DEFAULT_MSGLIST_CONFIG: ResolvedMsgListConfig = {
+  header: { show: true, title: true, newButton: true, newButtonText: "对话", refresh: true, context: true },
+  search: "auto",
+  searchPlaceholder: "搜索对话…",
+  card: { status: true, agent: true, description: true, activity: true, turns: true },
+  groups: { needs: "需要你处理", active: "进行中", done: "已结束", cancelled: "已取消" },
+  emptyTitle: "还没有对话",
+  emptyDescription: "点「对话」开始一个新的对话。",
+};
+
+export function resolveMsgListConfig(config: CliMsgListConfig = {}): ResolvedMsgListConfig {
+  const d = DEFAULT_MSGLIST_CONFIG;
+  return {
+    header: toggle(config.header, d.header),
+    search: config.search ?? d.search,
+    searchPlaceholder: config.searchPlaceholder ?? d.searchPlaceholder,
+    card: { ...d.card, ...defined(config.card) },
+    groups: { ...d.groups, ...defined(config.groups) },
+    emptyTitle: config.emptyTitle ?? d.emptyTitle,
+    emptyDescription: config.emptyDescription ?? d.emptyDescription,
+  };
+}
+
+// ── 小工具 ───────────────────────────────────────────
+
+/** 文案模板：{title}、{agent}。 */
+export function fillTemplate(template: string, vars: Record<string, string>) {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) => (key in vars ? vars[key] : match));
+}
+
+const isObj = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object";
+
+/** 去掉值为 undefined 的键，免得盖掉缺省值。 */
+function defined<T extends object>(value: T | undefined): Partial<T> {
+  if (!value) return {};
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as Partial<T>;
+}
+
+/**
+ * 开关型模块：false → 全关（show=false 且布尔项全 false，文案保留）；true / 不给 → 缺省；对象 → 合并缺省。
+ */
+function toggle<T extends { show: boolean }>(value: boolean | object | undefined, defaults: T): T {
+  if (value === false) {
+    const off = { ...defaults, show: false } as Record<string, unknown>;
+    for (const key of Object.keys(off)) if (typeof off[key] === "boolean") off[key] = false;
+    return off as T;
+  }
+  if (!isObj(value)) return { ...defaults };
+  return { ...defaults, ...defined(value as Partial<T>), show: true };
+}

package/src/core/conversation.ts

@@ -0,0 +1,371 @@
+/**
+ * 一个对话的前端状态，以及把 center 实时流的事件应用上去的纯函数（无 React，可单测）。
+ *
+ * 数据来自两层：
+ *   · 中枢轮次（turn）：每条消息一轮，排队 → 执行中 → 成功 / 失败 / 取消（或被合并进别的轮次）。
+ *   · 节点转录（transcript + node 事件）：Agent 实际的对话过程，规则与 Operator 的 useTaskStream 一致。
+ * 界面以节点转录为主；转录还没有（没派发、节点连不上）时用轮次的 input / reply 兜底。
+ */
+import type { AskAnswers, AskQuestion, CenterTurn, ConversationClosedCallback, ConversationTurnCallback, JobStatus, Message, Msg, NodeEvent, StreamItem, StreamSnapshot, ToolData, TurnUsage } from "./types.js";
+import { indexFromEnd, mergeSnapshot, toolDataOf } from "../ui/transcriptModel.js";
+import { formatAnswersText } from "../ui/format.js";
+
+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"]);
+/** 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 {
+  jobId: string;
+  job: ConvJob | null;
+  /** 中枢轮次，按 seq 升序。 */
+  turns: CenterTurn[];
+  /** 节点转录（Operator 消息）。 */
+  msgs: Msg[];
+  hasTranscript: boolean;
+  nodeRunning: boolean;
+  resolvedModel: string | null;
+  /** 上次刷新任务详情之后，实时流里累计的用量（usage 事件）。 */
+  liveUsage: { fresh: number; cacheRead: number };
+  stream: "idle" | "connecting" | "live" | "reconnecting" | "ended" | "error";
+  streamError: string | null;
+  endReason: string | null;
+  continuedBy: string | null;
+  /** 本页提交过的提问回答（askId → 答案）。节点上那一轮已被中枢结束，不会回 ask_answered，只能本地记。 */
+  localAnswers: Record<string, AskAnswers>;
+}
+
+export const emptyConv = (jobId: string): ConvState => ({
+  jobId, job: null, turns: [], msgs: [], hasTranscript: false, nodeRunning: false, resolvedModel: null,
+  liveUsage: { fresh: 0, cacheRead: 0 }, stream: "idle", streamError: null, endReason: null, continuedBy: null, localAnswers: {},
+});
+
+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 applySnapshot(conv: ConvState, snapshot: StreamSnapshot): ConvState {
+  const { job } = snapshot;
+  return {
+    ...conv,
+    job: { status: job.status, closed_reason: job.closed_reason, node_id: job.node_id, title: job.title },
+    turns: upsertTurns([], snapshot.turns),
+    resolvedModel: conv.resolvedModel ?? job.conversation?.last_turn?.resolved_model ?? null,
+  };
+}
+
+const toMsg = (m: Message): Msg => ({ id: m.id, role: m.role, content: m.content, generation: m.generation, ts: m.created_at });
+
+export function applyItems(conv: ConvState, items: StreamItem[]): ConvState {
+  let next = conv;
+  for (const item of items) {
+    if (item.type === "transcript") {
+      // 节点转录全量（连上 / 重连节点时各一次）：整体替换，没变的消息保留对象引用。
+      const messages = Array.isArray(item.messages) ? item.messages.map(toMsg) : [];
+      next = { ...next, msgs: mergeSnapshot(next.msgs, messages), hasTranscript: true, nodeRunning: item.running === true };
+    } else if (item.type === "node") {
+      next = applyNodeEvent(next, item.event);
+    } else if (item.type === "turn") {
+      next = { ...next, turns: upsertTurns(next.turns, [item.turn]), resolvedModel: item.turn.resolved_model ?? next.resolvedModel };
+    } else if (item.type === "job") {
+      next = { ...next, job: { ...next.job, status: item.job.status, closed_reason: item.job.closed_reason, node_id: item.job.node_id } };
+    }
+  }
+  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 };
+      return set(upsertMsg(conv.msgs, { id: e.msgId ?? localId("t"), role: "tool", content: JSON.stringify(data), generation: gen, toolId: e.id }));
+    }
+    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) return conv;
+      try {
+        const d = JSON.parse(arr[i].content) as ToolData;
+        d.result = e.content;
+        d.isError = e.isError;
+        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;
+  }
+}
+
+/** 正在执行的那一轮（派发中或执行中）。 */
+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);
+
+/**
+ * 界面上的转录：
+ *   1. 节点转录（首轮的固定启动语句换成真正的第一条消息）；没有转录时用轮次兜底；
+ *   2. 没送到节点就失败 / 取消的轮次，补一行说明（否则用户只看到消息石沉大海）；
+ *   3. 还在中枢排队的消息，作为「排队中」气泡（可撤回），由界面钉在最下面。
+ */
+export function viewMessages(conv: ConvState): Msg[] {
+  let out: Msg[] = [];
+  // 有节点消息就以节点为准：通常先收到全量转录，但新对话可能先来增量事件（user / assistant / tool），也算。
+  if (conv.msgs.length) {
+    // 节点转录只有当前这个 Operator 会话：它的开场是固定的启动语句，正文其实是开出这个会话的那一轮——
+    // 第 1 轮，或者节点会话重建过（context_reset）时最近重建的那一轮。
+    const opener = [...conv.turns].reverse().find((turn) => turn.context_reset && turn.started_at) ?? conv.turns.find((turn) => turn.seq === 1);
+    let replaced = false;
+    for (const m of conv.msgs) {
+      if (!replaced && m.role === "user" && m.content.trim() === OPERATOR_INITIAL_PROMPT && opener) {
+        replaced = true;
+        out.push({ ...m, content: opener.sent_input ?? opener.input });
+      } 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) {
+      notices.push({ id: `turn-fail-${turn.turn_id}`, role: "system", content: `⚠ 第 ${turn.seq} 条消息${turn.status === "cancelled" ? "已撤回" : "没有执行"}${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;
+}
+
+/** 把说明行按时间插进转录：放在时间不晚于它的最后一条消息之后（没有时间的消息沿用前一条的时间）。 */
+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,
+    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,
+    status: conv.job?.status ?? "succeeded",
+    closed_reason: conv.job?.closed_reason ?? null,
+    turns,
+    continued_by_job_id: conv.continuedBy,
+    occurred_at: new Date().toISOString(),
+  };
+}