TanStack · AlemTuzlak · May 19, 2026 · May 19, 2026
diff --git a/.changeset/feat-system-prompts-metadata.md b/.changeset/feat-system-prompts-metadata.md
diff --git a/packages/typescript/ai-anthropic/CHANGELOG.md b/packages/typescript/ai-anthropic/CHANGELOG.md
@@ -1,5 +1,87 @@
 # @tanstack/ai-anthropic
 
+## 0.10.0
+
+### Minor Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.9.0
 
 ### Minor Changes

diff --git a/packages/typescript/ai-anthropic/package.json b/packages/typescript/ai-anthropic/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-anthropic",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Anthropic Claude adapter for TanStack AI",
   "author": "",
   "license": "MIT",

diff --git a/packages/typescript/ai-client/CHANGELOG.md b/packages/typescript/ai-client/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-client
 
+## 0.11.2
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-event-client@0.3.5
+
 ## 0.11.1
 
 ### Patch Changes

diff --git a/packages/typescript/ai-client/package.json b/packages/typescript/ai-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-client",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "Framework-agnostic headless client for TanStack AI",
   "author": "",
   "license": "MIT",

diff --git a/packages/typescript/ai-code-mode-skills/CHANGELOG.md b/packages/typescript/ai-code-mode-skills/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-code-mode-skills
 
+## 0.1.15
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-code-mode@0.1.15
+
 ## 0.1.14
 
 ### Patch Changes

diff --git a/packages/typescript/ai-code-mode-skills/package.json b/packages/typescript/ai-code-mode-skills/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-code-mode-skills",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Persistent skill library for TanStack AI Code Mode - LLM-created reusable code snippets",
   "author": "",
   "license": "MIT",

diff --git a/packages/typescript/ai-code-mode/CHANGELOG.md b/packages/typescript/ai-code-mode/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/ai-code-mode
 
+## 0.1.15
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.1.14
 
 ### Patch Changes

diff --git a/packages/typescript/ai-code-mode/package.json b/packages/typescript/ai-code-mode/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-code-mode",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Code Mode for TanStack AI - LLM-driven code execution in secure sandboxes",
   "author": "",
   "license": "MIT",

diff --git a/packages/typescript/ai-devtools/CHANGELOG.md b/packages/typescript/ai-devtools/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-devtools-core
 
+## 0.3.32
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-event-client@0.3.5
+
 ## 0.3.31
 
 ### Patch Changes

diff --git a/packages/typescript/ai-devtools/package.json b/packages/typescript/ai-devtools/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-devtools-core",
-  "version": "0.3.31",
+  "version": "0.3.32",
   "description": "Core TanStack AI Devtools",
   "author": "",
   "license": "MIT",

diff --git a/packages/typescript/ai-elevenlabs/CHANGELOG.md b/packages/typescript/ai-elevenlabs/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-elevenlabs
 
+## 0.2.7
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-client@0.11.2
+
 ## 0.2.6
 
 ### Patch Changes

diff --git a/packages/typescript/ai-elevenlabs/package.json b/packages/typescript/ai-elevenlabs/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-elevenlabs",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "ElevenLabs adapter for TanStack AI realtime voice",
   "author": "",
   "license": "MIT",

diff --git a/packages/typescript/ai-event-client/CHANGELOG.md b/packages/typescript/ai-event-client/CHANGELOG.md
@@ -1,5 +1,85 @@
 # @tanstack/ai-event-client
 
+## 0.3.5
+
+### Patch Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.3.4
 
 ### Patch Changes

diff --git a/packages/typescript/ai-event-client/package.json b/packages/typescript/ai-event-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-event-client",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Event client for TanStack AI devtools integration",
   "author": "",
   "license": "MIT",

diff --git a/packages/typescript/ai-fal/CHANGELOG.md b/packages/typescript/ai-fal/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/ai-fal
 
+## 0.7.8
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.7.7
 
 ### Patch Changes