Open History to see the last commit
1/**
2 * A self-contained SQLite persistence backend for TanStack AI, built directly
3 * on the `@tanstack/ai-persistence` **core** store contracts and Node's built-in
4 * `node:sqlite` driver. No ORM, no extra dependencies — this is the whole thing.
5 *
6 * It exists as a worked demonstration of "rolling your own" concrete persistence
7 * on the core: the four chat state stores (`MessageStore`, `RunStore`,
8 * `InterruptStore`, `MetadataStore`) and the three generation stores
9 * (`GenerationRunStore`, `ArtifactStore`, `BlobStore`) are implemented here
10 * against raw SQL, and the result is a standard `AIPersistence` you hand to
11 * `withPersistence(...)` and `withGenerationPersistence(...)`.
12 *
13 * The store semantics mirror the reference in-memory backend shipped in
14 * `@tanstack/ai-persistence` (`memory.ts`) exactly — the shared conformance
15 * testkit (`sqlite-persistence.test.ts`) is the proof. If you copy this file
16 * into your own app, keep those invariants intact and the testkit green.
17 *
18 * Requires Node 22.5+ (for `node:sqlite`). The TanStack Start server this
19 * example runs on is a Node runtime, so `DatabaseSync` is available server-side.
20 */
21import { mkdirSync } from 'node:fs'
22import { dirname } from 'node:path'
23import { fileURLToPath } from 'node:url'
24import { DatabaseSync } from 'node:sqlite'
25import {
26 defineAIPersistence,
27 defineArtifactStore,
28 defineBlobStore,
29 defineGenerationRunStore,
30 defineInterruptStore,
31 defineMessageStore,
32 defineMetadataStore,
33 defineRunStore,
34 resolveBlobRange,
35} from '@tanstack/ai-persistence'
36import type {
37 ModelMessage,
38 PersistedArtifactRef,
39 TokenUsage,
40} from '@tanstack/ai'
41import type {
42 AIPersistence,
43 ArtifactRecord,
44 ArtifactStore,
45 BlobBody,
46 BlobListOptions,
47 BlobListPage,
48 BlobObject,
49 BlobRecord,
50 BlobStore,
51 GenerationRunRecord,
52 GenerationRunStatus,
53 GenerationRunStore,
54 InterruptRecord,
55 InterruptStore,
56 MessageStore,
57 MetadataStore,
58 RunRecord,
59 RunStatus,
60 RunStore,
61} from '@tanstack/ai-persistence'
62
63// ---------------------------------------------------------------------------
64// Schema
65// ---------------------------------------------------------------------------
66//
67// The canonical TanStack AI table layout: one row per thread transcript, plus
68// run/interrupt lifecycle rows and a scoped key/value table. JSON payloads live
69// in `text` columns (raw SQLite has no JSON column mode, so we serialize with
70// `JSON.stringify`/`JSON.parse` at the edges). Timestamps are epoch milliseconds
71// stored as `integer`. `CREATE TABLE IF NOT EXISTS` makes `migrate: true`
72// idempotent — a real adapter would track versioned migrations instead.
73const SCHEMA_SQL = `
74CREATE TABLE IF NOT EXISTS messages (
75 thread_id text PRIMARY KEY NOT NULL,
76 messages_json text NOT NULL
77);
78CREATE TABLE IF NOT EXISTS runs (
79 run_id text PRIMARY KEY NOT NULL,
80 thread_id text NOT NULL,
81 status text NOT NULL,
82 started_at integer NOT NULL,
83 finished_at integer,
84 error text,
85 error_code text,
86 usage_json text,
87 sandbox_key text,
88 detached_since integer,
89 cancel_requested integer,
90 driver_epoch integer
91);
92CREATE TABLE IF NOT EXISTS interrupts (
93 interrupt_id text PRIMARY KEY NOT NULL,
94 run_id text NOT NULL,
95 thread_id text NOT NULL,
96 status text NOT NULL,
97 requested_at integer NOT NULL,
98 resolved_at integer,
99 payload_json text NOT NULL,
100 response_json text
101);
102CREATE TABLE IF NOT EXISTS metadata (
103 scope text NOT NULL,
104 key text NOT NULL,
105 value_json text NOT NULL,
106 PRIMARY KEY (scope, key)
107);
108CREATE TABLE IF NOT EXISTS generation_runs (
109 run_id text PRIMARY KEY NOT NULL,
110 thread_id text NOT NULL,
111 activity text NOT NULL,
112 provider text NOT NULL,
113 model text NOT NULL,
114 status text NOT NULL,
115 started_at integer NOT NULL,
116 finished_at integer,
117 error_json text,
118 result_json text,
119 artifacts_json text,
120 usage_json text
121);
122-- findLatestForThread orders by started_at within a thread.
123CREATE INDEX IF NOT EXISTS generation_runs_thread_started
124 ON generation_runs (thread_id, started_at DESC);
125CREATE TABLE IF NOT EXISTS artifacts (
126 artifact_id text PRIMARY KEY NOT NULL,
127 run_id text NOT NULL,
128 thread_id text NOT NULL,
129 blob_key text,
130 name text NOT NULL,
131 mime_type text NOT NULL,
132 size integer NOT NULL,
133 source_url text,
134 created_at integer NOT NULL
135);
136CREATE INDEX IF NOT EXISTS artifacts_run ON artifacts (run_id);
137-- The bytes themselves. \`body\` is a BLOB column, so this file IS the object
138-- store; a production adapter would keep metadata here and put bytes in S3/R2.
139CREATE TABLE IF NOT EXISTS blobs (
140 key text PRIMARY KEY NOT NULL,
141 body blob NOT NULL,
142 size integer NOT NULL,
143 etag text NOT NULL,
144 content_type text,
145 custom_metadata_json text,
146 created_at integer NOT NULL,
147 updated_at integer NOT NULL
148);
149`
150
151/**
152 * Columns added to `runs` after the table first shipped.
153 *
154 * `CREATE TABLE IF NOT EXISTS` does NOT alter a table that already exists, so a
155 * `.data/*.db` written by an earlier version of this example has none of these.
156 * Without an additive migration that file breaks hard, and early: `createRunStore`
157 * prepares its `listReclaimable` statement eagerly, and `node:sqlite` resolves
158 * column names at prepare time, so `sqlitePersistence()` itself throws
159 * `no such column: detached_since` before a single request is served — `update`
160 * would fail the same way.
161 *
162 * SQLite has no `ADD COLUMN IF NOT EXISTS`, so {@link addMissingColumns} consults
163 * `PRAGMA table_info` instead of relying on a caught error. Adding a nullable
164 * column needs no table rewrite. A production adapter would keep versioned
165 * migration files; this stays honest about being an example.
166 */
167const RUNS_ADDED_COLUMNS: ReadonlyArray<{ name: string; type: string }> = [
168 { name: 'error_code', type: 'text' },
169 { name: 'usage_json', type: 'text' },
170 { name: 'sandbox_key', type: 'text' },
171 { name: 'detached_since', type: 'integer' },
172 { name: 'cancel_requested', type: 'integer' },
173 { name: 'driver_epoch', type: 'integer' },
174]
175
176/** `PRAGMA table_info` row, narrowed to the one field this uses. */
177interface TableInfoRow {
178 name: string
179}
180
181function hasName(value: unknown): value is TableInfoRow {
182 return (
183 typeof value === 'object' &&
184 value !== null &&
185 'name' in value &&
186 typeof (value as { name: unknown }).name === 'string'
187 )
188}
189
190/** Bring an existing `runs` table up to the current schema. Idempotent. */
191function addMissingColumns(db: DatabaseSync): void {
192 const existing = new Set(
193 db
194 .prepare(`PRAGMA table_info(runs)`)
195 .all()
196 .filter(hasName)
197 .map((row) => row.name),
198 )
199 // An empty set means the table does not exist at all, in which case SCHEMA_SQL
200 // just created it complete and there is nothing to add.
201 if (existing.size === 0) return
202 for (const column of RUNS_ADDED_COLUMNS) {
203 if (existing.has(column.name)) continue
204 db.exec(`ALTER TABLE runs ADD COLUMN ${column.name} ${column.type}`)
205 }
206}
207
208// Row shapes as SQLite hands them back (JSON columns are still text here).
209interface MessagesRow {
210 messages_json: string
211}
212interface RunRow {
213 run_id: string
214 thread_id: string
215 status: string
216 started_at: number
217 finished_at: number | null
218 error: string | null
219 error_code: string | null
220 usage_json: string | null
221 sandbox_key: string | null
222 detached_since: number | null
223 cancel_requested: number | null
224 driver_epoch: number | null
225}
226interface InterruptRow {
227 interrupt_id: string
228 run_id: string
229 thread_id: string
230 status: string
231 requested_at: number
232 resolved_at: number | null
233 payload_json: string
234 response_json: string | null
235}
236interface MetadataRow {
237 value_json: string
238}
239interface GenerationRunRow {
240 run_id: string
241 thread_id: string
242 activity: string
243 provider: string
244 model: string
245 status: string
246 started_at: number
247 finished_at: number | null
248 error_json: string | null
249 result_json: string | null
250 artifacts_json: string | null
251 usage_json: string | null
252}
253interface ArtifactRow {
254 artifact_id: string
255 run_id: string
256 thread_id: string
257 blob_key: string | null
258 name: string
259 mime_type: string
260 size: number
261 source_url: string | null
262 created_at: number
263}
264/** A `blobs` row without the bytes — what a metadata read selects. */
265interface BlobMetaRow {
266 key: string
267 size: number
268 etag: string
269 content_type: string | null
270 custom_metadata_json: string | null
271 created_at: number
272 updated_at: number
273}
274interface BlobRow extends BlobMetaRow {
275 body: Uint8Array
276}
277
278function parseJson<T>(text: string): T {
279 return JSON.parse(text) as T
280}
281
282// ---------------------------------------------------------------------------
283// MessageStore — full-transcript overwrite, keyed by thread.
284// ---------------------------------------------------------------------------
285function createMessageStore(db: DatabaseSync) {
286 const selectStmt = db.prepare(
287 'SELECT messages_json FROM messages WHERE thread_id = ?',
288 )
289 const upsertStmt = db.prepare(
290 `INSERT INTO messages (thread_id, messages_json) VALUES (?, ?)
291 ON CONFLICT(thread_id) DO UPDATE SET messages_json = excluded.messages_json`,
292 )
293 return defineMessageStore({
294 loadThread(threadId) {
295 const row = selectStmt.get(threadId) as MessagesRow | undefined
296 // INVARIANT: unknown thread returns [] (never null).
297 return Promise.resolve(
298 row ? parseJson<Array<ModelMessage>>(row.messages_json) : [],
299 )
300 },
301 saveThread(threadId, messages) {
302 // Full replace, not append — `messages` is the authoritative history.
303 upsertStmt.run(threadId, JSON.stringify(messages))
304 return Promise.resolve()
305 },
306 })
307}
308
309// ---------------------------------------------------------------------------
310// RunStore — idempotent create/resume + patch.
311// ---------------------------------------------------------------------------
312// `status` is stored verbatim as text, so the whole `RunStatus` union round-trips
313// — including `'aborted'` — without a schema change. The durable-agent-runs
314// fields (`sandboxKey`, `detachedSince`, `cancelRequested`, `driverEpoch`) each
315// get their own column: `sandbox_key`/`driver_epoch`/`detached_since` are plain
316// scalars (text / integer / integer epoch-ms, matching `finished_at`), and
317// `cancel_requested` is an `integer` 0/1 flag — SQLite has no native boolean, so
318// this file's convention is the same "integer used as a boolean" SQLite itself
319// uses internally.
320//
321// `RunRecord.error` is the structured `RunError` (`{ message, code? }`) and gets
322// two columns rather than one JSON blob: `error` for the provider's prose and
323// `error_code` for the stable classification. `code` is precisely the field an
324// operator filters and groups by (`WHERE error_code = 'rate_limited'`), which a
325// JSON blob would bury, and this file's convention reserves the `_json` suffix
326// for columns that really do hold serialized JSON.
327function mapRun(row: RunRow): RunRecord {
328 return {
329 runId: row.run_id,
330 threadId: row.thread_id,
331 status: row.status as RunStatus,
332 startedAt: row.started_at,
333 ...(row.finished_at != null ? { finishedAt: row.finished_at } : {}),
334 ...(row.error != null
335 ? {
336 error: {
337 message: row.error,
338 ...(row.error_code != null ? { code: row.error_code } : {}),
339 },
340 }
341 : {}),
342 ...(row.usage_json != null
343 ? { usage: parseJson<TokenUsage>(row.usage_json) }
344 : {}),
345 // Each column is omitted entirely (not surfaced as `null`/coerced `false`)
346 // when NULL: `undefined` and `false` mean different things for
347 // `cancelRequested`, and a spurious `detachedSince` would make a live run
348 // look detached to the reaper.
349 ...(row.sandbox_key != null ? { sandboxKey: row.sandbox_key } : {}),
350 ...(row.detached_since != null
351 ? { detachedSince: row.detached_since }
352 : {}),
353 ...(row.cancel_requested != null
354 ? { cancelRequested: row.cancel_requested !== 0 }
355 : {}),
356 ...(row.driver_epoch != null ? { driverEpoch: row.driver_epoch } : {}),
357 }
358}
359
360function createRunStore(db: DatabaseSync) {
361 const selectStmt = db.prepare('SELECT * FROM runs WHERE run_id = ?')
362 const insertStmt = db.prepare(
363 `INSERT INTO runs (run_id, thread_id, status, started_at) VALUES (?, ?, ?, ?)
364 ON CONFLICT(run_id) DO NOTHING`,
365 )
366 const activeStmt = db.prepare(
367 `SELECT * FROM runs WHERE thread_id = ? AND status = 'running'
368 ORDER BY started_at DESC LIMIT 1`,
369 )
370 // Reclaim candidates: ALL THREE of status === 'running', detachedSince set,
371 // and detachedSince <= now - ttlMs (inclusive cutoff — a run detached at
372 // exactly the boundary IS reclaimable, so this is `<=` not `<`). `cutoff` is
373 // computed in JS and bound as a single `?` parameter; the column names and
374 // comparison are fixed literals, so no patch/caller value ever reaches the
375 // SQL text itself.
376 //
377 // `detached_since IS NOT NULL` is written explicitly rather than relied on
378 // implicitly: SQLite's `NULL <= ?` already evaluates to NULL (excluding the
379 // row), but spelling out the NULL guard keeps the intent legible if this
380 // query is ever rewritten to a form where that implicit behavior doesn't
381 // hold.
382 const reclaimableStmt = db.prepare(
383 `SELECT * FROM runs WHERE status = 'running'
384 AND detached_since IS NOT NULL
385 AND detached_since <= ?`,
386 )
387 return defineRunStore({
388 createOrResume(input) {
389 // INVARIANT (idempotency): an existing run is returned unchanged; the
390 // insert is a no-op on conflict so startedAt/threadId/status never move.
391 const existing = selectStmt.get(input.runId) as RunRow | undefined
392 if (existing) return Promise.resolve(mapRun(existing))
393 const status: RunStatus = input.status ?? 'running'
394 insertStmt.run(input.runId, input.threadId, status, input.startedAt)
395 const created = selectStmt.get(input.runId) as RunRow | undefined
396 return Promise.resolve(
397 created
398 ? mapRun(created)
399 : {
400 runId: input.runId,
401 threadId: input.threadId,
402 status,
403 startedAt: input.startedAt,
404 },
405 )
406 },
407 update(runId, patch) {
408 // Build a dynamic SET from only the provided fields; empty patch is a
409 // no-op, and a missing run_id simply updates zero rows (no throw/create).
410 //
411 // All eight columns this schema has are mapped here. Never splice a
412 // patch key into SQL directly — the column name always comes from this
413 // fixed literal set, never from an object key the caller controls.
414 //
415 // `detachedSince`/`sandboxKey`/`cancelRequested`/`driverEpoch` use
416 // `'key' in patch` rather than `patch.key !== undefined`: a reattach
417 // clears `detachedSince` by passing it explicitly as `undefined`, which
418 // must write NULL, not be filtered out of the SET clause (a filtered-out
419 // clear would leave the old value and make every re-attached run look
420 // permanently detached to the reaper).
421 const sets: Array<string> = []
422 const params: Array<string | number | null> = []
423 if (patch.status !== undefined) {
424 sets.push('status = ?')
425 params.push(patch.status)
426 }
427 if (patch.finishedAt !== undefined) {
428 sets.push('finished_at = ?')
429 params.push(patch.finishedAt)
430 }
431 if (patch.error !== undefined) {
432 // Both halves of the structured error move together, so a later failure
433 // with no `code` cannot leave a stale code from an earlier one behind.
434 sets.push('error = ?', 'error_code = ?')
435 params.push(patch.error.message, patch.error.code ?? null)
436 }
437 if (patch.usage !== undefined) {
438 sets.push('usage_json = ?')
439 params.push(JSON.stringify(patch.usage))
440 }
441 if ('sandboxKey' in patch) {
442 sets.push('sandbox_key = ?')
443 params.push(patch.sandboxKey ?? null)
444 }
445 if ('detachedSince' in patch) {
446 sets.push('detached_since = ?')
447 params.push(patch.detachedSince ?? null)
448 }
449 if ('cancelRequested' in patch) {
450 sets.push('cancel_requested = ?')
451 params.push(
452 patch.cancelRequested === undefined
453 ? null
454 : patch.cancelRequested
455 ? 1
456 : 0,
457 )
458 }
459 if ('driverEpoch' in patch) {
460 sets.push('driver_epoch = ?')
461 params.push(patch.driverEpoch ?? null)
462 }
463 if (sets.length === 0) return Promise.resolve()
464 params.push(runId)
465 db.prepare(`UPDATE runs SET ${sets.join(', ')} WHERE run_id = ?`).run(
466 ...params,
467 )
468 return Promise.resolve()
469 },
470 get(runId) {
471 const row = selectStmt.get(runId) as RunRow | undefined
472 return Promise.resolve(row ? mapRun(row) : null)
473 },
474 // The most recent still-running run for the thread, so `reconstructChat`
475 // reports `activeRun` and a hydrating client (reload / another device /
476 // switching back to this thread) tails it via the durability replay. Without
477 // this method the contract treats the thread as having no live run.
478 findActiveRun(threadId) {
479 const row = activeStmt.get(threadId) as RunRow | undefined
480 return Promise.resolve(row ? mapRun(row) : null)
481 },
482 // Reclaim candidates for a sandbox reaper to sweep. Not thread-scoped —
483 // callers filter the result themselves when they need a subset.
484 listReclaimable(opts) {
485 const cutoff = opts.now - opts.ttlMs
486 const rows = reclaimableStmt.all(
487 cutoff,
488 ) as Array<unknown> as Array<RunRow>
489 return Promise.resolve(rows.map(mapRun))
490 },
491 })
492}
493
494// ---------------------------------------------------------------------------
495// InterruptStore — insert-if-absent, ordered listings.
496// ---------------------------------------------------------------------------
497function mapInterrupt(row: InterruptRow): InterruptRecord {
498 return {
499 interruptId: row.interrupt_id,
500 runId: row.run_id,
501 threadId: row.thread_id,
502 status: row.status as InterruptRecord['status'],
503 requestedAt: row.requested_at,
504 ...(row.resolved_at != null ? { resolvedAt: row.resolved_at } : {}),
505 payload: parseJson<Record<string, unknown>>(row.payload_json),
506 ...(row.response_json != null
507 ? { response: parseJson<unknown>(row.response_json) }
508 : {}),
509 }
510}
511
512function createInterruptStore(db: DatabaseSync) {
513 const insertStmt = db.prepare(
514 `INSERT INTO interrupts
515 (interrupt_id, run_id, thread_id, status, requested_at, payload_json, response_json)
516 VALUES (?, ?, ?, 'pending', ?, ?, ?)
517 ON CONFLICT(interrupt_id) DO NOTHING`,
518 )
519 const resolveStmt = db.prepare(
520 `UPDATE interrupts SET status = 'resolved', resolved_at = ?, response_json = ?
521 WHERE interrupt_id = ?`,
522 )
523 const cancelStmt = db.prepare(
524 `UPDATE interrupts SET status = 'cancelled', resolved_at = ? WHERE interrupt_id = ?`,
525 )
526 const getStmt = db.prepare('SELECT * FROM interrupts WHERE interrupt_id = ?')
527 // Every listing is ORDER BY requested_at ASC — the middleware and testkit
528 // rely on this stable ordering.
529 const listByThreadStmt = db.prepare(
530 'SELECT * FROM interrupts WHERE thread_id = ? ORDER BY requested_at ASC',
531 )
532 const listPendingByThreadStmt = db.prepare(
533 `SELECT * FROM interrupts WHERE thread_id = ? AND status = 'pending'
534 ORDER BY requested_at ASC`,
535 )
536 const listByRunStmt = db.prepare(
537 'SELECT * FROM interrupts WHERE run_id = ? ORDER BY requested_at ASC',
538 )
539 const listPendingByRunStmt = db.prepare(
540 `SELECT * FROM interrupts WHERE run_id = ? AND status = 'pending'
541 ORDER BY requested_at ASC`,
542 )
543 const mapRows = (rows: Array<unknown>): Array<InterruptRecord> =>
544 (rows as Array<InterruptRow>).map(mapInterrupt)
545 return defineInterruptStore({
546 create(record) {
547 // Insert-if-absent: a duplicate id must never clobber an already-resolved
548 // interrupt back to pending.
549 insertStmt.run(
550 record.interruptId,
551 record.runId,
552 record.threadId,
553 record.requestedAt,
554 JSON.stringify(record.payload),
555 record.response === undefined ? null : JSON.stringify(record.response),
556 )
557 return Promise.resolve()
558 },
559 resolve(interruptId, response) {
560 resolveStmt.run(
561 Date.now(),
562 response === undefined ? null : JSON.stringify(response),
563 interruptId,
564 )
565 return Promise.resolve()
566 },
567 cancel(interruptId) {
568 cancelStmt.run(Date.now(), interruptId)
569 return Promise.resolve()
570 },
571 get(interruptId) {
572 const row = getStmt.get(interruptId) as InterruptRow | undefined
573 return Promise.resolve(row ? mapInterrupt(row) : null)
574 },
575 list(threadId) {
576 return Promise.resolve(mapRows(listByThreadStmt.all(threadId)))
577 },
578 listPending(threadId) {
579 return Promise.resolve(mapRows(listPendingByThreadStmt.all(threadId)))
580 },
581 listByRun(runId) {
582 return Promise.resolve(mapRows(listByRunStmt.all(runId)))
583 },
584 listPendingByRun(runId) {
585 return Promise.resolve(mapRows(listPendingByRunStmt.all(runId)))
586 },
587 })
588}
589
590// ---------------------------------------------------------------------------
591// MetadataStore — scoped key/value JSON.
592// ---------------------------------------------------------------------------
593function assertStorableMetadata(value: unknown): void {
594 // SQL backends store JSON text in a NOT NULL column and cannot persist a
595 // nullish value. Reject it with a clear error (matching the sibling backends)
596 // instead of a cryptic driver failure; use `delete` to clear a value.
597 if (value == null) {
598 throw new TypeError(
599 `TanStack AI metadata values must be defined, non-null JSON; received ${
600 value === undefined ? '`undefined`' : '`null`'
601 }. Use \`delete(scope, key)\` to clear a value.`,
602 )
603 }
604}
605
606function createMetadataStore(db: DatabaseSync) {
607 const selectStmt = db.prepare(
608 'SELECT value_json FROM metadata WHERE scope = ? AND key = ?',
609 )
610 const upsertStmt = db.prepare(
611 `INSERT INTO metadata (scope, key, value_json) VALUES (?, ?, ?)
612 ON CONFLICT(scope, key) DO UPDATE SET value_json = excluded.value_json`,
613 )
614 const deleteStmt = db.prepare(
615 'DELETE FROM metadata WHERE scope = ? AND key = ?',
616 )
617 return defineMetadataStore({
618 get(scope, key) {
619 const row = selectStmt.get(scope, key) as MetadataRow | undefined
620 return Promise.resolve(row ? parseJson<unknown>(row.value_json) : null)
621 },
622 set(scope, key, value) {
623 assertStorableMetadata(value)
624 upsertStmt.run(scope, key, JSON.stringify(value))
625 return Promise.resolve()
626 },
627 delete(scope, key) {
628 deleteStmt.run(scope, key)
629 return Promise.resolve()
630 },
631 })
632}
633
634// ---------------------------------------------------------------------------
635// GenerationRunStore — the generation counterpart to RunStore.
636// ---------------------------------------------------------------------------
637//
638// Keyed by its own `runId` (the id the generation activity mints), with
639// `thread_id` the stable slot successive runs fill. `thread_id` is NOT NULL:
640// `findLatestForThread` is the only query that hydrates a run, so a row without
641// one could be written and then never read back. This stays a separate table
642// from `runs` rather than a status column on it because a generation run
643// carries its own activity/provider/model and its own artifacts.
644function mapGenerationRun(row: GenerationRunRow): GenerationRunRecord {
645 return {
646 runId: row.run_id,
647 threadId: row.thread_id,
648 activity: row.activity,
649 provider: row.provider,
650 model: row.model,
651 status: row.status as GenerationRunStatus,
652 startedAt: row.started_at,
653 ...(row.finished_at != null ? { finishedAt: row.finished_at } : {}),
654 ...(row.error_json != null
655 ? { error: parseJson<GenerationRunRecord['error']>(row.error_json) }
656 : {}),
657 ...(row.result_json != null
658 ? { result: parseJson<unknown>(row.result_json) }
659 : {}),
660 ...(row.artifacts_json != null
661 ? {
662 artifacts: parseJson<Array<PersistedArtifactRef>>(row.artifacts_json),
663 }
664 : {}),
665 ...(row.usage_json != null
666 ? { usage: parseJson<TokenUsage>(row.usage_json) }
667 : {}),
668 }
669}
670
671function createGenerationRunStore(db: DatabaseSync) {
672 const selectStmt = db.prepare(
673 'SELECT * FROM generation_runs WHERE run_id = ?',
674 )
675 const insertStmt = db.prepare(
676 `INSERT INTO generation_runs
677 (run_id, thread_id, activity, provider, model, status, started_at)
678 VALUES (?, ?, ?, ?, ?, ?, ?)
679 ON CONFLICT(run_id) DO NOTHING`,
680 )
681 const latestStmt = db.prepare(
682 `SELECT * FROM generation_runs WHERE thread_id = ?
683 ORDER BY started_at DESC LIMIT 1`,
684 )
685 return defineGenerationRunStore({
686 createOrResume(input) {
687 // INVARIANT (idempotency): same as the chat RunStore — a second call for
688 // a runId returns the stored record and mutates nothing.
689 const existing = selectStmt.get(input.runId) as
690 | GenerationRunRow
691 | undefined
692 if (existing) return Promise.resolve(mapGenerationRun(existing))
693 const status: GenerationRunStatus = input.status ?? 'running'
694 insertStmt.run(
695 input.runId,
696 input.threadId,
697 input.activity,
698 input.provider,
699 input.model,
700 status,
701 input.startedAt,
702 )
703 const created = selectStmt.get(input.runId) as
704 | GenerationRunRow
705 | undefined
706 return Promise.resolve(
707 created
708 ? mapGenerationRun(created)
709 : {
710 runId: input.runId,
711 threadId: input.threadId,
712 activity: input.activity,
713 provider: input.provider,
714 model: input.model,
715 status,
716 startedAt: input.startedAt,
717 },
718 )
719 },
720 update(runId, patch) {
721 // Same dynamic-SET shape as the chat RunStore; `error`, `result`,
722 // `artifacts` and `usage` are JSON columns rather than scalars.
723 const sets: Array<string> = []
724 const params: Array<string | number> = []
725 if (patch.status !== undefined) {
726 sets.push('status = ?')
727 params.push(patch.status)
728 }
729 if (patch.finishedAt !== undefined) {
730 sets.push('finished_at = ?')
731 params.push(patch.finishedAt)
732 }
733 if (patch.error !== undefined) {
734 sets.push('error_json = ?')
735 params.push(JSON.stringify(patch.error))
736 }
737 if (patch.result !== undefined) {
738 sets.push('result_json = ?')
739 params.push(JSON.stringify(patch.result))
740 }
741 if (patch.artifacts !== undefined) {
742 sets.push('artifacts_json = ?')
743 params.push(JSON.stringify(patch.artifacts))
744 }
745 if (patch.usage !== undefined) {
746 sets.push('usage_json = ?')
747 params.push(JSON.stringify(patch.usage))
748 }
749 if (sets.length === 0) return Promise.resolve()
750 params.push(runId)
751 db.prepare(
752 `UPDATE generation_runs SET ${sets.join(', ')} WHERE run_id = ?`,
753 ).run(...params)
754 return Promise.resolve()
755 },
756 get(runId) {
757 const row = selectStmt.get(runId) as GenerationRunRow | undefined
758 return Promise.resolve(row ? mapGenerationRun(row) : null)
759 },
760 // The most recent run linked to a thread. `reconstructGeneration` calls
761 // this so a `persistence: true` client hydrates the last generation for its
762 // thread from the stable thread id alone, with no run id to hand.
763 findLatestForThread(threadId) {
764 const row = latestStmt.get(threadId) as GenerationRunRow | undefined
765 return Promise.resolve(row ? mapGenerationRun(row) : null)
766 },
767 })
768}
769
770// ---------------------------------------------------------------------------
771// ArtifactStore — one metadata row per generated file.
772// ---------------------------------------------------------------------------
773function mapArtifact(row: ArtifactRow): ArtifactRecord {
774 return {
775 artifactId: row.artifact_id,
776 runId: row.run_id,
777 threadId: row.thread_id,
778 ...(row.blob_key != null ? { blobKey: row.blob_key } : {}),
779 name: row.name,
780 mimeType: row.mime_type,
781 size: row.size,
782 ...(row.source_url != null ? { sourceUrl: row.source_url } : {}),
783 createdAt: row.created_at,
784 }
785}
786
787function createArtifactStore(db: DatabaseSync) {
788 const upsertStmt = db.prepare(
789 `INSERT INTO artifacts
790 (artifact_id, run_id, thread_id, blob_key, name, mime_type, size, source_url, created_at)
791 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
792 ON CONFLICT(artifact_id) DO UPDATE SET
793 run_id = excluded.run_id, thread_id = excluded.thread_id,
794 blob_key = excluded.blob_key, name = excluded.name,
795 mime_type = excluded.mime_type, size = excluded.size,
796 source_url = excluded.source_url, created_at = excluded.created_at`,
797 )
798 const selectStmt = db.prepare('SELECT * FROM artifacts WHERE artifact_id = ?')
799 const byRunStmt = db.prepare(
800 'SELECT * FROM artifacts WHERE run_id = ? ORDER BY created_at ASC',
801 )
802 const deleteStmt = db.prepare('DELETE FROM artifacts WHERE artifact_id = ?')
803 const deleteForRunStmt = db.prepare('DELETE FROM artifacts WHERE run_id = ?')
804 return defineArtifactStore({
805 save(record) {
806 // Upsert, not insert-if-absent: unlike an interrupt, re-saving an
807 // artifact is a correction of its own metadata, never a state rollback.
808 upsertStmt.run(
809 record.artifactId,
810 record.runId,
811 record.threadId,
812 record.blobKey ?? null,
813 record.name,
814 record.mimeType,
815 record.size,
816 record.sourceUrl ?? null,
817 record.createdAt,
818 )
819 return Promise.resolve()
820 },
821 get(artifactId) {
822 const row = selectStmt.get(artifactId) as ArtifactRow | undefined
823 return Promise.resolve(row ? mapArtifact(row) : null)
824 },
825 list(runId) {
826 const rows: Array<unknown> = byRunStmt.all(runId)
827 return Promise.resolve((rows as Array<ArtifactRow>).map(mapArtifact))
828 },
829 delete(artifactId) {
830 deleteStmt.run(artifactId)
831 return Promise.resolve()
832 },
833 deleteForRun(runId) {
834 deleteForRunStmt.run(runId)
835 return Promise.resolve()
836 },
837 })
838}
839
840// ---------------------------------------------------------------------------
841// BlobStore — the bytes, in a BLOB column.
842// ---------------------------------------------------------------------------
843const textEncoder = new TextEncoder()
844const textDecoder = new TextDecoder()
845
846async function bytesFromBlobBody(body: BlobBody): Promise<Uint8Array> {
847 if (typeof body === 'string') return textEncoder.encode(body)
848 if (body instanceof ArrayBuffer) return new Uint8Array(body.slice(0))
849 if (ArrayBuffer.isView(body)) {
850 return new Uint8Array(
851 body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength),
852 )
853 }
854 if (body instanceof Blob) return new Uint8Array(await body.arrayBuffer())
855
856 // ReadableStream<Uint8Array>: drain it into one buffer.
857 const reader = body.getReader()
858 const chunks: Array<Uint8Array> = []
859 let total = 0
860 for (;;) {
861 const { done, value } = await reader.read()
862 if (done) break
863 chunks.push(value)
864 total += value.byteLength
865 }
866 const bytes = new Uint8Array(total)
867 let offset = 0
868 for (const chunk of chunks) {
869 bytes.set(chunk, offset)
870 offset += chunk.byteLength
871 }
872 return bytes
873}
874
875function mapBlobRecord(row: BlobMetaRow): BlobRecord {
876 return {
877 key: row.key,
878 size: row.size,
879 etag: row.etag,
880 ...(row.content_type != null ? { contentType: row.content_type } : {}),
881 ...(row.custom_metadata_json != null
882 ? {
883 customMetadata: parseJson<Record<string, string>>(
884 row.custom_metadata_json,
885 ),
886 }
887 : {}),
888 createdAt: row.created_at,
889 updatedAt: row.updated_at,
890 }
891}
892
893function blobObject(
894 record: BlobRecord,
895 bytes: Uint8Array,
896 range?: { offset: number; length: number },
897): BlobObject {
898 return {
899 ...record,
900 // `size` keeps describing the whole object; `range` describes these bytes.
901 ...(range ? { range } : {}),
902 body: new ReadableStream<Uint8Array>({
903 start(controller) {
904 controller.enqueue(bytes.slice())
905 controller.close()
906 },
907 }),
908 arrayBuffer() {
909 const copy = new ArrayBuffer(bytes.byteLength)
910 new Uint8Array(copy).set(bytes)
911 return Promise.resolve(copy)
912 },
913 text: () => Promise.resolve(textDecoder.decode(bytes)),
914 }
915}
916
917function createBlobStore(db: DatabaseSync) {
918 const upsertStmt = db.prepare(
919 `INSERT INTO blobs
920 (key, body, size, etag, content_type, custom_metadata_json, created_at, updated_at)
921 VALUES (?, ?, ?, ?, ?, ?, ?, ?)
922 ON CONFLICT(key) DO UPDATE SET
923 body = excluded.body, size = excluded.size, etag = excluded.etag,
924 content_type = excluded.content_type,
925 custom_metadata_json = excluded.custom_metadata_json,
926 updated_at = excluded.updated_at`,
927 )
928 const selectStmt = db.prepare('SELECT * FROM blobs WHERE key = ?')
929 // Everything EXCEPT `body`. A ranged read needs the metadata to clamp
930 // against, and `SELECT *` would materialize the whole object just to hand
931 // back a slice of it — the cost a range request exists to avoid.
932 const selectMetaStmt = db.prepare(
933 `SELECT key, size, etag, content_type, custom_metadata_json,
934 created_at, updated_at
935 FROM blobs WHERE key = ?`,
936 )
937 const rangeStmt = db.prepare(
938 'SELECT substr(body, ?, ?) AS body FROM blobs WHERE key = ?',
939 )
940 const createdAtStmt = db.prepare('SELECT created_at FROM blobs WHERE key = ?')
941 const deleteStmt = db.prepare('DELETE FROM blobs WHERE key = ?')
942 // Prefix match via `substr(...) = ?` rather than LIKE: SQLite's LIKE is
943 // case-INsensitive for ASCII and treats `%`/`_` as wildcards, and the
944 // contract says a prefix matches literally and case-sensitively. Letting
945 // SQLite compute `length(?)` keeps the character count in SQLite's terms
946 // instead of JS UTF-16 code units.
947 const PREFIX_WHERE = 'substr(key, 1, length(?)) = ?'
948 // Etags only have to change when the bytes do; a per-put counter keeps them
949 // distinct even for two writes inside the same millisecond.
950 let putSequence = 0
951
952 return defineBlobStore({
953 async put(key, body, options) {
954 const bytes = await bytesFromBlobBody(body)
955 const now = Date.now()
956 const prior = createdAtStmt.get(key) as { created_at: number } | undefined
957 // First write stamps createdAt; an overwrite keeps it and moves updatedAt.
958 const createdAt = prior?.created_at ?? now
959 const etag = `${now}-${putSequence++}`
960 const contentType =
961 options?.contentType ?? (body instanceof Blob ? body.type : '')
962 const record: BlobRecord = {
963 key,
964 size: bytes.byteLength,
965 etag,
966 ...(contentType ? { contentType } : {}),
967 ...(options?.customMetadata
968 ? { customMetadata: { ...options.customMetadata } }
969 : {}),
970 createdAt,
971 updatedAt: now,
972 }
973 upsertStmt.run(
974 key,
975 bytes,
976 record.size ?? bytes.byteLength,
977 etag,
978 record.contentType ?? null,
979 record.customMetadata ? JSON.stringify(record.customMetadata) : null,
980 createdAt,
981 now,
982 )
983 return record
984 },
985 get(key, options) {
986 if (!options?.range) {
987 const row = selectStmt.get(key) as BlobRow | undefined
988 return Promise.resolve(
989 row ? blobObject(mapBlobRecord(row), row.body) : null,
990 )
991 }
992 // Metadata WITHOUT the bytes, then the slice: clamp the request to the
993 // object the way every byte-storing backend must. `resolveBlobRange` is
994 // the shared implementation, and it throws on an offset past the end so
995 // an unsatisfiable range can't be served as a 206 — a route answers 416
996 // from `record.size` before getting here.
997 const meta = selectMetaStmt.get(key) as BlobMetaRow | undefined
998 if (!meta) return Promise.resolve(null)
999 const served = resolveBlobRange(meta.size, options.range)
1000 // Slice in SQLite (1-based, byte-wise over a BLOB), so seeking inside a
1001 // video reads a few hundred KB and not the whole clip. Reading the row
1002 // with `SELECT *` first would have loaded it anyway, which is the whole
1003 // cost a range request exists to avoid.
1004 const sliced = rangeStmt.get(served.offset + 1, served.length, key) as
1005 | Pick<BlobRow, 'body'>
1006 | undefined
1007 if (!sliced) return Promise.resolve(null)
1008 return Promise.resolve(
1009 blobObject(mapBlobRecord(meta), sliced.body, served),
1010 )
1011 },
1012 head(key) {
1013 // Metadata only: never pull the bytes for a question about the object.
1014 const row = selectMetaStmt.get(key) as BlobMetaRow | undefined
1015 return Promise.resolve(row ? mapBlobRecord(row) : null)
1016 },
1017 delete(key) {
1018 deleteStmt.run(key)
1019 return Promise.resolve()
1020 },
1021 list(options?: BlobListOptions): Promise<BlobListPage> {
1022 if (options?.limit === 0) {
1023 return Promise.resolve({ objects: [], truncated: false })
1024 }
1025 const prefix = options?.prefix ?? ''
1026 const params: Array<string | number> = [prefix, prefix]
1027 let where = PREFIX_WHERE
1028 if (options?.cursor !== undefined) {
1029 // Keyset paging: strictly-following keys, in the same byte order as the
1030 // sort, so a full scan visits every key exactly once.
1031 where += ' AND key > ?'
1032 params.push(options.cursor)
1033 }
1034 let sql = `SELECT * FROM blobs WHERE ${where} ORDER BY key ASC`
1035 const limit = options?.limit
1036 // One extra row detects truncation without a second COUNT query.
1037 if (limit !== undefined) {
1038 sql += ' LIMIT ?'
1039 params.push(limit + 1)
1040 }
1041 const selected: Array<unknown> = db.prepare(sql).all(...params)
1042 const rows = (selected as Array<BlobRow>).map(mapBlobRecord)
1043 if (limit !== undefined && rows.length > limit) {
1044 const objects = rows.slice(0, limit)
1045 const cursor = objects.at(-1)?.key
1046 return Promise.resolve({
1047 objects,
1048 truncated: true,
1049 ...(cursor !== undefined ? { cursor } : {}),
1050 })
1051 }
1052 return Promise.resolve({ objects: rows, truncated: false })
1053 },
1054 })
1055}
1056
1057export interface SqlitePersistenceOptions {
1058 /** `:memory:`, a filesystem path, or a `file:`-prefixed filesystem path. */
1059 url: string
1060 /** Create the TanStack AI tables on open (idempotent). */
1061 migrate?: boolean
1062}
1063
1064/**
1065 * Every store this backend provides, spelled out.
1066 *
1067 * Parameterize `AIPersistence` rather than leaving it bare: the unparameterized
1068 * type is the all-optional store bag, and `withPersistence` /
1069 * `withGenerationPersistence` reject it because `stores.messages` /
1070 * `stores.generationRuns` are possibly `undefined`. Spelling out all seven is
1071 * what makes one backend serve both middlewares — there is no packaged named
1072 * shape for "chat + generation" because the combination is a product choice.
1073 */
1074export type SqliteAIPersistence = AIPersistence<{
1075 messages: MessageStore
1076 runs: RunStore
1077 interrupts: InterruptStore
1078 metadata: MetadataStore
1079 generationRuns: GenerationRunStore
1080 artifacts: ArtifactStore
1081 blobs: BlobStore
1082}>
1083
1084/**
1085 * Build an `AIPersistence` over a `node:sqlite` database. The returned object
1086 * also exposes `close()` to release the file handle.
1087 *
1088 * Provides all four state stores (`messages`, `runs`, `interrupts`, `metadata`)
1089 * AND all three generation stores (`generationRuns`, `artifacts`, `blobs`), so
1090 * the same instance backs `withPersistence` and `withGenerationPersistence`.
1091 * Cross-worker coordination is a separate seam — a `LockStore` wired with
1092 * `withLocks`, not an eighth entry in `stores`.
1093 */
1094export function sqlitePersistence(
1095 options: SqlitePersistenceOptions,
1096): SqliteAIPersistence & { close: () => void } {
1097 const filename = normalizeSqliteUrl(options.url)
1098 ensureParentDirectory(filename)
1099 const db = new DatabaseSync(filename)
1100 try {
1101 if (options.migrate) {
1102 db.exec(SCHEMA_SQL)
1103 addMissingColumns(db)
1104 }
1105 } catch (error) {
1106 db.close()
1107 throw error
1108 }
1109
1110 const persistence = defineAIPersistence({
1111 stores: {
1112 messages: createMessageStore(db),
1113 runs: createRunStore(db),
1114 interrupts: createInterruptStore(db),
1115 metadata: createMetadataStore(db),
1116 generationRuns: createGenerationRunStore(db),
1117 artifacts: createArtifactStore(db),
1118 blobs: createBlobStore(db),
1119 },
1120 })
1121
1122 let closed = false
1123 return {
1124 ...persistence,
1125 close() {
1126 if (closed) return
1127 db.close()
1128 closed = true
1129 },
1130 }
1131}
1132
1133// ---------------------------------------------------------------------------
1134// URL / path helpers (kept identical to the packaged Node SQLite factory so the
1135// `{ url, migrate }` call site is a drop-in).
1136// ---------------------------------------------------------------------------
1137function normalizeSqliteUrl(url: string): string {
1138 if (url === ':memory:' || url === 'file::memory:') return ':memory:'
1139 if (url.startsWith('file://')) return validateFilename(fileURLToPath(url))
1140 if (url.startsWith('file:')) {
1141 return validateFilename(url.slice('file:'.length))
1142 }
1143 const isWindowsPath = /^[A-Za-z]:[\\/]/.test(url)
1144 if (!isWindowsPath && /^[A-Za-z][A-Za-z\d+.-]*:/.test(url)) {
1145 throw new Error(`Unsupported SQLite URL scheme: ${url}`)
1146 }
1147 return validateFilename(url)
1148}
1149
1150function validateFilename(filename: string): string {
1151 if (filename.length === 0 || filename.includes('\0')) {
1152 throw new Error('SQLite URL must identify a non-empty filesystem path')
1153 }
1154 return filename
1155}
1156
1157function ensureParentDirectory(filename: string): void {
1158 if (filename === ':memory:') return
1159 const parent = dirname(filename)
1160 if (parent !== '.') mkdirSync(parent, { recursive: true })
1161}