Skip to content

Commit 384878a

Browse files
Move app state persistence to centralized SQLite service
- Add server-side `PersistenceService` backed by SQLite with migrations and tests - Introduce shared state contracts/events and wire WebSocket bootstrap/catch-up flows - Migrate project/thread/message persistence from renderer-local state to server-managed state - Store turn diff summaries from checkpoint diffs for faster thread metadata rendering
1 parent bf9f653 commit 384878a

27 files changed

Lines changed: 3735 additions & 390 deletions

‎.plans/11-centralized-sqlite-persistence-revamp.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ Move durable core app state out of renderer `localStorage` and into a centralize
55

66
This plan preserves existing checkpoint patch storage in Git (`refs/t3/checkpoints/...`) and adds optional checkpoint diff summaries in SQLite (parsed via `@pierre/diffs`) for fast UI metadata rendering.
77

8+
Core migration goals:
9+
1. Data persistence scalability.
10+
2. Move as much logic and state control as possible to the server, keeping the frontend simple.
11+
812
## Why This Revamp
913
Current persistence is split across multiple stores:
1014

‎apps/server/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
"test": "vitest run"
1818
},
1919
"dependencies": {
20+
"@pierre/diffs": "^1.1.0-beta.16",
2021
"node-pty": "^1.1.0",
2122
"open": "^10.1.0",
2223
"ws": "^8.18.0"

‎apps/server/src/index.ts‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
66

77
import { fixPath } from "./fixPath";
88
import { createLogger } from "./logger";
9-
import { ProjectRegistry } from "./projectRegistry";
9+
import { PersistenceService } from "./persistenceService";
1010
import { createServer } from "./wsServer";
1111

1212
fixPath();
@@ -49,6 +49,13 @@ function resolveStateDir(raw: string | undefined): string {
4949
return path.resolve(expandHomePath(raw.trim()));
5050
}
5151

52+
function resolveStateDbPath(raw: string | undefined): string {
53+
if (!raw || raw.trim().length === 0) {
54+
return path.join(os.homedir(), ".t3", "state.sqlite");
55+
}
56+
return path.resolve(expandHomePath(raw.trim()));
57+
}
58+
5259
async function findAvailablePort(preferred: number): Promise<number> {
5360
return new Promise((resolve, reject) => {
5461
const server = net.createServer();
@@ -101,8 +108,12 @@ async function main() {
101108
const requestedPort = parsePort(process.env.T3CODE_PORT);
102109
const port =
103110
requestedPort ?? (mode === "desktop" ? DEFAULT_PORT : await findAvailablePort(DEFAULT_PORT));
104-
const stateDir = resolveStateDir(process.env.T3CODE_STATE_DIR);
105-
const projectRegistry = new ProjectRegistry(stateDir);
111+
const legacyStateDir = resolveStateDir(process.env.T3CODE_STATE_DIR);
112+
const stateDbPath = resolveStateDbPath(process.env.T3CODE_STATE_DB_PATH);
113+
const persistenceService = new PersistenceService({
114+
dbPath: stateDbPath,
115+
legacyProjectsJsonPath: path.join(legacyStateDir, "projects.json"),
116+
});
106117
const devUrl = process.env.VITE_DEV_SERVER_URL;
107118
const noBrowser = parseBooleanEnv(process.env.T3CODE_NO_BROWSER) ?? mode === "desktop";
108119
const authToken = process.env.T3CODE_AUTH_TOKEN;
@@ -120,7 +131,7 @@ async function main() {
120131
cwd,
121132
staticDir,
122133
devUrl,
123-
projectRegistry,
134+
persistenceService,
124135
authToken,
125136
});
126137
await server.start();
@@ -130,7 +141,8 @@ async function main() {
130141
url,
131142
cwd,
132143
mode,
133-
stateDir,
144+
stateDbPath,
145+
legacyStateDir,
134146
authEnabled: Boolean(authToken),
135147
});
136148

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
import fs from "node:fs";
2+
import os from "node:os";
3+
import path from "node:path";
4+
5+
import { afterEach, describe, expect, it } from "vitest";
6+
7+
import type { ProviderEvent } from "@t3tools/contracts";
8+
import { PersistenceService } from "./persistenceService";
9+
10+
const tempDirs: string[] = [];
11+
12+
function makeTempDir(prefix: string): string {
13+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
14+
tempDirs.push(dir);
15+
return dir;
16+
}
17+
18+
function iso(offsetMs = 0): string {
19+
return new Date(Date.now() + offsetMs).toISOString();
20+
}
21+
22+
afterEach(() => {
23+
for (const dir of tempDirs.splice(0, tempDirs.length)) {
24+
fs.rmSync(dir, { recursive: true, force: true });
25+
}
26+
});
27+
28+
describe("PersistenceService", () => {
29+
it("persists projects/threads/messages and serves bootstrap + catch-up", () => {
30+
const stateDir = makeTempDir("t3code-persistence-state-");
31+
const projectDir = makeTempDir("t3code-persistence-project-");
32+
const service = new PersistenceService({
33+
dbPath: path.join(stateDir, "state.sqlite"),
34+
});
35+
36+
const addedProject = service.addProject({ cwd: projectDir });
37+
expect(addedProject.created).toBe(true);
38+
39+
const createdThread = service.createThread({
40+
projectId: addedProject.project.id,
41+
title: "Thread 1",
42+
model: "gpt-5.3-codex",
43+
}).thread;
44+
45+
service.bindSessionToThread("sess-1", createdThread.id, "runtime-thread-1");
46+
service.persistUserMessageForTurn({
47+
sessionId: "sess-1",
48+
clientMessageId: "msg-user-1",
49+
clientMessageText: "hello world",
50+
input: "hello world",
51+
attachments: [],
52+
});
53+
54+
const baseEvent: Omit<ProviderEvent, "id" | "createdAt" | "method" | "payload"> = {
55+
kind: "notification",
56+
provider: "codex",
57+
sessionId: "sess-1",
58+
};
59+
60+
service.ingestProviderEvent({
61+
...baseEvent,
62+
id: "evt-1",
63+
createdAt: iso(10),
64+
method: "item/started",
65+
payload: {
66+
item: {
67+
type: "agentMessage",
68+
id: "assistant-msg-1",
69+
text: "",
70+
},
71+
},
72+
});
73+
74+
service.ingestProviderEvent({
75+
...baseEvent,
76+
id: "evt-2",
77+
createdAt: iso(20),
78+
method: "item/agentMessage/delta",
79+
itemId: "assistant-msg-1",
80+
textDelta: "hi",
81+
payload: {
82+
itemId: "assistant-msg-1",
83+
delta: "hi",
84+
},
85+
});
86+
87+
service.ingestProviderEvent({
88+
...baseEvent,
89+
id: "evt-3",
90+
createdAt: iso(30),
91+
method: "item/completed",
92+
payload: {
93+
item: {
94+
type: "agentMessage",
95+
id: "assistant-msg-1",
96+
text: "hi there",
97+
},
98+
},
99+
});
100+
101+
service.ingestProviderEvent({
102+
...baseEvent,
103+
id: "evt-4",
104+
createdAt: iso(40),
105+
method: "turn/completed",
106+
turnId: "turn-1",
107+
payload: {
108+
turn: {
109+
id: "turn-1",
110+
status: "completed",
111+
},
112+
},
113+
});
114+
115+
const snapshot = service.loadSnapshot();
116+
expect(snapshot.projects).toHaveLength(1);
117+
expect(snapshot.threads).toHaveLength(1);
118+
const thread = snapshot.threads[0];
119+
expect(thread?.messages.map((message) => message.id)).toEqual([
120+
"msg-user-1",
121+
"assistant-msg-1",
122+
]);
123+
expect(thread?.messages[1]?.text).toBe("hi there");
124+
expect(thread?.turnDiffSummaries[0]?.turnId).toBe("turn-1");
125+
126+
const catchUp = service.catchUp({ afterSeq: 0 });
127+
expect(catchUp.events.length).toBeGreaterThan(0);
128+
expect(catchUp.events.every((event, index, events) => event.seq === events[index]?.seq)).toBe(
129+
true,
130+
);
131+
expect(catchUp.events.some((event) => event.eventType === "project.upsert")).toBe(true);
132+
expect(catchUp.events.some((event) => event.eventType === "thread.upsert")).toBe(true);
133+
expect(catchUp.events.some((event) => event.eventType === "message.upsert")).toBe(true);
134+
135+
service.close();
136+
});
137+
138+
it("stores turn diff summaries parsed from checkpoint diffs", () => {
139+
const stateDir = makeTempDir("t3code-persistence-diff-state-");
140+
const projectDir = makeTempDir("t3code-persistence-diff-project-");
141+
const service = new PersistenceService({
142+
dbPath: path.join(stateDir, "state.sqlite"),
143+
});
144+
145+
const project = service.addProject({ cwd: projectDir }).project;
146+
const thread = service.createThread({
147+
projectId: project.id,
148+
title: "Thread 1",
149+
model: "gpt-5.3-codex",
150+
}).thread;
151+
service.bindSessionToThread("sess-1", thread.id, "runtime-thread-1");
152+
153+
service.persistTurnDiffSummaryFromCheckpoint({
154+
sessionId: "sess-1",
155+
runtimeThreadId: "runtime-thread-1",
156+
turnId: "turn-1",
157+
checkpointTurnCount: 1,
158+
completedAt: "2026-02-19T00:00:00.000Z",
159+
status: "completed",
160+
diff: [
161+
"diff --git a/src/app.ts b/src/app.ts",
162+
"index 1111111..2222222 100644",
163+
"--- a/src/app.ts",
164+
"+++ b/src/app.ts",
165+
"@@ -1,1 +1,2 @@",
166+
"-console.log('a')",
167+
"+console.log('b')",
168+
"+console.log('c')",
169+
].join("\n"),
170+
});
171+
172+
const snapshot = service.loadSnapshot();
173+
const summary = snapshot.threads[0]?.turnDiffSummaries[0];
174+
expect(summary?.turnId).toBe("turn-1");
175+
expect(summary?.checkpointTurnCount).toBe(1);
176+
expect(summary?.files[0]?.path).toBe("src/app.ts");
177+
expect(summary?.files[0]?.additions).toBe(2);
178+
expect(summary?.files[0]?.deletions).toBe(1);
179+
180+
service.close();
181+
});
182+
183+
it("imports legacy renderer state once and reports idempotent re-imports", () => {
184+
const stateDir = makeTempDir("t3code-persistence-legacy-state-");
185+
const projectDir = makeTempDir("t3code-persistence-legacy-project-");
186+
const service = new PersistenceService({
187+
dbPath: path.join(stateDir, "state.sqlite"),
188+
});
189+
190+
const firstImport = service.importLegacyRendererState({
191+
projects: [
192+
{
193+
id: "project-legacy-1",
194+
name: "legacy",
195+
cwd: projectDir,
196+
scripts: [],
197+
},
198+
],
199+
threads: [
200+
{
201+
id: "thread-legacy-1",
202+
projectId: "project-legacy-1",
203+
title: "Imported",
204+
model: "gpt-5.3-codex",
205+
createdAt: "2026-02-19T00:00:00.000Z",
206+
messages: [
207+
{
208+
id: "msg-legacy-1",
209+
role: "user",
210+
text: "legacy message",
211+
createdAt: "2026-02-19T00:00:01.000Z",
212+
streaming: false,
213+
},
214+
],
215+
},
216+
],
217+
});
218+
expect(firstImport).toEqual({
219+
imported: true,
220+
alreadyImported: false,
221+
});
222+
223+
const secondImport = service.importLegacyRendererState({
224+
projects: [],
225+
threads: [],
226+
});
227+
expect(secondImport).toEqual({
228+
imported: false,
229+
alreadyImported: true,
230+
});
231+
232+
const snapshot = service.loadSnapshot();
233+
expect(snapshot.projects).toHaveLength(1);
234+
expect(snapshot.threads).toHaveLength(1);
235+
expect(snapshot.threads[0]?.messages).toHaveLength(1);
236+
237+
service.close();
238+
});
239+
});

0 commit comments

Comments
 (0)