@tanstack/ai 0.19.1 → 0.20.1

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/tools/provider-tool.ts

@@ -23,3 +23,17 @@ export interface ProviderTool<
   readonly '~provider': TProvider
   readonly '~toolKind': TKind
 }
+
+/**
+ * Attach the `ProviderTool` phantom brand to a plain `Tool`-shaped object.
+ *
+ * The brand fields (`'~provider'`, `'~toolKind'`) exist only in the type
+ * system and are never assigned at runtime, so this is a single audited
+ * type-only assertion. Use it inside adapter `xxxTool()` factories instead
+ * of `as unknown as` — the cast collapses to one named site.
+ */
+export function brandProviderTool<T extends ProviderTool<string, string>>(
+  tool: Omit<T, '~provider' | '~toolKind'>,
+): T {
+  return tool as T
+}

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,
@@ -585,7 +586,9 @@ export interface Tool<
    *   return weather; // Can return object or string
    * }
    */
-  execute?: (args: any, context?: ToolExecutionContext) => Promise<any> | any
+  execute?:
+    | ((args: any, context?: ToolExecutionContext) => Promise<any> | any)
+    | undefined
 
   /** If true, tool execution requires user approval before running. Works with both server and client tools. */
   needsApproval?: boolean
@@ -594,7 +597,7 @@ export interface Tool<
   lazy?: boolean
 
   /** Additional metadata for adapters or custom extensions */
-  metadata?: Record<string, any>
+  metadata?: Record<string, any> | undefined
 }
 
 export interface ToolConfig {
@@ -728,8 +731,22 @@ export interface TextOptions<
 > {
   model: string
   messages: Array<ModelMessage>
-  tools?: Array<Tool<any, any, any>>
-  systemPrompts?: Array<string>
+  tools?: Array<Tool<any, any, any>> | undefined
+  /**
+   * 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.
@@ -776,7 +793,7 @@ export interface TextOptions<
    * - Anthropic: `metadata` (Record<string, any>) - includes optional user_id (max 256 chars)
    * - Gemini: Not directly available in TextProviderOptions
    */
-  metadata?: Record<string, any>
+  metadata?: Record<string, any> | undefined
   modelOptions?: TProviderOptionsForModel
   request?: Request | RequestInit
 
@@ -923,10 +940,12 @@ export interface RunErrorEvent extends AGUIRunErrorEvent {
    * @deprecated Use top-level `message` and `code` fields instead.
    * Kept for backward compatibility.
    */
-  error?: {
-    message: string
-    code?: string
-  }
+  error?:
+    | {
+        message: string
+        code?: string | undefined
+      }
+    | undefined
 }
 
 /**

package/src/utilities/ag-ui-wire.ts

@@ -61,7 +61,7 @@ export function uiMessagesToWire(
         content:
           parts.length > 0
             ? collectText(parts)
-            : ((msg as unknown as { content?: string }).content ?? ''),
+            : ((msg as { content?: string }).content ?? ''),
       })
       continue
     }
@@ -72,7 +72,7 @@ export function uiMessagesToWire(
         content:
           parts.length > 0
             ? collectUserContent(parts)
-            : ((msg as unknown as { content?: string }).content ?? ''),
+            : ((msg as { content?: string }).content ?? ''),
       })
       continue
     }

package/src/utilities/chat-params.ts

@@ -131,7 +131,7 @@ export async function chatParamsFromRequest(
       'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',
       { status: 400 },
     )
-    ;(res as unknown as { cause?: unknown }).cause = cause
+    ;(res as { cause?: unknown }).cause = cause
     throw res
   }
   try {
@@ -145,7 +145,7 @@ export async function chatParamsFromRequest(
       'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',
       { status: 400 },
     )
-    ;(res as unknown as { cause?: unknown }).cause = cause
+    ;(res as { cause?: unknown }).cause = cause
     throw res
   }
 }