@thaut/claude-ide 0.0.0-stage → 1.0.0

package/web/src/transcript.ts

@@ -0,0 +1,583 @@
+import type { LiveEvent, SdkMessageLike } from "@shared/protocol.ts";
+import { toolResultSourceUuid } from "./message-bodies.ts";
+
+/**
+ * Turns jsonl history + live events into a flat list of render items.
+ * Messages are deduped by uuid (history and live overlap after a turn ends).
+ */
+
+export type ContentBlock =
+  | { type: "text"; text: string }
+  | { type: "thinking"; thinking: string }
+  | { type: "image"; source?: { media_type?: string; data?: string } }
+  | { type: "tool_use"; id: string; name: string; input: Record<string, unknown> }
+  | { type: "tool_result"; tool_use_id: string; content: unknown; is_error?: boolean }
+  | { type: string; [k: string]: unknown };
+
+export type ToolResult = { content: unknown; isError: boolean; structured?: unknown; deferredUuid?: string };
+
+/** Live state of a subagent / background task, from task_* system events. */
+export type TaskProgress = {
+  taskId: string;
+  status: "running" | "completed" | "failed" | "stopped" | "killed";
+  description?: string;
+  subagentType?: string;
+  lastTool?: string;
+  toolUses?: number;
+  durationMs?: number;
+  summary?: string;
+};
+
+export type BuildOptions = {
+  /** Build the transcript of one subagent (the Agent tool_use id) instead of the main thread. */
+  parent?: string;
+  /** Other invocations of the same stable subagent, never its descendants. */
+  parents?: ReadonlySet<string>;
+};
+
+export type Item = (
+  | { kind: "user"; key: string; text: string; images: number; imageSrcs?: string[]; scheduled?: boolean }
+  | { kind: "text"; key: string; text: string; streaming?: boolean }
+  | { kind: "thinking"; key: string; text: string; streaming?: boolean; streamStateKey?: string }
+  | { kind: "tool"; key: string; id: string; name: string; input: Record<string, unknown>; result?: ToolResult; task?: TaskProgress; steps?: number }
+  | { kind: "result"; key: string; ok: boolean; subtype: string; costUsd?: number; durationMs?: number; error?: string; turnCostUsd?: number; userMessageIds?: string[] }
+  /** `!command` and its output (running until the output arrives). */
+  | { kind: "bash"; key: string; command: string; stdout?: string; stderr?: string; running: boolean }
+  /** Output of a local slash command (/cost, /context…), shown verbatim. */
+  | { kind: "local"; key: string; text: string }
+  | { kind: "notice"; key: string; text: string; tone: "info" | "error" }
+) & { deferred?: { uuid: string; bytes: number }; ts?: number };
+
+type Msg = { uuid: string; type: string; parent: string | null; fromHistory: boolean; message: { role?: string; content?: unknown; id?: string }; raw: SdkMessageLike; ts?: number };
+
+/** Strip CLI-internal wrappers out of user text; returns null for messages that should not be shown. */
+function visibleUserText(text: string): string | null {
+  if (/^\s*<(local-command-caveat|command-name|local-command-stdout|task-notification|system-reminder)/.test(text)) return null;
+  if (text.startsWith("Caveat: The messages below were generated")) return null;
+  // /goal bookkeeping the CLI injects; the goal bar shows its state instead.
+  if (text.startsWith("A session-scoped Stop hook is now active") || text.startsWith("Stop hook feedback:")) return null;
+  return text;
+}
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+
+/** Parse an SDK ISO timestamp; live emitters without one fall back to receive time. */
+function timestampOf(raw: SdkMessageLike, fallback: boolean): number | undefined {
+  const value = raw.timestamp;
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (!fallback) return undefined;
+  const ts = Date.now();
+  // Keep the fallback on the raw record so freezing live history into the
+  // transcript preserves the same displayed time instead of losing it.
+  try { raw.timestamp = new Date(ts).toISOString(); } catch { /* frozen SDK object */ }
+  return ts;
+}
+
+function localText(s: string): string {
+  return s.replace(/<\/?local-command-std(out|err)>/g, "").replace(ANSI, "").trim();
+}
+
+/** `<command-name>/x</command-name>…<command-args>a</command-args>` → "/x a" */
+function slashCommandText(text: string): string | null {
+  const name = /<command-name>([^<]*)<\/command-name>/.exec(text)?.[1];
+  if (!name) return null;
+  const args = /<command-args>([\s\S]*?)<\/command-args>/.exec(text)?.[1]?.trim();
+  return `${name.startsWith("/") ? name : `/${name}`}${args ? ` ${args}` : ""}`;
+}
+
+function parseBash(text: string): { command?: string; stdout?: string; stderr?: string } | null {
+  const input = /^\s*<bash-input>([\s\S]*?)<\/bash-input>/.exec(text);
+  const stdout = /<bash-stdout>([\s\S]*?)<\/bash-stdout>/.exec(text);
+  if (!input && !stdout) return null;
+  const stderr = /<bash-stderr>([\s\S]*?)<\/bash-stderr>/.exec(text);
+  return { command: input?.[1], stdout: stdout?.[1]?.replace(ANSI, ""), stderr: stderr?.[1]?.replace(ANSI, "") };
+}
+
+function blocksOf(content: unknown): ContentBlock[] {
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  if (Array.isArray(content)) return content as ContentBlock[];
+  return [];
+}
+
+type Draft = { parent: string | null; msgId: string; index: number; kind: "text" | "thinking"; text: string; checkpoint?: boolean; truncated?: boolean; ts: number };
+
+const draftKey = (parent: string | null, msgId: string, index: number) => JSON.stringify([parent, msgId, index]);
+const draftItemKey = (parent: string | null, msgId: string, index: number) =>
+  parent === null ? `draft-${msgId}:${index}` : `draft-${draftKey(parent, msgId, index)}`;
+
+/** Everything learned from history + events so far; items are derived from it. */
+type State = {
+  msgs: Msg[];
+  tasks: Map<string, TaskProgress>; // by tool_use_id
+  taskTool: Map<string, string>; // task_id → tool_use_id
+  steps: Map<string, number>; // subagent messages seen live, by parent tool_use_id
+  seen: Set<string>;
+  positions: Map<string, number>;
+  liveSeen: Set<string>;
+  liveAfter?: number;
+  replayAnchored: boolean;
+  results: Extract<Item, { kind: "result" }>[];
+  notices: { after: number; item: Item }[];
+  drafts: Map<string, Draft>;
+  settledDrafts: Set<string>;
+  thinkingStreams: Map<string, string>;
+  bashPending: Set<string>;
+};
+
+const freshState = (): State => ({
+  msgs: [],
+  tasks: new Map(),
+  taskTool: new Map(),
+  steps: new Map(),
+  seen: new Set(),
+  positions: new Map(),
+  liveSeen: new Set(),
+  replayAnchored: false,
+  results: [],
+  notices: [],
+  drafts: new Map(),
+  settledDrafts: new Set(),
+  thinkingStreams: new Map(),
+  bashPending: new Set(),
+});
+
+/**
+ * Incremental transcript: history is read once, and live events are applied as they
+ * are appended (live.ts only ever appends to a session's event array, or replaces it).
+ * Items whose content did not change keep their object identity, so memoized rows
+ * skip re-rendering.
+ */
+export class Transcript {
+  private s = freshState();
+  private history?: SdkMessageLike[];
+  private events?: LiveEvent[];
+  private applied = 0;
+  private last: Item[] = [];
+  /** `last` without the streaming drafts at its end. */
+  private base?: Item[];
+  private byKey = new Map<string, Item>();
+
+  constructor(private readonly opts: BuildOptions = {}) {}
+
+  update(history: SdkMessageLike[] | undefined, events: LiveEvent[]): Item[] {
+    const n = this.applied;
+    let extended =
+      this.events !== undefined &&
+      history === this.history &&
+      events.length >= n &&
+      (n === 0 || (events[0] === this.events[0] && events[n - 1] === this.events[n - 1]));
+    // History and WebSocket replay can arrive in separate batches. Once the first
+    // shared history message arrives, rebuild so earlier live-only frames take their real position.
+    if (extended && !this.s.replayAnchored && history?.length) {
+      extended = !events.slice(n).some((ev) => {
+        const uuid = ev.k === "sdk" ? ev.m.uuid : ev.k === "user" || ev.k === "bash" ? ev.uuid : undefined;
+        const position = uuid ? this.s.positions.get(uuid) : undefined;
+        return position !== undefined && this.s.msgs[position]?.fromHistory;
+      });
+    }
+    if (extended && events.length === n) {
+      this.events = events;
+      return this.last;
+    }
+    if (!extended) {
+      this.s = freshState();
+      for (const m of history ?? []) {
+        if (m.type === "system" && m.subtype === "compact_boundary") this.apply({ k: "sdk", m });
+        else this.push(m, true);
+      }
+      // Replayed events belong among the history, rather than after all of it.
+      // A leading result with no preceding buffered message goes before the next known message.
+      for (const ev of events) {
+        const uuid = ev.k === "sdk" ? ev.m.uuid : ev.k === "user" || ev.k === "bash" ? ev.uuid : undefined;
+        const position = uuid ? this.s.positions.get(uuid) : undefined;
+        if (position !== undefined) { this.s.liveAfter = position; this.s.replayAnchored = true; break; }
+      }
+      this.applied = 0;
+      this.base = undefined;
+    }
+    // Streaming text only grows the drafts at the end: everything before them stays as it was.
+    let onlyText = extended && this.base !== undefined;
+    for (let i = this.applied; i < events.length; i++) {
+      const ev = events[i]!;
+      if (ev.k !== "delta") onlyText = false;
+      this.apply(ev);
+    }
+    this.history = history;
+    this.events = events;
+    this.applied = events.length;
+    const prevDrafts = new Map(this.last.slice(this.base?.length ?? this.last.length).map((it) => [it.key, it]));
+    if (!onlyText) this.base = this.stabilize(this.derive());
+    const drafts = [...this.s.drafts.values()]
+      .filter((d) => d.text.trim() || d.truncated)
+      .sort((a, b) => a.index - b.index)
+      .map((d): Item => {
+        const key = draftItemKey(d.parent, d.msgId, d.index);
+        const prev = prevDrafts.get(key);
+        const text = d.truncated ? `${d.text}\n\n（流式预览已截断，完成后可加载完整消息。）` : d.text;
+        return prev && prev.kind === d.kind && (prev as { text: string }).text === text ? prev : { kind: d.kind, key, text, streaming: true, ts: d.ts };
+      });
+    this.last = drafts.length ? [...this.base!, ...drafts] : this.base!;
+    return this.last;
+  }
+
+  /** Reuse the previous object for items whose content is unchanged. */
+  private stabilize(items: Item[]): Item[] {
+    const byKey = new Map<string, Item>();
+    const out = items.map((it) => {
+      const prev = this.byKey.get(it.key);
+      const keep = prev && sameItem(prev, it) ? prev : it;
+      byKey.set(it.key, keep);
+      return keep;
+    });
+    this.byKey = byKey;
+    return out;
+  }
+
+  private push(raw: SdkMessageLike, fromHistory = false) {
+    const s = this.s;
+    const isLocal = raw.type === "system" && raw.subtype === "local_command";
+    if (raw.type !== "user" && raw.type !== "assistant" && !isLocal) return;
+    const parent = raw.parent_tool_use_id ?? null;
+    const uuid = raw.uuid ?? `anon-${s.msgs.length}`;
+    const firstLive = !fromHistory && !s.liveSeen.has(uuid);
+    if (firstLive) {
+      // Even a frame already loaded from history must settle its replayed streaming draft.
+      if (raw.type === "assistant") this.settleDrafts(raw, parent);
+      s.liveSeen.add(uuid);
+    }
+    if (raw._bash && s.bashPending.delete(uuid)) {
+      const pending = s.msgs.find((m) => m.uuid === uuid);
+      if (pending) {
+        pending.raw = raw;
+        pending.message = (raw.message ?? {}) as Msg["message"];
+        pending.ts ??= timestampOf(raw, true);
+      }
+      return;
+    }
+    if (s.seen.has(uuid)) {
+      const position = s.positions.get(uuid);
+      if (position !== undefined) {
+        const existing = s.msgs[position];
+        if (existing && existing.ts === undefined) existing.ts = timestampOf(raw, false);
+        if (firstLive) s.liveAfter = Math.max(s.liveAfter ?? 0, position + 1);
+      }
+      return;
+    }
+    s.seen.add(uuid);
+    if (parent && raw.type === "assistant") s.steps.set(parent, (s.steps.get(parent) ?? 0) + 1);
+    // A live-only frame belongs at the replay cursor, before later history, not at the array's end.
+    const at = fromHistory ? s.msgs.length : s.liveAfter ?? s.msgs.length;
+    s.msgs.splice(at, 0, { uuid, type: raw.type, parent, fromHistory, message: (raw.message ?? {}) as Msg["message"], raw, ts: timestampOf(raw, !fromHistory) });
+    for (let i = at; i < s.msgs.length; i++) s.positions.set(s.msgs[i]!.uuid, i);
+    if (!fromHistory) {
+      s.liveAfter = at + 1;
+      for (const notice of s.notices) if (notice.after > at) notice.after++;
+    }
+  }
+
+  private settleDrafts(raw: SdkMessageLike, parent: string | null) {
+    if (!this.ownsParent(parent)) return;
+    const message = raw.message as Msg["message"] | undefined;
+    if (!message?.id) return;
+    const blocks = blocksOf(message.content);
+    const rememberThinking = (blockIndex: number, streamIndex: number) => {
+      // Keep the final SDK UUID as the item/annotation identity. Only its UI
+      // fold state inherits the identity of the streaming block it replaces.
+      if (raw.uuid) this.s.thinkingStreams.set(`${raw.uuid}:${blockIndex}`, draftItemKey(parent, message.id!, streamIndex));
+    };
+    if (Array.isArray(raw._streamBlocks) && raw._streamBlocks.length) {
+      const indexes = raw._streamBlocks.filter((index): index is number => Number.isInteger(index) && index >= 0);
+      const thinking = raw._streamThinking as Record<number, number> | undefined;
+      const streamed = blocks.map((block, index) => ({ block, index })).filter(({ block }) => block.type === "thinking" || block.type === "text");
+      const remaining = new Set(indexes);
+      for (const [position, { block, index: blockIndex }] of streamed.entries()) {
+        // Compacted replay retains the settled indices even after deltas are
+        // discarded. Prefer the exact mapping; older servers only send indices,
+        // which are unambiguous if every text/thinking block is accounted for.
+        const recorded = thinking?.[blockIndex];
+        const index = block.type === "thinking" && recorded !== undefined && remaining.has(recorded) ? recorded
+          : streamed.length === indexes.length ? indexes[position] : indexes.find((candidate) => {
+            const draft = this.s.drafts.get(draftKey(parent, message.id!, candidate));
+            const text = block.type === "thinking" ? block.thinking : block.type === "text" ? block.text : undefined;
+            return remaining.has(candidate) && draft?.kind === block.type && typeof text === "string"
+              && (raw._deferred || draft.checkpoint || text.startsWith(draft.text));
+          });
+        if (index === undefined) continue;
+        remaining.delete(index);
+        const draft = this.s.drafts.get(draftKey(parent, message.id, index));
+        if (block.type === "thinking" && (!draft || draft.kind === "thinking")) rememberThinking(blockIndex, index);
+      }
+      for (const index of indexes) {
+        const key = draftKey(parent, message.id, index);
+        this.s.drafts.delete(key);
+        this.s.settledDrafts.add(key);
+      }
+      return;
+    }
+    for (const [blockIndex, block] of blocks.entries()) {
+      const text = block.type === "thinking" ? block.thinking : block.type === "text" ? block.text : undefined;
+      if (typeof text !== "string") continue;
+      // SDK frames contain completed blocks, often one at a time with the same message.id.
+      // A tool block must not remove a thinking/text draft, nor may a replay remove a later block.
+      const match = [...this.s.drafts.entries()]
+        .filter(([, draft]) => draft.parent === parent && draft.msgId === message.id && draft.kind === block.type && (raw._deferred || draft.checkpoint || text.startsWith(draft.text)))
+        .sort(([, a], [, b]) => a.index - b.index)[0];
+      if (match) {
+        if (block.type === "thinking") rememberThinking(blockIndex, match[1].index);
+        this.s.drafts.delete(match[0]);
+        this.s.settledDrafts.add(match[0]);
+      }
+    }
+  }
+
+  private ownsParent(parent: string | null): boolean {
+    return parent === (this.opts.parent ?? null)
+      || !!this.opts.parent && parent !== null && this.opts.parents?.has(parent) === true;
+  }
+
+  private apply(ev: LiveEvent) {
+    const s = this.s;
+    const want = this.opts.parent ?? null;
+    if (ev.k === "sdk") {
+      if (ev.m.type === "result" && !want) {
+        const r = ev.m;
+        if (r.uuid && s.seen.has(r.uuid)) return;
+        if (r.uuid) s.seen.add(r.uuid);
+        s.results.push({
+          kind: "result",
+          key: `result-${r.uuid ?? s.results.length}`,
+          ok: r.subtype === "success" && !r.is_error,
+          subtype: String(r.subtype),
+          costUsd: typeof r.total_cost_usd === "number" ? r.total_cost_usd : undefined,
+          turnCostUsd: typeof r.turn_cost_usd === "number" ? r.turn_cost_usd : undefined,
+          userMessageIds: Array.isArray(r.user_message_uuids) ? r.user_message_uuids.filter((id): id is string => typeof id === "string") : undefined,
+          durationMs: typeof r.duration_ms === "number" ? r.duration_ms : undefined,
+          error: Array.isArray(r.errors) ? (r.errors as string[]).join("\n") : undefined,
+          ts: timestampOf(r, true),
+        });
+        s.notices.push({ after: s.liveAfter ?? s.msgs.length, item: s.results[s.results.length - 1]! });
+        s.drafts.clear();
+      } else if (ev.m.type === "system" && typeof ev.m.subtype === "string" && ev.m.subtype.startsWith("task_")) {
+        this.trackTask(ev.m);
+      } else if (ev.m.type === "system" && ev.m.subtype === "compact_boundary") {
+        const key = `compact-${ev.m.uuid}`;
+        if (s.seen.has(key)) return;
+        s.seen.add(key);
+        s.notices.push({ after: s.liveAfter ?? s.msgs.length, item: { kind: "notice", key: `compact-${ev.m.uuid}`, text: "上下文已压缩", tone: "info", ts: timestampOf(ev.m, true) } });
+      } else {
+        this.push(ev.m);
+      }
+    } else if (ev.k === "user") {
+      // The CLI does not echo prompts; the server's own echo keeps them in stream order.
+      const content: ContentBlock[] = ev.imageData?.length
+        ? ev.imageData.map((img) => ({ type: "image", source: { media_type: img.mediaType, data: img.data } }) as ContentBlock)
+        : [...Array.from({ length: ev.images ?? 0 }, () => ({ type: "image" }) as ContentBlock)];
+      if (ev.text) content.push({ type: "text", text: ev.text });
+      if (s.bashPending.delete(ev.uuid)) {
+        // `!command` finished: fill in the output of the block shown while it ran.
+        const pending = s.msgs.find((m) => m.uuid === ev.uuid);
+        if (pending) pending.message = { role: "user", content };
+        return;
+      }
+      this.push({ type: "user", uuid: ev.uuid, parent_tool_use_id: null, timestamp: new Date(ev.ts).toISOString(), scheduled: ev.scheduled, message: { role: "user", content } });
+    } else if (ev.k === "bash") {
+      if (s.seen.has(ev.uuid)) return;
+      s.bashPending.add(ev.uuid);
+      this.push({ type: "user", uuid: ev.uuid, parent_tool_use_id: null, timestamp: new Date(ev.ts).toISOString(), message: { role: "user", content: `<bash-input>${ev.command}</bash-input>` } });
+    } else if (ev.k === "delta") {
+      const parent = ev.parent ?? null;
+      if (!this.ownsParent(parent)) return;
+      const key = draftKey(parent, ev.msgId, ev.index);
+      if ((!ev.text && !ev.truncated) || s.settledDrafts.has(key)) return;
+      const d = s.drafts.get(key);
+      if (d && !ev.checkpoint) { d.text += ev.text; d.truncated ||= ev.truncated; }
+      else s.drafts.set(key, { parent, msgId: ev.msgId, index: ev.index, kind: ev.kind, text: ev.text, checkpoint: ev.checkpoint, truncated: ev.truncated, ts: d?.ts ?? Date.now() });
+    } else if (ev.k === "error" && !want) {
+      s.notices.push({ after: s.liveAfter ?? s.msgs.length, item: { kind: "notice", key: `err-${s.notices.length}`, text: ev.message, tone: "error", ts: Date.now() } });
+    }
+  }
+
+  private trackTask(m: SdkMessageLike) {
+    const s = this.s;
+    const toolUseId = (m.tool_use_id as string | undefined) ?? s.taskTool.get(m.task_id as string);
+    if (!toolUseId) return;
+    s.taskTool.set(m.task_id as string, toolUseId);
+    const cur: TaskProgress = s.tasks.get(toolUseId) ?? { taskId: m.task_id as string, status: "running" };
+    const usage = m.usage as { tool_uses?: number; duration_ms?: number } | undefined;
+    const next: TaskProgress = { ...cur };
+    if (m.description) next.description = m.description as string;
+    if (m.subagent_type) next.subagentType = m.subagent_type as string;
+    if (m.last_tool_name) next.lastTool = m.last_tool_name as string;
+    if (usage?.tool_uses !== undefined) next.toolUses = usage.tool_uses;
+    if (usage?.duration_ms !== undefined) next.durationMs = usage.duration_ms;
+    if (m.summary) next.summary = m.summary as string;
+    const status = (m.status as string | undefined) ?? (m.patch as { status?: string } | undefined)?.status;
+    if (status === "completed" || status === "failed" || status === "stopped" || status === "killed") next.status = status;
+    s.tasks.set(toolUseId, next);
+  }
+
+  /** The flat item list from the current state: a cheap linear pass. */
+  private derive(): Item[] {
+    const { msgs, notices, tasks, steps, bashPending } = this.s;
+    const want = this.opts.parent ?? null;
+
+    // Tool results are attached to their tool_use.
+    const toolResults = new Map<string, ToolResult>();
+    const resultSources = new Map<string, string | undefined>();
+    const rememberResult = (id: string, result: ToolResult, uuid?: string) => {
+      // Paging may retain both forms of one result. A preview cannot replace its
+      // already loaded body, but a genuinely later result remains authoritative.
+      if (uuid && resultSources.get(id) === uuid && result.deferredUuid && !toolResults.get(id)?.deferredUuid) return;
+      toolResults.set(id, result);
+      resultSources.set(id, uuid);
+    };
+    for (const m of msgs) {
+      for (const [id, result] of Object.entries((m.raw.linkedToolResults ?? {}) as Record<string, ToolResult>)) rememberResult(id, result, toolResultSourceUuid(m.raw, id, result));
+      if (m.type !== "user") continue;
+      for (const b of blocksOf(m.message.content)) {
+        if (b.type === "tool_result") {
+          const tr = b as Extract<ContentBlock, { type: "tool_result" }>;
+          rememberResult(tr.tool_use_id, { content: tr.content, isError: !!tr.is_error, structured: m.raw.tool_use_result, ...(m.raw._deferred ? { deferredUuid: m.uuid } : {}) }, m.uuid);
+        }
+      }
+    }
+
+    const items: Item[] = [];
+    let ni = 0;
+    const flushNotices = (upTo: number) => {
+      while (ni < notices.length && notices[ni]!.after <= upTo) items.push(notices[ni++]!.item);
+    };
+
+    const localTexts = new Set<string>();
+    msgs.forEach((m, i) => {
+      flushNotices(i);
+      // Main view: subagent traffic is shown inside its tool card. Subagent view: its own file + live frames.
+      if (want ? !(m.fromHistory || this.ownsParent(m.parent)) : m.parent) return;
+      if (m.type === "system") {
+        const text = localText(String(m.raw.content ?? ""));
+        localTexts.add(text);
+        if (text) items.push({ kind: "local", key: m.uuid, text, ts: m.ts });
+        return;
+      }
+      const blocks = blocksOf(m.message.content);
+      if (m.type === "assistant" && (m.message as { model?: string }).model === "<synthetic>") {
+        // Local slash command output (live); the same text from history is already shown.
+        const text = localText(blocks.map((b) => (b.type === "text" ? (b as { text: string }).text : "")).join("\n"));
+        if (text && !localTexts.has(text)) items.push({ kind: "local", key: m.uuid, text, ts: m.ts });
+        return;
+      }
+      if (m.type === "user") {
+        const firstText = blocks.find((b) => b.type === "text") as { text: string } | undefined;
+        // CLI output written as a user record (e.g. a skill's failed `!command` preamble).
+        if (firstText && /^\s*<local-command-std(out|err)>/.test(firstText.text)) {
+          const text = localText(firstText.text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&"));
+          if (text && !localTexts.has(text)) {
+            localTexts.add(text);
+            items.push({ kind: "local", key: m.uuid, text, ts: m.ts });
+          }
+          return;
+        }
+        const bash = (!m.raw._hydrated ? m.raw._bash as { command?: string; stdout?: string; stderr?: string } | undefined : undefined) ?? (firstText ? parseBash(firstText.text) : null);
+        if (bash) {
+          const prev = items[items.length - 1];
+          if (bash.command === undefined && prev?.kind === "bash" && prev.stdout === undefined) {
+            // The CLI's own bash mode writes the output as a separate message.
+            prev.stdout = bash.stdout;
+            prev.stderr = bash.stderr;
+            prev.running = false;
+          } else {
+            items.push({ kind: "bash", key: m.uuid, command: bash.command ?? "", stdout: bash.stdout, stderr: bash.stderr, running: bash.stdout === undefined && bashPending.has(m.uuid), ts: m.ts });
+          }
+          return;
+        }
+        const slash = firstText ? slashCommandText(firstText.text) : null;
+        if (slash) {
+          items.push({ kind: "user", key: m.uuid, text: slash, images: 0, ts: m.ts, ...(m.raw.scheduled === true ? { scheduled: true } : {}) });
+          return;
+        }
+        const texts: string[] = [];
+        const imageSrcs: string[] = [];
+        let images = 0;
+        for (const b of blocks) {
+          if (b.type === "text") {
+            const t = visibleUserText((b as { text: string }).text);
+            if (t !== null) texts.push(t);
+          } else if (b.type === "image") {
+            images++;
+            const src = (b as { source?: { media_type?: string; data?: string } }).source;
+            if (src?.data) imageSrcs.push(`data:${src.media_type ?? "image/png"};base64,${src.data}`);
+          }
+        }
+        if (texts.length || images) items.push({ kind: "user", key: m.uuid, text: texts.join("\n\n"), images, ...(imageSrcs.length ? { imageSrcs } : {}), ...(m.raw.scheduled === true ? { scheduled: true } : {}), ts: m.ts });
+        return;
+      }
+      blocks.forEach((b, j) => {
+        const key = `${m.uuid}:${j}`;
+        if (b.type === "text") {
+          const text = (b as { text: string }).text;
+          // API failures (rate limit, auth, overload…) arrive as assistant text with an `error` tag.
+          if (m.raw.error && text.trim()) items.push({ kind: "notice", key, text, tone: "error", ts: m.ts });
+          else if (text.trim()) items.push({ kind: "text", key, text, ts: m.ts });
+        } else if (b.type === "thinking") {
+          const text = (b as { thinking: string }).thinking;
+          const streamStateKey = this.s.thinkingStreams.get(key);
+          if (text.trim()) items.push({ kind: "thinking", key, text, ...(streamStateKey ? { streamStateKey } : {}), ts: m.ts });
+        } else if (b.type === "tool_use") {
+          const tu = b as Extract<ContentBlock, { type: "tool_use" }>;
+          items.push({
+            kind: "tool",
+            key: tu.id,
+            id: tu.id,
+            name: tu.name,
+            input: tu.input ?? {},
+            result: toolResults.get(tu.id),
+            task: tasks.get(tu.id),
+            steps: steps.get(tu.id),
+            ts: m.ts,
+          });
+        }
+      });
+    });
+    flushNotices(Infinity);
+    for (const m of msgs) {
+      const deferred = m.raw._deferred as { bytes: number } | undefined;
+      if (!deferred || !this.ownsParent(m.parent) && !m.fromHistory) continue;
+      const ids = blocksOf(m.message.content).filter((b) => b.type === "tool_use").map((b) => (b as { id: string }).id);
+      const owner = items.find((it) => it.key === m.uuid || it.key.startsWith(`${m.uuid}:`) || ids.includes(it.key));
+      if (owner) owner.deferred = { uuid: m.uuid, bytes: deferred.bytes };
+      else if (!blocksOf(m.message.content).some((b) => b.type === "tool_result")) items.push({ kind: "notice", key: m.uuid, text: "较大的历史消息", tone: "info", deferred: { uuid: m.uuid, bytes: deferred.bytes }, ts: m.ts });
+    }
+    return items;
+  }
+}
+
+/** One-shot build (subagent pages and other places that do not stream long transcripts). */
+export function buildItems(history: SdkMessageLike[] | undefined, events: LiveEvent[], opts: BuildOptions = {}): Item[] {
+  return new Transcript(opts).update(history, events);
+}
+
+/** Same content: equal fields, comparing nested objects and arrays one level deep. */
+function sameItem(a: Item, b: Item): boolean {
+  if (a.kind !== b.kind) return false;
+  const ra = a as Record<string, unknown>;
+  const rb = b as Record<string, unknown>;
+  const ka = Object.keys(ra);
+  if (ka.length !== Object.keys(rb).length) return false;
+  return ka.every((k) => shallowEqual(ra[k], rb[k]));
+}
+
+function shallowEqual(x: unknown, y: unknown): boolean {
+  if (x === y) return true;
+  if (!x || !y || typeof x !== "object" || typeof y !== "object") return false;
+  if (Array.isArray(x)) return Array.isArray(y) && x.length === y.length && x.every((v, i) => v === y[i]);
+  const ox = x as Record<string, unknown>;
+  const oy = y as Record<string, unknown>;
+  const kx = Object.keys(ox);
+  return kx.length === Object.keys(oy).length && kx.every((k) => ox[k] === oy[k]);
+}
+
+export { deriveTodos, type Todo } from "@shared/todos.ts";