@thaut/claude-ide 0.0.0-stage → 1.0.0

package/web/src/live-message-hydration.test.ts

@@ -0,0 +1,253 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { historyPage, historyMessage } from "../../server/history-pages.ts";
+import type { SdkMessageLike } from "@shared/protocol.ts";
+import { buildItems } from "./transcript.ts";
+import { MESSAGE_LIMIT } from "@shared/message-window.ts";
+
+(globalThis as any).document = { querySelector: () => null };
+const { useLive, hydrateSessionMessage, loadSessionHistory } = await import("./live.ts");
+const snapshot = { state: "idle" as const, pending: [], planMode: false, crons: [], tasks: [] };
+const structured = { structuredPatch: [{ oldStart: 80, newStart: 80, lines: [" context", "-old", "+new"] }] };
+const call = (): SdkMessageLike => ({ type: "assistant", uuid: "call", parent_tool_use_id: "agent-tool", message: { content: [
+  { type: "tool_use", id: "edit", name: "Edit", input: { file_path: "/a", old_string: "old", new_string: "new" } },
+] }, linkedToolResults: { edit: { content: "deferred", isError: false, deferredUuid: "result" } } });
+const result = () => ({ type: "user", uuid: "result", parent_tool_use_id: null,
+  message: { content: [{ type: "tool_result", tool_use_id: "edit", content: "edited" }] }, tool_use_result: structured });
+const child = (): SdkMessageLike => ({ type: "assistant", uuid: "child", parent_tool_use_id: "agent-tool", _streamBlocks: [0],
+  _deferred: { bytes: 300000 }, message: { content: [{ type: "text", text: "preview" }] } });
+const fullChild = () => ({ type: "assistant", uuid: "child", parent_tool_use_id: null, message: { content: [{ type: "text", text: "full child answer" }] } });
+function seed(items: SdkMessageLike[], events: SdkMessageLike[] = []) {
+  useLive.setState({ sessions: { s: { epoch: "e", seq: 1, resetCount: 1, snapshot, events: events.map((m) => ({ k: "sdk", m })),
+    history: { source: "agent", mode: "history", generation: "g", request: 1, older: "yes", items } } } });
+}
+
+test("linked-only hydration admits its owner and projects complete structured Edit results", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => Response.json(result());
+  try {
+    seed([call()]);
+    await hydrateSessionMessage("s", "p", "result", "agent");
+    const current = useLive.getState().sessions.s!;
+    const tool = buildItems(current.history!.items, [], { parent: "agent-tool" }).find((item) => item.kind === "tool");
+    assert.equal(tool?.kind, "tool");
+    if (tool?.kind !== "tool") throw new Error("missing tool");
+    assert.deepEqual(tool.result, { content: "edited", isError: false, structured });
+    assert.deepEqual(current.history!.items[0]!._hydratedMessageUuids, ["result"]);
+  } finally { globalThis.fetch = original; }
+});
+
+test("REST body hydration retains live child envelope and stream settlement metadata", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => Response.json(fullChild());
+  try {
+    seed([], [child()]);
+    await hydrateSessionMessage("s", "p", "child", "agent");
+    const current = useLive.getState().sessions.s!;
+    const event = current.events[0]!;
+    assert.equal(event.k, "sdk");
+    if (event.k !== "sdk") throw new Error("missing event");
+    assert.equal(event.m.parent_tool_use_id, "agent-tool");
+    assert.deepEqual(event.m._streamBlocks, [0]);
+    assert.equal(event.m._deferred, undefined);
+    assert.ok(buildItems(undefined, current.events, { parent: "agent-tool" }).some((item) => item.kind === "text" && item.text === "full child answer"));
+    assert.equal(buildItems(undefined, current.events).length, 0);
+  } finally { globalThis.fetch = original; }
+});
+
+test("pending older page adopts hydrated linked/child bodies and protects them through trimming", async () => {
+  const original = globalThis.fetch;
+  let resolve!: (response: Response) => void;
+  globalThis.fetch = async (input) => {
+    const url = String(input);
+    if (url.includes("/messages/result")) return Response.json(result());
+    if (url.includes("/messages/child")) return Response.json(fullChild());
+    return new Promise((r) => { resolve = r; });
+  };
+  try {
+    seed([call(), child()], [child()]);
+    const pending = loadSessionHistory("s", "p", "older", "agent");
+    await hydrateSessionMessage("s", "p", "result", "agent");
+    await hydrateSessionMessage("s", "p", "child", "agent");
+    // The response overlaps both frozen records with stale previews and adds enough
+    // older records that ordinary backwards trimming would remove the hydrated tail.
+    resolve(Response.json({ generation: "g", items: [
+      ...Array.from({ length: MESSAGE_LIMIT }, (_, i) => ({ type: "user", uuid: `old-${i}`, message: { content: `older ${i}` } })), call(), child(),
+    ] }));
+    await pending;
+    const current = useLive.getState().sessions.s!;
+    assert.equal(current.history?.error, undefined);
+    assert.ok(current.history!.items.length + current.events.length <= MESSAGE_LIMIT);
+    assert.equal(current.evicted, true);
+    assert.deepEqual(current.history!.items.slice(-2).map((m) => m.uuid), ["call", "child"]);
+    const items = buildItems(current.history!.items, current.events, { parent: "agent-tool" });
+    const tool = items.find((item) => item.kind === "tool");
+    assert.equal(tool?.kind, "tool");
+    if (tool?.kind !== "tool") throw new Error("missing tool");
+    assert.deepEqual(tool.result, { content: "edited", isError: false, structured });
+    assert.ok(items.some((item) => item.kind === "text" && item.text === "full child answer" && !item.deferred));
+    const event = current.events.find((event) => event.k === "sdk" && event.m.uuid === "child");
+    assert.ok(event?.k === "sdk" && event.m.parent_tool_use_id === "agent-tool");
+  } finally { globalThis.fetch = original; }
+});
+
+test("unretainable linked hydration rejects without mutating the previous cached preview", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => Response.json({ ...result(), message: { content: [{ type: "tool_result", tool_use_id: "edit", content: "x".repeat(7 * 1024 * 1024) }] } });
+  try {
+    const owner = call();
+    owner.message = { content: "x".repeat(14 * 1024 * 1024) };
+    owner._hydrated = true;
+    seed([owner]);
+    const before = useLive.getState().sessions.s;
+    await assert.rejects(hydrateSessionMessage("s", "p", "result", "agent"), /cannot fit/);
+    assert.equal(useLive.getState().sessions.s, before);
+  } finally { globalThis.fetch = original; }
+});
+
+test("hydration rejected after branch change or missing target cannot report success", async () => {
+  const original = globalThis.fetch;
+  let resolve!: (response: Response) => void;
+  globalThis.fetch = () => new Promise((r) => { resolve = r; });
+  try {
+    seed([child()]);
+    const pending = hydrateSessionMessage("s", "p", "child", "agent");
+    useLive.setState((state) => ({ sessions: { s: { ...state.sessions.s!, historyRevision: "new-branch" } } }));
+    resolve(Response.json(fullChild()));
+    await assert.rejects(pending, /会话已更新/);
+    seed([]);
+    globalThis.fetch = async () => Response.json(fullChild());
+    await assert.rejects(hydrateSessionMessage("s", "p", "child", "agent"), /cannot fit/);
+  } finally { globalThis.fetch = original; }
+});
+
+test("paging introduces standalone previews without losing hydrated results in main or agent views", async () => {
+  const original = globalThis.fetch;
+  try {
+    for (const agentId of [undefined, "agent"]) {
+      const source = agentId ?? "main";
+      const owner = { ...call(), parent_tool_use_id: null };
+      useLive.setState({ sessions: { s: { epoch: "e", seq: 1, resetCount: 1, snapshot, events: [],
+        history: { source, mode: "history", generation: "g", request: 1, older: "yes", items: [owner] } } } });
+      globalThis.fetch = async (input) => String(input).includes("/messages/result") ? Response.json(result())
+        : Response.json({ generation: "g", items: [owner, { ...result(), _deferred: { bytes: 300000 },
+          message: { content: [{ type: "tool_result", tool_use_id: "edit", content: "short" }] } }] });
+      await hydrateSessionMessage("s", "p", "result", agentId);
+      await loadSessionHistory("s", "p", "latest", agentId);
+      const current = useLive.getState().sessions.s!;
+      const visible = buildItems(current.history!.items, [], agentId ? { parent: "agent-tool" } : {});
+      const tool = visible.find((item) => item.kind === "tool");
+      assert.equal(tool?.kind, "tool");
+      if (tool?.kind !== "tool") throw new Error("missing tool");
+      assert.deepEqual(tool.result, { content: "edited", isError: false, structured });
+      const standalone = current.history!.items.find((m) => m.uuid === "result")!;
+      assert.equal((standalone.linkedToolResults as Record<string, { content: unknown }>).edit!.content, "edited");
+    }
+  } finally { globalThis.fetch = original; }
+});
+
+test("authoritative branch replacement never adopts hydrated results from the previous view", async () => {
+  const original = globalThis.fetch;
+  try {
+    seed([call()]);
+    globalThis.fetch = async () => Response.json(result());
+    await hydrateSessionMessage("s", "p", "result", "agent");
+    useLive.setState((state) => ({ sessions: { s: { ...state.sessions.s!, historyRevision: "old" } } }));
+    globalThis.fetch = async () => Response.json({ generation: "new", historyRevision: "new", items: [
+      call(), { ...result(), _deferred: { bytes: 300000 }, message: { content: [{ type: "tool_result", tool_use_id: "edit", content: "new branch preview" }] } },
+    ] });
+    await loadSessionHistory("s", "p", "latest", "agent");
+    const current = useLive.getState().sessions.s!;
+    assert.equal(current.historyRevision, "new");
+    const tool = buildItems(current.history!.items, [], { parent: "agent-tool" }).find((item) => item.kind === "tool");
+    assert.equal(tool?.kind === "tool" && tool.result?.content, "new branch preview");
+    assert.equal(current.history!.items.some((m) => m._hydrated), false);
+  } finally { globalThis.fetch = original; }
+});
+
+test("result hydration survives paging away its owner and returning to the tool call", async () => {
+  const original = globalThis.fetch;
+  try {
+    seed([call()]);
+    globalThis.fetch = async () => Response.json(result());
+    await hydrateSessionMessage("s", "p", "result", "agent");
+    globalThis.fetch = async () => Response.json({ generation: "g", older: "yes", items: [
+      { ...result(), _deferred: { bytes: 300000 }, message: { content: [{ type: "tool_result", tool_use_id: "edit", content: "short" }] } },
+    ] });
+    await loadSessionHistory("s", "p", "latest", "agent");
+    let current = useLive.getState().sessions.s!;
+    assert.deepEqual(current.history!.items.map((m) => m.uuid), ["result"]);
+    assert.equal((current.history!.items[0]!.linkedToolResults as Record<string, { content: unknown }>).edit!.content, "edited");
+    globalThis.fetch = async () => Response.json({ generation: "g", items: [call()] });
+    await loadSessionHistory("s", "p", "older", "agent");
+    current = useLive.getState().sessions.s!;
+    const tool = buildItems(current.history!.items, [], { parent: "agent-tool" }).find((item) => item.kind === "tool");
+    assert.equal(tool?.kind === "tool" && tool.result?.content, "edited");
+  } finally { globalThis.fetch = original; }
+});
+
+test("three page transitions keep provenance when a previously deferred linked result fits normally", async () => {
+  const original = globalThis.fetch;
+  try {
+    seed([call()]);
+    globalThis.fetch = async () => Response.json(result());
+    await hydrateSessionMessage("s", "p", "result", "agent");
+    const completeCall = { ...call(), linkedToolResults: { edit: { content: "edited", isError: false, structured } }, _toolResultUuids: { edit: "result" } };
+    globalThis.fetch = async () => Response.json({ generation: "g", items: [completeCall] });
+    await loadSessionHistory("s", "p", "latest", "agent");
+    assert.deepEqual(useLive.getState().sessions.s!.history!.items[0]!._hydratedToolResultUuids, { edit: "result" });
+    globalThis.fetch = async () => Response.json({ generation: "g", items: [call(),
+      { ...result(), _deferred: { bytes: 300000 }, message: { content: [{ type: "tool_result", tool_use_id: "edit", content: "short" }] } },
+    ] });
+    await loadSessionHistory("s", "p", "latest", "agent");
+    const current = useLive.getState().sessions.s!;
+    const tool = buildItems(current.history!.items, [], { parent: "agent-tool" }).find((item) => item.kind === "tool");
+    assert.equal(tool?.kind === "tool" && tool.result?.content, "edited");
+  } finally { globalThis.fetch = original; }
+});
+
+
+test("real server preview truncation preserves every hydrated result when its owner leaves and returns", async (t) => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "cide-result-blocks-"));
+  t.after(() => fs.rm(directory, { recursive: true, force: true }));
+  const file = path.join(directory, "session.jsonl");
+  const text = "complete ".repeat(2000);
+  const ids = Array.from({ length: 21 }, (_, index) => `tool-${index}`);
+  const records: Record<string, unknown>[] = [{ type: "assistant", uuid: "owner", parentUuid: null,
+    message: { role: "assistant", content: ids.map((id) => ({ type: "tool_use", id, name: "Read", input: { file_path: `/${id}` } })) } }];
+  for (let index = 0; index < 110; index++) records.push({ type: "user", uuid: `padding-${index}`, parentUuid: index ? `padding-${index - 1}` : "owner",
+    message: { role: "user", content: `padding ${index}` } });
+  records.push({ type: "user", uuid: "result", parentUuid: "padding-109",
+    message: { role: "user", content: ids.map((tool_use_id) => ({ type: "tool_result", tool_use_id, content: text })) } });
+  await fs.writeFile(file, records.map((record) => JSON.stringify(record)).join("\n") + "\n");
+  const initial = await historyPage(file, { before: "padding-0" });
+  useLive.setState({ sessions: { s: { epoch: "e", seq: 1, resetCount: 1, snapshot, events: [],
+    history: { ...initial, source: "main", mode: "history", request: 1 } } } });
+  const original = globalThis.fetch;
+  globalThis.fetch = async (input) => {
+    const url = new URL(String(input), "http://fixture.invalid");
+    if (url.pathname.endsWith("/messages/result")) return Response.json(await historyMessage(file, "result"));
+    return Response.json(await historyPage(file, { before: url.searchParams.get("before") ?? undefined }));
+  };
+  try {
+    await hydrateSessionMessage("s", "p", "result");
+    let current = useLive.getState().sessions.s!;
+    assert.equal(buildItems(current.history!.items, []).filter((item) => item.kind === "tool" && item.result?.content === text).length, ids.length);
+    await loadSessionHistory("s", "p", "latest");
+    current = useLive.getState().sessions.s!;
+    assert.equal(current.history!.items.some((message) => message.uuid === "owner"), false);
+    const standalone = current.history!.items.find((message) => message.uuid === "result")!;
+    assert.ok(standalone._deferred, "other preview content remains deferred");
+    const preview = (standalone.message as { content: { type?: string }[] }).content;
+    assert.ok(preview.filter((block) => block?.type === "tool_result").length < ids.length, "fixture must really truncate whole blocks");
+    assert.equal(Object.keys(standalone.linkedToolResults as object).length, ids.length);
+    await loadSessionHistory("s", "p", "older");
+    current = useLive.getState().sessions.s!;
+    const tools = buildItems(current.history!.items, []).filter((item) => item.kind === "tool");
+    assert.equal(tools.length, ids.length);
+    assert.ok(tools.every((item) => item.result?.content === text && !item.result.deferredUuid));
+  } finally { globalThis.fetch = original; }
+});

package/web/src/live.ts

@@ -0,0 +1,404 @@
+import { create } from "zustand";
+import type { ClientMsg, HistoryPage, LiveEvent, LiveSnapshot, SdkMessageLike, ServerMsg } from "@shared/protocol.ts";
+import { buildItems, deriveTodos } from "./transcript.ts";
+import { api } from "./api.ts";
+import { invalidateAuth, onAuthInvalidated } from "./auth-events.ts";
+import { boundSession, boundSessions, browsingBase, compactEvents, edgeMessage, mergePage } from "./message-cache.ts";
+import { SESSION_BYTES, contentBytes, displayEvent } from "@shared/message-window.ts";
+import { queryClient } from "./queryClient.ts";
+import { mergeSnapshot, updateTodosFromEvents, type SessionLive } from "./live-merge.ts";
+import { hydrateMessageBody, preserveHydratedBodies } from "./message-bodies.ts";
+import { mergeAgentOwners } from "./agent-owners.ts";
+
+
+const emptySnapshot: LiveSnapshot = { state: "idle", pending: [], planMode: false, crons: [], tasks: [] };
+
+type LiveStore = {
+  connected: boolean;
+  distVersion?: string;
+  sessions: Record<string, SessionLive>;
+};
+
+export const useLive = create<LiveStore>(() => ({ connected: false, sessions: {} }));
+export const loadedBuildVersion = document.querySelector<HTMLMetaElement>('meta[name="cide-build"]')?.content;
+
+export function useSessionLive(sessionId: string | undefined): SessionLive | undefined {
+  return useLive((s) => (sessionId ? s.sessions[sessionId] : undefined));
+}
+
+/** Apply one event to the snapshot so UI state (status, pending…) is derived in one place. */
+function applyToSnapshot(snap: LiveSnapshot, ev: LiveEvent): LiveSnapshot {
+  switch (ev.k) {
+    case "state":
+      return { ...snap, state: ev.state };
+    case "pending":
+      return { ...snap, pending: [...snap.pending.filter((p) => p.id !== ev.req.id), ev.req] };
+    case "resolved":
+      return { ...snap, pending: snap.pending.filter((p) => p.id !== ev.id) };
+    case "crons":
+      return { ...snap, crons: ev.crons, cronsStale: false };
+    case "tasks":
+      return { ...snap, tasks: ev.tasks };
+    case "agent_tasks":
+      return { ...snap, agentTasks: ev.tasks };
+    case "settings":
+      return { ...snap, model: ev.model, effort: ev.effort, planMode: ev.planMode, askQuestionsEnabled: ev.askQuestionsEnabled ?? snap.askQuestionsEnabled, writeEnabled: ev.writeEnabled ?? snap.writeEnabled };
+    case "sdk":
+      if (ev.m.type === "result" && typeof ev.m.total_cost_usd === "number") return { ...snap, costUsd: ev.m.total_cost_usd };
+      return snap;
+    default:
+      return snap;
+  }
+}
+
+// ---------- connection ----------
+
+type Sub = { projectId: string };
+
+let ws: WebSocket | undefined;
+let retry = 0;
+let authBlocked = false;
+const subs = new Map<string, Sub>();
+const outbox: ClientMsg[] = [];
+
+function wsUrl() {
+  const proto = location.protocol === "https:" ? "wss:" : "ws:";
+  return `${proto}//${location.host}/ws`;
+}
+
+function rawSend(msg: ClientMsg) {
+  if (authBlocked) return;
+  if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
+  // Subscriptions are re-sent from `subs` on (re)connect; queueing them would subscribe twice.
+  else if (msg.t !== "sub" && msg.t !== "unsub") outbox.push(msg);
+}
+
+function subscribeMsg(sessionId: string, sub: Sub): ClientMsg {
+  flushLive();
+  const cur = useLive.getState().sessions[sessionId];
+  return { t: "sub", sessionId, projectId: sub.projectId, epoch: cur?.epoch, seq: cur?.seq, bounded: true };
+}
+
+let retryTimer: ReturnType<typeof setTimeout> | undefined;
+
+const visible = () => document.visibilityState === "visible";
+
+/**
+ * Open the socket unless one is already open or opening. Exactly one reconnect timer exists,
+ * and callbacks of a superseded socket are ignored, so a phone waking up while a retry is
+ * pending never ends up with two sockets or a "disconnected" badge on a live one.
+ */
+function connect() {
+  if (authBlocked) return;
+  if (retryTimer) clearTimeout(retryTimer);
+  retryTimer = undefined;
+  if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) return;
+  const sock = new WebSocket(wsUrl());
+  ws = sock;
+  sock.onopen = () => {
+    if (ws !== sock) return;
+    retry = 0;
+    useLive.setState({ connected: true });
+    if (loadedBuildVersion) sock.send(JSON.stringify({ t: "clientVersion", version: loadedBuildVersion } satisfies ClientMsg));
+    sock.send(JSON.stringify({ t: "visibility", visible: visible() } satisfies ClientMsg));
+    for (const [id, sub] of subs) sock.send(JSON.stringify(subscribeMsg(id, sub)));
+    for (const m of outbox.splice(0)) sock.send(JSON.stringify(m));
+  };
+  sock.onmessage = (e) => {
+    if (ws === sock) onServerMsg(JSON.parse(e.data) as ServerMsg);
+  };
+  sock.onclose = (e) => {
+    if (ws !== sock) return;
+    useLive.setState({ connected: false });
+    ws = undefined;
+    if (e.code === 4401) {
+      invalidateAuth();
+      return;
+    }
+    const delay = Math.min(10_000, 500 * 2 ** retry++);
+    retryTimer = setTimeout(connect, delay);
+  };
+}
+
+function onServerMsg(msg: ServerMsg) {
+  if (msg.t === "version") {
+    useLive.setState({ distVersion: msg.version });
+    return;
+  }
+  if (msg.t === "pong") {
+    if (pongTimer) clearTimeout(pongTimer);
+    pongTimer = undefined;
+    return;
+  }
+  if (msg.t === "sessions") {
+    queryClient.invalidateQueries({ queryKey: ["sessions", msg.projectId] });
+    queryClient.invalidateQueries({ queryKey: ["overview"] });
+    queryClient.invalidateQueries({ queryKey: ["btw", msg.projectId] });
+    return;
+  }
+  if (msg.t === "activity") {
+    for (const fn of activityListeners) fn(msg);
+    return;
+  }
+  if (msg.t === "error") {
+    console.warn("server error:", msg.message);
+    return;
+  }
+  if (msg.t === "ev") {
+    queue(msg.sessionId, msg.seq, msg.ev);
+    return;
+  }
+  // A snapshot follows our own `sub`: commit what is queued first so the order stays intact.
+  flushLive();
+  useLive.setState((st) => {
+    const cur = st.sessions[msg.sessionId];
+    const next = mergeSnapshot(cur, msg);
+    return { sessions: boundSessions({ ...st.sessions, [msg.sessionId]: next }, new Set(subs.keys())) };
+  });
+}
+
+// ---------- batched commits ----------
+//
+// Live events are not committed to the store one by one: every commit re-renders the
+// transcript. Streaming text (the server already merges deltas every ~50ms) is committed
+// at most every 100–400ms, slower when the last commit took long to render (slow phones,
+// long sessions); other events go out within a frame. See NOTES.md "性能".
+
+const queued = new Map<string, { seq: number; ev: LiveEvent }[]>();
+let flushTimer: ReturnType<typeof setTimeout> | undefined;
+let flushDue = Infinity;
+let lastCommitCost = 0;
+
+function queue(sessionId: string, seq: number, ev: LiveEvent) {
+  let q = queued.get(sessionId);
+  if (!q) queued.set(sessionId, (q = []));
+  q.push({ seq, ev });
+  schedule(ev.k === "delta" ? Math.min(400, Math.max(100, lastCommitCost * 4)) : 16);
+}
+
+function schedule(delay: number) {
+  const due = performance.now() + delay;
+  if (flushTimer !== undefined && flushDue <= due) return;
+  clearTimeout(flushTimer);
+  flushDue = due;
+  flushTimer = setTimeout(flushLive, delay);
+}
+
+const sameDraft = (a: LiveEvent | undefined, b: Extract<LiveEvent, { k: "delta" }>): a is Extract<LiveEvent, { k: "delta" }> =>
+  a?.k === "delta" && a.msgId === b.msgId && a.index === b.index && a.kind === b.kind && a.parent === b.parent;
+
+/** Commit queued events to the store (merging consecutive text deltas of one block). */
+function flushLive() {
+  clearTimeout(flushTimer);
+  flushTimer = undefined;
+  flushDue = Infinity;
+  if (queued.size === 0) return;
+  const batch = [...queued];
+  queued.clear();
+  const t0 = performance.now();
+  useLive.setState((st) => {
+    let sessions = st.sessions;
+    for (const [id, evs] of batch) {
+      const cur = sessions[id];
+      if (!cur) continue;
+      let { seq, snapshot, events, resetCount, historyRevision } = cur;
+      let agentOwners = cur.agentOwners;
+      const added: LiveEvent[] = [];
+      for (const { seq: s, ev: raw } of evs) {
+        const ev = displayEvent(raw);
+        if (s <= seq) continue;
+        seq = s;
+        if (ev.k === "reset") {
+          events = [];
+          added.length = 0;
+          resetCount++;
+          historyRevision = ev.historyRevision;
+          agentOwners = undefined;
+          continue;
+        }
+        snapshot = applyToSnapshot(snapshot, ev);
+        const last = added[added.length - 1];
+        if (ev.k === "delta" && sameDraft(last, ev)) added[added.length - 1] = { ...last, text: last.text + ev.text };
+        else added.push(ev);
+      }
+      if (seq === cur.seq) continue;
+      const combined = added.length ? [...events, ...added] : events;
+      const compact = combined.length > 128 && (combined.length - events.length >= 128 || combined.length % 128 < added.length);
+      const reset = resetCount !== cur.resetCount;
+      const todos = updateTodosFromEvents(combined, added, reset ? undefined : cur.todos);
+      sessions = { ...sessions, [id]: boundSession({ ...cur, seq, snapshot, resetCount, historyRevision, todos,
+        agentOwners: mergeAgentOwners(agentOwners, added, snapshot.agentTasks),
+        history: reset ? undefined : cur.history, events: compact ? compactEvents(combined) : combined }) };
+    }
+    return sessions === st.sessions ? st : { sessions: boundSessions(sessions, new Set(subs.keys())) };
+  });
+  // Time until the frame showing this commit is out: the rendering cost of one commit.
+  requestAnimationFrame(() => setTimeout(() => (lastCommitCost = performance.now() - t0), 0));
+}
+
+type Activity = Extract<ServerMsg, { t: "activity" }>;
+const activityListeners = new Set<(a: Activity) => void>();
+
+/** Session finished / needs attention, from any project. */
+export function onActivity(fn: (a: Activity) => void) {
+  activityListeners.add(fn);
+  return () => {
+    activityListeners.delete(fn);
+  };
+}
+
+let pongTimer: ReturnType<typeof setTimeout> | undefined;
+let started = false;
+
+onAuthInvalidated(() => {
+  if (authBlocked) return;
+  authBlocked = true;
+  outbox.length = 0;
+  if (retryTimer) clearTimeout(retryTimer);
+  retryTimer = undefined;
+  if (pongTimer) clearTimeout(pongTimer);
+  pongTimer = undefined;
+  // Detach first: a late close/open callback must not reconnect or flush old commands.
+  const sock = ws;
+  ws = undefined;
+  useLive.setState({ connected: false });
+  sock?.close();
+  queryClient.setQueryData(["auth"], { authed: false });
+  void queryClient.invalidateQueries({ queryKey: ["auth"] });
+});
+
+/** A socket can look OPEN after a phone slept although the connection is gone: probe it. */
+function probe() {
+  const sock = ws;
+  if (!sock || sock.readyState !== WebSocket.OPEN) return connect();
+  sock.send(JSON.stringify({ t: "ping" } satisfies ClientMsg));
+  if (pongTimer) clearTimeout(pongTimer);
+  pongTimer = setTimeout(() => {
+    if (ws !== sock) return;
+    // No answer: drop it (its onclose would come late or never) and reconnect now.
+    ws = undefined;
+    useLive.setState({ connected: false });
+    sock.close();
+    connect();
+  }, 3000);
+}
+
+export function startLive() {
+  authBlocked = false;
+  if (!ws) connect();
+  if (started) return;
+  started = true;
+  document.addEventListener("visibilitychange", () => {
+    // Tell the server whether anyone is actually looking, so it pushes to background tabs.
+    if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ t: "visibility", visible: visible() } satisfies ClientMsg));
+    // Phones drop sockets while locked; check the connection as soon as the page is back.
+    if (visible()) probe();
+  });
+}
+
+export function subscribeSession(sessionId: string, projectId: string) {
+  subs.set(sessionId, { projectId });
+  useLive.setState((st) => {
+    const cur = st.sessions[sessionId];
+    return { sessions: boundSessions({ ...st.sessions, [sessionId]: { ...(cur ?? { seq: 0, snapshot: emptySnapshot, events: [], resetCount: 0 }), accessed: Date.now() } }, new Set(subs.keys())) };
+  });
+  rawSend(subscribeMsg(sessionId, { projectId }));
+  return () => {
+    subs.delete(sessionId);
+    rawSend({ t: "unsub", sessionId });
+    historyRequests.get(sessionId)?.abort();
+    useLive.setState((st) => ({ sessions: boundSessions(st.sessions, new Set(subs.keys())) }));
+  };
+}
+
+export function sendClient(msg: ClientMsg) {
+  // Settings changes show immediately; the server's `settings` event confirms them.
+  if (msg.t === "setModel" || msg.t === "setEffort" || msg.t === "setPlanMode") {
+    const patch = msg.t === "setModel" ? { model: msg.model } : msg.t === "setEffort" ? { effort: msg.effort } : { planMode: msg.on };
+    useLive.setState((st) => {
+      const cur = st.sessions[msg.sessionId];
+      if (!cur) return st;
+      return { sessions: { ...st.sessions, [msg.sessionId]: { ...cur, snapshot: { ...cur.snapshot, ...patch } } } };
+    });
+  }
+  rawSend(msg);
+}
+
+export { emptySnapshot };
+
+// History bodies live in the same bounded session store as live replay, not in a second query cache.
+const historyRequests = new Map<string, AbortController>();
+let historyRequestId = 0;
+export async function loadSessionHistory(sessionId: string, projectId: string, direction: "latest" | "older" | "newer" = "latest", agentId?: string) {
+  historyRequests.get(sessionId)?.abort();
+  const controller = new AbortController();
+  historyRequests.set(sessionId, controller);
+  const request = ++historyRequestId;
+  const initial = useLive.getState().sessions[sessionId];
+  if (!initial) { historyRequests.delete(sessionId); return; }
+  const source = agentId ?? "main";
+  const base = `/api/projects/${projectId}/sessions/${sessionId}${agentId ? `/subagents/${encodeURIComponent(agentId)}` : ""}/messages`;
+  const baseHistory = direction !== "latest" ? browsingBase(initial) : undefined;
+  const initialBodies = new Set([...initial.events.flatMap((event) => event.k === "sdk" ? [event.m] : []), ...(initial.history?.items ?? [])]);
+  const resetCount = initial.resetCount;
+  const historyRevision = initial.historyRevision;
+  const edge = initial.history?.source === source ? edgeMessage(initial, direction === "older" ? "first" : "last") : undefined;
+  const params = new URLSearchParams({ page: "1" });
+  if (direction !== "latest" && edge) params.set(direction === "older" ? "before" : "after", edge);
+  useLive.setState((st) => {
+    const cur = st.sessions[sessionId];
+    if (!cur) return st;
+    return { sessions: { ...st.sessions, [sessionId]: { ...cur, history: { items: [], generation: "", mode: "latest", ...(cur.history?.source === source ? cur.history : {}), source, loading: true, error: undefined, request } } } };
+  });
+  try {
+    const page = await api<HistoryPage>(`${base}?${params}`, { signal: controller.signal });
+    useLive.setState((st) => {
+      const cur = st.sessions[sessionId];
+      if (!cur || cur.resetCount !== resetCount || cur.history?.request !== request) return st;
+      if (cur.historyRevision !== historyRevision && cur.historyRevision !== page.historyRevision) {
+        // The first socket may have established a newer branch while HTTP was in flight.
+        // Trigger the view's normal reload instead of leaving its loading flag stranded.
+        return { sessions: { ...st.sessions, [sessionId]: { ...cur, history: undefined, resetCount: cur.resetCount + 1 } } };
+      }
+      // With no intervening WS update, HTTP is authoritative too (e.g. server restart
+      // while WS remains unavailable). Adopt its new revision rather than retry forever.
+      const changedView = cur.historyRevision !== undefined && page.historyRevision !== undefined && cur.historyRevision !== page.historyRevision;
+      const events = changedView ? [] : cur.events;
+      const merged = mergePage(changedView ? undefined : baseHistory ?? cur.history, page, changedView ? "latest" : direction, request);
+      const currentBodies = !changedView && cur.history?.source === source ? [
+        ...cur.events.flatMap((event) => event.k === "sdk" ? [event.m] : []), ...cur.history.items,
+      ] : [];
+      const history = { ...merged, items: preserveHydratedBodies(merged.items, currentBodies), source };
+      const hydratedDuringRequest = currentBodies.filter((m) => m._hydrated && !initialBodies.has(m));
+      const protectedMessages = hydratedDuringRequest.flatMap((m) => [
+        ...(m._hydratedMessageUuids as string[] ?? []), ...(!m._deferred && m.uuid ? [m.uuid] : []),
+      ]);
+      const todos = source === "main" ? deriveTodos(buildItems(undefined, events), page.todos) : changedView ? undefined : cur.todos;
+      const next = boundSession({ ...cur, events, resetCount: cur.resetCount + (changedView ? 1 : 0), historyRevision: page.historyRevision ?? cur.historyRevision, todos, history }, { protectedMessages });
+      return { sessions: boundSessions({ ...st.sessions, [sessionId]: next }, new Set(subs.keys())) };
+    });
+  } catch (error) {
+    if (controller.signal.aborted) return;
+    useLive.setState((st) => {
+      const cur = st.sessions[sessionId];
+      if (!cur?.history || cur.history.request !== request) return st;
+      return { sessions: { ...st.sessions, [sessionId]: { ...cur, history: { ...cur.history, loading: false, error: (error as Error).message } } } };
+    });
+  } finally { if (historyRequests.get(sessionId) === controller) historyRequests.delete(sessionId); }
+}
+
+export async function hydrateSessionMessage(sessionId: string, projectId: string, uuid: string, agentId?: string) {
+  const start = useLive.getState().sessions[sessionId];
+  if (!start) throw new Error("消息所在的会话已不在缓存中，请重新加载");
+  const message = await api<SdkMessageLike>(`/api/projects/${projectId}/sessions/${sessionId}${agentId ? `/subagents/${encodeURIComponent(agentId)}` : ""}/messages/${encodeURIComponent(uuid)}`);
+  if (contentBytes(message) > SESSION_BYTES / 2) throw new Error("这条消息超过缓存上限，请导出会话查看");
+  message._hydrated = true;
+  useLive.setState((st) => {
+    const cur = st.sessions[sessionId];
+    if (!cur || cur.resetCount !== start.resetCount || cur.epoch !== start.epoch || cur.historyRevision !== start.historyRevision) throw new Error("会话已更新，请重新加载这条消息");
+    const hydrate = (m: SdkMessageLike) => hydrateMessageBody(m, message, uuid);
+    const history = cur.history ? { ...cur.history, items: cur.history.items.map(hydrate) } : undefined;
+    const events = cur.events.map((e) => e.k === "sdk" ? { ...e, m: hydrate(e.m) } : e);
+    return { sessions: boundSessions({ ...st.sessions, [sessionId]: boundSession({ ...cur, history, events }, { protectedMessage: uuid }) }, new Set([...subs.keys(), sessionId])) };
+  });
+}