@spzxg/cli-ui 0.0.0-stage → 0.3.0

package/src/core/conversation.ts

@@ -0,0 +1,439 @@
+/**
+ * 一个对话的前端状态，以及把 center 实时流的事件应用上去的纯函数（无 React，可单测）。
+ *
+ * 数据来自两层：
+ *   · 中枢轮次（turn）：每条消息一轮，排队 → 执行中 → 成功 / 失败 / 取消（或被合并进别的轮次）。
+ *   · 节点转录（transcript + node 事件）：Agent 实际的对话过程，规则与 Operator 的 useTaskStream 一致。
+ * 界面以节点转录为主；转录还没有（没派发、节点连不上）时用轮次的 input / reply 兜底。
+ */
+import type { AskAnswers, AskQuestion, CenterTurn, ConversationClosedCallback, ConversationTurnCallback, JobStatus, Message, Msg, NodeEvent, StreamItem, StreamSnapshot, StreamTask, 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"]);
+
+// ── 对话键 ─────────────────────────────────────────────
+//
+// 一个对话任务（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;
+  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 = (key: string): ConvState => ({
+  key, ...parseConvKey(key), job: null, task: 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 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): ConvState {
+  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([], snapshot.turns),
+    resolvedModel: conv.resolvedModel ?? job.conversation?.last_turn?.resolved_model ?? null,
+  };
+}
+
+// 缺字段时兜底：generation 缺省 1（按它分会话，缺了会把顺序排乱）；时间缺就不显示。
+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 (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") {
+      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, node_id: item.job.node_id } };
+    } else if (item.type === "task") {
+      next = { ...next, task: item.task };
+    }
+  }
+  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 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);
+
+/**
+ * 界面上的转录：
+ *   1. 节点转录（首轮的固定启动语句换成真正的第一条消息）；没有转录时用轮次兜底；
+ *   2. 没送到节点就失败 / 取消的轮次，补一行说明（否则用户只看到消息石沉大海）；
+ *   3. 还在中枢排队的消息，作为「排队中」气泡（可撤回），由界面钉在最下面。
+ */
+export function viewMessages(conv: ConvState): Msg[] {
+  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;
+    let replaced = false;
+    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;
+}
+
+/** 把说明行按时间插进转录：放在时间不晚于它的最后一条消息之后（没有时间的消息沿用前一条的时间）。 */
+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,
+    // 只关掉了这一个对话（对话任务还开着）：带上是哪个，原因写 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(),
+  };
+}

package/src/core/provider.tsx

@@ -0,0 +1,103 @@
+import { createContext, useContext, useEffect, useMemo, useRef, useSyncExternalStore, type ReactNode } from "react";
+import { createCliStore, type CliEvent, type CliState, type CliStore, type CliStoreOptions } from "./store.js";
+import type { ConversationCallback, ConversationEndPayload, TurnEndPayload } from "./types.js";
+
+/**
+ * 积木的拼接点。放在同一个 <CliCenterProvider> 里的组件共享一个仓库：
+ * 列表点哪个对话，对话组件就显示哪个；同一个对话只连一条实时流。
+ *
+ *   <CliCenterProvider baseUrl="/api/center">
+ *     <CliMsgList />
+ *     <CliChat />
+ *   </CliCenterProvider>
+ *
+ * 组件单独使用时不需要它：组件发现外面没有 Provider，会用自己的 props 建一个。
+ */
+const StoreContext = createContext<CliStore | null>(null);
+
+export interface CliCenterProviderProps extends CliStoreOptions, ResultHandlers {
+  /** 外部建好的仓库（例如 Web Component 按 group 共享的）；给了就不再自己建。 */
+  store?: CliStore;
+  /** 监听仓库事件：选中、一轮结束、对话结束、job 变化、错误。 */
+  onEvent?: (event: CliEvent) => void;
+  children: ReactNode;
+}
+
+/**
+ * 结果通知：组件从实时流里看到一轮结束 / 对话结束时调用，全在浏览器里发生，**和 center 的 callback.url 无关**——
+ * 不配 callback 也照样会调。载荷字段与 center 回调体一致，方便业务后端和前端用同一套代码解析。
+ */
+export interface ResultHandlers {
+  /** 一轮结束（成功 / 失败 / 取消）。 */
+  onTurnEnd?: (payload: TurnEndPayload) => void;
+  /** 对话结束（关闭 / 取消 / 过期……）。 */
+  onConversationEnd?: (payload: ConversationEndPayload) => void;
+  /** @deprecated 旧名字，等同于同时监听 onTurnEnd 和 onConversationEnd（payload.type 区分）。 */
+  onCallback?: (payload: ConversationCallback) => void;
+}
+
+export function dispatchResult(event: CliEvent, handlers: ResultHandlers) {
+  if (event.type === "conversation_turn") { handlers.onTurnEnd?.(event.payload); handlers.onCallback?.(event.payload); }
+  else if (event.type === "conversation_closed") { handlers.onConversationEnd?.(event.payload); handlers.onCallback?.(event.payload); }
+}
+
+export function CliCenterProvider({ store: external, onEvent, onTurnEnd, onConversationEnd, onCallback, children, ...options }: CliCenterProviderProps) {
+  // 连接参数只在建仓库时用一次：中途换 baseUrl / token 请换 key 重建。
+  const optionsRef = useRef(options);
+  const store = useMemo(() => external ?? createCliStore(optionsRef.current), [external]);
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent;
+  const resultRef = useRef<ResultHandlers>({});
+  resultRef.current = { onTurnEnd, onConversationEnd, onCallback };
+  useEffect(() => store.on((event) => {
+    onEventRef.current?.(event);
+    dispatchResult(event, resultRef.current);
+  }), [store]);
+  return <StoreContext.Provider value={store}>{children}</StoreContext.Provider>;
+}
+
+export function useCliStoreContext(): CliStore | null {
+  return useContext(StoreContext);
+}
+
+export function useCliStore(): CliStore {
+  const store = useContext(StoreContext);
+  if (!store) throw new Error("useCliStore 必须在 <CliCenterProvider> 内使用");
+  return store;
+}
+
+/** 订阅仓库状态的一部分。选择器返回的值按引用比较，状态是不可变的，所以返回子对象是安全的。 */
+export function useCliState<T>(selector: (state: CliState) => T): T {
+  const store = useCliStore();
+  return useSyncExternalStore(store.subscribe, () => selector(store.getState()), () => selector(store.getState()));
+}
+
+/** 组件外面没有 Provider 时，用组件自己的 props 包一层。 */
+export function withOwnProvider<P extends object>(props: P & CliStoreOptions & ResultHandlers & { onEvent?: (event: CliEvent) => void; store?: CliStore }, inner: ReactNode, hasContext: boolean) {
+  if (hasContext) return inner;
+  const { baseUrl, token, line, headers, fetch, client, namespace, newConversation, createConversation, businessIdFor, onEvent, onTurnEnd, onConversationEnd, onCallback, store } = props;
+  // 连接参数变了（换了中枢地址、令牌、产品线、命名空间）就换一个新仓库重连，不沿用旧连接。
+  const connection = [baseUrl ?? "", token ?? "", line ?? "", namespace ?? ""].join("\u0000");
+  return (
+    <CliCenterProvider key={store ? "external" : connection} {...{ baseUrl, token, line, headers, fetch, client, namespace, newConversation, createConversation, businessIdFor, onEvent, onTurnEnd, onConversationEnd, onCallback, store }}>
+      {inner}
+    </CliCenterProvider>
+  );
+}
+
+/**
+ * 组件自己的 onEvent / onTurnEnd / onConversationEnd：组件放在外层 Provider 里时由这里订阅
+ * （自己建 Provider 时交给那个 Provider，免得调两次）。
+ */
+export function useComponentEvents(onEvent: ((event: CliEvent) => void) | undefined, results: ResultHandlers, enabled: boolean) {
+  const store = useContext(StoreContext);
+  const ref = useRef({ onEvent, results });
+  ref.current = { onEvent, results };
+  useEffect(() => {
+    if (!enabled || !store) return;
+    return store.on((event) => {
+      ref.current.onEvent?.(event);
+      dispatchResult(event, ref.current.results);
+    });
+  }, [store, enabled]);
+}

package/src/core/sse.ts

@@ -0,0 +1,51 @@
+/**
+ * 极简 SSE 解析器。用 fetch 读流而不是 EventSource：EventSource 不能带 Authorization 头，
+ * 而 center 的接口按产品线令牌鉴权（直连或经代理都可能需要带头）。
+ *
+ * 按 https://html.spec.whatwg.org/multipage/server-sent-events.html 的行规则：
+ * `event:` 设事件名，`data:` 累加数据，空行派发；以 `:` 开头的是注释（心跳 ping）。
+ */
+export interface SseMessage { event: string; data: string }
+
+export function createSseParser(onMessage: (message: SseMessage) => void) {
+  let buffer = "";
+  let event = "";
+  let data: string[] = [];
+
+  const dispatch = () => {
+    if (data.length) onMessage({ event: event || "message", data: data.join("\n") });
+    event = "";
+    data = [];
+  };
+
+  const line = (raw: string) => {
+    if (raw === "") return dispatch();
+    if (raw.startsWith(":")) return;
+    const colon = raw.indexOf(":");
+    const field = colon === -1 ? raw : raw.slice(0, colon);
+    let value = colon === -1 ? "" : raw.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") event = value;
+    else if (field === "data") data.push(value);
+  };
+
+  return {
+    push(chunk: string) {
+      buffer += chunk;
+      let index: number;
+      // 行尾可能是 \n、\r\n 或 \r。
+      while ((index = buffer.search(/\r\n|\r|\n/)) !== -1) {
+        const sep = buffer.startsWith("\r\n", index) ? 2 : 1;
+        // 只剩一个 \r 时等下一块：它可能是 \r\n 的前半。
+        if (buffer[index] === "\r" && sep === 1 && index === buffer.length - 1) break;
+        line(buffer.slice(0, index));
+        buffer = buffer.slice(index + sep);
+      }
+    },
+    end() {
+      if (buffer) line(buffer);
+      buffer = "";
+      dispatch();
+    },
+  };
+}