Open source CapCut alternative.
TypeScript
fix(cut): save a chat thread from the chat itself and catch it up from the turn journal
David Le6e388b748e8e
diff --git a/site/src/cut/components/AiPanel.tsx b/site/src/cut/components/AiPanel.tsxindex 3030d644..8ae51d20 100644--- a/site/src/cut/components/AiPanel.tsx+++ b/site/src/cut/components/AiPanel.tsx@@ -7,8 +7,8 @@ import { ChatStatusBadge, type ChatStatus } from "./ChatStatusBadge";import { chatRuntime, cutJudge } from "@/cut/lib/chatRuntime";import { ChatRequests } from "@/cut/lib/chatRequests";import { Fragment, memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, type ReactNode } from "react";-import { useChat } from "@ai-sdk/react";-import { DefaultChatTransport, type ChatTransport, type UIMessage, type UIMessageChunk } from "ai";+import { Chat, useChat } from "@ai-sdk/react";+import { DefaultChatTransport, type ChatInit, type ChatTransport, type UIMessage, type UIMessageChunk } from "ai";import {ArrowUp,Brain,@@ -61,9 +61,11 @@ import {isStoredThread,readActiveChat,readRawThreads,+ recordThread,writeActiveChat,writeRawThreads,subscribeChatThreads,+ type ThreadRecorder,} from "@/cut/lib/chatThreads";import {deleteCloudThread,@@ -106,9 +108,9 @@ import { withChatProject } from "@/cut/lib/projectChatTools";import { runAiTool } from "@/cut/lib/aiTools";import { holdEditorChat } from "@/cut/lib/editorWork";import { recoverSceneCall } from "@/cut/lib/chatRecovery";-import { replayChatStream } from "@/cut/lib/chatReplay";-import { INTERRUPTED_ERROR, isResumeMessage, RESUME_LIMIT, resumePrompt, scrubLostTurn, unfinishedAsk, type ResumeMetadata, type TurnSettled } from "@/cut/lib/chatResume";-import { answerEngineGate, claimEngineTool, cancelEngineChat, foldIntoEngineChat, joinRunningEngineChat } from "@/cut/lib/engineChat";+import { countChunks, replayChatStream } from "@/cut/lib/chatReplay";+import { INTERRUPTED_ERROR, isResumeMessage, journalAhead, RESUME_LIMIT, resumePrompt, scrubLostTurn, unfinishedAsk, type JournalMark, type ResumeMetadata, type TurnSettled } from "@/cut/lib/chatResume";+import { answerEngineGate, claimEngineTool, cancelEngineChat, foldIntoEngineChat, joinRunningEngineChat, peekEngineChat } from "@/cut/lib/engineChat";import { messageText } from "@/cut/lib/messageText";import { EngineGate, engineInstant, handledSince, judgeEngineTurn } from "@/cut/lib/pi/engineTurn";import type { EngineRoute } from "@/cut/server/ai/turnCatalog";@@ -178,6 +180,9 @@ interface ChatThread {/** The pi loop's LLM context (structured tool history included), when the* thread has run on it. */pi?: AgentMessage[];+ /** How much of its newest engine turn's journal the thread was saved from,+ * once that turn ended. */+ journal?: JournalMark;}@@ -933,6 +938,33 @@ async function accountJudges(queryClient: QueryClient): Promise<boolean> {}}+type ChatEvents = Pick<ChatInit<UIMessage>, "onError" | "onFinish" | "onData" | "onToolCall">;++/** A session's Chat. Its callbacks and transport route to the ones the latest+ * commit bound, as useChat does with its own, so the Chat can live outside+ * the hook and the thread's record can follow it directly. */+function sessionChat(id: string, messages: UIMessage[] | undefined) {+ type Bound = ChatEvents & { transport: ChatTransport<UIMessage> };+ let bound: Bound | null = null;+ const transport = () => {+ if (!bound) throw new Error("The chat is not ready yet.");+ return bound.transport;+ };+ const chat = new Chat<UIMessage>({+ id,+ messages,+ transport: {+ sendMessages: (options) => transport().sendMessages(options),+ reconnectToStream: (options) => transport().reconnectToStream(options),+ },+ onError: (error) => bound?.onError?.(error),+ onFinish: (event) => bound?.onFinish?.(event),+ onData: (part) => bound?.onData?.(part),+ onToolCall: (call) => bound?.onToolCall?.(call),+ });+ return { chat, bind: (next: Bound) => { bound = next; } };+}+/** Running sessions stay mounted for the lifetime of their editor. */function ChatSession({projectId,@@ -1085,6 +1117,13 @@ function ChatSession({const completedMessageId = useRef(initialThread?.completedMessageId);const turnSettled = useRef<TurnSettled | undefined>(initialThread?.turnSettled);const resumed = useRef(initialThread?.resumed ?? 0);+ // The journal chunks the newest engine turn's stream handed the chat, and+ // the mark the thread keeps once that turn ends (see journalAhead).+ const streamed = useRef<JournalMark | null>(null);+ const journalMark = useRef(initialThread?.journal);+ // A replay catching the thread up to the engine's journal: "finished" when+ // that turn is over, so its tool calls and gate are history, not requests.+ const catchingUp = useRef<"running" | "finished" | null>(null);const userStopped = useRef(false);// A dropped connection with continuations left: the turn rests, then resumes.const [retryDisconnect, setRetryDisconnect] = useState(false);@@ -1186,6 +1225,7 @@ function ChatSession({// A new turn opens with no verdict; a continuation keeps its ask's count.turnSettled.current = undefined;userStopped.current = false;+ streamed.current = null;const newest = options.messages.at(-1);if (!newest || !isResumeMessage(newest)) resumed.current = 0;if (provider(currentModel()) === "gemini") {@@ -1219,30 +1259,41 @@ function ChatSession({const ask = options.messages.findLast((m) => m.role === "user" && !isResumeMessage(m));engineGateRef.current = decision?.route.gate ? new EngineGate(ask ? messageText(ask) : "") : null;const send: EngineSend = { context: deps.buildContext(), route: decision?.route };- return engine().sendMessages({ ...options, body: { ...options.body, ...send } });+ return countChunks(await engine().sendMessages({ ...options, body: { ...options.body, ...send } }), (mark) => { streamed.current = mark; });},reconnectToStream: async (options) => {if (provider(currentModel()) === "gemini") return Promise.resolve(null);setClientTools(false);+ streamed.current = null;let replay: ReadableStream<UIMessageChunk> | null = null;try {const stream = await engine().reconnectToStream(options);- replay = stream ? await replayChatStream(stream, prepareReplay, attachReplay, completedMessageId.current) : null;+ // A catch-up replays the reply the thread already counts as done.+ replay = stream ? await replayChatStream(stream, prepareReplay, attachReplay, catchingUp.current ? undefined : completedMessageId.current) : null;} finally {// A replay settles the reconnect when it finishes (onFinish); with// nothing to replay the resume effect moves on to a continuation.- if (!replay) setReconnect("done");+ if (!replay) {+ catchingUp.current = null;+ setReconnect("done");+ }}- return replay;+ return replay && countChunks(replay, (mark) => { streamed.current = mark; });},};}, [threadId, projectId, currentModel, sessionFor, setClientTools, prepareReplay, attachReplay, registerBrowserTurn, queryClient]);- const { messages, setMessages, sendMessage, stop, status, error, clearError, resumeStream } = useChat({- id: threadId,- messages: initialThread && settleInterruptedTools(initialThread.messages),- transport,+ // The session owns its Chat so the thread's record can follow the chat's+ // own state (recordThread, below) rather than this component's renders: a+ // tab that cannot paint keeps streaming and running tools while React may+ // commit nothing.+ const [session] = useState(() => sessionChat(threadId, initialThread && settleInterruptedTools(initialThread.messages)));+ const chat = session.chat;+ const { messages, setMessages, sendMessage, stop, status, error, clearError, resumeStream } = useChat({ chat });+ // Bound on every commit, so the Chat always reaches the newest closures.+ const chatEvents: ChatEvents = {onError: () => {+ catchingUp.current = null;finishBrowserTurn.current?.();finishBrowserTurn.current = null;endChatTurn(threadId);@@ -1253,7 +1304,12 @@ function ChatSession({finishBrowserTurn.current?.();finishBrowserTurn.current = null;if (chatThreadDeleted(projectId, threadId)) return;- if (!isAbort && !isDisconnect && !isError) completedMessageId.current = message.id;+ catchingUp.current = null;+ if (!isAbort && !isDisconnect && !isError) {+ completedMessageId.current = message.id;+ // The whole turn landed: the thread now holds this much of its journal.+ if (streamed.current?.messageId === message.id) journalMark.current = streamed.current;+ }// A verdict holds the thread for the user. A detach (this panel closing// its reader while the engine keeps working) and a dropped connection// with continuations left leave none, so the turn resumes.@@ -1280,6 +1336,7 @@ function ChatSession({messages: recoverSceneCall(finished, threadId, useEditor.getState().projectId === projectId ? useEditor.getState().genvideo : undefined),sessions: { ...providerSessions.current },pi: readPiSession(threadId) ?? previous?.pi,+ journal: journalMark.current,};seenThreadAt.current = thread.updatedAt;writeThreads(projectId, [thread, ...stored.filter((item) => item.id !== threadId)]);@@ -1300,7 +1357,7 @@ function ChatSession({}// The engine's turn is signing off: judge its record and answer with// the next pass's steer, or none to let it close.- if (part.type === "data-gate") {+ if (part.type === "data-gate" && catchingUp.current !== "finished") {const { gateId, reply } = part.data as { gateId: string; reply: string };const gate = engineGateRef.current;const sessionKey = sessionKeyRef.current;@@ -1317,6 +1374,8 @@ function ChatSession({// Gemini turns already executed the tool in the transport loop; their// tool chunks are display-only.if (clientToolsRef.current) return;+ // A finished turn replayed to catch up already ran its tools.+ if (catchingUp.current === "finished") return;// Execute on the editor store, then hand the result back to the// server-side bridge (which is holding the provider's tool call open).const sessionKey = sessionKeyRef.current;@@ -1348,13 +1407,17 @@ function ChatSession({}})();},- });+ };+ useLayoutEffect(() => session.bind({ transport, ...chatEvents }));const savedScene = useEditor((s) => s.projectId === projectId ? s.genvideo : undefined);useLayoutEffect(() => {replayHandler.current = (id, requestId) => {const lastUser = messages.findLast((m) => m.role === "user");- if (requestId && lastUser?.id !== requestId) return false;+ // A catch-up already matched the journal's reply to the thread's last+ // message; a message folded into that turn sits after its ask.+ const caughtUp = catchingUp.current !== null && messages.at(-1)?.id === id;+ if (requestId && lastUser?.id !== requestId && !caughtUp) return false;setMessages((current) => current.map((m) => m.id === id ? { ...m, parts: [] } : m));return true;};@@ -1413,7 +1476,67 @@ function ChatSession({useEffect(() => {if (busy) return holdEditorChat(projectId);}, [busy, projectId]);- const receivedThread = useRef(false);+ // Keep the thread saved (so it shows up in the Threads panel) as it grows.+ // A save rereads, re-slims, and rewrites the project's whole stored history —+ // synchronous main-thread work that scales with everything the chats have+ // ever produced — and a streaming turn changes the chat every chunk, so+ // saving on each change ground the editor down as transcripts grew. A+ // change arms one save, at most once per THREAD_SAVE_MS, that reads the+ // chat as it stands when it lands; turn end, thread switch, and pagehide+ // flush it, so nothing is lost. The recorder follows the Chat itself, not+ // this component's renders: a screen-locked or background tab keeps+ // streaming and running tools while it commits nothing, and its record+ // used to stop at the last render before the screen went dark.+ const saveThreadNow = useCallback((live: UIMessage[]) => {+ if (live.length === 0 || chatThreadDeleted(projectId, threadId)) return;+ const firstUser = live.find((m) => m.role === "user");+ const stored = readThreads(projectId);+ // The pi transcript is held for the recent threads only; a thread whose+ // session has been let go reads back as undefined, and writing that would+ // erase the tool-call context the stored one still has. What is on disk+ // stands until a live session replaces it.+ const thread: ChatThread = {+ id: threadId,+ title: (firstUser ? messageText(firstUser) : "").slice(0, 80) || "New chat",+ updatedAt: Date.now(),+ messages: recoverSceneCall(live, threadId, useEditor.getState().genvideo),+ sessions: { ...providerSessions.current },+ completedMessageId: completedMessageId.current,+ turnSettled: turnSettled.current,+ resumed: resumed.current,+ pi: readPiSession(threadId) ?? stored.find((t) => t.id === threadId)?.pi,+ journal: journalMark.current,+ };+ seenThreadAt.current = thread.updatedAt;+ writeThreads(projectId, [thread, ...stored.filter((t) => t.id !== threadId)]);+ // Cloud projects mirror the thread server-side (debounced while it streams).+ queueCloudThreadSave(projectId, slimForStorage([thread])[0]);+ }, [projectId, threadId]);+ const recorder = useRef<ThreadRecorder | null>(null);+ // A thread switch unmounts this session mid-throttle; the page going away+ // skips unmounts entirely. Both flush the waiting save.+ useEffect(() => {+ const record = recordThread(chat, saveThreadNow, THREAD_SAVE_MS);+ recorder.current = record;+ const onPageHide = () => {+ record.flush();+ flushCloudThreadSaves(true);+ };+ window.addEventListener("pagehide", onPageHide);+ return () => {+ window.removeEventListener("pagehide", onPageHide);+ recorder.current = null;+ record.stop();+ flushCloudThreadSaves();+ };+ }, [chat, saveThreadNow]);+ // Land the final transcript locally and on the server as soon as the turn+ // settles instead of waiting out the save throttle.+ useEffect(() => {+ if (busy) return;+ recorder.current?.flush();+ flushCloudThreadSaves();+ }, [busy]);useEffect(() => {const receive = () => {if (chatThreadDeleted(projectId, threadId)) {@@ -1429,14 +1552,17 @@ function ChatSession({const thread = readThreads(projectId).find((t) => t.id === threadId);if (!thread || thread.updatedAt <= seenThreadAt.current) return;seenThreadAt.current = thread.updatedAt;- receivedThread.current = true;completedMessageId.current = thread.completedMessageId;turnSettled.current = thread.turnSettled;resumed.current = thread.resumed ?? 0;+ journalMark.current = thread.journal;providerSessions.current = { ...thread.sessions };dropPiSession(threadId);hydratePiSession(threadId, thread.pi);- setMessages(thread.messages);+ // Read back from storage: the copy is not saved back over itself.+ const apply = () => setMessages(thread.messages);+ if (recorder.current) recorder.current.quietly(apply);+ else apply();};const unsubscribe = subscribeChatThreads(projectId, receive);receive();@@ -1467,84 +1593,6 @@ function ChatSession({return () => useEditor.getState().endHistoryBatch();}, [busy]);- // Keep the thread saved (so it shows up in the Threads panel) as it grows.- // A save rereads, re-slims, and rewrites the project's whole stored history —- // synchronous main-thread work that scales with everything the chats have- // ever produced — and a streaming turn replaces `messages` every chunk, so- // saving on each change ground the editor down as transcripts grew. The- // newest snapshot parks in a ref and lands at most once per THREAD_SAVE_MS;- // turn end, thread switch, and pagehide flush it, so nothing is lost.- const pendingThread = useRef<ChatThread | null>(null);- const saveTimer = useRef<number | null>(null);- const saveThreadNow = useCallback(() => {- const thread = pendingThread.current;- pendingThread.current = null;- if (!thread || chatThreadDeleted(projectId, thread.id)) return;- if (saveTimer.current !== null) {- window.clearTimeout(saveTimer.current);- saveTimer.current = null;- }- const stored = readThreads(projectId);- // The pi transcript is held for the recent threads only; a thread whose- // session has been let go reads back as undefined, and writing that would- // erase the tool-call context the stored one still has. What is on disk- // stands until a live session replaces it.- const merged = {- ...thread,- completedMessageId: completedMessageId.current,- turnSettled: turnSettled.current,- resumed: resumed.current,- pi: thread.pi ?? stored.find((t) => t.id === thread.id)?.pi,- };- seenThreadAt.current = merged.updatedAt;- writeThreads(projectId, [merged, ...stored.filter((t) => t.id !== thread.id)]);- // Cloud projects mirror the thread server-side (debounced while it streams).- queueCloudThreadSave(projectId, slimForStorage([merged])[0]);- }, [projectId]);- useEffect(() => {- if (messages.length === 0) return;- if (receivedThread.current) { receivedThread.current = false; return; }- const firstUser = messages.find((m) => m.role === "user");- const title = (firstUser ? messageText(firstUser) : "").slice(0, 80) || "New chat";- pendingThread.current = {- id: threadId,- title,- updatedAt: Date.now(),- messages: recoverSceneCall(messages, threadId, useEditor.getState().genvideo),- sessions: { ...providerSessions.current },- pi: readPiSession(threadId),- };- if (saveTimer.current === null) {- saveTimer.current = window.setTimeout(() => {- saveTimer.current = null;- saveThreadNow();- }, THREAD_SAVE_MS);- }- }, [messages, threadId, projectId, saveThreadNow]);-- // Land the final transcript locally and on the server as soon as the turn- // settles instead of waiting out the save throttle.- useEffect(() => {- if (busy) return;- saveThreadNow();- flushCloudThreadSaves();- }, [busy, saveThreadNow]);-- // A thread switch unmounts this session mid-throttle; the page going away- // skips unmounts entirely. Both flush the parked snapshot.- useEffect(() => {- const onPageHide = () => {- saveThreadNow();- flushCloudThreadSaves(true);- };- window.addEventListener("pagehide", onPageHide);- return () => {- window.removeEventListener("pagehide", onPageHide);- saveThreadNow();- flushCloudThreadSaves();- };- }, [saveThreadNow]);-// Stay glued to the newest message while the user sits at the bottom;// scrolling up releases the glue until they return. The ResizeObserver// catches growth the messages effect misses — streamed text reflowing and@@ -1903,6 +1951,39 @@ function ChatSession({dispatchChat(() => sendMessage({ text: resumePrompt(ask), metadata }));}, [status, busy, requests, dispatchChat, readOnly, projectLoaded, currentAvailable, model, signedIn, info, reconnect, resumeOwed, resumeStream, setMessages, sendMessage, projectId, threadId]);+ // A thread that ended but whose saved copy falls short of the engine's+ // journal of that turn — the page lost renders or saves while it ran, or+ // the copy predates journal marks — replays the journal to catch up. The+ // engine is asked when the thread opens and whenever the tab comes back+ // into view; an unfinished turn takes the reconnect above instead, which+ // replays the same journal.+ const [journal, setJournal] = useState<(JournalMark & { running: boolean }) | null>(null);+ const engineThread = provider(model) !== "gemini" && !!info && !readOnly;+ useEffect(() => {+ if (!engineThread) return;+ let alive = true;+ const peek = () => {+ if (document.hidden) return;+ void peekEngineChat(projectId, threadId).then((found) => {+ if (alive) setJournal(found);+ });+ };+ peek();+ document.addEventListener("visibilitychange", peek);+ return () => {+ alive = false;+ document.removeEventListener("visibilitychange", peek);+ };+ }, [engineThread, projectId, threadId]);+ useEffect(() => {+ if (!journal || status !== "ready" || busy || requests.snapshot() || !projectLoaded || resumeOwed()) return;+ // eslint-disable-next-line react-hooks/set-state-in-effect -- the peek answered once; clearing it gates the catch-up to one replay+ setJournal(null);+ if (!journalAhead(messages, journalMark.current, journal)) return;+ catchingUp.current = journal.running ? "running" : "finished";+ dispatchChat(() => resumeStream());+ }, [journal, status, busy, requests, projectLoaded, resumeOwed, messages, dispatchChat, resumeStream]);+// Drain the queue as turns settle. drainedRef keeps it to one dispatch per// ready period — the effect re-runs when the queue changes before useChat// surfaces the new turn's status. A dispatched row stays in the queue asdiff --git a/site/src/cut/lib/chatReplay.test.ts b/site/src/cut/lib/chatReplay.test.tsindex 5ccfdf27..5a8e33a2 100644--- a/site/src/cut/lib/chatReplay.test.ts+++ b/site/src/cut/lib/chatReplay.test.ts@@ -1,6 +1,8 @@import { expect, test } from "bun:test";-import type { UIMessageChunk } from "ai";-import { replayChatStream } from "./chatReplay";+import { Chat } from "@ai-sdk/react";+import type { UIMessage, UIMessageChunk } from "ai";+import { countChunks, replayChatStream } from "./chatReplay";+import { journalAhead, type JournalMark } from "./chatResume";test("replay identifies the saved reply before exposing any chunks", async () => {let prepared = false;@@ -74,3 +76,72 @@ test("a new reply resumes after the previous reply was completed", async () => {expect(replay).not.toBe(null);await replay!.cancel();});++test("a stream's chunks are counted under its turn", async () => {+ const marks: { messageId: string; chunks: number }[] = [];+ const source = new ReadableStream<UIMessageChunk>({ start(controller) {+ controller.enqueue({ type: "start", messageId: "turn-1" });+ controller.enqueue({ type: "text-start", id: "t" });+ controller.enqueue({ type: "finish" });+ controller.close();+ } });+ const reader = countChunks(source, (mark) => marks.push(mark)).getReader();+ while (!(await reader.read()).done);+ expect(marks.at(-1)).toEqual({ messageId: "turn-1", chunks: 3 });+});++// The engine kept the whole turn in its journal while the page's saved copy+// stopped at call 71 and was stamped complete. Opening the thread replays the+// journal over that copy, and the thread then counts the whole journal.+test("a completed thread saved short of its journal catches up by replaying it", async () => {+ const journal: UIMessageChunk[] = [+ { type: "start", messageId: "turn-1", messageMetadata: { requestMessageId: "ask" } },+ ...Array.from({ length: 296 }, (_, i): UIMessageChunk[] => [+ { type: "tool-input-available", toolCallId: `call-${i}`, toolName: "add_title", input: { text: `CLIP ${i}` } },+ { type: "tool-output-available", toolCallId: `call-${i}`, output: { id: `title-${i}` } },+ ]).flat(),+ { type: "text-start", id: "t" },+ { type: "text-delta", id: "t", delta: "FINAL: every title is in." },+ { type: "text-end", id: "t" },+ { type: "finish" },+ ];+ const saved: UIMessage[] = [+ { id: "ask", role: "user", parts: [{ type: "text", text: "build the titles" }] },+ { id: "turn-1", role: "assistant", parts: journal.slice(1, 143).flatMap((chunk) => chunk.type === "tool-output-available"+ ? [{ type: "tool-add_title", toolCallId: chunk.toolCallId, state: "output-available", input: {}, output: chunk.output } as unknown as UIMessage["parts"][number]]+ : []) },+ ];+ expect(saved[1].parts).toHaveLength(71);+ const peeked = { messageId: "turn-1", chunks: journal.length };+ expect(journalAhead(saved, undefined, peeked)).toBe(true);+ let mark: JournalMark | null = null;+ let toolCalls = 0;+ const chat = new Chat<UIMessage>({+ id: "thread",+ messages: saved,+ // The replay hands every call to onToolCall again; the panel lets them+ // pass, since a finished turn's tools already ran.+ onToolCall: () => { toolCalls++; },+ transport: {+ sendMessages: async () => { throw new Error("A catch-up sends nothing."); },+ reconnectToStream: async () => {+ const source = new ReadableStream<UIMessageChunk>({ start(controller) {+ for (const chunk of journal) controller.enqueue(chunk);+ controller.close();+ } });+ const replay = await replayChatStream(source, (id) => {+ chat.messages = chat.messages.map((m) => m.id === id ? { ...m, parts: [] } : m);+ return true;+ }, () => {});+ return replay && countChunks(replay, (next) => { mark = next; });+ },+ },+ });+ await chat.resumeStream();+ const reply = chat.messages.at(-1)!;+ expect(chat.messages.map((m) => m.id)).toEqual(["ask", "turn-1"]);+ expect(reply.parts.filter((p) => p.type.startsWith("tool-"))).toHaveLength(296);+ expect(reply.parts.at(-1)).toMatchObject({ type: "text", text: "FINAL: every title is in." });+ expect(toolCalls).toBe(296);+ expect(journalAhead(chat.messages, mark ?? undefined, peeked)).toBe(false);+});diff --git a/site/src/cut/lib/chatReplay.ts b/site/src/cut/lib/chatReplay.tsindex 6c72d0c0..54579acd 100644--- a/site/src/cut/lib/chatReplay.ts+++ b/site/src/cut/lib/chatReplay.ts@@ -1,4 +1,19 @@import type { UIMessageChunk } from "ai";+import type { JournalMark } from "./chatResume";++/** Count the chunks an engine turn's stream hands the chat. The engine's+ * journal counts the same chunks, so a finished turn's count is the mark its+ * saved thread keeps (see journalAhead). */+export function countChunks(source: ReadableStream<UIMessageChunk>, count: (mark: JournalMark) => void): ReadableStream<UIMessageChunk> {+ let mark: JournalMark | null = null;+ return source.pipeThrough(new TransformStream<UIMessageChunk, UIMessageChunk>({+ transform(chunk, controller) {+ if (chunk.type === "start" && chunk.messageId) mark = { messageId: chunk.messageId, chunks: 0 };+ if (mark) count(mark = { ...mark, chunks: mark.chunks + 1 });+ controller.enqueue(chunk);+ },+ }));+}/** Read the journal identity before the SDK snapshots its current assistant message. */export async function replayChatStream(diff --git a/site/src/cut/lib/chatResume.test.ts b/site/src/cut/lib/chatResume.test.tsindex 80ce8ea0..35df0334 100644--- a/site/src/cut/lib/chatResume.test.ts+++ b/site/src/cut/lib/chatResume.test.ts@@ -1,6 +1,6 @@import { expect, test } from "bun:test";import type { UIMessage } from "ai";-import { DETACHED_MEDIA_ERROR, DETACHED_UI_NOTE, INTERRUPTED_ERROR, isResumeMessage, pendingAsk, resumePrompt, scrubLostTurn, unfinishedAsk } from "./chatResume";+import { DETACHED_MEDIA_ERROR, DETACHED_UI_NOTE, INTERRUPTED_ERROR, isResumeMessage, journalAhead, pendingAsk, resumePrompt, scrubLostTurn, unfinishedAsk } from "./chatResume";const user = (id: string, text: string, metadata?: Record<string, unknown>): UIMessage =>({ id, role: "user", parts: [{ type: "text", text }], ...(metadata ? { metadata } : {}) }) as UIMessage;@@ -79,3 +79,17 @@ test("a continuation stands alone, since it quotes its ask", () => {const messages = [user("a", "cut the pauses"), user("b", resumePrompt(user("a", "cut the pauses")), { resume: true })];expect(pendingAsk(messages).text).toBe(resumePrompt(user("a", "cut the pauses")));});++test("a thread saved short of its newest turn's journal catches up from it", () => {+ const messages = [user("ask", "build the titles"), reply("turn-1")];+ const journal = { messageId: "turn-1", chunks: 900 };+ // Saved from fewer chunks than the engine wrote, or before marks were kept.+ expect(journalAhead(messages, { messageId: "turn-1", chunks: 240 }, journal)).toBe(true);+ expect(journalAhead(messages, undefined, journal)).toBe(true);+ expect(journalAhead(messages, { messageId: "turn-0", chunks: 2000 }, journal)).toBe(true);+ // A whole copy, a journal of another turn, a thread that moved on, or no journal.+ expect(journalAhead(messages, { messageId: "turn-1", chunks: 900 }, journal)).toBe(false);+ expect(journalAhead(messages, undefined, { messageId: "turn-0", chunks: 900 })).toBe(false);+ expect(journalAhead([...messages, user("next", "now the music")], undefined, journal)).toBe(false);+ expect(journalAhead(messages, undefined, null)).toBe(false);+});diff --git a/site/src/cut/lib/chatResume.ts b/site/src/cut/lib/chatResume.tsindex 3ecef477..380ffc8f 100644--- a/site/src/cut/lib/chatResume.ts+++ b/site/src/cut/lib/chatResume.ts@@ -97,6 +97,21 @@ export function unfinishedAsk(return ask;}+/** How much of an engine turn's journal a record was built from: the turn's+ * reply and the chunks read for it. A thread keeps the mark of the turn it+ * last saw end, and the engine answers a peek with its own. */+export type JournalMark = { messageId: string; chunks: number };++/** Whether the engine's journal holds more of the thread's newest reply than+ * the saved thread does: a page that lost renders or saves while the turn ran+ * (or one saved before marks were kept) has a shorter copy, and replays the+ * journal to catch up. A thread that has moved on past that reply, or whose+ * mark already covers the journal, is left alone. */+export function journalAhead(messages: UIMessage[], held: JournalMark | undefined, journal: JournalMark | null | undefined): boolean {+ if (!journal || messages.at(-1)?.id !== journal.messageId) return false;+ return held?.messageId !== journal.messageId || held.chunks < journal.chunks;+}+/** The continuation a resumed turn opens with. It carries the ask itself, so* a provider session that never received it still knows the job. */export function resumePrompt(ask: UIMessage): string {diff --git a/site/src/cut/lib/chatThreads.test.ts b/site/src/cut/lib/chatThreads.test.tsindex bd750e28..59b3b49a 100644--- a/site/src/cut/lib/chatThreads.test.ts+++ b/site/src/cut/lib/chatThreads.test.ts@@ -1,4 +1,6 @@import { beforeEach, describe, expect, test } from "bun:test";+import { Chat } from "@ai-sdk/react";+import type { ChatTransport, UIMessage, UIMessageChunk } from "ai";import {chatThreadDeleted,@@ -7,8 +9,10 @@ import {mergeThreads,readProjectThreads,readThreadIds,+ recordThread,threadsKey,writeProjectThreads,+ writeRawThreads,} from "./chatThreads";// Bun's test runtime has no localStorage; the module reads it per call.@@ -71,3 +75,81 @@ test("a deleted thread stays deleted after a late completion or stale remote savexpect(readThreadIds("p").has("a")).toBe(false);expect(mergeThreads([{ id: "a", deleted: true }], [{ id: "a", updatedAt: 999 }])[0].deleted).toBe(true);});++// A screen-locked, minimised, or background tab paints nothing: no animation+// frame fires and React may commit nothing for minutes, while the stream and+// the tools keep running. The stored thread has to follow the chat itself.+describe("a running thread's record", () => {+ const chunks = (calls: number): UIMessageChunk[] => [+ { type: "start", messageId: "turn-1" },+ { type: "text-start", id: "t1" },+ { type: "text-delta", id: "t1", delta: "Building it." },+ { type: "text-end", id: "t1" },+ ...Array.from({ length: calls }, (_, i): UIMessageChunk[] => [+ { type: "tool-input-available", toolCallId: `call-${i}`, toolName: "add_title", input: { text: `CLIP ${i}` } },+ { type: "tool-output-available", toolCallId: `call-${i}`, output: { id: `title-${i}` } },+ ]).flat(),+ { type: "text-start", id: "t2" },+ { type: "text-delta", id: "t2", delta: "FINAL: every title is in." },+ { type: "text-end", id: "t2" },+ { type: "finish" },+ ];+ const stored = () => (readProjectThreads("p")[0] as { messages?: UIMessage[] } | undefined)?.messages ?? [];+ const tools = (messages: UIMessage[]) => messages.at(-1)?.parts.filter((p) => p.type.startsWith("tool-")) ?? [];++ test("keeps saving every part while the page cannot paint", async () => {+ const page = globalThis as unknown as Record<string, unknown>;+ const previous = { raf: page.requestAnimationFrame, document: page.document };+ page.requestAnimationFrame = () => 0;+ page.document = { hidden: true, visibilityState: "hidden" };+ try {+ const all = chunks(296);+ let sent = 0;+ let release = () => {};+ const transport: ChatTransport<UIMessage> = {+ sendMessages: async () => new ReadableStream<UIMessageChunk>({+ async pull(controller) {+ // The turn pauses partway, as a long tool would, for the+ // record to be read mid-turn.+ if (sent === 150) await new Promise<void>((resolve) => { release = resolve; });+ else await new Promise((resolve) => setTimeout(resolve, 0));+ if (sent < all.length) controller.enqueue(all[sent++]);+ else controller.close();+ },+ }),+ reconnectToStream: async () => null,+ };+ // Nothing renders this chat: no component, no effect, no frame.+ const chat = new Chat<UIMessage>({ id: "t", transport });+ const recorder = recordThread(chat, (messages) => writeRawThreads("p", [{ id: "t", updatedAt: Date.now(), messages }]), 5);+ const turn = chat.sendMessage({ text: "build the titles" });+ while (sent < 150) await new Promise((resolve) => setTimeout(resolve, 1));+ await new Promise((resolve) => setTimeout(resolve, 20));+ expect(tools(stored()).length).toBeGreaterThan(60);+ release();+ await turn;+ await new Promise((resolve) => setTimeout(resolve, 20));+ const final = stored();+ expect(tools(final)).toHaveLength(296);+ expect(tools(final).every((p) => (p as { state?: string }).state === "output-available")).toBe(true);+ expect(final.at(-1)?.parts.at(-1)).toMatchObject({ type: "text", text: "FINAL: every title is in." });+ recorder.stop();+ } finally {+ page.requestAnimationFrame = previous.raf;+ page.document = previous.document;+ }+ });++ test("a thread read back from storage is not saved back over it", async () => {+ const chat = new Chat<UIMessage>({ id: "t", transport: { sendMessages: async () => new ReadableStream(), reconnectToStream: async () => null } });+ let saves = 0;+ const recorder = recordThread(chat, () => { saves++; }, 1);+ recorder.quietly(() => { chat.messages = [{ id: "a", role: "user", parts: [{ type: "text", text: "from another tab" }] }]; });+ await new Promise((resolve) => setTimeout(resolve, 10));+ expect(saves).toBe(0);+ chat.messages = [...chat.messages, { id: "b", role: "user", parts: [{ type: "text", text: "typed here" }] }];+ recorder.flush();+ expect(saves).toBe(1);+ recorder.stop();+ });+});diff --git a/site/src/cut/lib/chatThreads.ts b/site/src/cut/lib/chatThreads.tsindex 8d5795a2..40e41f0d 100644--- a/site/src/cut/lib/chatThreads.ts+++ b/site/src/cut/lib/chatThreads.ts@@ -145,3 +145,54 @@ export function deleteStoredThread(projectId: string, threadId: string): void {const threads = readProjectThreads(projectId).filter((t) => t.id !== threadId);writeProjectThreads(projectId, [{ id: threadId, updatedAt: Date.now(), deleted: true }, ...threads]);}++/** The live state of one chat as the AI SDK's Chat holds it: its messages and+ * the change callback its own React hook subscribes through. */+export interface ChatSource<M> {+ readonly messages: M[];+ "~registerMessagesCallback": (onChange: () => void) => () => void;+}++export interface ThreadRecorder {+ /** Save now if a change is waiting. */+ flush: () => void;+ /** Apply a change that came from storage without saving it back. */+ quietly: (apply: () => void) => void;+ /** Stop following, saving whatever is still waiting. */+ stop: () => void;+}++/** Keep a thread's stored copy following its chat. Saves hang off the chat's+ * own state rather than the panel's renders: a tab that cannot paint (the+ * screen locked, the window minimised, the tab behind another) may commit no+ * render for minutes while its stream and tools keep running, and every part+ * that arrives meanwhile still lands. A change arms one save, which reads the+ * chat as it stands when it fires, so a save never writes an older copy than+ * the chat holds. */+export function recordThread<M>(chat: ChatSource<M>, save: (messages: M[]) => void, waitMs: number): ThreadRecorder {+ let timer: ReturnType<typeof setTimeout> | null = null;+ let quiet = false;+ const land = () => {+ timer = null;+ save(chat.messages);+ };+ const unsubscribe = chat["~registerMessagesCallback"](() => {+ if (!quiet && timer === null) timer = setTimeout(land, waitMs);+ });+ const flush = () => {+ if (timer === null) return;+ clearTimeout(timer);+ land();+ };+ return {+ flush,+ quietly: (apply) => {+ quiet = true;+ try { apply(); } finally { quiet = false; }+ },+ stop: () => {+ unsubscribe();+ flush();+ },+ };+}diff --git a/site/src/cut/lib/engineChat.test.ts b/site/src/cut/lib/engineChat.test.tsindex 1fd06717..bed9ef7f 100644--- a/site/src/cut/lib/engineChat.test.ts+++ b/site/src/cut/lib/engineChat.test.ts@@ -1,7 +1,7 @@import { afterEach, expect, spyOn, test } from "bun:test";import type { UIMessage } from "ai";import { localBackend } from "@/cut/lib/backend/local";-import { joinRunningEngineChat } from "@/cut/lib/engineChat";+import { joinRunningEngineChat, peekEngineChat } from "@/cut/lib/engineChat";let cleanup = () => {};afterEach(() => cleanup());@@ -32,3 +32,25 @@ test("a turn that ended before the fold leaves the message to go out as its own"expect(await joinRunningEngineChat("project", "thread", { messages: [user("a", "fix the tilt")], context: {} })).toBeNull();expect(calls).toHaveLength(1);});++test("a peek reads how far the thread's journal reaches", async () => {+ const paths: string[] = [];+ const spy = spyOn(localBackend, "fetch").mockImplementation(async (path) => {+ paths.push(path);+ return Response.json({ journal: { messageId: "turn-1", chunks: 900, running: false } });+ });+ cleanup = () => spy.mockRestore();+ expect(await peekEngineChat("project", "thread")).toEqual({ messageId: "turn-1", chunks: 900, running: false });+ expect(paths).toEqual(["/api/cut/ai/chat/thread/stream?projectId=project&peek=1"]);+});++test("a thread with no journal, or an engine that predates peeking, reads as none", async () => {+ let answer = () => Response.json({ journal: null });+ const spy = spyOn(localBackend, "fetch").mockImplementation(async () => answer());+ cleanup = () => spy.mockRestore();+ expect(await peekEngineChat("project", "thread")).toBeNull();+ let cancelled = false;+ answer = () => new Response(new ReadableStream({ cancel() { cancelled = true; } }), { headers: { "Content-Type": "text/event-stream" } });+ expect(await peekEngineChat("project", "thread")).toBeNull();+ expect(cancelled).toBe(true);+});diff --git a/site/src/cut/lib/engineChat.ts b/site/src/cut/lib/engineChat.tsindex fddde07d..85015f3e 100644--- a/site/src/cut/lib/engineChat.ts+++ b/site/src/cut/lib/engineChat.ts@@ -1,6 +1,6 @@import type { UIMessage } from "ai";import { localBackend } from "./backend/local";-import { pendingAsk } from "./chatResume";+import { pendingAsk, type JournalMark } from "./chatResume";export async function claimEngineTool(sessionKey: string | null, toolCallId: string): Promise<boolean> {const response = await localBackend.fetch("/api/cut/ai/tool-claim", {@@ -52,6 +52,23 @@ export async function joinRunningEngineChat(return response.ok && response.status !== 204 ? response : null;}+/** How far the engine's journal of the thread's newest turn reaches, and+ * whether that turn still runs. Null when the engine keeps no journal for the+ * thread, cannot be reached, or predates peeking (it answers with the stream+ * itself, which is left unread). */+export async function peekEngineChat(projectId: string, threadId: string): Promise<(JournalMark & { running: boolean }) | null> {+ const response = await localBackend.fetch(+ `/api/cut/ai/chat/${encodeURIComponent(threadId)}/stream?projectId=${encodeURIComponent(projectId)}&peek=1`,+ ).catch(() => null);+ if (!response?.ok || !response.headers.get("Content-Type")?.includes("application/json")) {+ void response?.body?.cancel().catch(() => {});+ return null;+ }+ const { journal } = await response.json().catch(() => ({})) as { journal?: { messageId?: unknown; chunks?: unknown; running?: unknown } | null };+ if (typeof journal?.messageId !== "string" || typeof journal.chunks !== "number") return null;+ return { messageId: journal.messageId, chunks: journal.chunks, running: journal.running === true };+}+/** Answer the engine's quality gate for a signing-off turn: the steer for its* next pass, or null to let it close. A gate the engine no longer holds is* dropped. */diff --git a/site/src/cut/server/ai/turnStreams.test.ts b/site/src/cut/server/ai/turnStreams.test.tsindex a032cf47..2ac9714c 100644--- a/site/src/cut/server/ai/turnStreams.test.ts+++ b/site/src/cut/server/ai/turnStreams.test.ts@@ -3,7 +3,7 @@ import { mkdtemp, rm } from "node:fs/promises";import os from "node:os";import path from "node:path";import type { UIMessageChunk } from "ai";-import { cancelTurnStream, followTurnStream, startTurnStream } from "./turnStreams";+import { cancelTurnStream, followTurnStream, peekTurnStream, startTurnStream } from "./turnStreams";import { askPageGate, callBrowserTool, claimBrowserTool, detachSession, registerSession, resolveBrowserTool, resolvePageGate, unregisterSession } from "./bridge";import { createProject, readProject } from "../projects";@@ -36,6 +36,24 @@ test("the engine completes with no readers and replays the finished journal", asexpect(await replay.text()).toContain("Finished after closing the tab.");});+test("a peek reports how far the journal reaches while the turn runs and after", async () => {+ expect(await peekTurnStream("project", "never")).toBeNull();+ let output!: ReadableStreamDefaultController<UIMessageChunk>;+ const response = await startTurnStream("project", "peek", () => new ReadableStream({ start(controller) {+ output = controller;+ controller.enqueue({ type: "start", messageId: "turn-peek" });+ controller.enqueue({ type: "tool-input-available", toolCallId: "a", toolName: "add_title", input: {} });+ } }), () => {}, () => {});+ await response.body!.cancel();+ await new Promise((resolve) => setTimeout(resolve, 20));+ expect(await peekTurnStream("project", "peek")).toEqual({ messageId: "turn-peek", chunks: 2, running: true });+ output.enqueue({ type: "tool-output-available", toolCallId: "a", output: {} });+ output.enqueue({ type: "finish" });+ output.close();+ await new Promise((resolve) => setTimeout(resolve, 20));+ expect(await peekTurnStream("project", "peek")).toEqual({ messageId: "turn-peek", chunks: 4, running: false });+});+test("Stop cancels the run explicitly", async () => {let signal!: AbortSignal;const response = await startTurnStream("project", "stop", (abort) => {diff --git a/site/src/cut/server/ai/turnStreams.ts b/site/src/cut/server/ai/turnStreams.tsindex 026927c9..9c7b558b 100644--- a/site/src/cut/server/ai/turnStreams.ts+++ b/site/src/cut/server/ai/turnStreams.ts@@ -1,5 +1,5 @@import { chatRuntime } from "../../lib/chatRuntime";-import { mkdir, open, stat } from "node:fs/promises";+import { mkdir, open, readFile, stat } from "node:fs/promises";import { createHash } from "node:crypto";import path from "node:path";import type { UIMessageChunk } from "ai";@@ -125,6 +125,22 @@ export async function followTurnStream(projectId: string, threadId: string, sign} });}+/** How much of a thread's newest turn its journal holds, without following+ * it: the turn's message, the chunks written so far, and whether it still+ * runs. A page compares the chunks with the ones its saved thread was built+ * from, and replays the journal when its copy fell behind. Null when the+ * thread has no journal. */+export async function peekTurnStream(projectId: string, threadId: string): Promise<{ messageId: string; chunks: number; running: boolean } | null> {+ const key = keyFor(projectId, threadId);+ const text = await readFile(fileFor(key), "utf8").catch(() => null);+ const chunks = text?.split("\n").filter((line) => line.startsWith("data: {")) ?? [];+ if (chunks.length === 0) return null;+ let start: { type?: unknown; messageId?: unknown };+ try { start = JSON.parse(chunks[0].slice("data: ".length)) as typeof start; } catch { return null; }+ if (start.type !== "start" || typeof start.messageId !== "string") return null;+ return { messageId: start.messageId, chunks: chunks.length, running: running.has(key) };+}+export function cancelTurnStream(projectId: string, threadId: string): void {running.get(keyFor(projectId, threadId))?.abort.abort();}diff --git a/site/src/cut/server/http/ai.ts b/site/src/cut/server/http/ai.tsindex 54d232d6..6f7849b2 100644--- a/site/src/cut/server/http/ai.ts+++ b/site/src/cut/server/http/ai.ts@@ -2,7 +2,7 @@ import { spawn, execFile } from "node:child_process";import os from "node:os";import { z } from "zod";import { SETTINGS } from "@/lib/config/registry";-import { startTurnStream, followTurnStream, cancelTurnStream } from "../ai/turnStreams";+import { startTurnStream, followTurnStream, cancelTurnStream, peekTurnStream } from "../ai/turnStreams";import { foldIntoTurn, openFoldInbox, type Fold, type FoldInbox } from "../ai/turnFolds";import path from "node:path";import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";@@ -646,6 +646,8 @@ export const aiApi = {async resumeChat(req: Request, threadId: string) {const projectId = new URL(req.url).searchParams.get("projectId");if (!projectId) return Response.json({ error: "A project is required." }, { status: 400 });+ // A peek reports how far the journal reaches instead of following it.+ if (new URL(req.url).searchParams.has("peek")) return Response.json({ journal: await peekTurnStream(projectId, threadId) });return followTurnStream(projectId, threadId, req.signal);},