Skip to content

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.tsx
index 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 as
diff --git a/site/src/cut/lib/chatReplay.test.ts b/site/src/cut/lib/chatReplay.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 sav
expect(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.ts
index 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.ts
index 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.ts
index 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.ts
index 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", as
expect(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.ts
index 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.ts
index 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);
},