fix(ai-persistence): persist chat run usage by kolaworld · Pull Request #1129 · TanStack/ai

kolaworld · 2026-08-17T21:36:44Z

Fixes#1128

🎯 Changes

Accumulates usage across every provider call in a chat invocation.
Persists known usage when a run completes, interrupts, fails, or aborts.
Preserves accumulated usage across same-run continuations.
Sums numeric usage fields while retaining the latest opaque providerUsageDetails.
Continues omitting usage when the adapter reports none.
Updates store conformance, persistence tests, provider-free E2E coverage, and documentation.

✅ 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
- Chat runs now retain and accumulate token usage across multiple model calls, tool calls, interruptions, failures, aborts, and resumed executions.
- Persisted usage includes prompt, completion, and total token counts, while preserving the latest provider-specific details.
- Interrupted runs can resume with their previously recorded usage.
Bug Fixes
- Usage is no longer lost when runs are cancelled or fail during structured-output processing.
Documentation
- Expanded guidance on usage reporting, run lifecycle behavior, continuation, and persistence semantics.

coderabbitai · 2026-08-17T21:37:08Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ea2be4b6-ad2f-4ffa-8586-1a5b27c7614a

📥 Commits

Reviewing files that changed from the base of the PR and between 2c6d142 and 9fa0e0b.

📒 Files selected for processing (2)

packages/ai-persistence/src/middleware.ts
packages/ai-persistence/tests/with-persistence.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

packages/ai-persistence/tests/with-persistence.test.ts
packages/ai-persistence/src/middleware.ts

Included review availability: Your plan includes up to 8 reviews per rolling hour; 6 remain after this review.

📝 Walkthrough

Walkthrough

The persistence middleware now aggregates token usage across provider calls and preserves it through interrupted, completed, failed, and aborted runs. Tests, an end-to-end scenario, documentation, and a patch changeset cover the behavior.

Changes

Usage persistence

Layer / File(s)	Summary
Middleware usage lifecycle `packages/ai-persistence/src/middleware.ts`	Run state restores stored usage, accumulates numeric and provider-specific usage, and persists it across lifecycle transitions.
Persistence behavior validation `packages/ai-persistence/src/testkit/conformance.ts`, `packages/ai-persistence/tests/*`	Tests verify cumulative usage, idempotent resumption, and retention across interrupted, failed, aborted, tool-call, and structured-output runs.
End-to-end usage scenario `testing/e2e/src/routes/api.persistence-durability.ts`, `testing/e2e/tests/persistence-durability.spec.ts`	The durability route performs two persisted calls and validates cumulative token usage through an end-to-end test.
Persistence documentation and release metadata `docs/persistence/*`, `packages/ai-persistence/skills/ai-persistence/stores/SKILL.md`, `.changeset/persist-chat-run-usage.md`	Documentation describes usage aggregation, lifecycle persistence, continuation behavior, and unchanged run restoration. A patch changeset records the package release.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk:⚪ Minimal · up to 9fa0e

This change persists accumulated chat-run usage across completion, interruption, failure, abort, and continuation paths; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
participant ChatEngine
participant withPersistence
participant RunRecord
ChatEngine->>withPersistence: emit usage for each provider call
withPersistence->>withPersistence: accumulate usage
withPersistence->>RunRecord: persist aggregate at interruption or terminal state
RunRecord-->>withPersistence: restore usage for continuation

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: persisting chat run usage in ai-persistence.
Description check	✅ Passed	The description explains the changes, confirms both checklist items, and identifies the published-code release impact and changeset.
Linked Issues check	✅ Passed	The implementation addresses issue `#1128` by aggregating and persisting usage across calls, interruptions, continuations, failures, and aborts.
Out of Scope Changes check	✅ Passed	The code, tests, end-to-end coverage, documentation, and changeset changes directly support the linked issue and pull request objectives.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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

_{Comment @coderabbitai help to get the list of available commands.}

nx-cloud · 2026-08-18T14:19:17Z

View your CI Pipeline Execution ↗ for commit 9fa0e0b

Command	Status	Duration	Result
`nx run-many --targets=build --exclude=examples/...`	✅ Succeeded	6s	View ↗

☁️ Nx Cloud last updated this comment at 2026-08-18 14:19:34 UTC

pkg-pr-new · 2026-08-18T14:20:36Z

Open in StackBlitz

@tanstack/ai

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai@1129

@tanstack/ai-acp

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-acp@1129

@tanstack/ai-angular

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-angular@1129

@tanstack/ai-anthropic

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-anthropic@1129

@tanstack/ai-bedrock

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-bedrock@1129

@tanstack/ai-byteplus

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-byteplus@1129

@tanstack/ai-claude-code

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-claude-code@1129

@tanstack/ai-client

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-client@1129

@tanstack/ai-code-mode

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode@1129

@tanstack/ai-code-mode-snippets

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode-snippets@1129

@tanstack/ai-codex

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-codex@1129

@tanstack/ai-cohere

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-cohere@1129

@tanstack/ai-devtools-core

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-devtools-core@1129

@tanstack/ai-durable-stream

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-durable-stream@1129

@tanstack/ai-elevenlabs

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-elevenlabs@1129

@tanstack/ai-event-client

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-event-client@1129

@tanstack/ai-fal

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-fal@1129

@tanstack/ai-gemini

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-gemini@1129

@tanstack/ai-grok

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok@1129

@tanstack/ai-grok-build

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok-build@1129

@tanstack/ai-groq

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-groq@1129

@tanstack/ai-isolate-cloudflare

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-cloudflare@1129

@tanstack/ai-isolate-daytona

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-daytona@1129

@tanstack/ai-isolate-node

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-node@1129

@tanstack/ai-isolate-quickjs

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-quickjs@1129

@tanstack/ai-isolate-quickjs-bun

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-quickjs-bun@1129

@tanstack/ai-mcp

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mcp@1129

@tanstack/ai-memory

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-memory@1129

@tanstack/ai-mistral

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mistral@1129

@tanstack/ai-ollama

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-ollama@1129

@tanstack/ai-openai

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openai@1129

@tanstack/ai-opencode

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-opencode@1129

@tanstack/ai-openrouter

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openrouter@1129

@tanstack/ai-perplexity

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-perplexity@1129

@tanstack/ai-persistence

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-persistence@1129

@tanstack/ai-preact

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-preact@1129

@tanstack/ai-react

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react@1129

@tanstack/ai-react-ui

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react-ui@1129

@tanstack/ai-sandbox

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox@1129

@tanstack/ai-sandbox-cloudflare

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-cloudflare@1129

@tanstack/ai-sandbox-daytona

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-daytona@1129

@tanstack/ai-sandbox-docker

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-docker@1129

@tanstack/ai-sandbox-local-process

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-local-process@1129

@tanstack/ai-sandbox-sprites

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-sprites@1129

@tanstack/ai-sandbox-vercel

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-vercel@1129

@tanstack/ai-solid

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid@1129

@tanstack/ai-solid-ui

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid-ui@1129

@tanstack/ai-svelte

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-svelte@1129

@tanstack/ai-utils

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-utils@1129

@tanstack/ai-vercel-gateway

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vercel-gateway@1129

@tanstack/ai-vue

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue@1129

@tanstack/ai-vue-ui

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue-ui@1129

@tanstack/openai-base

npm i https://pkg.pr.new/TanStack/ai/@tanstack/openai-base@1129

@tanstack/preact-ai-devtools

npm i https://pkg.pr.new/TanStack/ai/@tanstack/preact-ai-devtools@1129

@tanstack/react-ai-devtools

npm i https://pkg.pr.new/TanStack/ai/@tanstack/react-ai-devtools@1129

@tanstack/solid-ai-devtools

npm i https://pkg.pr.new/TanStack/ai/@tanstack/solid-ai-devtools@1129

commit: 9fa0e0b

Resolved 4 conflicts. Both sides were kept in every case: - packages/ai/src/adapter-internals.ts Additive on both sides. Kept the interrupt exports and main's structured-output-text / structured-output-events exports. - packages/ai-persistence/src/middleware.ts (onFinish) Kept this branch's try/catch and its saveThread -> commitPendingResumes -> completeRun order, so a failed batch write still calls failRun and leaves pending resumes retryable. Took main's accumulated usage from #1129: completeRun now gets `state?.usage ?? info.usage`, and failRun in the catch gets `state?.usage` so every terminal path persists usage the same way onError already does. - packages/ai-persistence/tests/interrupts.test.ts Unioned the imports. Kept this branch's schema fixtures and the isInterruptFinished predicate, plus main's usage-aware interruptFinished(runId, usage) signature. - docs/persistence/chat-persistence.md Kept this branch's atomic-commitBatch and legacy-sequential-fallback paragraphs and folded in main's sentence about terminal paths retaining usage.

kolaworld added 2 commits August 17, 2026 13:45

fix(ai-persistence): persist cumulative run usage
8d9b791

docs(ai-persistence): clarify persisted run usage
2c6d142

kolaworld changed the title ~~Fix/1128 persist chat run usage~~fix(ai-persistence): persist chat run usageAug 17, 2026

github-actionsBot added the waiting-on: maintainer The ball is in the maintainers’ court label Aug 18, 2026

AlemTuzlak approved these changes Aug 18, 2026
View reviewed changes

Merge branch 'main' into fix/1128-persist-chat-run-usage
9fa0e0b

AlemTuzlak merged commit 302c9f6 into TanStack:mainAug 18, 2026
9 checks passed

github-actionsBot mentioned this pull request Aug 18, 2026
ci: Version Packages #1118
Merged

coderabbitaiBot mentioned this pull request Aug 19, 2026
fix(ai-persistence): persist structured output #1126
Open
4 tasks

Navigation Menu

Uh oh!

Uh oh!

fix(ai-persistence): persist chat run usage - #1129

fix(ai-persistence): persist chat run usage#1129
AlemTuzlak merged 3 commits into
TanStack:mainfrom
kolaworld:fix/1128-persist-chat-run-usage

kolaworld commented Aug 17, 2026•
edited by coderabbitai Bot
Loading

Uh oh!

coderabbitaiBot commented Aug 17, 2026•
edited
Loading

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

nx-cloudBot commented Aug 18, 2026•
edited
Loading

Uh oh!

pkg-pr-newBot commented Aug 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

kolaworld commented Aug 17, 2026• edited by coderabbitai BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

coderabbitaiBot commented Aug 17, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

nx-cloudBot commented Aug 18, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-newBot commented Aug 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kolaworld commented Aug 17, 2026•
edited by coderabbitai Bot
Loading

coderabbitaiBot commented Aug 17, 2026•
edited
Loading

nx-cloudBot commented Aug 18, 2026•
edited
Loading