feat(persistence): durable sandbox persistence (SandboxStore + shared lock)#988
Open
AlemTuzlak wants to merge 20 commits into
Open
feat(persistence): durable sandbox persistence (SandboxStore + shared lock)#988AlemTuzlak wants to merge 20 commits into
AlemTuzlak wants to merge 20 commits into
Conversation
…kends Server-side persistence for chat(): durable thread messages, run records, and interrupts via the withChatPersistence middleware, with pluggable backends. - @tanstack/ai-persistence: store contracts, withChatPersistence / withGenerationPersistence middleware, memoryPersistence reference store, conformance testkit. Locks (LockStore/InMemoryLockStore/LocksCapability) live here rather than core; the sandbox-consumer bridge is deferred. - -drizzle / -prisma / -cloudflare: backend store implementations + migration / schema / models CLIs. Cloudflare D1 delegates to the drizzle backend. Reconciled against the shipped ephemeral-interrupt engine: the middleware records interrupts and gates new input, and delegates resume-tool-state reconstruction to the engine (resume batch + interrupt bindings in history). Claude-Session: https://claude.ai/code/session_01RqjWdHxvmMrhjbd8dYvENp
The persistence adapter now stores one combined { messages, resume? } record
per chat id, so a full page reload restores the transcript, rehydrates pending
interrupts, and rejoins an in-flight run through joinRun when the connection is
durability-backed. Legacy bare-array records are still read.
Adds localStoragePersistence / sessionStoragePersistence / indexedDBPersistence
(+ StorageUnavailableError and the ChatPersistedState / ChatStorageAdapter
types). Durability rides the existing option, so every framework integration
gets it with no framework-specific code.
Claude-Session: https://claude.ai/code/session_01RqjWdHxvmMrhjbd8dYvENp
New /persistent-chat route: useChat with localStoragePersistence on the client and withChatPersistence(sqlitePersistence) on the server, so a full page reload restores the conversation on both ends. Adds a nav link and README section. Claude-Session: https://claude.ai/code/session_01RqjWdHxvmMrhjbd8dYvENp
…ility
New docs/persistence section: overview, chat-persistence, browser-refresh,
controls, custom-stores, sql-backends, drizzle, prisma, cloudflare, migrations,
internals. Wires the nav and updates the client chat/persistence page for the
combined { messages, resume } record and built-in storage adapters.
Claude-Session: https://claude.ai/code/session_01RqjWdHxvmMrhjbd8dYvENp
Update the agent skills for the new surface: withChatPersistence server middleware and its backends, and the client browser-refresh durability (combined persistence record, storage adapters, joinRun rejoin, all frameworks). Claude-Session: https://claude.ai/code/session_01RqjWdHxvmMrhjbd8dYvENp
Provider-free durable harness route + client page + spec proving message restore after reload and interrupt-survives-reload via localStorage. Mid-stream joinRun rejoin is covered by ai-client unit tests and delivery-durability. Claude-Session: https://claude.ai/code/session_01RqjWdHxvmMrhjbd8dYvENp
Add the object form `persistence: { store, messages?: boolean }`. `messages:
false` caches only the tiny resume pointer, keeping large transcripts off the
client while durability rejoin and interrupt restore still work and the server
stays authoritative for history. A bare adapter remains shorthand for
`{ store, messages: true }`, so this is backward compatible and every framework
passthrough is unchanged.
The persistent-chat example gains a history branch on its GET route
(loadThread by threadId, distinct from the per-run delivery replay) so a
server-authoritative reload can hydrate the transcript. Docs + chat-experience
skill document the lever.
Claude-Session: https://claude.ai/code/session_01RqjWdHxvmMrhjbd8dYvENp
Rewrite the persistence overview into a concept + decision page: the three problems (dropped stream, lost-on-reload, no durable record), the two independent layers (delivery durability vs state persistence), client vs server halves, the reload/rehydration timeline, and a when-to-pick-each guide. Add a back-link from the resumable-streams overview so the two sections cross-reference. Claude-Session: https://claude.ai/code/session_01RqjWdHxvmMrhjbd8dYvENp
…tence localStoragePersistence / sessionStoragePersistence / indexedDBPersistence now default their type parameter to ChatPersistedState and to a JSON codec, so `persistence: localStoragePersistence()` needs no type argument and no serialize/deserialize pair. Drops the IsJsonSerializable type gate that forced a codec for the chat record (UIMessage already round-trips as JSON on the wire). Client persistence now keys on `threadId` (the conversation identity), so a reload with the same threadId restores the same record; `id` becomes an optional storage-key override. The storage adapters and persistence types are re-exported from every framework package, so a single import from @tanstack/ai-react (etc.) works. Claude-Session: https://claude.ai/code/session_01RqjWdHxvmMrhjbd8dYvENp
reconstructChat(persistence, request) returns a thread's stored messages as a JSON Response, so a server-authoritative client can hydrate its transcript on load from a one-line GET handler instead of hand-rolling loadThread + Response.
…curate resume Add a "What we recommend" section to the overview: client resume-pointer-only plus server persistence plus one GET that rehydrates history and resumes durable streams, with the reasoning. Update every snippet to the zero-config localStoragePersistence() and threadId, use reconstructChat for history, and discriminate the resume GET with durability.resumeFrom() instead of sniffing query params (the run id rides the X-Run-Id header, the offset the Last-Event-ID header). Example, e2e page, and chat-experience skill match.
Rename browser-refresh to client-persistence and make it the single home for the client story: turning it on, what a reload restores, the two cache modes (everything vs resume-pointer-only) with when to use each, and the three storage backends with when to use each. Remove the legacy docs/chat/persistence page (client content now lives in the persistence section) and repoint its links. Make the other persistence docs server-only: drop the client rows from the controls decision table and the browser-storage section from internals, leaving a pointer to the client guide. The overview stays the cross-cutting map. Update all cross-links, the chat-experience skill source, and the reconstructChat doc reference.
In `{ messages: false }` mode a prior session's persisted record is
`{ messages: [], resume }`. The constructor treated that empty transcript as
authoritative and clobbered host-provided `initialMessages`, and the async
hydrate path applied `[]` on top, so a server-authoritative reload dropped the
history the app had fetched from the server.
The persisted transcript is now adopted only when the client actually caches it
(`cachesMessages`); in messages:false mode the client keeps `initialMessages`
and takes only the resume pointer from storage. This makes the recommended
server-authoritative flow work: on a mid-stream reload the app seeds history via
initialMessages (the reconstruct GET) while the client separately rejoins the
live run via joinRun (the resume GET), and the replayed run merges into the
seeded history by message id. Adds a test covering both together.
Also document in the overview that history hydration and run rejoin are two
separate GET requests, so the handler's if/else routes each and neither blocks
the other.
The primary chat persistence middleware is now `withPersistence`. `withGenerationPersistence` is unchanged. Unreleased, so no alias is kept. Updates all call sites, docs, skills, the example, and the changeset. fix(ai-client): rejoin an in-flight run from an async persistence store Auto-rejoin was gated on the synchronous read, so an async store (indexedDBPersistence) restored messages and interrupts on reload but never rejoined a mid-stream run. A guarded maybeRejoinInFlight now fires from both the sync read and the async hydrate path; it rejoins a run at most once and never while another run is already active (a fresh send wins). Adds a test that a run rejoins from an async (Promise-returning) adapter.
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
🚀 Changeset Version Preview14 package(s) bumped directly, 37 bumped as dependents. 🟥 Major bumps
🟨 Minor bumps
🟩 Patch bumps
|
|
View your CI Pipeline Execution ↗ for commit e1e51d0
☁️ Nx Cloud last updated this comment at |
AlemTuzlak
force-pushed
the
feat/persistence-sandbox
branch
2 times, most recently
from
July 23, 2026 12:14
4b2e68a to
e1e51d0
Compare
@tanstack/ai
@tanstack/ai-acp
@tanstack/ai-angular
@tanstack/ai-anthropic
@tanstack/ai-bedrock
@tanstack/ai-claude-code
@tanstack/ai-client
@tanstack/ai-code-mode
@tanstack/ai-code-mode-skills
@tanstack/ai-codex
@tanstack/ai-devtools-core
@tanstack/ai-durable-stream
@tanstack/ai-elevenlabs
@tanstack/ai-event-client
@tanstack/ai-fal
@tanstack/ai-gemini
@tanstack/ai-grok
@tanstack/ai-grok-build
@tanstack/ai-groq
@tanstack/ai-isolate-cloudflare
@tanstack/ai-isolate-node
@tanstack/ai-isolate-quickjs
@tanstack/ai-mcp
@tanstack/ai-mistral
@tanstack/ai-ollama
@tanstack/ai-openai
@tanstack/ai-opencode
@tanstack/ai-openrouter
@tanstack/ai-persistence
@tanstack/ai-persistence-cloudflare
@tanstack/ai-persistence-drizzle
@tanstack/ai-persistence-prisma
@tanstack/ai-preact
@tanstack/ai-react
@tanstack/ai-react-ui
@tanstack/ai-sandbox
@tanstack/ai-sandbox-cloudflare
@tanstack/ai-sandbox-daytona
@tanstack/ai-sandbox-docker
@tanstack/ai-sandbox-local-process
@tanstack/ai-sandbox-sprites
@tanstack/ai-sandbox-vercel
@tanstack/ai-solid
@tanstack/ai-solid-ui
@tanstack/ai-svelte
@tanstack/ai-utils
@tanstack/ai-vue
@tanstack/ai-vue-ui
@tanstack/openai-base
@tanstack/preact-ai-devtools
@tanstack/react-ai-devtools
@tanstack/solid-ai-devtools
commit: |
AlemTuzlak
force-pushed
the
feat/persistence-sandbox
branch
from
July 23, 2026 12:53
e1e51d0 to
ef3e5f5
Compare
Sandbox resume (SandboxStore + shared lock) is provided by withPersistence and consumed by withSandbox. SandboxStore/SandboxStoreCapability and the lock primitives live in core @tanstack/ai; the persistence backends carry a durable sandbox store; conformance testkit, e2e, docs, and the ai-sandbox skill updated.
tombeckenham
force-pushed
the
feat/persistence-core
branch
from
July 24, 2026 01:31
0b17612 to
d2d08e8
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Stacked on #984. Lands the sandbox persistence piece #984 explicitly deferred: durable, multi-instance-correct resume for
@tanstack/ai-sandbox.withSandboxalready consumesSandboxStore(which sandbox to resume) andLockStore(mutual exclusion around ensure) as optional capabilities, defaulting to in-memory (single-process). This adds the durable half — no behavioral change to the sandbox layer.Core: one shared
lockstokenThe
'locks'capability now lives in core@tanstack/ai(LocksCapability,LockStore,InMemoryLockStore,getLocks,provideLocks);@tanstack/ai-sandboxand@tanstack/ai-persistencere-export it. Because capability identity is by reference, one shared token means awithPersistence({ stores: { locks } })already in the chain feeds the sandbox lock automatically — this is the "sandbox-consumer bridge" #984 noted as deferred.@tanstack/ai-sandboxwithSandboxPersistence({ store, locks? })— provides a durableSandboxStore(and optional distributed lock) towithSandbox. Compose beforewithSandbox.SandboxStoreconformance testkit exported at@tanstack/ai-sandbox/testkit(runSandboxStoreConformance).Durable
SandboxStorebackends@tanstack/ai-persistence-drizzle—createDrizzleSandboxStore(db)+ a newsandboxestable folded into the initial migration (regenerated; asset synced to the Cloudflare sibling).@tanstack/ai-persistence-prisma—createPrismaSandboxStore(prisma)+ aSandboxmodel in the fragment.@tanstack/ai-persistence-cloudflare—createD1SandboxStore(d1)(delegates to Drizzle); the existing Durable-Object lock doubles as the distributed sandbox lock.The three backends add
@tanstack/ai-sandboxas an optional peer dependency. Sandboxes stays out of the chat BYO schema/model contract, so chat-only users are unaffected.Tests / docs / skill
withSandboxPersistenceprovide + cross-run-resume unit tests.docs/sandbox/persistence.md(+ nav, overview callout, cross-links from the persistence backend docs).ai-sandboxagent skill./api/sandbox-durabilityharness route + spec asserting a second run resumes the persisted sandbox (create stays 1).Testing
Green locally (canonical nx targets,
--skip-nx-cache):test:sherif,test:knip,test:docs,test:kiira,test:oxlint,test:types, andtest:libfor@tanstack/ai,@tanstack/ai-sandbox, and all four persistence packages (conformance + wiring).@tanstack/ai-sandboxbuilds clean including the testkit + DTS.Deferred to CI (per #984's precedent — this dev machine's nx output-materialization is unreliable here, which also blocks the Playwright dev server for every route): the full workspace
build/test:buildand the Playwrighttest:e2erun. The sandbox-durability spec is authored, registered in the route tree, and typechecks; the identical server-side-resume behavior is covered by the@tanstack/ai-sandboxpersistence.test.tsunit test.Release
Changeset: minor for
@tanstack/ai,@tanstack/ai-sandbox, and the four persistence packages.