fix(ai-persistence): make RunStore.findActiveRun required #1004
main fromrefs/pull/1004/head·merged by tombeckenham View on GitHub🎯 Changes#
findActiveRun was optional on the RunStore contract and feature-detected at the call site (store.findActiveRun?.(threadId)). That made a backend which hadn't implemented it indistinguishable from one whose thread is genuinely idle — both answer null — so reconnect silently turned off in production instead of failing at build time. A client reloading (or switching back to) a still-generating thread restored the transcript but never resumed the live reply, with nothing to detect it.
- Make
findActiveRunrequired onRunStore; drop the optional call inreconstructChat. - Record the evolution policy in
types.ts: store methods are required, and capability tiers belong at the store level (omitruns, declareChatTranscriptStores) — never at the method level. An absent store is caught by the type system; an incomplete one fails silently at runtime. - Drop the conformance skip so every backend providing
runsmust satisfy the invariants (most-recent-running wins, thread-scoped, null when idle); implementfindActiveRunin the test fixture store. - Update the adapter guide, the
ai-persistencestores skill, and thedefineRunStorechangeset accordingly. - Enable
migrate: truein the ts-react-chat persistent store example.
Breaking for adapter authors: any external RunStore implementation without findActiveRun now gets a compile error — which is the point.
✅ Checklist#
- I have followed the steps in the Contributing guide.
- I have tested this code locally with
pnpm run test:pr.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Summary by CodeRabbit#
New Features
- Active-run detection is now required for persistence adapters, enabling reconnection to in-progress replies without a client-held run ID.
- SQLite persistence examples now enable automatic schema migration on first database open.
Bug Fixes
- Active runs are consistently identified by selecting the most recently started running reply.
- Invalid adapters now fail clearly instead of silently appearing idle.
Documentation
- Updated adapter guidance, examples, and contract documentation to reflect required active-run support and handling for backends without run lifecycle tracking.
- 1
🚀 Changeset Version Preview#
16 package(s) bumped directly, 34 bumped as dependents.
🟥 Major bumps#
Package Version Reason @tanstack/ai-angular0.3.1 → 1.0.0 Changeset @tanstack/ai-durable-stream0.0.0 → 1.0.0 Changeset @tanstack/ai-memory0.0.0 → 1.0.0 Changeset @tanstack/ai-openrouter0.15.10 → 1.0.0 Changeset @tanstack/ai-persistence0.0.0 → 1.0.0 Changeset @tanstack/ai-preact0.11.1 → 1.0.0 Changeset @tanstack/ai-react0.18.1 → 1.0.0 Changeset @tanstack/ai-sandbox0.2.4 → 1.0.0 Changeset @tanstack/ai-solid0.15.1 → 1.0.0 Changeset @tanstack/ai-svelte0.15.1 → 1.0.0 Changeset @tanstack/ai-vue0.15.1 → 1.0.0 Changeset @tanstack/ai-acp0.2.3 → 1.0.0 Dependent @tanstack/ai-anthropic0.16.3 → 1.0.0 Dependent @tanstack/ai-bedrock0.1.4 → 1.0.0 Dependent @tanstack/ai-claude-code0.2.3 → 1.0.0 Dependent @tanstack/ai-code-mode0.3.8 → 1.0.0 Dependent @tanstack/ai-code-mode-skills0.3.11 → 1.0.0 Dependent @tanstack/ai-codex0.2.3 → 1.0.0 Dependent @tanstack/ai-elevenlabs0.2.34 → 1.0.0 Dependent @tanstack/ai-fal0.9.12 → 1.0.0 Dependent @tanstack/ai-gemini0.20.1 → 1.0.0 Dependent @tanstack/ai-grok0.14.9 → 1.0.0 Dependent @tanstack/ai-grok-build0.2.3 → 1.0.0 Dependent @tanstack/ai-groq0.5.3 → 1.0.0 Dependent @tanstack/ai-isolate-node0.1.47 → 1.0.0 Dependent @tanstack/ai-isolate-quickjs0.1.47 → 1.0.0 Dependent @tanstack/ai-mistral0.2.3 → 1.0.0 Dependent @tanstack/ai-ollama0.8.16 → 1.0.0 Dependent @tanstack/ai-openai0.17.1 → 1.0.0 Dependent @tanstack/ai-opencode0.2.3 → 1.0.0 Dependent @tanstack/ai-react-ui0.8.15 → 1.0.0 Dependent @tanstack/ai-sandbox-cloudflare0.2.4 → 1.0.0 Dependent @tanstack/ai-sandbox-daytona0.2.0 → 1.0.0 Dependent @tanstack/ai-sandbox-docker0.2.0 → 1.0.0 Dependent @tanstack/ai-sandbox-local-process0.2.0 → 1.0.0 Dependent @tanstack/ai-sandbox-sprites0.2.1 → 1.0.0 Dependent @tanstack/ai-sandbox-vercel0.2.0 → 1.0.0 Dependent @tanstack/ai-solid-ui0.7.14 → 1.0.0 Dependent @tanstack/openai-base0.9.9 → 1.0.0 Dependent 🟨 Minor bumps#
Package Version Reason @tanstack/ai0.42.0 → 0.43.0 Changeset @tanstack/ai-client0.22.1 → 0.23.0 Changeset @tanstack/ai-devtools-core0.4.24 → 0.5.0 Changeset @tanstack/ai-event-client0.6.8 → 0.7.0 Changeset 🟩 Patch bumps#
Package Version Reason @tanstack/ai-mcp0.2.5 → 0.2.6 Changeset @tanstack/ai-isolate-cloudflare0.2.38 → 0.2.39 Dependent @tanstack/ai-vue-ui0.2.34 → 0.2.35 Dependent @tanstack/preact-ai-devtools0.1.67 → 0.1.68 Dependent @tanstack/react-ai-devtools0.2.67 → 0.2.68 Dependent @tanstack/solid-ai-devtools0.2.67 → 0.2.68 Dependent ag-ui0.0.2 → 0.0.3 Dependent View your CI Pipeline Execution ↗ for commit e83018c8eec4972aafd73fa44a00bcfb8723f17f
Command Status Duration Result nx affected --targets=test:sherif,test:knip,tes...✅ Succeeded 42s View ↗ nx run-many --targets=build --exclude=examples/...✅ Succeeded 3s View ↗
☁️ Nx Cloud last updated this comment at
2026-07-27 23:50:02UTC@tanstack/ai
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai@1004@tanstack/ai-acp
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-acp@1004@tanstack/ai-angular
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-angular@1004@tanstack/ai-anthropic
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-anthropic@1004@tanstack/ai-bedrock
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-bedrock@1004@tanstack/ai-claude-code
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-claude-code@1004@tanstack/ai-client
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-client@1004@tanstack/ai-code-mode
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode@1004@tanstack/ai-code-mode-skills
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode-skills@1004@tanstack/ai-codex
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-codex@1004@tanstack/ai-devtools-core
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-devtools-core@1004@tanstack/ai-durable-stream
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-durable-stream@1004@tanstack/ai-elevenlabs
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-elevenlabs@1004@tanstack/ai-event-client
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-event-client@1004@tanstack/ai-fal
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-fal@1004@tanstack/ai-gemini
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-gemini@1004@tanstack/ai-grok
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok@1004@tanstack/ai-grok-build
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok-build@1004@tanstack/ai-groq
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-groq@1004@tanstack/ai-isolate-cloudflare
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-cloudflare@1004@tanstack/ai-isolate-node
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-node@1004@tanstack/ai-isolate-quickjs
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-quickjs@1004@tanstack/ai-mcp
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mcp@1004@tanstack/ai-memory
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-memory@1004@tanstack/ai-mistral
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mistral@1004@tanstack/ai-ollama
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-ollama@1004@tanstack/ai-openai
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openai@1004@tanstack/ai-opencode
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-opencode@1004@tanstack/ai-openrouter
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openrouter@1004@tanstack/ai-persistence
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-persistence@1004@tanstack/ai-preact
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-preact@1004@tanstack/ai-react
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react@1004@tanstack/ai-react-ui
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react-ui@1004@tanstack/ai-sandbox
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox@1004@tanstack/ai-sandbox-cloudflare
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-cloudflare@1004@tanstack/ai-sandbox-daytona
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-daytona@1004@tanstack/ai-sandbox-docker
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-docker@1004@tanstack/ai-sandbox-local-process
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-local-process@1004@tanstack/ai-sandbox-sprites
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-sprites@1004@tanstack/ai-sandbox-vercel
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-vercel@1004@tanstack/ai-solid
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid@1004@tanstack/ai-solid-ui
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid-ui@1004@tanstack/ai-svelte
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-svelte@1004@tanstack/ai-utils
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-utils@1004@tanstack/ai-vue
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue@1004@tanstack/ai-vue-ui
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue-ui@1004@tanstack/openai-base
npm i https://pkg.pr.new/TanStack/ai/@tanstack/openai-base@1004@tanstack/preact-ai-devtools
npm i https://pkg.pr.new/TanStack/ai/@tanstack/preact-ai-devtools@1004@tanstack/react-ai-devtools
npm i https://pkg.pr.new/TanStack/ai/@tanstack/react-ai-devtools@1004@tanstack/solid-ai-devtools
npm i https://pkg.pr.new/TanStack/ai/@tanstack/solid-ai-devtools@1004commit:
e83018cActionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@docs/config.json`: - Line 269: Update the updatedAt field in the documentation configuration to use today’s review date, 2026-07-27, instead of the future date 2026-07-28.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
213dd69f-61ae-4151-8051-aeb565fe1628📥 Commits
Reviewing files that changed from the base of the PR and between 4ab149fd46a1cf55691266cdd118fdc9999c0b2a and e83018c8eec4972aafd73fa44a00bcfb8723f17f.
📒 Files selected for processing (10)
.changeset/define-store-helpers.md.changeset/run-store-find-active-run-required.mddocs/config.jsondocs/persistence/build-your-own-adapter.mdexamples/ts-react-chat/src/lib/persistent-chat-store.tspackages/ai-persistence/skills/ai-persistence/stores/SKILL.mdpackages/ai-persistence/src/reconstruct.tspackages/ai-persistence/src/testkit/conformance.tspackages/ai-persistence/src/types.tspackages/ai-persistence/tests/persistence-fixtures.ts
docs/config.json line 269@@ -266,4 +266,4 @@266266 "label": "Build Your Own Adapter",267267 "to": "persistence/build-your-own-adapter",268268 "addedAt": "2026-07-24",269- "updatedAt": "2026-07-27"269+ "updatedAt": "2026-07-28"📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use today’s date for
updatedAt.The current review date is July 27, 2026, but this value is future-dated as
2026-07-28. Change it to2026-07-27.As per coding guidelines, documentation timestamps must use today’s date for content changes.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/config.json` at line 269, Update the updatedAt field in the documentation configuration to use today’s review date, 2026-07-27, instead of the future date 2026-07-28.Source: Coding guidelines
jherr approved these changes
tombeckenham added labelspersistence
tombeckenham merged this1120f0f
tombeckenham closed this
Sign in to join this conversation.
📝 Walkthrough
Walkthrough#
RunStore.findActiveRunis now required when a runs store is provided. Reconstruction calls it directly, conformance fixtures implement latest-running-run lookup, documentation reflects the contract, and the SQLite example enables migrations.Changes#
RunStore contract enforcement
.changeset/*,packages/ai-persistence/src/types.ts,packages/ai-persistence/skills/...,docs/persistence/...findActiveRunis required, must return the latest running run ornull, and stores without run lifecycle should omitruns.packages/ai-persistence/src/reconstruct.ts,packages/ai-persistence/src/testkit/conformance.ts,packages/ai-persistence/tests/persistence-fixtures.tsfindActiveRundirectly; conformance tests and fixtures require and implement the lookup.examples/ts-react-chat/src/lib/persistent-chat-store.ts,docs/config.jsonEstimated code review effort: 3 (Moderate) | ~20 minutes
Possibly related PRs
reconstructChat, which this change updates to use required active-run lookup.Suggested reviewers:
alemtuzlak🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
✨ Finishing Touches
📝 Generate docstrings
🧪 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.
❤️ Share