Merge branch 'main' into worktree-serialized-exploring-wall

Reconcile the typed-stream-chunks feature with main's typed-runtime-context
(#628) and multimodal-tool-result (#666) work, which had diverged on the same
hot paths. Key conflict resolutions:

- types.ts: keep the branch's Pick<>-based event interfaces + TypedStreamChunk
  machinery; layer in main's `usage?: TokenUsage`, multimodal
  `result?: string | Array<ContentPart>`, and `state?: ToolOutputState` on
  ToolCallEndEvent (added `state` to the drift-guard Omit). Switched the
  typed-chunk constraints from `Tool<any,any,any>` to main's `AnyTool` (its
  bivariant `execute` is what lets concrete tools satisfy the constraint).
- chat/index.ts: unify the two generic systems — main's `const TTools`
  inference (for context) now also feeds the branch's
  `TextActivityResult<…, TTools>` so streaming tool-call events stay typed.
  `tools?` widened to ReadonlyArray so const-inferred tuples / mergeAgentTools'
  readonly return fit. Removed now-unnecessary `as StreamChunk` casts (the
  literal `type` discriminators check structurally).
- tool-calls.ts: executeTools keeps both the branch's typed `output` and main's
  `normalizeToolResult`/`state`/typed `executionContext`.
- chat-params.ts: mergeAgentTools stays generic over `const TServerTools`
  (constrained to AnyTool) for name narrowing.
- createChatOptions: preserve the concrete tool tuple in the return type while
  threading main's InferredContext.

Validated: @tanstack/ai type-check + 1006 unit tests + 0 lint errors; affected
workspace type-check (32 projects), unit tests (31), eslint, and build all pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tombeckenham

.changeset/config.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
   "changelog": [
-    "@svitejs/changesets-changelog-github-compact",
-    { "repo": "TanStack/ai" }
+    "@changesets/changelog-github",
+    { "repo": "TanStack/ai", "disableThanks": true }
   ],
   "commit": false,
   "access": "public",

.github/workflows/autofix.yml

@@ -26,7 +26,7 @@ jobs:
         with:
           persist-credentials: false
       - name: Setup Tools
-        uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
+        uses: TanStack/config/.github/setup@a4c6d06ed525a310901e3e9fbed9b2301ebecfd5 # main
       - name: Fix formatting
         run: pnpm format
       - name: Apply fixes

.github/workflows/e2e.yml

@@ -28,7 +28,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Tools
-        uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
+        uses: TanStack/config/.github/setup@a4c6d06ed525a310901e3e9fbed9b2301ebecfd5 # main
 
       - name: Cache Playwright Browsers
         id: playwright-cache

.github/workflows/pr.yml

@@ -24,7 +24,7 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
       - name: Setup Tools
-        uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
+        uses: TanStack/config/.github/setup@a4c6d06ed525a310901e3e9fbed9b2301ebecfd5 # main
       - name: Get base and head commits for `nx affected`
         uses: nrwl/nx-set-shas@3e9ad7370203c1e93d109be57f3b72eb0eb511b1 # v4.4.0
         with:
@@ -43,7 +43,7 @@ jobs:
         with:
           persist-credentials: false
       - name: Setup Tools
-        uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
+        uses: TanStack/config/.github/setup@a4c6d06ed525a310901e3e9fbed9b2301ebecfd5 # main
       - name: Build Packages
         run: pnpm run build:all
       - name: Publish Previews
@@ -60,6 +60,6 @@ jobs:
         with:
           persist-credentials: false
       - name: Setup Tools
-        uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
+        uses: TanStack/config/.github/setup@a4c6d06ed525a310901e3e9fbed9b2301ebecfd5 # main
       - name: Changeset Preview
-        uses: TanStack/config/.github/changeset-preview@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
+        uses: TanStack/config/.github/changeset-preview@a4c6d06ed525a310901e3e9fbed9b2301ebecfd5 # main

.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
           fetch-depth: 0
           persist-credentials: true # release job pushes version/docs changes
       - name: Setup Tools
-        uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
+        uses: TanStack/config/.github/setup@a4c6d06ed525a310901e3e9fbed9b2301ebecfd5 # main
       - name: Run Tests
         run: pnpm run test:ci
       - name: Run Changesets (version or publish)
@@ -59,6 +59,6 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Comment on PRs about release
         if: steps.changesets.outputs.published == 'true'
-        uses: TanStack/config/.github/comment-on-release@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
+        uses: TanStack/config/.github/comment-on-release@a4c6d06ed525a310901e3e9fbed9b2301ebecfd5 # main
         with:
           published-packages: ${{ steps.changesets.outputs.publishedPackages }}

.github/workflows/sync-models.yml

@@ -25,7 +25,7 @@ jobs:
           persist-credentials: true # sync job pushes generated model updates
 
       - name: Setup Tools
-        uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
+        uses: TanStack/config/.github/setup@a4c6d06ed525a310901e3e9fbed9b2301ebecfd5 # main
 
       - name: Fetch and sync model metadata
         run: pnpm generate:models

.gitignore

@@ -72,6 +72,7 @@ docs/superpowers
 # Only .claude.settings.json should be committed
 .claude/settings.local.json
 .claude/worktrees/*
+.claude/scheduled_tasks.lock
 solo.yml
 
 # Agent scratch output (gap-analysis reports, triage notes — generated locally)

AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md
+
+Cross-agent guidance for this repository. See `CLAUDE.md` for the full project
+overview, architecture, and conventions — this file mirrors the rules that
+apply to every coding agent regardless of tool.
+
+## Dependency Install
+
+Run `pnpm install` before starting any task and again after every merge with
+`main`.
+
+## Pre-PR Quality Gate (MANDATORY)
+
+**Before committing, run the narrowest meaningful quality checks for your
+changes and confirm they pass locally. Before opening a PR or pushing changes
+intended for review, run the same checks CI runs.** If you make post-commit
+changes, rebase, or merge before pushing to a PR, rerun the relevant checks
+first.
+
+Use the repo-preferred package manager, scripts, and Nx targets where
+applicable. Do **not** commit or push while quality checks are failing unless
+the user explicitly instructs otherwise; report the exact failing command and
+failure instead.
+
+The single canonical command is:
+
+```bash
+pnpm test:pr
+```
+
+This runs the exact target set the `PR` workflow runs in CI
+(`nx affected --targets=test:sherif,test:knip,test:docs,test:eslint,test:lib,test:types,test:build,build --exclude=examples/**,testing/**`).
+
+If you can't run `test:pr` (e.g. it's too slow on your machine), at minimum run
+each of these and confirm they're green before pushing:
+
+- `pnpm test:sherif` — workspace consistency
+- `pnpm test:knip` — unused dependencies
+- `pnpm test:docs` — doc link verification
+- `pnpm test:eslint` — lint
+- `pnpm test:types` — typecheck
+- `pnpm test:lib` — unit tests
+- `pnpm test:build` — build artifact verification
+- `pnpm build` — build all affected packages
+- `pnpm --filter @tanstack/ai-e2e test:e2e` — E2E suite (mandatory for any
+  behavior change; see `testing/e2e/README.md`)
+
+Do **not** rely on CI as your first signal. Run locally, fix, then push.
+
+## Everything Else
+
+For package manager (`pnpm@10.17.0`), monorepo layout, adapter architecture,
+tool system, framework integrations, E2E requirements, and all other
+conventions, read `CLAUDE.md` in this directory.

CLAUDE.md

@@ -15,6 +15,9 @@ TanStack AI is a type-safe, provider-agnostic AI SDK for building AI-powered app
 - **Linting**: ESLint with custom TanStack config
 - **Formatting**: Prettier
 
+Run `pnpm install` before starting any task and again after every merge with
+`main`.
+
 ## Common Commands
 
 ### Testing
@@ -215,6 +218,34 @@ Each framework integration uses the headless `ai-client` under the hood.
 8. Format code: `pnpm format`
 9. Verify build: `pnpm test:build` or `pnpm build`
 
+### Pre-PR Quality Gate (MANDATORY)
+
+**Before committing, run the narrowest meaningful quality checks for your changes and confirm they pass locally. Before opening a PR or pushing changes intended for review, run the same checks CI runs.** If you make post-commit changes, rebase, or merge before pushing to a PR, rerun the relevant checks first.
+
+Use the repo-preferred package manager, scripts, and Nx targets where applicable. Do **not** commit or push while quality checks are failing unless the user explicitly instructs otherwise; report the exact failing command and failure instead.
+
+The single canonical command is:
+
+```bash
+pnpm test:pr
+```
+
+This runs the exact target set the `PR` workflow runs in CI (`nx affected --targets=test:sherif,test:knip,test:docs,test:eslint,test:lib,test:types,test:build,build --exclude=examples/**,testing/**`).
+
+If you can't run `test:pr` (e.g. it's too slow on your machine), at minimum run each of these and confirm they're green before pushing:
+
+- `pnpm test:sherif` — workspace consistency
+- `pnpm test:knip` — unused dependencies
+- `pnpm test:docs` — doc link verification
+- `pnpm test:eslint` — lint
+- `pnpm test:types` — typecheck
+- `pnpm test:lib` — unit tests
+- `pnpm test:build` — build artifact verification
+- `pnpm build` — build all affected packages
+- `pnpm --filter @tanstack/ai-e2e test:e2e` — E2E suite (mandatory for any behavior change; see E2E Testing)
+
+Do **not** rely on CI as your first signal. Run locally, fix, then push.
+
 ### Working with Examples
 
 Examples are not built by Nx. To run an example:

README.md

@@ -186,7 +186,7 @@ Official adapters include:
 
 | Package                                                                              | Use it for                                                                     |
 | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
-| [`@tanstack/ai-openrouter`](https://tanstack.com/ai/latest/docs/adapters/openrouter) | 300+ models through one OpenRouter API                                         |
+| [`@tanstack/ai-openrouter`](https://tanstack.com/ai/latest/docs/adapters/openrouter) | 300+ models through one OpenRouter API, with per-request cost tracking         |
 | [`@tanstack/ai-openai`](https://tanstack.com/ai/latest/docs/adapters/openai)         | OpenAI chat, image, video, speech, transcription, realtime, and provider tools |
 | [`@tanstack/ai-anthropic`](https://tanstack.com/ai/latest/docs/adapters/anthropic)   | Anthropic Claude chat, thinking, tools, and structured outputs                 |
 | [`@tanstack/ai-gemini`](https://tanstack.com/ai/latest/docs/adapters/gemini)         | Google Gemini chat, image, speech, and audio generation                        |