@tanstack/ai 0.22.0 → 0.23.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TanStack/ai.git",
-    "directory": "packages/typescript/ai"
+    "directory": "packages/ai"
   },
   "type": "module",
   "module": "./dist/esm/index.js",
@@ -17,6 +17,10 @@
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
     },
+    "./client": {
+      "types": "./dist/esm/client.d.ts",
+      "import": "./dist/esm/client.js"
+    },
     "./adapters": {
       "types": "./dist/esm/activities/index.d.ts",
       "import": "./dist/esm/activities/index.js"
@@ -64,7 +68,7 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.3.11"
+    "@tanstack/ai-event-client": "0.4.1"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/skills/ai-core/adapter-configuration/SKILL.md

@@ -26,7 +26,7 @@ sources:
 
 > **Before implementing:** Ask the user which provider and model they want.
 > Then fetch the latest available models from the provider's source code
-> (check the adapter's model metadata file, e.g. `packages/typescript/ai-openai/src/model-meta.ts`)
+> (check the adapter's model metadata file, e.g. `packages/ai-openai/src/model-meta.ts`)
 > or from the provider's API/docs to recommend the most current model.
 > The model lists in this skill and its reference files may be outdated.
 > Always verify against the source before recommending a specific model.

package/skills/ai-core/debug-logging/SKILL.md

@@ -253,7 +253,7 @@ const safe: Logger = {
 }
 ```
 
-Source: packages/typescript/ai/src/logger/internal-logger.ts
+Source: packages/ai/src/logger/internal-logger.ts
 
 ## Cross-References
 

package/src/activities/chat/index.ts

@@ -481,6 +481,7 @@ class TextEngine<
     this.middlewareCtx = {
       requestId: this.requestId,
       streamId: this.streamId,
+      runId: this.runIdOverride ?? this.requestId,
       threadId: this.threadId,
       // Legacy alias kept on the ctx so middleware that reads
       // `ctx.conversationId` keeps working. Always equals `threadId`.

package/src/activities/chat/middleware/types.ts

@@ -4,6 +4,7 @@ import type {
   StreamChunk,
   Tool,
   ToolCall,
+  UsageTotals,
 } from '../../../types'
 import type { SystemPrompt } from '../../../system-prompts'
 
@@ -38,6 +39,8 @@ export interface ChatMiddlewareContext {
   requestId: string
   /** Unique identifier for this stream */
   streamId: string
+  /** AG-UI run identifier for correlating client and server events */
+  runId: string
   /**
    * AG-UI thread identifier — a stable per-conversation ID used to
    * correlate client and server devtools events. Resolves to the
@@ -262,12 +265,12 @@ export interface ToolPhaseCompleteInfo {
 /**
  * Token usage statistics passed to the onUsage hook.
  * Extracted from the RUN_FINISHED chunk when usage data is present.
+ *
+ * Includes optional provider-reported `cost`/`costDetails` (see {@link UsageTotals}).
+ * Kept as an interface extending `UsageTotals` to preserve declaration merging for
+ * this publicly exported type.
  */
-export interface UsageInfo {
-  promptTokens: number
-  completionTokens: number
-  totalTokens: number
-}
+export interface UsageInfo extends UsageTotals {}
 
 // ===========================
 // Terminal Hook Info
@@ -283,14 +286,8 @@ export interface FinishInfo {
   duration: number
   /** Final accumulated text content */
   content: string
-  /** Final usage totals, if available */
-  usage?:
-    | {
-        promptTokens: number
-        completionTokens: number
-        totalTokens: number
-      }
-    | undefined
+  /** Final usage totals, if available (optionally including provider-reported cost) */
+  usage?: UsageTotals | undefined
 }
 
 /**

package/src/activities/chat/stream/processor.ts

@@ -98,6 +98,17 @@ export interface StreamProcessorEvents {
     stepId: string,
     content: string,
   ) => void
+  onStructuredOutputChange?: (args: {
+    phase: 'start' | 'update' | 'complete' | 'error'
+    messageId: string
+    status: 'streaming' | 'complete' | 'error'
+    raw: string
+    partial?: unknown
+    data?: unknown
+    reasoning?: string
+    errorMessage?: string
+    delta?: string
+  }) => void
 }
 
 /**
@@ -116,6 +127,8 @@ export interface StreamProcessorOptions {
   initialMessages?: Array<UIMessage>
 }
 
+const STRUCTURED_OUTPUT_UPDATE_BATCH_SIZE = 12
+
 /**
  * StreamProcessor - State machine for processing AI response streams
  *
@@ -149,6 +162,13 @@ export class StreamProcessor {
   private pendingThinkingStepId: string | null = null
 
   private readonly structuredMessageIds: Set<string> = new Set()
+  private readonly structuredOutputUpdateBatches = new Map<
+    string,
+    {
+      delta: string
+      chunkCount: number
+    }
+  >()
 
   // Run tracking (for concurrent run safety)
   private readonly activeRuns = new Set<string>()
@@ -401,6 +421,9 @@ export class StreamProcessor {
     for (const id of this.structuredMessageIds) {
       if (!keptIds.has(id)) this.structuredMessageIds.delete(id)
     }
+    for (const id of this.structuredOutputUpdateBatches.keys()) {
+      if (!keptIds.has(id)) this.structuredOutputUpdateBatches.delete(id)
+    }
     for (const id of this.messageStates.keys()) {
       if (!keptIds.has(id)) this.messageStates.delete(id)
     }
@@ -423,6 +446,7 @@ export class StreamProcessor {
     this.activeMessageIds.clear()
     this.toolCallToMessage.clear()
     this.structuredMessageIds.clear()
+    this.structuredOutputUpdateBatches.clear()
     this.pendingManualMessageId = null
     this.emitMessagesChange()
   }
@@ -899,6 +923,7 @@ export class StreamProcessor {
           delta,
         )
         state.totalTextContent += delta
+        this.queueStructuredOutputUpdate(messageId, delta)
         this.emitMessagesChange()
       }
       return
@@ -1269,12 +1294,14 @@ export class StreamProcessor {
     }
 
     if (this.structuredMessageIds.has(messageId)) {
+      this.flushStructuredOutputUpdate(messageId)
       this.messages = errorStructuredOutputPart(
         this.messages,
         messageId,
         errorMessage,
       )
       this.structuredMessageIds.delete(messageId)
+      this.emitStructuredOutputChange(messageId, 'error')
       this.emitMessagesChange()
     }
 
@@ -1463,6 +1490,13 @@ export class StreamProcessor {
       if (targetId) {
         this.ensureAssistantMessage(targetId)
         this.structuredMessageIds.add(targetId)
+        this.structuredOutputUpdateBatches.delete(targetId)
+        this.events.onStructuredOutputChange?.({
+          phase: 'start',
+          messageId: targetId,
+          status: 'streaming',
+          raw: '',
+        })
       }
       return
     }
@@ -1476,6 +1510,7 @@ export class StreamProcessor {
       }
       const targetId = v.messageId ?? messageId
       if (targetId) {
+        this.flushStructuredOutputUpdate(targetId)
         this.messages = completeStructuredOutputPart(
           this.messages,
           targetId,
@@ -1484,6 +1519,7 @@ export class StreamProcessor {
           v.reasoning,
         )
         this.structuredMessageIds.delete(targetId)
+        this.emitStructuredOutputChange(targetId, 'complete')
         this.emitMessagesChange()
       }
       // Fall through so user `onCustomEvent` callbacks still observe the event.
@@ -1665,6 +1701,58 @@ export class StreamProcessor {
     this.events.onTextUpdate?.(messageId, state.currentSegmentText)
   }
 
+  private queueStructuredOutputUpdate(messageId: string, delta: string): void {
+    const existing = this.structuredOutputUpdateBatches.get(messageId)
+    const next = {
+      delta: `${existing?.delta ?? ''}${delta}`,
+      chunkCount: (existing?.chunkCount ?? 0) + 1,
+    }
+
+    this.structuredOutputUpdateBatches.set(messageId, next)
+
+    if (next.chunkCount >= STRUCTURED_OUTPUT_UPDATE_BATCH_SIZE) {
+      this.flushStructuredOutputUpdate(messageId)
+    }
+  }
+
+  private flushStructuredOutputUpdate(messageId: string): void {
+    const batch = this.structuredOutputUpdateBatches.get(messageId)
+    if (!batch || batch.chunkCount === 0) return
+
+    this.structuredOutputUpdateBatches.delete(messageId)
+    this.emitStructuredOutputChange(messageId, 'update', batch.delta)
+  }
+
+  private emitStructuredOutputChange(
+    messageId: string,
+    phase: 'update' | 'complete' | 'error',
+    delta?: string,
+  ): void {
+    const part = this.messages
+      .find((message) => message.id === messageId)
+      ?.parts.find(
+        (
+          messagePart,
+        ): messagePart is Extract<MessagePart, { type: 'structured-output' }> =>
+          messagePart.type === 'structured-output',
+      )
+    if (!part) return
+
+    this.events.onStructuredOutputChange?.({
+      phase,
+      messageId,
+      status: part.status,
+      raw: part.raw,
+      ...(part.partial !== undefined ? { partial: part.partial } : {}),
+      ...(part.data !== undefined ? { data: part.data } : {}),
+      ...(part.reasoning !== undefined ? { reasoning: part.reasoning } : {}),
+      ...(part.errorMessage !== undefined
+        ? { errorMessage: part.errorMessage }
+        : {}),
+      ...(delta !== undefined ? { delta } : {}),
+    })
+  }
+
   /**
    * Emit messages change event
    */
@@ -1718,13 +1806,16 @@ export class StreamProcessor {
     // definition a non-errored, never-completed run (the multi-run case:
     // run-A errors, run-B is still streaming when finalize fires).
     for (const messageId of this.structuredMessageIds) {
+      this.flushStructuredOutputUpdate(messageId)
       this.messages = errorStructuredOutputPart(
         this.messages,
         messageId,
         'Stream ended without structured-output.complete',
       )
+      this.emitStructuredOutputChange(messageId, 'error')
     }
     this.structuredMessageIds.clear()
+    this.structuredOutputUpdateBatches.clear()
 
     this.activeMessageIds.clear()
 
@@ -1855,6 +1946,7 @@ export class StreamProcessor {
     this.activeRuns.clear()
     this.toolCallToMessage.clear()
     this.structuredMessageIds.clear()
+    this.structuredOutputUpdateBatches.clear()
     this.pendingManualMessageId = null
     this.pendingThinkingStepId = null
     this.finishReason = null

package/src/client.ts

@@ -0,0 +1,132 @@
+export enum EventType {
+  TEXT_MESSAGE_START = 'TEXT_MESSAGE_START',
+  TEXT_MESSAGE_CONTENT = 'TEXT_MESSAGE_CONTENT',
+  TEXT_MESSAGE_END = 'TEXT_MESSAGE_END',
+  TEXT_MESSAGE_CHUNK = 'TEXT_MESSAGE_CHUNK',
+  TOOL_CALL_START = 'TOOL_CALL_START',
+  TOOL_CALL_ARGS = 'TOOL_CALL_ARGS',
+  TOOL_CALL_END = 'TOOL_CALL_END',
+  TOOL_CALL_CHUNK = 'TOOL_CALL_CHUNK',
+  TOOL_CALL_RESULT = 'TOOL_CALL_RESULT',
+  THINKING_START = 'THINKING_START',
+  THINKING_END = 'THINKING_END',
+  THINKING_TEXT_MESSAGE_START = 'THINKING_TEXT_MESSAGE_START',
+  THINKING_TEXT_MESSAGE_CONTENT = 'THINKING_TEXT_MESSAGE_CONTENT',
+  THINKING_TEXT_MESSAGE_END = 'THINKING_TEXT_MESSAGE_END',
+  STATE_SNAPSHOT = 'STATE_SNAPSHOT',
+  STATE_DELTA = 'STATE_DELTA',
+  MESSAGES_SNAPSHOT = 'MESSAGES_SNAPSHOT',
+  ACTIVITY_SNAPSHOT = 'ACTIVITY_SNAPSHOT',
+  ACTIVITY_DELTA = 'ACTIVITY_DELTA',
+  RAW = 'RAW',
+  CUSTOM = 'CUSTOM',
+  RUN_STARTED = 'RUN_STARTED',
+  RUN_FINISHED = 'RUN_FINISHED',
+  RUN_ERROR = 'RUN_ERROR',
+  STEP_STARTED = 'STEP_STARTED',
+  STEP_FINISHED = 'STEP_FINISHED',
+  REASONING_START = 'REASONING_START',
+  REASONING_MESSAGE_START = 'REASONING_MESSAGE_START',
+  REASONING_MESSAGE_CONTENT = 'REASONING_MESSAGE_CONTENT',
+  REASONING_MESSAGE_END = 'REASONING_MESSAGE_END',
+  REASONING_MESSAGE_CHUNK = 'REASONING_MESSAGE_CHUNK',
+  REASONING_END = 'REASONING_END',
+  REASONING_ENCRYPTED_VALUE = 'REASONING_ENCRYPTED_VALUE',
+}
+
+export {
+  toolDefinition,
+  type AnyClientTool,
+  type ClientTool,
+  type InferToolInput,
+  type InferToolName,
+  type InferToolOutput,
+  type ToolDefinition,
+  type ToolDefinitionConfig,
+  type ToolDefinitionInstance,
+} from './activities/chat/tools/tool-definition'
+
+export { convertSchemaToJsonSchema } from './activities/chat/tools/schema-converter'
+
+export {
+  convertMessagesToModelMessages,
+  generateMessageId,
+  modelMessageToUIMessage,
+  modelMessagesToUIMessages,
+  normalizeToUIMessage,
+  uiMessageToModelMessages,
+} from './activities/chat/messages'
+
+export {
+  BatchStrategy,
+  CompositeStrategy,
+  defaultJSONParser,
+  ImmediateStrategy,
+  parsePartialJSON,
+  PartialJSONParser,
+  PunctuationStrategy,
+  StreamProcessor,
+  WordBoundaryStrategy,
+} from './activities/chat/stream/index'
+export type {
+  ChunkRecording,
+  ChunkStrategy,
+  InternalToolCallState,
+  JSONParser,
+  ProcessorResult,
+  ProcessorState,
+  StreamProcessorEvents,
+  StreamProcessorOptions,
+  ToolCallState,
+  ToolResultState,
+} from './activities/chat/stream/index'
+
+export { uiMessagesToWire } from './utilities/ag-ui-wire'
+export type { WireMessage } from './utilities/ag-ui-wire'
+
+export type {
+  AudioPart,
+  ContentPart,
+  ContentPartDataSource,
+  ContentPartSource,
+  ContentPartUrlSource,
+  CustomEvent,
+  DocumentPart,
+  ImagePart,
+  MessagePart,
+  ModelMessage,
+  RunErrorEvent,
+  RunFinishedEvent,
+  SchemaInput,
+  StreamChunk,
+  StructuredOutputPart,
+  TextPart,
+  ThinkingPart,
+  ToolCall,
+  ToolCallPart,
+  ToolResultPart,
+  UIMessage,
+  VideoPart,
+  InferSchemaType,
+} from './types'
+
+export type {
+  AudioVisualization,
+  RealtimeError,
+  RealtimeErrorCode,
+  RealtimeEvent,
+  RealtimeEventHandler,
+  RealtimeEventPayloads,
+  RealtimeMessage,
+  RealtimeMessagePart,
+  RealtimeMode,
+  RealtimeSessionConfig,
+  RealtimeStatus,
+  RealtimeToken,
+  RealtimeAudioPart,
+  RealtimeImagePart,
+  RealtimeTextPart,
+  RealtimeToolCallPart,
+  RealtimeToolResultPart,
+  VADConfig,
+} from './realtime/types'

package/src/types.ts

@@ -925,6 +925,39 @@ export interface RunStartedEvent extends AGUIRunStartedEvent {
   model?: string
 }
 
+/**
+ * Provider-reported cost breakdown for a single request, normalized onto a
+ * canonical shape so consumer code is portable across gateways. Each adapter's
+ * extractor maps its provider-specific wire keys (e.g. OpenRouter's
+ * `upstream_inference_prompt_cost`, `upstream_inference_input_cost`) onto these
+ * fields at runtime.
+ */
+export interface UsageCostBreakdown {
+  /** Total cost the gateway paid the upstream provider. */
+  upstreamCost?: number
+  /** Upstream cost for input (prompt) tokens. */
+  upstreamInputCost?: number
+  /** Upstream cost for output (completion) tokens. */
+  upstreamOutputCost?: number
+}
+
+/**
+ * Token usage totals for a run, optionally including provider-reported cost.
+ *
+ * `cost` and `costDetails` are populated only by adapters whose provider returns
+ * authoritative per-request cost (e.g. OpenRouter). They are absent for adapters
+ * that do not report cost, so consumers must treat them as optional.
+ */
+export interface UsageTotals {
+  promptTokens: number
+  completionTokens: number
+  totalTokens: number
+  /** Provider-reported cost for the request, when available. */
+  cost?: number
+  /** Provider-reported cost breakdown, when available. */
+  costDetails?: UsageCostBreakdown
+}
+
 /**
  * Emitted when a run completes successfully.
  *
@@ -936,12 +969,8 @@ export interface RunFinishedEvent extends AGUIRunFinishedEvent {
   model?: string
   /** Why the generation stopped */
   finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null
-  /** Token usage statistics */
-  usage?: {
-    promptTokens: number
-    completionTokens: number
-    totalTokens: number
-  }
+  /** Token usage statistics, optionally including provider-reported cost. */
+  usage?: UsageTotals
 }
 
 /**