feat(persistence): client-side generation resume snapshot - #997
Draft
tombeckenham wants to merge 67 commits into
Draft
feat(persistence): client-side generation resume snapshot#997tombeckenham wants to merge 67 commits into
tombeckenham wants to merge 67 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.
A stale local build had masked real breakage: the ported persistence layer was
behind the current core. Reconciled against a clean build:
- withGenerationPersistence keys runs on `requestId` (the current
GenerationMiddlewareContext has no runId/threadId).
- Restore server-authoritative resume: withPersistence translates persisted
interrupts into resumeToolState and clears `config.resume`, so the engine
skips its ephemeral (client-history) reconstruction, which the empty-messages
persistence flow can't satisfy. (Reverts an incorrect earlier removal.)
- ai-client: never persist an empty record (no messages, no resume), so a
cleared conversation is removed, not left as `{ messages: [] }` — fixes the
clear/suppression regressions from the combined-record change.
- Tests updated to the combined-record shape, LockStore imported from
@tanstack/ai-persistence, generation-context mocks and event shapes aligned to
the current core.
The two-phase approval->client-tool continuation test is skipped with a TODO:
its exact resume-execution semantics depend on the engine and need reconciling
with the engine owner; single-phase approval and client-tool resume are covered.
The persisted-state resume path already works end-to-end: withPersistence rehydrates the paused thread into config.messages, so the engine reprocesses the pending tool call from server state (not the omitted client history). Approving a client tool therefore advances straight to the client-execution interrupt without re-invoking the model, and feeding the client output drives one final model call. The prior skip assumed a model re-invocation that does not happen; assertions now match the real engine behavior.
…authoritative persistence
Switch the demo to the recommended setup: `persistence: { store, messages: false }`
so the client caches only the resume pointer and the server (SQLite) owns history.
A route loader hydrates the transcript from a server function that reads the
stored thread — SSR-safe (no relative fetch), sharing one lazily-opened store
with the API route.
Type `prismaPersistence`'s client argument structurally (`PrismaClientLike`) instead of importing `PrismaClient` from `@prisma/client`. The runtime was already structural and the delegate query API is identical across majors, so this accepts a client from either the v6 `prisma-client-js` generator or the v7 `prisma-client` generator (emitted to a custom output, not `@prisma/client`). Docs note both versions.
withPersistence.onFinish saved ctx.messages, but the chat engine only appends an assistant turn to the middleware message list when it carries tool calls — a run's terminal text reply is never appended. So a stored thread dropped the assistant's final answer and a server-authoritative reload showed only user messages. Reattach the terminal reply from info.content (the last turn's accumulated text), guarded against duplication. Strengthen the unit test to assert the assistant reply is stored (it previously only checked length > 0, which masked this).
Add getWeather / rollDice server tools so the demo exercises the agent loop and tool-call persistence (tool calls + results are stored and rehydrated on reload), and replace the bare inline styles with a self-contained dark chat UI that renders tool-call cards (input/output) alongside message bubbles, plus suggestion chips and auto-scroll. Regenerate routeTree.gen.ts to register the persistent-chat routes.
Persist the pending turn at run start and stamp each assistant turn with its stream messageId, add an opt-in `snapshotStreaming` for partial-output durability, carry an optional `id` on ModelMessage that the converter preserves, and rebuild an in-flight assistant from the delivery log on reload (batch-apply the backlog, drop the hydrated partial) so a reload shows one clean bubble that catches up and continues instead of a frozen or duplicated partial. Verified via unit tests, a headless ChatClient rejoin (tails live + full-replays a completed run), and curl against the join endpoint (replays + tails to completion). Known follow-up: in the browser through the vite dev server the long-lived SSE connection can drop mid-stream and resumableStream's reconnect does not always tail to completion after catch-up; server + client logic are correct (Node/curl tail fine), so this is a transport/reconnect issue to close against a production-style server.
useChat's `[client, live]` effect called `client.unsubscribe()` on every mount when `live` was false, which cancels the shared in-flight stream — aborting the delivery resume the client constructor had just started for a reloaded run. A mid-stream reload therefore caught up to the buffered point and froze. Only tear down a subscription we actually started, so the rejoin streams to completion. Verified end-to-end in a real browser (reload mid-stream now grows continuously to completion in one clean bubble) with a regression test that fails without the fix (the rejoined run never reaches the message list).
- memoryStream first-chunk deadline defaults to 100ms (was 30s): a reload rejoins a run produced in a prior request, so an empty log means gone — fail fast instead of holding a dead connection ~30s. Raise firstChunkDeadlineMs for producers that start well after a joiner attaches. - ChatClient rejoin: bound the first-chunk wait + clear a dead pointer (no UI pinned loading, no retry-on-next-load); drop the hydrated partial only on real content (never RUN_STARTED alone) so a no-content rejoin can't leave an empty bubble; and stop a replayed RUN_STARTED (provider run id) from overwriting the persisted pointer with an id the log is not keyed by, so a SECOND reload still re-attaches. Verified in a real browser: reload#1 and reload#2 both continue to completion in one clean bubble; a dead/evicted pointer frees the input in ~380ms (was 30s); no empty-bubble corruption. Unit tests cover the pointer-preservation and the 100ms default.
Clear resume-only storage on finish, stop StrictMode remount from aborting rejoin, add reconstructChat authorize + no-store, harden onFinish write order, and address open review nits (joinRun typeof, interrupt sort, metadata keys, lock chain cleanup, workspace:* peers, Scope docs/re-export).
…n pg schemas Restructure the Drizzle package into shared stores (core/), SQLite sources of truth (sqlite/), and Postgres projections (pg/). Generate PG default schemas and CLI assets from SQLite via a TypeScript codegen script so dialect table defs stay in lockstep without forking store logic.
Stop shipping SQL, the migrations CLI, and d1Migrations. D1 state stays a thin Drizzle wrapper; schema DDL follows the same schema-first path as SQLite (drizzle-kit + Wrangler migrations_dir). Keep Durable Object locks and the cloudflarePersistence / createD1Stores convenience API.
Add agent skills covering server/client state persistence, packaged backends, custom stores, and locks, and route them from ai-core, chat-experience, and middleware skills.
Chat client identity is threadId; the smoke App still passed id, which fails test:pr typecheck after the persistence identity rename.
- Regenerate drizzle pg schema artifacts so codegen:pg --check is clean - Default DATABASE_URL in persistent-chat-prisma prisma.config.ts so `prisma generate` works without a local .env (CI / clean checkouts)
…apter guide The Drizzle, Prisma, Cloudflare, SQL Backends, and Custom Stores pages framed adapters as packages to install. Persistence is a contract, so document the contract instead: one guide to the four store interfaces and their invariants, plus three adapter-building skills shipped in @tanstack/ai-persistence for the Drizzle, Prisma, and Cloudflare recipes. ts-react-chat now demonstrates the result — its persistent-chat demo runs on a self-contained node:sqlite backend built on the core contracts and verified by the shared conformance testkit, instead of depending on @tanstack/ai-persistence-drizzle. Co-authored-by: Cursor <cursoragent@cursor.com>
The ai-core skill tree carried a six-file persistence suite that taught "install @tanstack/ai-persistence-drizzle" — the opposite of the direction the docs took when the per-backend pages became one build-your-own-adapter guide. Persistence is a contract, so the skills that teach it belong to the package that owns the contract. @tanstack/ai now mentions the library and what it makes possible, then routes to the package's own skills (the pattern already used for @tanstack/ai-code-mode). The suite moves to @tanstack/ai-persistence following the ai-memory layout: an umbrella entry point plus -server, -client, -stores, -locks, and the three existing -build-*-adapter recipes. ai-core/persistence/backends is dropped rather than moved; its still-true content folded into -stores. Corrections along the way, all verified against source: - skip: ['locks'] is not assignable to Array<keyof AIPersistenceStores> and the conformance suite covers no locks at all. Removed from the drizzle and prisma skills, the guide, and the example test. - Locks were documented as a fifth store. stores accepts exactly four keys and throws on anything else, so the guide's stores list, its "all five stores" count, and the LockStore entry under the store-interface reference are fixed. - The cloudflare skill imported the two packages it exists to replace, composed locks through composePersistence (rejected at compile time and runtime), told you to include locks in the conformance run, and described a migrations CLI deleted in 14f6cfa. Rewritten around raw D1 stores and an own DO lock class. - The drizzle skill's migrations section described bundled .sql assets and a tanstack-ai-drizzle-migrations CLI that do not exist; it is schema-first now, and the Postgres recipe it was missing is documented. - sources: frontmatter no longer cites the five doc pages c5f391e deleted. - metadata's first argument is namespace, matching types.ts. @tanstack/ai-persistence was missing the tanstack-intent keyword, so intent install could not discover its skills at all. Added, and the docs now show the install path instead of "ask your AI assistant for the skill". Also fixes the two type errors the example carried: the factory annotated its return as bare AIPersistence (the all-optional bag, which withPersistence rejects) and passed the invalid skip key.
Drop @tanstack/ai-persistence-drizzle, -prisma, and -cloudflare, and the two
examples built on them.
Persistence is a contract. The core never inspects your tables, so a packaged
backend buys an application very little beyond a schema it did not choose — and
costs it a dependency, a migration story, and a schema owner that is not the
app. Every packaged backend was also a second place for the store invariants to
drift from the ones the middleware actually relies on.
What ships instead is the thing that was always doing the work:
- the four store contracts and their invariants,
- withPersistence / withGenerationPersistence and reconstructChat,
- memoryPersistence() as the in-process reference backend,
- LockStore / withLocks for coordination,
- and the conformance testkit, which is the real compatibility gate — point it
at your factory and it holds you to the same rules every backend was held to.
Applications implement the stores against the database they already run.
examples/ts-react-chat does exactly that on a self-contained node:sqlite
adapter, verified by the shared testkit, and the Build Your Own Adapter guide
walks the same path end to end. The Drizzle, Prisma, and Cloudflare recipes
survive as Agent Skills in @tanstack/ai-persistence, so the knowledge is still
shipped — as a recipe you own rather than a package you depend on.
Also drops the prisma/better-sqlite3 build-script allowances and the sherif
prisma ignores, which existed only for the deleted packages, and fixes three
useChat({ id }) call sites in ts-code-mode-web and ts-react-native-chat that
the hook's threadId-identity change left behind.
The three -build-*-adapter skills read as "build a publishable adapter package": peer deps, dual edge-safe/Node entry points, dialect overloads, a schema-emitting CLI, BYO-schema validation. None of that survives the move to one file in a consumer's app, which is what someone adding persistence actually wants. Each recipe now opens by reading the app it is running in — dialect, schema file, db handle lifetime, migration flow, naming conventions, import alias — appends the four tables to the schema that already exists, and produces a single src/lib/chat-persistence.ts against the existing client. The package material is demoted to a short "only if you are publishing this as a package" tail. Drizzle and Prisma carry the complete file; Cloudflare leads with per-request bindings and routes to the Drizzle recipe when the Worker already uses it. Adds -build-custom-adapter for the stacks with no dedicated recipe (raw pg, Kysely, node:sqlite, Mongo, Supabase, Redis): the five engine-independent invariants, a worked pg example, and per-engine notes. The recipes are sliced by access layer, not by engine, so there is no SQLite skill — SQLite is already the default dialect in three of the four. Fixes carried through every recipe: metadata columns are named `namespace` to match the MetadataStore argument, and findActiveRun was missing everywhere. Docs: the persistence overview now says to install @tanstack/ai-persistence and run `intent install` before writing any of it — the package install previously appeared exactly once in the whole docs tree, buried at the bottom of build-your-own-adapter. Chat persistence gets the same install block, and the adapter guide's recipe section explains what the skills now produce.
The two failing chat-persistence specs were one bug, in the harness rather
than the library. This branch changed what a client `persistence` adapter's
`setItem` receives — the combined `{ messages, resume? }` record instead of a
bare `UIMessage[]` — and the e2e page's hand-rolled adapter was updated on
neither side: it wrote the new object, then fed it to a reader that throws on
anything but an array. Adapter reads are best-effort, so the throw was
swallowed and the transcript silently never restored. The clear() spec kept
passing because it asserts emptiness after reload, which holds whether
persistence works or is entirely dead.
Any user with a hand-rolled adapter hits the same silent failure on upgrade:
`getItem` has a back-compat path for reading legacy arrays, `setItem` has none
for writing them. The durability changeset now carries that migration note, and
client-persistence.md gains a "Writing your own" section with the correct
round-trip and a warning that a wrong-shape parse fails silently.
Separately, three packages shipped skills that TanStack Intent could never
load. Intent scans node_modules for the `tanstack-intent` keyword and can only
see what npm publishes; @tanstack/ai-mcp wrote its skill into a directory
missing from `files` (never published at all), while @tanstack/ai-memory and
@tanstack/ai-sandbox published theirs without the keyword. All three now match
the packages that already worked.
The client persistence skill also moves to @tanstack/ai as
ai-core/client-persistence. It teaches localStoragePersistence and the
`persistence` option on useChat — framework-package code, not
@tanstack/ai-persistence code — so an app persisting only in the browser never
installed the package that carried its guidance, and ai-core routed to a path
that did not exist on disk. Skills follow the code that owns them.
Layer a lightweight, read-only resume snapshot onto media generation. As a run streams, the client builds a GenerationResumeSnapshot (run identity, status, errors, result metadata + artifact refs — never media bytes) and writes it to an optional GenerationServerPersistence store. - ai-client: GenerationResumeSnapshot types + updateGenerationResumeSnapshot reducer; GenerationClient/VideoGenerationClient observe chunks, persist snapshots (serialized queue, warn-not-throw), expose getResumeSnapshot(); disposed guard. No resume() action (stream re-attach is PR #955). - ai-event-client: optional threadId/runId on generation events. - react/solid/vue/svelte/angular hooks: persistence + initialResumeSnapshot options; expose resumeSnapshot/resumeState (+ pending/result artifacts). - example: Persisted mode on the image generation route. - docs: persistence/generation-persistence.md + nav entry. Pairs with the existing withGenerationPersistence server middleware.
Drop the bespoke `GenerationServerPersistence` type and the `{ server }`
option wrapper. The `persistence` option is now a bare storage adapter
reusing the shared `ChatStorageAdapter` contract (aliased as
`GenerationPersistence`), so `localStoragePersistence` /
`sessionStoragePersistence` / `indexedDBPersistence` work for generations
exactly as they do for chat — matching main's ergonomics.
…istence (no call-site generic)
Default `localStoragePersistence` / `sessionStoragePersistence` /
`indexedDBPersistence` to a value-agnostic `TValue` so a bare, unannotated
call works for BOTH chat and generation persistence — the consuming
`persistence` option constrains the stored value. Generation docs/example now
use `localStoragePersistence({ keyPrefix })` with no type declaration.
PR #955 (resumable streams) is merged, so delivery durability is available today — it was wrongly described as an unlanded future feature. Rewrite the generation-persistence doc: the server example now wires a durability adapter + GET handler, and the delivery section explains that a dropped mid-generation connection re-attaches through the same adapters useChat uses. Clarify that the read-only snapshot carries run state (incl. runId) across reloads, while hooks do not auto-resume on mount.
Contributor
|
Important Review skippedDraft detected. 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 |
12 tasks
Contributor
🚀 Changeset Version Preview16 package(s) bumped directly, 34 bumped as dependents. 🟥 Major bumps
🟨 Minor bumps
🟩 Patch bumps
|
|
View your CI Pipeline Execution ↗ for commit 34c8b69
☁️ Nx Cloud last updated this comment at |
@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-memory
@tanstack/ai-mistral
@tanstack/ai-ollama
@tanstack/ai-openai
@tanstack/ai-opencode
@tanstack/ai-openrouter
@tanstack/ai-persistence
@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: |
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
3 participants
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.
🎯 Changes
Stack 1 of 2. Split out of #987, rebuilt on the current
feat/persistence-core(which dropped the packaged backends in62c99754d). Stacked follow-up: the durable media-byte half.Client-side generation persistence: a lightweight, read-only resume snapshot for media generation activities.
As a run streams, the client builds a
GenerationResumeSnapshot— run identity, status, errors, and result metadata, but never the generated media bytes — and writes it to apersistencestorage adapter. The option reuses the sameChatStorageAdaptercontract as chat, solocalStoragePersistence/sessionStoragePersistence/indexedDBPersistencework with no type argument.Generation hooks (
useGenerateImage,useGenerateVideo,useGenerateAudio,useGenerateSpeech,useGeneration,useSummarize,useTranscription, plus the Solid/Vue/Svelte/Angular equivalents) acceptpersistenceandinitialResumeSnapshot, and exposeresumeSnapshot/resumeState/pendingArtifacts/resultArtifacts.There is no
resume()action and no restart of provider work — generation still only begins whengenerate(...)is called. Reconnecting to an in-flight stream is the delivery layer's job (resumable streams, #955), wired via adurabilityadapter +GEThandler exactly as for chat.PersistedArtifactRefalready exists on the base branch as dormant wire surface, so this half consumes it and is independently mergeable — thegeneration:artifactsevent simply never fires until the stacked byte-storage PR lands.Packages
@tanstack/ai-client— the resume-snapshot reducer, thepersistenceoption, artifact refs.@tanstack/ai-event-client— optionalthreadId/runIdon generation events.docs/persistence/generation-persistence.md, kiira-verified.Carried over from review of #987; tracked here rather than silently shipped.
generate().dispose()setsdisposed = trueand nothing ever clears it, so after StrictMode's mount→cleanup→mount replay against the same memoized client everygenerate()call returns immediately. Reproduced under{ wrapper: StrictMode }. The fix pattern already exists atdevtools.ts:571. Affectsgeneration-client.tsandvideo-generation-client.ts.persistence.getItem— apps must read storage themselves and passinitialResumeSnapshot. Either wire hydration (as chat does atclient-persistor.ts:129) or rewrite the section.console.warnper chunk on quota errors.fetcher(non-streaming) path never records a snapshot at all.getResumePersistenceError()is dead public API — zero call sites.tanstack-ai:key prefix, so auseChat({id})anduseGenerateImage({id})on one adapter collide.threadId/runIdwere added to 18 devtools event interfaces but no emit site populates them.localStoragePersistence<TValue = ChatPersistedState>to<TValue = any>(3 oxlint suppressions) so the factories can be reused for generations. That degrades the already-shipped chat path; it arguably belongs infeat/persistence-coreon its own merits.✅ Checklist
pnpm run test:pr. — ran the affected subset:build,test:types,test:lib,test:oxlintgreen across ai, ai-utils, ai-event-client, ai-client, ai-persistence + the four framework packages.🚀 Release Impact