Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

Add provider checkpoints and thread rollback support

Julius Marminge351736baa119
diff --git a/apps/server/src/codexAppServerManager.test.ts b/apps/server/src/codexAppServerManager.test.ts
index 4a97814a7..e1ce2fcd1 100644
--- a/apps/server/src/codexAppServerManager.test.ts
+++ b/apps/server/src/codexAppServerManager.test.ts
@@ -43,6 +43,36 @@ function createSendTurnHarness() {
return { manager, context, requireSession, sendRequest, updateSession };
}
+function createThreadControlHarness() {
+ const manager = new CodexAppServerManager();
+ const context = {
+ session: {
+ sessionId: "sess_1",
+ provider: "codex",
+ status: "ready",
+ threadId: "thread_1",
+ createdAt: "2026-02-10T00:00:00.000Z",
+ updatedAt: "2026-02-10T00:00:00.000Z",
+ },
+ };
+
+ const requireSession = vi
+ .spyOn(
+ manager as unknown as { requireSession: (sessionId: string) => unknown },
+ "requireSession",
+ )
+ .mockReturnValue(context);
+ const sendRequest = vi.spyOn(
+ manager as unknown as { sendRequest: (...args: unknown[]) => Promise<unknown> },
+ "sendRequest",
+ );
+ const updateSession = vi
+ .spyOn(manager as unknown as { updateSession: (...args: unknown[]) => void }, "updateSession")
+ .mockImplementation(() => {});
+
+ return { manager, context, requireSession, sendRequest, updateSession };
+}
+
describe("classifyCodexStderrLine", () => {
it("ignores empty lines", () => {
expect(classifyCodexStderrLine(" ")).toBeNull();
@@ -198,3 +228,62 @@ describe("sendTurn", () => {
).rejects.toThrow("Turn input must include text or attachments.");
});
});
+
+describe("thread checkpoint control", () => {
+ it("reads thread turns from thread/read", async () => {
+ const { manager, context, requireSession, sendRequest } = createThreadControlHarness();
+ sendRequest.mockResolvedValue({
+ thread: {
+ id: "thread_1",
+ turns: [
+ {
+ id: "turn_1",
+ items: [{ type: "userMessage", content: [{ type: "text", text: "hello" }] }],
+ },
+ ],
+ },
+ });
+
+ const result = await manager.readThread("sess_1");
+
+ expect(requireSession).toHaveBeenCalledWith("sess_1");
+ expect(sendRequest).toHaveBeenCalledWith(context, "thread/read", {
+ threadId: "thread_1",
+ includeTurns: true,
+ });
+ expect(result).toEqual({
+ threadId: "thread_1",
+ turns: [
+ {
+ id: "turn_1",
+ items: [{ type: "userMessage", content: [{ type: "text", text: "hello" }] }],
+ },
+ ],
+ });
+ });
+
+ it("rolls back turns via thread/rollback and resets session running state", async () => {
+ const { manager, context, sendRequest, updateSession } = createThreadControlHarness();
+ sendRequest.mockResolvedValue({
+ thread: {
+ id: "thread_1",
+ turns: [],
+ },
+ });
+
+ const result = await manager.rollbackThread("sess_1", 2);
+
+ expect(sendRequest).toHaveBeenCalledWith(context, "thread/rollback", {
+ threadId: "thread_1",
+ numTurns: 2,
+ });
+ expect(updateSession).toHaveBeenCalledWith(context, {
+ status: "ready",
+ activeTurnId: undefined,
+ });
+ expect(result).toEqual({
+ threadId: "thread_1",
+ turns: [],
+ });
+ });
+});
diff --git a/apps/server/src/codexAppServerManager.ts b/apps/server/src/codexAppServerManager.ts
index 27da26fb0..01722a696 100644
--- a/apps/server/src/codexAppServerManager.ts
+++ b/apps/server/src/codexAppServerManager.ts
@@ -65,6 +65,16 @@ interface JsonRpcNotification {
params?: unknown;
}
+export interface CodexThreadTurnSnapshot {
+ id: string;
+ items: unknown[];
+}
+
+export interface CodexThreadSnapshot {
+ threadId: string;
+ turns: CodexThreadTurnSnapshot[];
+}
+
const ANSI_ESCAPE_CHAR = String.fromCharCode(27);
const ANSI_ESCAPE_REGEX = new RegExp(`${ANSI_ESCAPE_CHAR}\\[[0-9;]*m`, "g");
const CODEX_STDERR_LOG_REGEX =
@@ -331,6 +341,41 @@ export class CodexAppServerManager extends EventEmitter<CodexAppServerManagerEve
});
}
+ async readThread(sessionId: string): Promise<CodexThreadSnapshot> {
+ const context = this.requireSession(sessionId);
+ const threadId = context.session.threadId;
+ if (!threadId) {
+ throw new Error("Session is missing a thread id.");
+ }
+
+ const response = await this.sendRequest(context, "thread/read", {
+ threadId,
+ includeTurns: true,
+ });
+ return this.parseThreadSnapshot("thread/read", response);
+ }
+
+ async rollbackThread(sessionId: string, numTurns: number): Promise<CodexThreadSnapshot> {
+ const context = this.requireSession(sessionId);
+ const threadId = context.session.threadId;
+ if (!threadId) {
+ throw new Error("Session is missing a thread id.");
+ }
+ if (!Number.isInteger(numTurns) || numTurns < 1) {
+ throw new Error("numTurns must be an integer >= 1.");
+ }
+
+ const response = await this.sendRequest(context, "thread/rollback", {
+ threadId,
+ numTurns,
+ });
+ this.updateSession(context, {
+ status: "ready",
+ activeTurnId: undefined,
+ });
+ return this.parseThreadSnapshot("thread/rollback", response);
+ }
+
async respondToRequest(
sessionId: string,
requestId: string,
@@ -742,6 +787,31 @@ export class CodexAppServerManager extends EventEmitter<CodexAppServerManagerEve
return undefined;
}
+ private parseThreadSnapshot(method: string, response: unknown): CodexThreadSnapshot {
+ const responseRecord = this.readObject(response);
+ const thread = this.readObject(responseRecord, "thread");
+ const threadId = this.readString(thread, "id") ?? this.readString(responseRecord, "threadId");
+ if (!threadId) {
+ throw new Error(`${method} response did not include a thread id.`);
+ }
+
+ const turnsRaw = this.readArray(thread, "turns") ?? [];
+ const turns = turnsRaw.map((turnValue, index) => {
+ const turn = this.readObject(turnValue);
+ const turnId = this.readString(turn, "id") ?? `${threadId}:turn:${index + 1}`;
+ const items = this.readArray(turn, "items") ?? [];
+ return {
+ id: turnId,
+ items,
+ };
+ });
+
+ return {
+ threadId,
+ turns,
+ };
+ }
+
private isServerRequest(value: unknown): value is JsonRpcRequest {
if (!value || typeof value !== "object") {
return false;
@@ -823,6 +893,16 @@ export class CodexAppServerManager extends EventEmitter<CodexAppServerManagerEve
return target as Record<string, unknown>;
}
+ private readArray(value: unknown, key?: string): unknown[] | undefined {
+ const target =
+ key === undefined
+ ? value
+ : value && typeof value === "object"
+ ? (value as Record<string, unknown>)[key]
+ : undefined;
+ return Array.isArray(target) ? target : undefined;
+ }
+
private readString(value: unknown, key: string): string | undefined {
if (!value || typeof value !== "object") {
return undefined;
diff --git a/apps/server/src/providerManager.test.ts b/apps/server/src/providerManager.test.ts
index 424cfce16..7d7e7ad76 100644
--- a/apps/server/src/providerManager.test.ts
+++ b/apps/server/src/providerManager.test.ts
@@ -59,4 +59,136 @@ describe("ProviderManager", () => {
manager.dispose();
});
+
+ it("rejects checkpoint operations for unknown sessions", async () => {
+ const manager = new ProviderManager();
+
+ await expect(
+ manager.listCheckpoints({
+ sessionId: "missing-session",
+ }),
+ ).rejects.toThrow("Unknown provider session: missing-session");
+
+ await expect(
+ manager.revertToCheckpoint({
+ sessionId: "missing-session",
+ turnCount: 0,
+ }),
+ ).rejects.toThrow("Unknown provider session: missing-session");
+
+ manager.dispose();
+ });
+
+ it("derives checkpoints from thread turns", async () => {
+ const manager = new ProviderManager();
+ const codex = (
+ manager as unknown as {
+ codex: {
+ hasSession: (sessionId: string) => boolean;
+ readThread: (sessionId: string) => Promise<{
+ threadId: string;
+ turns: Array<{ id: string; items: unknown[] }>;
+ }>;
+ };
+ }
+ ).codex;
+
+ codex.hasSession = () => true;
+ codex.readThread = async () => ({
+ threadId: "thr_1",
+ turns: [
+ {
+ id: "turn_1",
+ items: [
+ {
+ type: "userMessage",
+ content: [{ type: "text", text: "Refactor the logger" }],
+ },
+ {
+ type: "agentMessage",
+ text: "I refactored it.",
+ },
+ ],
+ },
+ ],
+ });
+
+ const result = await manager.listCheckpoints({
+ sessionId: "sess_1",
+ });
+
+ expect(result).toEqual({
+ threadId: "thr_1",
+ checkpoints: [
+ {
+ id: "root",
+ turnCount: 0,
+ messageCount: 0,
+ label: "Start of conversation",
+ isCurrent: false,
+ },
+ {
+ id: "turn_1",
+ turnCount: 1,
+ messageCount: 2,
+ label: "Turn 1",
+ preview: "Refactor the logger",
+ isCurrent: true,
+ },
+ ],
+ });
+
+ manager.dispose();
+ });
+
+ it("rolls back from a selected checkpoint turn count", async () => {
+ const manager = new ProviderManager();
+ const codex = (
+ manager as unknown as {
+ codex: {
+ hasSession: (sessionId: string) => boolean;
+ readThread: (sessionId: string) => Promise<{
+ threadId: string;
+ turns: Array<{ id: string; items: unknown[] }>;
+ }>;
+ rollbackThread: (sessionId: string, numTurns: number) => Promise<{
+ threadId: string;
+ turns: Array<{ id: string; items: unknown[] }>;
+ }>;
+ };
+ }
+ ).codex;
+
+ const rollbackCalls: Array<{ sessionId: string; numTurns: number }> = [];
+ codex.hasSession = () => true;
+ codex.readThread = async () => ({
+ threadId: "thr_1",
+ turns: [
+ { id: "turn_1", items: [] },
+ { id: "turn_2", items: [] },
+ { id: "turn_3", items: [] },
+ ],
+ });
+ codex.rollbackThread = async (sessionId, numTurns) => {
+ rollbackCalls.push({ sessionId, numTurns });
+ return {
+ threadId: "thr_1",
+ turns: [{ id: "turn_1", items: [] }],
+ };
+ };
+
+ const result = await manager.revertToCheckpoint({
+ sessionId: "sess_1",
+ turnCount: 1,
+ });
+
+ expect(rollbackCalls).toEqual([{ sessionId: "sess_1", numTurns: 2 }]);
+ expect(result.threadId).toBe("thr_1");
+ expect(result.turnCount).toBe(1);
+ expect(result.messageCount).toBe(0);
+ expect(result.rolledBackTurns).toBe(2);
+ expect(result.checkpoints).toHaveLength(2);
+
+ manager.dispose();
+ });
});
diff --git a/apps/server/src/providerManager.ts b/apps/server/src/providerManager.ts
index 52fb1b648..58977b29b 100644
--- a/apps/server/src/providerManager.ts
+++ b/apps/server/src/providerManager.ts
@@ -3,8 +3,13 @@ import fs from "node:fs";
import path from "node:path";
import {
+ type ProviderCheckpoint,
type ProviderEvent,
type ProviderInterruptTurnInput,
+ type ProviderListCheckpointsInput,
+ type ProviderListCheckpointsResult,
+ type ProviderRevertToCheckpointInput,
+ type ProviderRevertToCheckpointResult,
type ProviderRespondToRequestInput,
type ProviderSendTurnInput,
type ProviderSession,
@@ -12,17 +17,144 @@ import {
type ProviderStopSessionInput,
type ProviderTurnStartResult,
providerInterruptTurnInputSchema,
+ providerListCheckpointsInputSchema,
+ providerRevertToCheckpointInputSchema,
providerRespondToRequestInputSchema,
providerSendTurnInputSchema,
providerSessionStartInputSchema,
providerStopSessionInputSchema,
} from "@t3tools/contracts";
+import type { CodexThreadTurnSnapshot } from "./codexAppServerManager";
import { CodexAppServerManager } from "./codexAppServerManager";
export interface ProviderManagerEvents {
event: [event: ProviderEvent];
}
+function asObject(value: unknown): Record<string, unknown> | undefined {
+ if (!value || typeof value !== "object") {
+ return undefined;
+ }
+ return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | undefined {
+ return typeof value === "string" ? value : undefined;
+}
+
+function asArray(value: unknown): unknown[] {
+ return Array.isArray(value) ? value : [];
+}
+
+function trimToPreview(value: string): string {
+ const normalized = value.replace(/\s+/g, " ").trim();
+ if (normalized.length <= 120) {
+ return normalized;
+ }
+ return `${normalized.slice(0, 117)}...`;
+}
+
+function summarizeUserMessageContent(content: unknown[]): string | undefined {
+ const segments: string[] = [];
+
+ for (const part of content) {
+ const record = asObject(part);
+ const type = asString(record?.type);
+ if (!type) continue;
+
+ if (type === "text") {
+ const text = asString(record?.text);
+ if (text && text.trim().length > 0) {
+ segments.push(text.trim());
+ }
+ continue;
+ }
+
+ if (type === "image") {
+ segments.push("[Image attachment]");
+ continue;
+ }
+
+ if (type === "localImage") {
+ segments.push("[Local image attachment]");
+ continue;
+ }
+ }
+
+ if (segments.length === 0) {
+ return undefined;
+ }
+ return trimToPreview(segments.join(" "));
+}
+
+function summarizeTurn(turn: CodexThreadTurnSnapshot): {
+ messageCountDelta: number;
+ preview?: string;
+} {
+ let messageCountDelta = 0;
+ let preview: string | undefined;
+
+ for (const item of turn.items) {
+ const record = asObject(item);
+ const type = asString(record?.type);
+ if (!type) continue;
+
+ if (type === "userMessage") {
+ messageCountDelta += 1;
+ if (!preview) {
+ const content = asArray(record?.content);
+ preview = summarizeUserMessageContent(content);
+ }
+ continue;
+ }
+
+ if (type === "agentMessage") {
+ messageCountDelta += 1;
+ if (!preview) {
+ const text = asString(record?.text);
+ if (text && text.trim().length > 0) {
+ preview = trimToPreview(text);
+ }
+ }
+ }
+ }
+
+ return {
+ messageCountDelta,
+ ...(preview ? { preview } : {}),
+ };
+}
+
+function buildCheckpoints(turns: CodexThreadTurnSnapshot[]): ProviderCheckpoint[] {
+ const checkpoints: ProviderCheckpoint[] = [];
+ let messageCount = 0;
+ const isEmpty = turns.length === 0;
+ checkpoints.push({
+ id: "root",
+ turnCount: 0,
+ messageCount: 0,
+ label: "Start of conversation",
+ isCurrent: isEmpty,
+ });
+
+ for (let index = 0; index < turns.length; index += 1) {
+ const turn = turns[index];
+ if (!turn) continue;
+ const turnSummary = summarizeTurn(turn);
+ messageCount += turnSummary.messageCountDelta;
+ checkpoints.push({
+ id: turn.id,
+ turnCount: index + 1,
+ messageCount,
+ label: `Turn ${index + 1}`,
+ ...(turnSummary.preview ? { preview: turnSummary.preview } : {}),
+ isCurrent: index === turns.length - 1,
+ });
+ }
+
+ return checkpoints;
+}
+
export class ProviderManager extends EventEmitter<ProviderManagerEvents> {
private readonly codex = new CodexAppServerManager();
private readonly threadLogsDir: string;
@@ -101,6 +233,56 @@ export class ProviderManager extends EventEmitter<ProviderManagerEvents> {
return this.codex.listSessions();
}
+ async listCheckpoints(raw: ProviderListCheckpointsInput): Promise<ProviderListCheckpointsResult> {
+ const input = providerListCheckpointsInputSchema.parse(raw);
+ if (!this.codex.hasSession(input.sessionId)) {
+ throw new Error(`Unknown provider session: ${input.sessionId}`);
+ }
+
+ const snapshot = await this.codex.readThread(input.sessionId);
+ return {
+ threadId: snapshot.threadId,
+ checkpoints: buildCheckpoints(snapshot.turns),
+ };
+ }
+
+ async revertToCheckpoint(
+ raw: ProviderRevertToCheckpointInput,
+ ): Promise<ProviderRevertToCheckpointResult> {
+ const input = providerRevertToCheckpointInputSchema.parse(raw);
+ if (!this.codex.hasSession(input.sessionId)) {
+ throw new Error(`Unknown provider session: ${input.sessionId}`);
+ }
+
+ const beforeSnapshot = await this.codex.readThread(input.sessionId);
+ const currentTurnCount = beforeSnapshot.turns.length;
+ if (input.turnCount > currentTurnCount) {
+ throw new Error(
+ `Checkpoint turn count ${input.turnCount} exceeds current turn count ${currentTurnCount}.`,
+ );
+ }
+
+ const requestedRollbackTurns = currentTurnCount - input.turnCount;
+ const afterSnapshot =
+ requestedRollbackTurns > 0
+ ? await this.codex.rollbackThread(input.sessionId, requestedRollbackTurns)
+ : beforeSnapshot;
+ const checkpoints = buildCheckpoints(afterSnapshot.turns);
+ const currentCheckpoint =
+ checkpoints.find((checkpoint) => checkpoint.isCurrent) ??
+ checkpoints[checkpoints.length - 1] ??
+ checkpoints[0];
+ const rolledBackTurns = Math.max(0, currentTurnCount - afterSnapshot.turns.length);
+
+ return {
+ threadId: afterSnapshot.threadId,
+ turnCount: currentCheckpoint?.turnCount ?? 0,
+ messageCount: currentCheckpoint?.messageCount ?? 0,
+ rolledBackTurns,
+ checkpoints,
+ };
+ }
+
stopAll(): void {
this.codex.stopAll();
}
diff --git a/apps/server/src/wsServer.test.ts b/apps/server/src/wsServer.test.ts
index 635bfbb81..a860c5d8a 100644
--- a/apps/server/src/wsServer.test.ts
+++ b/apps/server/src/wsServer.test.ts
@@ -646,6 +646,30 @@ describe("WebSocket Server", () => {
expect(response.result).toEqual([]);
});
+ it("returns unknown-session errors for checkpoint RPCs without an active provider session", async () => {
+ server = createTestServer({ cwd: "/test" });
+ await server.start();
+ const addr = server.httpServer.address();
+ const port = typeof addr === "object" && addr !== null ? addr.port : 0;
+
+ const ws = await connectWs(port);
+ connections.push(ws);
+ await waitForMessage(ws);
+
+ const listResponse = await sendRequest(ws, WS_METHODS.providersListCheckpoints, {
+ sessionId: "missing-session",
+ });
+ expect(listResponse.result).toBeUndefined();
+ expect(listResponse.error?.message).toContain("Unknown provider session");
+
+ const revertResponse = await sendRequest(ws, WS_METHODS.providersRevertToCheckpoint, {
+ sessionId: "missing-session",
+ turnCount: 0,
+ });
+ expect(revertResponse.result).toBeUndefined();
+ expect(revertResponse.error?.message).toContain("Unknown provider session");
+ });
+
it("routes terminal RPC methods and broadcasts terminal events", async () => {
const cwd = makeTempDir("t3code-ws-terminal-cwd-");
const terminalManager = new MockTerminalManager();
diff --git a/apps/server/src/wsServer.ts b/apps/server/src/wsServer.ts
index ce9878cd4..ec0d73d59 100644
--- a/apps/server/src/wsServer.ts
+++ b/apps/server/src/wsServer.ts
@@ -310,6 +310,12 @@ export function createServer(options: ServerOptions) {
case WS_METHODS.providersListSessions:
return providerManager.listSessions();
+ case WS_METHODS.providersListCheckpoints:
+ return providerManager.listCheckpoints(request.params as never);
+
+ case WS_METHODS.providersRevertToCheckpoint:
+ return providerManager.revertToCheckpoint(request.params as never);
+
case WS_METHODS.projectsList:
return projectRegistry.list();
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 27904e29e..2fdccc071 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -8,6 +8,7 @@ import {
PROVIDER_SEND_TURN_MAX_INPUT_CHARS,
PROVIDER_SEND_TURN_MAX_ATTACHMENTS,
PROVIDER_SEND_TURN_MAX_IMAGE_BYTES,
+ type ProviderCheckpoint,
type ResolvedKeybindingsConfig,
type ProviderApprovalDecision,
type ProviderSendTurnAttachmentInput,
@@ -345,6 +346,9 @@ export default function ChatView() {
const [expandedImage, setExpandedImage] = useState<ExpandedImagePreview | null>(null);
const [isSending, setIsSending] = useState(false);
const [isConnecting, setIsConnecting] = useState(false);
+ const [isLoadingCheckpoints, setIsLoadingCheckpoints] = useState(false);
+ const [isRevertingCheckpoint, setIsRevertingCheckpoint] = useState(false);
+ const [checkpoints, setCheckpoints] = useState<ProviderCheckpoint[]>([]);
const [selectedEffort, setSelectedEffort] = useState(DEFAULT_REASONING);
const [envMode, setEnvMode] = useState<"local" | "worktree">("local");
const [isSwitchingRuntimeMode, setIsSwitchingRuntimeMode] = useState(false);
@@ -374,7 +378,7 @@ export default function ChatView() {
activeThread?.model ?? activeProject?.model ?? DEFAULT_MODEL,
);
const phase = derivePhase(activeThread?.session ?? null);
- const isWorking = phase === "running" || isSending || isConnecting;
+ const isWorking = phase === "running" || isSending || isConnecting || isRevertingCheckpoint;
const nowIso = new Date(nowTick).toISOString();
const workLogEntries = useMemo(
() => deriveWorkLogEntries(activeThread?.events ?? [], undefined),
@@ -575,6 +579,12 @@ export default function ChatView() {
);
const hasReachedTerminalLimit =
(activeThread?.terminalIds.length ?? 0) >= MAX_THREAD_TERMINAL_COUNT;
+ const canCheckpoint =
+ Boolean(api && activeThread && (activeThread.codexThreadId ?? activeThread.session?.threadId)) &&
+ phase !== "running" &&
+ !isSending &&
+ !isConnecting &&
+ !isRevertingCheckpoint;
const revokePreviewUrls = useCallback((images: Array<{ previewUrl?: string }>) => {
for (const image of images) {
@@ -963,6 +973,12 @@ export default function ChatView() {
);
}, [composerMenuItems, composerMenuOpen]);
+ useEffect(() => {
+ setCheckpoints([]);
+ setIsLoadingCheckpoints(false);
+ setIsRevertingCheckpoint(false);
+ }, [activeThread?.id]);
+
useEffect(() => {
if (!activeThread?.id || activeThread.terminalOpen) return;
const frame = window.requestAnimationFrame(() => {
@@ -1311,6 +1327,78 @@ export default function ChatView() {
}
};
+ const loadCheckpoints = async (): Promise<ProviderCheckpoint[] | null> => {
+ if (!api || !activeThread) return null;
+ if (phase === "running" || isSending || isConnecting || isRevertingCheckpoint) {
+ return null;
+ }
+ const hasThreadIdentity = Boolean(activeThread.codexThreadId ?? activeThread.session?.threadId);
+ if (!hasThreadIdentity) {
+ setCheckpoints([]);
+ return [];
+ }
+
+ setIsLoadingCheckpoints(true);
+ setThreadError(activeThread.id, null);
+ try {
+ const sessionInfo = await ensureSession();
+ if (!sessionInfo) {
+ return null;
+ }
+ const result = await api.providers.listCheckpoints({
+ sessionId: sessionInfo.sessionId,
+ });
+ setCheckpoints(result.checkpoints);
+ return result.checkpoints;
+ } catch (err) {
+ setThreadError(
+ activeThread.id,
+ err instanceof Error ? err.message : "Failed to load checkpoints.",
+ );
+ return null;
+ } finally {
+ setIsLoadingCheckpoints(false);
+ }
+ };
+
+ const onRevertToCheckpoint = async (checkpoint: ProviderCheckpoint) => {
+ if (!api || !activeThread || checkpoint.isCurrent || isRevertingCheckpoint) {
+ return;
+ }
+ if (phase === "running" || isSending || isConnecting) {
+ setThreadError(activeThread.id, "Interrupt the current turn before reverting checkpoints.");
+ return;
+ }
+
+ setIsRevertingCheckpoint(true);
+ setThreadError(activeThread.id, null);
+ try {
+ const sessionInfo = await ensureSession();
+ if (!sessionInfo) {
+ return;
+ }
+ const result = await api.providers.revertToCheckpoint({
+ sessionId: sessionInfo.sessionId,
+ turnCount: checkpoint.turnCount,
+ });
+ dispatch({
+ type: "REVERT_TO_CHECKPOINT",
+ threadId: activeThread.id,
+ sessionId: sessionInfo.sessionId,
+ threadRuntimeId: result.threadId,
+ messageCount: result.messageCount,
+ });
+ setCheckpoints(result.checkpoints);
+ } catch (err) {
+ setThreadError(
+ activeThread.id,
+ err instanceof Error ? err.message : "Failed to revert checkpoint.",
+ );
+ } finally {
+ setIsRevertingCheckpoint(false);
+ }
+ };
+
const onSend = async (e: FormEvent) => {
e.preventDefault();
if (!api || !activeThread || isSending || isConnecting) return;
@@ -1641,6 +1729,14 @@ export default function ChatView() {
onAddProjectScript={saveProjectScript}
onUpdateProjectScript={updateProjectScript}
onToggleDiff={onToggleDiff}
+ checkpoints={checkpoints}
+ canCheckpoint={canCheckpoint}
+ isLoadingCheckpoints={isLoadingCheckpoints}
+ isRevertingCheckpoint={isRevertingCheckpoint}
+ onOpenCheckpoints={() => {
+ void loadCheckpoints();
+ }}
+ onRevertToCheckpoint={onRevertToCheckpoint}
/>
</header>
@@ -1974,6 +2070,12 @@ interface ChatHeaderProps {
onAddProjectScript: (input: NewProjectScriptInput) => Promise<void>;
onUpdateProjectScript: (scriptId: string, input: NewProjectScriptInput) => Promise<void>;
onToggleDiff: () => void;
+ checkpoints: ProviderCheckpoint[];
+ canCheckpoint: boolean;
+ isLoadingCheckpoints: boolean;
+ isRevertingCheckpoint: boolean;
+ onOpenCheckpoints: () => void;
+ onRevertToCheckpoint: (checkpoint: ProviderCheckpoint) => void;
}
const ChatHeader = memo(function ChatHeader({
@@ -1989,6 +2091,12 @@ const ChatHeader = memo(function ChatHeader({
onAddProjectScript,
onUpdateProjectScript,
onToggleDiff,
+ checkpoints,
+ canCheckpoint,
+ isLoadingCheckpoints,
+ isRevertingCheckpoint,
+ onOpenCheckpoints,
+ onRevertToCheckpoint,
}: ChatHeaderProps) {
return (
<>
@@ -2011,6 +2119,46 @@ const ChatHeader = memo(function ChatHeader({
)}
{activeProjectName && <OpenInPicker keybindings={keybindings} />}
{activeProjectName && <GitActionsControl api={api} gitCwd={gitCwd} />}
+ <Menu>
+ <MenuTrigger
+ render={
+ <Button
+ size="xs"
+ variant="ghost"
+ className="text-muted-foreground/70 hover:text-foreground/80"
+ disabled={!canCheckpoint || isRevertingCheckpoint}
+ onClick={onOpenCheckpoints}
+ >
+ {isRevertingCheckpoint
+ ? "Reverting..."
+ : isLoadingCheckpoints
+ ? "Loading..."
+ : "Checkpoints"}
+ </Button>
+ }
+ />
+ <MenuPopup align="end" className="w-72">
+ {!canCheckpoint ? (
+ <MenuItem disabled>Send at least one message to create checkpoints.</MenuItem>
+ ) : checkpoints.length === 0 ? (
+ <MenuItem disabled>
+ {isLoadingCheckpoints ? "Loading checkpoints..." : "No checkpoints available."}
+ </MenuItem>
+ ) : (
+ checkpoints.map((checkpoint) => (
+ <MenuItem
+ key={checkpoint.id}
+ disabled={checkpoint.isCurrent || isRevertingCheckpoint}
+ onClick={() => onRevertToCheckpoint(checkpoint)}
+ >
+ {checkpoint.label}
+ {checkpoint.preview ? `: ${checkpoint.preview}` : ""}
+ {checkpoint.isCurrent ? " (Current)" : ""}
+ </MenuItem>
+ ))
+ )}
+ </MenuPopup>
+ </Menu>
<Button
size="xs"
variant="ghost"
diff --git a/apps/web/src/store.test.ts b/apps/web/src/store.test.ts
index 764d6ec4d..4ba4b4a50 100644
--- a/apps/web/src/store.test.ts
+++ b/apps/web/src/store.test.ts
@@ -718,4 +718,66 @@ describe("store reducer thread continuity", () => {
expect(next.threads[0]?.latestTurnCompletedAt).toBe(completedAt);
expect(next.threads[0]?.lastVisitedAt).toBe(completedAt);
});
+
+ it("reverts thread state to a checkpoint snapshot", () => {
+ const state = makeState(
+ makeThread({
+ codexThreadId: "thr_before",
+ session: makeSession({
+ status: "running",
+ threadId: "thr_before",
+ activeTurnId: "turn-live",
+ }),
+ messages: [
+ {
+ id: "m-1",
+ role: "user",
+ text: "First",
+ createdAt: "2026-02-08T10:00:00.000Z",
+ streaming: false,
+ },
+ {
+ id: "m-2",
+ role: "assistant",
+ text: "First reply",
+ createdAt: "2026-02-08T10:00:01.000Z",
+ streaming: false,
+ },
+ {
+ id: "m-3",
+ role: "user",
+ text: "Second",
+ createdAt: "2026-02-08T10:00:02.000Z",
+ streaming: false,
+ },
+ ],
+ events: [
+ makeEvent({
+ method: "turn/started",
+ turnId: "turn-live",
+ }),
+ ],
+ error: "temporary failure",
+ latestTurnId: "turn-live",
+ latestTurnStartedAt: "2026-02-08T10:00:03.000Z",
+ }),
+ );
+
+ const next = reducer(state, {
+ type: "REVERT_TO_CHECKPOINT",
+ threadId: "thread-local-1",
+ sessionId: "sess-1",
+ threadRuntimeId: "thr_after",
+ messageCount: 2,
+ });
+
+ expect(next.threads[0]?.codexThreadId).toBe("thr_after");
+ expect(next.threads[0]?.messages.map((message) => message.id)).toEqual(["m-1", "m-2"]);
+ expect(next.threads[0]?.events).toEqual([]);
+ expect(next.threads[0]?.error).toBeNull();
+ expect(next.threads[0]?.session?.status).toBe("ready");
+ expect(next.threads[0]?.session?.activeTurnId).toBeUndefined();
+ expect(next.threads[0]?.session?.threadId).toBe("thr_after");
+ expect(next.threads[0]?.latestTurnId).toBeUndefined();
+ });
});
diff --git a/apps/web/src/store.ts b/apps/web/src/store.ts
index b45e36e17..e3dc1d50d 100644
--- a/apps/web/src/store.ts
+++ b/apps/web/src/store.ts
@@ -59,6 +59,13 @@ type Action =
| { type: "SET_ERROR"; threadId: string; error: string | null }
| { type: "SET_THREAD_TITLE"; threadId: string; title: string }
| { type: "SET_THREAD_MODEL"; threadId: string; model: string }
+ | {
+ type: "REVERT_TO_CHECKPOINT";
+ threadId: string;
+ sessionId: string;
+ threadRuntimeId: string;
+ messageCount: number;
+ }
| {
type: "SET_THREAD_BRANCH";
threadId: string;
@@ -834,6 +841,38 @@ export function reducer(state: AppState, action: Action): AppState {
})),
};
+ case "REVERT_TO_CHECKPOINT":
+ return {
+ ...state,
+ threads: updateThread(state.threads, action.threadId, (t) => {
+ const nextMessageCount = Math.max(0, Math.floor(action.messageCount));
+ const now = new Date().toISOString();
+ return {
+ ...t,
+ codexThreadId: action.threadRuntimeId,
+ session:
+ t.session?.sessionId === action.sessionId
+ ? {
+ ...t.session,
+ status: "ready",
+ threadId: action.threadRuntimeId,
+ activeTurnId: undefined,
+ updatedAt: now,
+ lastError: undefined,
+ }
+ : t.session,
+ messages: t.messages.slice(0, nextMessageCount),
+ events: [],
+ error: null,
+ latestTurnId: undefined,
+ latestTurnStartedAt: undefined,
+ latestTurnCompletedAt: undefined,
+ latestTurnDurationMs: undefined,
+ lastVisitedAt: now,
+ };
+ }),
+ };
+
case "SET_THREAD_BRANCH": {
return {
...state,
diff --git a/apps/web/src/wsNativeApi.ts b/apps/web/src/wsNativeApi.ts
index bf5dc8b30..80e1e8f72 100644
--- a/apps/web/src/wsNativeApi.ts
+++ b/apps/web/src/wsNativeApi.ts
@@ -91,6 +91,9 @@ export function createWsNativeApi(): NativeApi {
respondToRequest: (input) => transport.request(WS_METHODS.providersRespondToRequest, input),
stopSession: (input) => transport.request(WS_METHODS.providersStopSession, input),
listSessions: () => transport.request(WS_METHODS.providersListSessions),
+ listCheckpoints: (input) => transport.request(WS_METHODS.providersListCheckpoints, input),
+ revertToCheckpoint: (input) =>
+ transport.request(WS_METHODS.providersRevertToCheckpoint, input),
onEvent: (callback) =>
transport.subscribe(WS_CHANNELS.providerEvent, callback as (data: unknown) => void),
},
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 3153037a9..317bff60a 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -18,6 +18,10 @@ import type {
import type {
ProviderEvent,
ProviderInterruptTurnInput,
+ ProviderListCheckpointsInput,
+ ProviderListCheckpointsResult,
+ ProviderRevertToCheckpointInput,
+ ProviderRevertToCheckpointResult,
ProviderRespondToRequestInput,
ProviderSendTurnInput,
ProviderSession,
@@ -89,6 +93,10 @@ export interface NativeApi {
respondToRequest: (input: ProviderRespondToRequestInput) => Promise<void>;
stopSession: (input: ProviderStopSessionInput) => Promise<void>;
listSessions: () => Promise<ProviderSession[]>;
+ listCheckpoints: (input: ProviderListCheckpointsInput) => Promise<ProviderListCheckpointsResult>;
+ revertToCheckpoint: (
+ input: ProviderRevertToCheckpointInput,
+ ) => Promise<ProviderRevertToCheckpointResult>;
onEvent: (callback: (event: ProviderEvent) => void) => () => void;
};
projects: {
diff --git a/packages/contracts/src/provider.test.ts b/packages/contracts/src/provider.test.ts
index e2ccd990b..bc406c370 100644
--- a/packages/contracts/src/provider.test.ts
+++ b/packages/contracts/src/provider.test.ts
@@ -2,7 +2,12 @@ import { describe, expect, it } from "vitest";
import {
PROVIDER_SEND_TURN_MAX_ATTACHMENTS,
+ providerCheckpointSchema,
providerEventSchema,
+ providerListCheckpointsInputSchema,
+ providerListCheckpointsResultSchema,
+ providerRevertToCheckpointInputSchema,
+ providerRevertToCheckpointResultSchema,
providerRespondToRequestInputSchema,
providerSendTurnInputSchema,
providerSessionStartInputSchema,
@@ -157,3 +162,71 @@ describe("providerRespondToRequestInputSchema", () => {
).toThrow();
});
});
+
+describe("provider checkpoint schemas", () => {
+ it("accepts list checkpoint inputs", () => {
+ const parsed = providerListCheckpointsInputSchema.parse({
+ sessionId: "sess_1",
+ });
+ expect(parsed.sessionId).toBe("sess_1");
+ });
+
+ it("accepts checkpoint records and list results", () => {
+ const checkpoint = providerCheckpointSchema.parse({
+ id: "turn_1",
+ turnCount: 1,
+ messageCount: 2,
+ label: "Turn 1",
+ preview: "Summarize this file",
+ isCurrent: true,
+ });
+ expect(checkpoint.turnCount).toBe(1);
+
+ const listResult = providerListCheckpointsResultSchema.parse({
+ threadId: "thr_1",
+ checkpoints: [checkpoint],
+ });
+ expect(listResult.checkpoints).toHaveLength(1);
+ });
+
+ it("accepts revert checkpoint input/result", () => {
+ const input = providerRevertToCheckpointInputSchema.parse({
+ sessionId: "sess_1",
+ turnCount: 2,
+ });
+ expect(input.turnCount).toBe(2);
+
+ const result = providerRevertToCheckpointResultSchema.parse({
+ threadId: "thr_1",
+ turnCount: 2,
+ messageCount: 4,
+ rolledBackTurns: 1,
+ checkpoints: [
+ {
+ id: "root",
+ turnCount: 0,
+ messageCount: 0,
+ label: "Start of conversation",
+ isCurrent: false,
+ },
+ {
+ id: "turn_2",
+ turnCount: 2,
+ messageCount: 4,
+ label: "Turn 2",
+ isCurrent: true,
+ },
+ ],
+ });
+ expect(result.rolledBackTurns).toBe(1);
+ });
+
+ it("rejects negative turn counts", () => {
+ expect(() =>
+ providerRevertToCheckpointInputSchema.parse({
+ sessionId: "sess_1",
+ turnCount: -1,
+ }),
+ ).toThrow();
+ });
+});
diff --git a/packages/contracts/src/provider.ts b/packages/contracts/src/provider.ts
index 01910dd9f..ca599a347 100644
--- a/packages/contracts/src/provider.ts
+++ b/packages/contracts/src/provider.ts
@@ -111,6 +111,37 @@ export const providerStopSessionInputSchema = z.object({
sessionId: z.string().min(1),
});
+export const providerListCheckpointsInputSchema = z.object({
+ sessionId: z.string().min(1),
+});
+
+export const providerCheckpointSchema = z.object({
+ id: z.string().min(1),
+ turnCount: z.number().int().min(0),
+ messageCount: z.number().int().min(0),
+ label: z.string().min(1),
+ preview: z.string().min(1).optional(),
+ isCurrent: z.boolean(),
+});
+
+export const providerListCheckpointsResultSchema = z.object({
+ threadId: z.string().min(1),
+ checkpoints: z.array(providerCheckpointSchema),
+});
+
+export const providerRevertToCheckpointInputSchema = z.object({
+ sessionId: z.string().min(1),
+ turnCount: z.number().int().min(0),
+});
+
+export const providerRevertToCheckpointResultSchema = z.object({
+ threadId: z.string().min(1),
+ turnCount: z.number().int().min(0),
+ messageCount: z.number().int().min(0),
+ rolledBackTurns: z.number().int().min(0),
+ checkpoints: z.array(providerCheckpointSchema),
+});
+
export const providerRespondToRequestInputSchema = z.object({
sessionId: z.string().min(1),
requestId: z.string().min(1),
@@ -151,6 +182,13 @@ export type ProviderSendTurnInput = z.input<typeof providerSendTurnInputSchema>;
export type ProviderTurnStartResult = z.infer<typeof providerTurnStartResultSchema>;
export type ProviderInterruptTurnInput = z.input<typeof providerInterruptTurnInputSchema>;
export type ProviderStopSessionInput = z.input<typeof providerStopSessionInputSchema>;
+export type ProviderListCheckpointsInput = z.input<typeof providerListCheckpointsInputSchema>;
+export type ProviderCheckpoint = z.infer<typeof providerCheckpointSchema>;
+export type ProviderListCheckpointsResult = z.infer<typeof providerListCheckpointsResultSchema>;
+export type ProviderRevertToCheckpointInput = z.input<typeof providerRevertToCheckpointInputSchema>;
+export type ProviderRevertToCheckpointResult = z.infer<
+ typeof providerRevertToCheckpointResultSchema
+>;
export type ProviderRespondToRequestInput = z.input<typeof providerRespondToRequestInputSchema>;
export type ProviderEventKind = z.infer<typeof providerEventKindSchema>;
export type ProviderEvent = z.infer<typeof providerEventSchema>;
diff --git a/packages/contracts/src/ws.ts b/packages/contracts/src/ws.ts
index 7d4abb60f..ef395962c 100644
--- a/packages/contracts/src/ws.ts
+++ b/packages/contracts/src/ws.ts
@@ -10,6 +10,8 @@ export const WS_METHODS = {
providersRespondToRequest: "providers.respondToRequest",
providersStopSession: "providers.stopSession",
providersListSessions: "providers.listSessions",
+ providersListCheckpoints: "providers.listCheckpoints",
+ providersRevertToCheckpoint: "providers.revertToCheckpoint",
// Project registry methods
projectsList: "projects.list",