@tanstack/ai 0.19.0 → 0.20.0

package/src/index.ts

@@ -104,6 +104,10 @@ export type {
 // All types
 export * from './types'
 
+// System prompts (type + normaliser used by adapters)
+export type { SystemPrompt, NormalizedSystemPrompt } from './system-prompts'
+export { normalizeSystemPrompts } from './system-prompts'
+
 // Utility functions
 export { detectImageMimeType } from './utils'
 

package/src/middlewares/otel.ts

@@ -372,9 +372,29 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
         state.assistantTextBufferTruncated = false
 
         if (captureContent) {
+          const systemPromptContents = config.systemPrompts.map((p) =>
+            typeof p === 'string' ? p : p.content,
+          )
+          // Anthropic prompt-caching users need to know which prompt carried
+          // `cache_control`: it's the one attribute that explains cache
+          // hit/miss in observability. Serialise per-prompt metadata as a
+          // single JSON span attribute so backends that don't understand
+          // GenAI events can still surface it. Kept off span events to
+          // avoid breaking the one-event-per-message GenAI semconv contract.
+          const systemPromptMetadata = config.systemPrompts.map((p) =>
+            typeof p === 'string' || p.metadata === undefined
+              ? null
+              : p.metadata,
+          )
+          if (systemPromptMetadata.some((m) => m !== null)) {
+            iterSpan.setAttribute(
+              'tanstack.ai.system_prompt.metadata',
+              JSON.stringify(systemPromptMetadata),
+            )
+          }
           // Span events follow the original GenAI semconv (one event per
           // message). Backends that read events get content this way.
-          for (const sys of config.systemPrompts) {
+          for (const sys of systemPromptContents) {
             iterSpan.addEvent('gen_ai.system.message', {
               content: redactContent(sys),
             })
@@ -391,7 +411,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
           // (`gen_ai.input.messages`) — backends like PostHog read prompt
           // content from this attribute, not from span events.
           const inputMessages: Array<{ role: string; content: string }> = []
-          for (const sys of config.systemPrompts) {
+          for (const sys of systemPromptContents) {
             inputMessages.push({
               role: 'system',
               content: redactContent(sys),

package/src/system-prompts.ts

@@ -0,0 +1,98 @@
+/**
+ * A single entry in `chat({ systemPrompts: [...] })`.
+ *
+ * Accepts a plain string (the common case) or a structured object that lets
+ * providers attach typed metadata to the prompt — e.g. Anthropic
+ * `cache_control` for prompt caching, future per-prompt safety overrides for
+ * Gemini, etc.
+ *
+ * At the chat call site, `metadata` is narrowed by the adapter via
+ * `~types['systemPromptMetadata']`. Providers that don't declare one inherit
+ * the default `never`, which makes the field carry no meaningful value: TS
+ * only accepts `undefined` there, and provider-foreign metadata that reaches
+ * an adapter via JS / `as any` is silently dropped, never written to the
+ * wire. For type-safe per-provider metadata, refer to the provider's
+ * `<Provider>SystemPromptMetadata` interface (e.g. `AnthropicSystemPromptMetadata`).
+ *
+ * @example
+ *   // The 90% case — plain strings work everywhere.
+ *   systemPrompts: ['Be concise.', 'Cite sources.']
+ *
+ * @example
+ *   // Provider-specific metadata via the object form. No `satisfies` cast
+ *   // is needed — the adapter narrows the `metadata` field's type at the
+ *   // call site so users get autocomplete and structural checking
+ *   // automatically.
+ *   import { anthropicText } from '@tanstack/ai-anthropic'
+ *
+ *   chat({
+ *     adapter: anthropicText(),
+ *     systemPrompts: [
+ *       {
+ *         content: 'Stable instructions — cache me.',
+ *         metadata: { cache_control: { type: 'ephemeral' } },
+ *       },
+ *       'Volatile per-request instruction.',
+ *     ],
+ *   })
+ */
+export type SystemPrompt<TMetadata = unknown> =
+  | string
+  | {
+      content: string
+      metadata?: TMetadata
+    }
+
+/**
+ * Normalised shape adapters see after the chat layer turns string entries
+ * into `{ content }` objects. Adapters call `normalizeSystemPrompts` once at
+ * the top of their option-mapping pipeline so the rest of the code only has
+ * to handle one shape.
+ */
+export interface NormalizedSystemPrompt<TMetadata = unknown> {
+  content: string
+  metadata?: TMetadata
+}
+
+/**
+ * Normalise the public `systemPrompts` shape (`Array<string | { content, metadata? }>`)
+ * to a homogenous `Array<{ content, metadata? }>`. Adapters use this so they
+ * don't have to type-narrow string vs object inline.
+ *
+ * Returns an empty array (never `undefined`) so callers can chain `.map` /
+ * `.join` without an extra null check.
+ *
+ * Throws a `TypeError` (naming the offending index) if an object-form entry's
+ * `content` isn't a string. Public API boundary — callers reaching this
+ * function through `as any` / external JS would otherwise stream a literal
+ * `"undefined"` into the model's system prompt with no signal.
+ */
+export function normalizeSystemPrompts<TMetadata = unknown>(
+  // Accept the wide public shape (`SystemPrompt<unknown>`) regardless of the
+  // caller's `TMetadata`. Adapters know their own metadata shape; the
+  // generic narrows the *output* so adapter code can read `p.metadata.X`
+  // without an additional cast.
+  prompts: ReadonlyArray<SystemPrompt> | undefined,
+): Array<NormalizedSystemPrompt<TMetadata>> {
+  if (!prompts || prompts.length === 0) return []
+  return prompts.map((p, i) => {
+    if (typeof p === 'string') return { content: p }
+    // Defence in depth: TypeScript narrows `p` to the object arm here, but
+    // this function is a public API boundary that callers can reach via
+    // plain JS or `as any`. Re-validate at runtime so we never stream a
+    // literal `"undefined"` into the model.
+    const candidate = p as unknown
+    if (candidate === null || typeof candidate !== 'object') {
+      throw new TypeError(
+        `systemPrompts[${i}]: expected a string or { content, metadata? }, got ${candidate === null ? 'null' : typeof candidate}`,
+      )
+    }
+    const { content } = candidate as { content?: unknown }
+    if (typeof content !== 'string') {
+      throw new TypeError(
+        `systemPrompts[${i}]: content must be a string, got ${typeof content}`,
+      )
+    }
+    return p as NormalizedSystemPrompt<TMetadata>
+  })
+}

package/src/types.ts

@@ -3,6 +3,7 @@ import type {
   StandardSchemaV1,
 } from '@standard-schema/spec'
 import type { InternalLogger } from './logger/internal-logger'
+import type { SystemPrompt } from './system-prompts'
 import type {
   BaseEvent as AGUIBaseEvent,
   CustomEvent as AGUICustomEvent,
@@ -729,7 +730,21 @@ export interface TextOptions<
   model: string
   messages: Array<ModelMessage>
   tools?: Array<Tool<any, any, any>>
-  systemPrompts?: Array<string>
+  /**
+   * System prompts to include with the request.
+   *
+   * Accepts plain strings (the common case) or `{ content, metadata }`
+   * objects that let providers attach typed metadata (e.g. Anthropic
+   * `cache_control` for prompt caching) per prompt. At the chat call site
+   * the adapter narrows `metadata`'s type via `~types['systemPromptMetadata']`
+   * — providers that don't declare one default to `never`, which makes the
+   * field carry no meaningful value (TypeScript will only accept
+   * `undefined` there). Provider-foreign metadata that reaches an adapter
+   * via JS / `as any` is silently dropped, never written to the wire.
+   *
+   * @see SystemPrompt
+   */
+  systemPrompts?: Array<SystemPrompt>
   agentLoopStrategy?: AgentLoopStrategy
   /**
    * Controls the randomness of the output.
@@ -1146,10 +1161,9 @@ export interface CustomEvent extends AGUICustomEvent {
  * }
  * ```
  */
-export interface StructuredOutputCompleteEvent<T = unknown> extends Omit<
-  CustomEvent,
-  'name' | 'value'
-> {
+export interface StructuredOutputCompleteEvent<
+  T = unknown,
+> extends CustomEvent {
   name: 'structured-output.complete'
   value: { object: T; raw: string; reasoning?: string }
 }
@@ -1162,10 +1176,7 @@ export interface StructuredOutputCompleteEvent<T = unknown> extends Omit<
  * `messageId` the deltas will be tagged with so the routing decision can be
  * made per-message rather than globally.
  */
-export interface StructuredOutputStartEvent extends Omit<
-  CustomEvent,
-  'name' | 'value'
-> {
+export interface StructuredOutputStartEvent extends CustomEvent {
   name: 'structured-output.start'
   value: { messageId: string }
 }
@@ -1177,10 +1188,7 @@ export interface StructuredOutputStartEvent extends Omit<
  * (the agent-loop branch of `runStreamingStructuredOutputImpl` in
  * `activities/chat/index.ts` forwards CUSTOM events from `TextEngine.run()`).
  */
-export interface ApprovalRequestedEvent extends Omit<
-  CustomEvent,
-  'name' | 'value'
-> {
+export interface ApprovalRequestedEvent extends CustomEvent {
   name: 'approval-requested'
   value: {
     toolCallId: string
@@ -1196,10 +1204,7 @@ export interface ApprovalRequestedEvent extends Omit<
  * will not fire for that run. Shape fixed by the agent-loop forwarding in
  * `runStreamingStructuredOutputImpl` in `activities/chat/index.ts`.
  */
-export interface ToolInputAvailableEvent extends Omit<
-  CustomEvent,
-  'name' | 'value'
-> {
+export interface ToolInputAvailableEvent extends CustomEvent {
   name: 'tool-input-available'
   value: {
     toolCallId: string