Merge origin/main into feat/improve-usage

Reconcile the usage-detail work with main's restructure (packages/typescript/*
→ packages/*), shared @tanstack/openai-base adapters, summarize delegation, and
the IterationCard devtools rewrite.

- Drop the separate `TokenUsage` type; fold its detail fields
  (promptTokensDetails, completionTokensDetails, durationSeconds,
  providerUsageDetails) into the existing `UsageTotals`, alongside main's
  cost/costDetails. All references updated to `UsageTotals`.
- Consolidate OpenAI-family usage extraction into @tanstack/openai-base
  (buildChatCompletionsUsage / buildResponsesUsage), so OpenAI, Grok, Groq and
  any future chat-completions/responses provider get cached + reasoning token
  detail. Remove the now-redundant per-adapter usage.ts for grok/openai; their
  end-to-end usage-extraction tests now validate the shared path.
- Keep standalone-SDK helpers (Anthropic, Gemini, Ollama, OpenRouter) and wire
  them into main's adapters; OpenRouter merges detail with extractUsageCost.
- Omit usage entirely when a provider reports none (no fabricated zeros),
  consistent across every finish path under exactOptionalPropertyTypes.
- Port the cached/reasoning token badges from the deleted MessageCard/
  MessageGroup into IterationCard.
- Fix two usage-extraction tests whose `class { chat }` SDK mocks collided with
  the `chat` named import under useDefineForClassFields.

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

Author: tombeckenham

.agent/self-learning/.gitignore

@@ -0,0 +1,2 @@
+fallback-counts.json
+*.bak

.agent/self-learning/INDEX.md

@@ -0,0 +1,12 @@
+# Lessons Index
+
+Read this index every turn. Each entry below is a routing condition.
+If a `Use when ...` condition matches the current task, read the full lesson file.
+
+<!-- LESSONS:START -->
+<!-- Auto-managed by self-improve plugin. Manual edits preserved between markers. -->
+
+- [build-before-running-examples](lessons/2026-05-14-build-before-running-examples.md) — Use when starting any tanstack/ai example dev server — build workspace packages first
+- [update-skills-with-feature-work](lessons/2026-05-19-update-skills-with-feature-work.md) — Use when implementing a feature in tanstack/ai that touches a surface covered by an agent skill — the skill needs to be updated in the same PR
+- [update-docs-with-new-cases](lessons/2026-05-19-update-docs-with-new-cases.md) — Use when adding a new use case, capability, or behavior change to tanstack/ai — public docs that cover the surface need updating in the same PR
+<!-- LESSONS:END -->

.agent/self-learning/config.yml

@@ -0,0 +1,15 @@
+# Self-improve plugin behavior knobs. Edit and commit per repo.
+correction_detection:
+  enabled: true
+  regex_strictness: loose # loose | strict
+coupling_detection:
+  enabled: true
+  regex_strictness: loose
+enforcement:
+  pre_push_block: true # false = warn only, do not block push
+curation:
+  default_interval_days: 30
+promotion:
+  auto_suggest_global: true
+  skill_improve_threshold: 3
+skills_repo: ~/.claude/skills

.agent/self-learning/coupling.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "./coupling.schema.json",
+  "couplings": [
+    {
+      "id": "ai-source-touches-agent-skills",
+      "trigger": "packages/ai*/src/**/*.ts",
+      "impacts": [
+        {
+          "target": [
+            "packages/ai/skills/ai-core/structured-outputs/SKILL.md",
+            "packages/ai/skills/ai-core/chat-experience/SKILL.md",
+            "packages/ai/skills/ai-core/tool-calling/SKILL.md",
+            "packages/ai/skills/ai-core/adapter-configuration/SKILL.md",
+            "packages/ai/skills/ai-core/middleware/SKILL.md",
+            "packages/ai/skills/ai-core/media-generation/SKILL.md",
+            "packages/ai/skills/ai-core/ag-ui-protocol/SKILL.md",
+            "packages/ai/skills/ai-core/debug-logging/SKILL.md",
+            "packages/ai/skills/ai-core/custom-backend-integration/SKILL.md",
+            "packages/ai-code-mode/skills/ai-code-mode/SKILL.md"
+          ],
+          "kind": "change-required",
+          "why": "Agent skills are a contract with downstream coding agents. When the source surface they cover changes (new public API, changed type, new pattern, removed pattern, deprecation), the skill must be updated in the same PR — otherwise agents reading the skill keep generating obsolete or wrong code targeting a surface that no longer exists. Use this list to decide which skill(s) cover the file you're touching: `activities/chat/**` → chat-experience / structured-outputs / tool-calling; `activities/generateImage|generateAudio|generateVideo|generateSpeech|generateTranscription|summarize/**` → media-generation; `middleware/**` → middleware; `protocol/**` → ag-ui-protocol; `adapters/**` or anything that affects the adapter contract → adapter-configuration. Skip only for pure refactors / perf / internal-only changes that don't surface a new pattern or change observable behavior."
+        }
+      ]
+    },
+    {
+      "id": "ai-source-touches-public-docs",
+      "trigger": "packages/ai*/src/**/*.ts",
+      "impacts": [
+        {
+          "target": [
+            "docs/structured-outputs/**/*.md",
+            "docs/chat/**/*.md",
+            "docs/tools/**/*.md",
+            "docs/adapters/**/*.md",
+            "docs/advanced/**/*.md",
+            "docs/api/**/*.md",
+            "docs/getting-started/**/*.md",
+            "docs/protocol/**/*.md",
+            "docs/media/**/*.md",
+            "docs/code-mode/**/*.md",
+            "docs/migration/**/*.md"
+          ],
+          "kind": "change-required",
+          "why": "Public docs are the canonical source for users. When the source surface they describe changes — new capability, behavior change, deprecation — the docs must be updated in the same PR. Cases to watch for: (1) the new behavior contradicts existing doc advice (e.g. removing a hack the doc still recommends); (2) the new capability opens a use case no existing page covers (consider whether a new page is needed, plus nav config and cross-links); (3) a public type / function gains or loses generic parameters, optional fields, etc. Run `pnpm test:docs` after editing to catch cross-link rot. Skip only for pure refactors / perf / internal-only changes."
+        }
+      ]
+    },
+    {
+      "id": "ai-source-touches-e2e-coverage",
+      "trigger": "packages/ai*/src/**/*.ts",
+      "impacts": [
+        {
+          "target": [
+            "testing/e2e/tests/**/*.spec.ts",
+            "testing/e2e/fixtures/**",
+            "testing/e2e/src/lib/feature-support.ts",
+            "testing/e2e/src/lib/types.ts"
+          ],
+          "kind": "new-code-required",
+          "why": "Per CLAUDE.md, every feature / bug fix / behavior change MUST include E2E test coverage. When a new public capability is added, a corresponding spec under testing/e2e/tests/ plus a fixture under testing/e2e/fixtures/ are required — often plus a new entry in feature-support.ts and types.ts. The full pattern is: add the Feature flag, decide provider support, optionally add a per-feature config (system prompt, schema, tools), wire it through src/routes/api.chat.ts (or the relevant route), write the fixture(s), write the spec iterating `providersFor(feature)`. Spec must run against every supported provider so non-native-streaming providers exercise the fallback path. Skip only for refactors that don't change observable behavior."
+        }
+      ]
+    }
+  ]
+}

.agent/self-learning/curation-state.yml

@@ -0,0 +1,3 @@
+last_curated: 2026-05-14
+next_nag: 2026-06-13
+default_interval_days: 30

.agent/self-learning/lessons/2026-05-14-build-before-running-examples.md

@@ -0,0 +1,19 @@
+---
+name: build-before-running-examples
+description: Use when starting any tanstack/ai example dev server — build workspace packages first
+tags: [monorepo, examples, dev-workflow, build]
+scope: repo
+source:
+  type: auto-captured
+  created: 2026-05-14T13:05:00Z
+related_skill: null
+related: []
+---
+
+# Build Workspace Packages Before Running Examples
+
+**Rule:** Run `pnpm -w run build:all` from the repo root before starting any example dev server (`examples/ts-react-chat`, `ts-solid-chat`, `ts-vue-chat`, `ts-svelte-chat`, `vanilla-chat`, `ts-group-chat`).
+
+**Why:** "this was a mistake by you, you should always build packages inside of this repo before you run the examples" — examples import workspace packages (`@tanstack/ai`, `@tanstack/react-ai-devtools`, `@tanstack/ai-devtools-core`, etc.) via `workspace:*` and resolve through each package's `exports` field pointing at `dist/`. If `dist/` is missing for any package — including transitive ones — vite's dep-scan fails and SSR returns a 500. Fixing the first missing package one at a time wastes round-trips: I tried `pnpm --filter @tanstack/react-ai-devtools build`, hit a missing `@tanstack/ai-devtools-core`, etc. The cure is one command up front.
+
+**How to apply:** Before any `pnpm --filter "<example-name>" dev` (or running an example via its own directory), run `pnpm -w run build:all` from the worktree root. Nx caches the build so re-runs are cheap. Skip only if the user has just explicitly said the workspace is freshly built.

.agent/self-learning/lessons/2026-05-19-update-docs-with-new-cases.md

@@ -0,0 +1,28 @@
+---
+name: update-docs-with-new-cases
+description: Use when adding a new use case, capability, or behavior change to tanstack/ai — public docs that cover the surface need updating in the same PR
+tags: [documentation, monorepo, pr-discipline]
+scope: repo
+source:
+  type: user-correction
+  created: 2026-05-19T11:50:00Z
+related_skill: null
+related: [update-skills-with-feature-work]
+---
+
+# Docs Need to Be Updated When Adding New Cases
+
+**Rule:** When a PR adds a new pattern, capability, or behavior change to the public surface of any tanstack/ai package, update the corresponding doc page(s) in `docs/**` in the same PR. New cases that aren't documented don't exist for users.
+
+**Why:** The user flagged this after shipping the multi-turn structured-output PR. Initial commits added the typed `StructuredOutputPart` on `useChat`'s `messages`, the schema-generic flow through `UIMessage<TTools, TData>`, and the recipe-builder pattern — but the docs only got updated several turns later, after the user explicitly asked. The window between "feature ships" and "docs catch up" is a window where users following the docs hit either obsolete advice (the "hide TextPart" filter hack the PR removed) or missing capability (no mention of multi-turn structured chat at all). Both are silent failures.
+
+**How to apply:**
+
+1. **At feature-design time**, identify which doc pages cover the surface being changed. Grep `docs/**` for the symbols, types, hooks, or patterns the feature touches. Note them as part of the implementation plan, not as follow-up.
+2. **For each affected doc page, decide:** does it need a correction (the feature contradicts what's written) or an addition (the feature opens a new use case)? Often both.
+3. **If a new use case warrants its own page**, plan the page placement / IA at feature-design time. New pages often imply nav-config updates (`docs/config.json`), a deprecation stub at the old location, and cross-link edits in adapter / API reference docs.
+4. **Run `pnpm test:docs` after editing** — the link checker catches the cross-link rot reorgs introduce.
+5. **Fact-check the docs** the same way as agent skills — dispatch a verification pass against the current source. Hallucinated APIs in docs send users down dead ends.
+6. **Coordinate with the related skill update** (see [[update-skills-with-feature-work]]) — the same surface change usually needs both, and the same fact-check pattern catches the same kinds of bugs.
+
+**Heuristic for "does this PR need doc updates":** if the answer to "would a user reading the existing docs after this PR ships be misled?" is yes, the docs need updating. If the answer to "would a user benefit from knowing about the new capability?" is yes, the docs need adding to. Most non-trivial PRs hit one of those two.

.agent/self-learning/lessons/2026-05-19-update-skills-with-feature-work.md

@@ -0,0 +1,27 @@
+---
+name: update-skills-with-feature-work
+description: Use when implementing a feature in tanstack/ai that touches a surface covered by an agent skill — the skill needs to be updated in the same PR
+tags: [agent-skills, documentation, monorepo, pr-discipline]
+scope: repo
+source:
+  type: user-correction
+  created: 2026-05-19T11:50:00Z
+related_skill: null
+related: [update-docs-with-new-cases]
+---
+
+# Agent Skills Need to Be Updated With the Feature Work That Touches Them
+
+**Rule:** When implementing a feature that changes or extends a surface covered by an agent skill under `packages/ai/skills/**` or `packages/ai-code-mode/skills/**`, update the skill in the same PR. Don't treat skill updates as a follow-up — they ship to coding agents that read them as authoritative.
+
+**Why:** The user pointed this out after I'd already landed code, docs, e2e tests, and the example UI for the multi-turn structured-output PR (#577) without touching `ai-core/structured-outputs/SKILL.md`. The skill was still documenting the old single-slot `partial` / `final` design and still telling agents to filter `TextPart`s out of `useChat` renderers — the exact hack the PR removes. Without the skill update, every coding agent reading that skill would continue generating the obsolete pattern. Skills are a contract with downstream agents the same way the public API is a contract with users.
+
+**How to apply:**
+
+1. **Before shipping any non-trivial feature**, grep `packages/ai*/skills/**/SKILL.md` for the symbols, types, hooks, or patterns the feature touches. If any skill mentions them, that skill needs review.
+2. **Check both directions:** does the skill teach something the feature now makes wrong? Does the feature introduce a pattern the skill should add? Both warrant edits.
+3. **Update in the same PR as the feature code.** Splitting into a follow-up means the skill is stale during the window between merges — and during that window, agents reading the skill generate broken code that targets a surface that no longer exists.
+4. **After updating, fact-check the skill the same way as the docs** — dispatch a verification pass against the current source code. Hallucinations in skills propagate further than hallucinations in docs because agents act on them autonomously.
+5. **Don't forget the description / sources frontmatter** — `sources:` paths break silently when docs get reorganized (e.g. when `chat/structured-outputs.md` becomes a redirect stub and the real content moves to `structured-outputs/*`).
+
+**Heuristic for "is this feature skill-relevant":** if the feature adds a new public API, changes the shape of a public type, deprecates a pattern, or introduces a new way of consuming an existing surface, the answer is yes. Pure refactors and internal-only changes can usually skip it.