Start with a saved conversation
TanStack AI 1.0 requires coordinated client and server upgrades and no longer loads bare message arrays from browser persistence. TanStack announced the release on October 23, 2026. For an existing application, deployment compatibility and stored history belong in the same migration plan. Sources: TanStack
Begin by capturing representative records before changing code. Keep a completed conversation, completed tool work, pending approval, pending browser tool, interrupted stream, and attached artifact where those features exist. Record message ordering, message identifiers, tool-call identifiers, and storage keys. Use these fixtures to check whether the upgraded application can continue old work as well as display its transcript.
Inventory framework, client, core, persistence, provider adapter, and experimental dependencies across every deployment. Include independently deployed API services and browser bundles that may remain cached. TanStack removed deprecated 0.x APIs in 1.0, although their replacements had already shipped during 0.x. Updating those usages before cutover can make the remaining changes easier to inspect. Sources: TanStack
Preserve thread identity through code changes
Apply the documented codemod, then inspect its diff and the paths it cannot cover. TanStack says it misses calls through barrel re-exports and several factory and Angular options, and it cannot choose conversation identifiers. Review wrapper hooks, request parsing, and custom transports manually. Avoid globally renaming every occurrence of body; unrelated application fields need separate review. Sources: TanStack
Chat configuration changes body to forwardedProps and conversationId to threadId, with an explicit, stable identifier required on both sides. Server code must read top-level params.threadId rather than an identifier nested in forwarded properties. Build an explicit mapping from existing storage keys and route identifiers to threadId. Preserve that mapping during hydration instead of generating a new identifier. Sources: TanStack
Tool approval now uses resolution of a tool-approval interrupt instead of addToolApprovalResponse(). The separate React, Solid, and Vue UI packages disappear, with UI factories moving to their framework packages’ /ui exports. Custom streaming servers must end with the RUN_FINISHED event. TanStack’s completion checks include type-checking, searching for removed names, streaming a reply, and restoring a saved chat. Sources: TanStack
Migrate the stored formats the app uses
Rehearse data transformations on a copy of the captured records. Count affected records before and after conversion, make transformations repeatable, and retain originals until acceptance checks pass. TanStack’s persistence guidance puts schema changes before dependent code and assigns schema ownership to the application’s adapter. It recommends using the project’s production migration tooling and considering rollback and partial deployments. Sources: TanStack
The table below separates migrations by the formats an application uses. The 1.0 guide requires browser persistence to return an object containing messages and optional resume state; bare arrays no longer load. Only bound interrupts can resume, so older pending interrupts must be resolved or dropped before deployment. Prefer finishing pending work where possible, and make discarding work an explicit application decision. Sources: TanStack
Table
Saved-data changes required for 1.0
| Existing state | Required treatment |
|---|---|
| Browser persistence returns a bare message array. | Return an object with messages and optional resume state. |
| Pending interrupts lack bindings. | Resolve or drop before deployment. |
| Artifact records lack blobKey. | Backfill the legacy default artifact path; custom stores must persist blobKey. |
| Cloudflare sandbox uses old run-log records. | Finish or delete in-progress runs, then clear old rec: records. |
The migration helpers migrateStoredRunRecord and resolveArtifactBlobKey() have been removed. For artifacts, check both the migrated metadata and whether the referenced bytes remain accessible. TanStack describes creating tables when an adapter opens as a development convenience, not a production request-time migration strategy. Schedule storage changes as a deployment operation with a clear recovery path. Sources: TanStack
Verify history and stream recovery separately
TanStack distinguishes saved conversation state from stream replay. Its withPersistence integration stores messages, run status, and pending approvals. Enabling client persistence requests history by threadId, while reconstructChat returns messages and an active run where applicable. Continuing a stream uses its durability log. After a transcript loads, check separately whether an interrupted response can continue correctly. Sources: TanStack
For production, TanStack calls for durable database storage and a stream log shared across server processes; memoryPersistence() is a development example. Test server-owned history from another device and after a server restart so browser storage cannot conceal a missing server record. Restoring activity rows through AG-UI requires an activities store, and those rows are excluded from subsequent model input. Check visible activity and model-bound history as separate outcomes. Sources: TanStack
Use the acceptance matrix below as a proposed test plan, with the original fixtures as inputs. Inspect the next server request after restoration instead of stopping when the transcript looks correct. Delay hydration while switching threads to check for messages arriving in the wrong conversation. Keep a pre-upgrade browser tab open through cutover to check for a controlled reload or compatible routing.
Table
Recommended restoration acceptance checks
| Test | Evidence to capture | Failure to investigate |
|---|---|---|
| Restore a completed chat | Same message identifiers, roles, order, and content | Storage format or thread mapping errors |
| Send a follow-up | Expected model-bound history | Visible transcript missing from context |
| Restore completed tool work | Call/result associations and outputs | Orphaned results or duplicate calls |
| Approve and reject pending work | Correct execution or blocking | Unusable continuation state |
| Reload a pending browser tool | Invocation count unchanged until explicit handling | Duplicate effects or stalled interface |
| Reload during a stream | One coherent continuation | Replay gaps or duplicate parts |
| Open a server-owned thread on another device | Same history and pending decisions | Browser cache concealing missing server history |
| Restart the server mid-conversation | Durable history and expected replay behavior | Reliance on memory storage |
| Restore an attachment | Accessible bytes from migrated record | Broken object reference |
Test tool continuation beyond approval
Pending browser tools need an explicit restoration policy because hydration does not automatically execute them again. TanStack says restored executions remain internal interrupts and do not appear in the public interrupts collection. The documentation exposes hydration-origin changes through onInterruptStateChange and demonstrates cancellation with cancelInterrupts(). Test the application’s chosen handling with deterministic tools that record inputs and invocation counts. Sources: TanStack
Include Model Context Protocol input-request continuation if the application uses it. Issue #1885 reports a server tool repeatedly requesting a city because persisted resume left ctx.inputResponse empty after the user answered Paris. The reporter observed this with @tanstack/ai 1.0.0 and 0.69.0 on Node.js 24; client-message-based continuation reportedly worked. As of October 24, 2026, the issue awaited a maintainer response and had no linked fix or independently verified reproduction. The explanation remained the reporter’s diagnosis. Sources: GitHub
For pending approvals, test both acceptance and rejection, then verify whether the tool executes and the conversation continues. For completed tools, preserve the association between each call and its result. Use invocation counters to detect duplicate side effects and recorded inputs to check continuation behavior. Follow deterministic checks with a small live-provider smoke test to cover provider compatibility.
Keep experimental harness adoption separate
TanStack’s stable boundary excludes @tanstack/ai-harness, @tanstack/ai-harness-cli, @tanstack/ai-skills/harness, and @tanstack/ai-acp/agent. Harness packages remain at 0.x, and experimental entry points can change in minor releases. An existing chat application does not need to adopt the harness to upgrade. Keep that decision separate so the migration’s acceptance criteria stay focused on existing behavior. Sources: TanStack
Applications already using the harness need additional deployment checks. Its documentation describes shared-log ownership across hosts, background workers taking unfinished work, and recoverable shutdown. For coding tools that depend on a host’s filesystem, it recommends stable host identity and considers ownership expiry during restarts. Test those recovery paths separately from ordinary conversation restoration. Sources: GitHub
Before reopening traffic, verify that an old thread reopens and accepts a follow-up. Verify that pending work either continues correctly or has been explicitly resolved or discarded under the application’s migration policy. Keep the captured records as regression fixtures after deployment. If a test fails, use the original identifiers, storage keys, and invocation records to locate the failure. That evidence can guide a data repair, a change to continuation handling, or a rollback.