@tanstack/ai 0.22.1 → 0.23.0

package/dist/esm/activities/chat/middleware/types.d.ts

@@ -1,4 +1,4 @@
-import { JSONSchema, ModelMessage, StreamChunk, Tool, ToolCall } from '../../../types.js';
+import { JSONSchema, ModelMessage, StreamChunk, Tool, ToolCall, UsageTotals } from '../../../types.js';
 import { SystemPrompt } from '../../../system-prompts.js';
 /**
  * Phase of the chat middleware lifecycle.
@@ -203,11 +203,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 {
 }
 /**
  * Information passed to onFinish.
@@ -219,12 +220,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;
 }
 /**
  * Information passed to onAbort.

package/dist/esm/client.d.ts

@@ -0,0 +1,44 @@
+export declare 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.js';
+export { convertSchemaToJsonSchema } from './activities/chat/tools/schema-converter.js';
+export { convertMessagesToModelMessages, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, uiMessageToModelMessages, } from './activities/chat/messages.js';
+export { BatchStrategy, CompositeStrategy, defaultJSONParser, ImmediateStrategy, parsePartialJSON, PartialJSONParser, PunctuationStrategy, StreamProcessor, WordBoundaryStrategy, } from './activities/chat/stream/index.js';
+export type { ChunkRecording, ChunkStrategy, InternalToolCallState, JSONParser, ProcessorResult, ProcessorState, StreamProcessorEvents, StreamProcessorOptions, ToolCallState, ToolResultState, } from './activities/chat/stream/index.js';
+export { uiMessagesToWire } from './utilities/ag-ui-wire.js';
+export type { WireMessage } from './utilities/ag-ui-wire.js';
+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.js';
+export type { AudioVisualization, RealtimeError, RealtimeErrorCode, RealtimeEvent, RealtimeEventHandler, RealtimeEventPayloads, RealtimeMessage, RealtimeMessagePart, RealtimeMode, RealtimeSessionConfig, RealtimeStatus, RealtimeToken, RealtimeAudioPart, RealtimeImagePart, RealtimeTextPart, RealtimeToolCallPart, RealtimeToolResultPart, VADConfig, } from './realtime/types.js';

package/dist/esm/client.js

@@ -0,0 +1,65 @@
+import { toolDefinition } from "./activities/chat/tools/tool-definition.js";
+import { convertSchemaToJsonSchema } from "./activities/chat/tools/schema-converter.js";
+import { convertMessagesToModelMessages, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, uiMessageToModelMessages } from "./activities/chat/messages.js";
+import { uiMessagesToWire } from "./utilities/ag-ui-wire.js";
+import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PunctuationStrategy, WordBoundaryStrategy } from "./activities/chat/stream/strategies.js";
+import { PartialJSONParser, defaultJSONParser, parsePartialJSON } from "./activities/chat/stream/json-parser.js";
+import { StreamProcessor } from "./activities/chat/stream/processor.js";
+var EventType = /* @__PURE__ */ ((EventType2) => {
+  EventType2["TEXT_MESSAGE_START"] = "TEXT_MESSAGE_START";
+  EventType2["TEXT_MESSAGE_CONTENT"] = "TEXT_MESSAGE_CONTENT";
+  EventType2["TEXT_MESSAGE_END"] = "TEXT_MESSAGE_END";
+  EventType2["TEXT_MESSAGE_CHUNK"] = "TEXT_MESSAGE_CHUNK";
+  EventType2["TOOL_CALL_START"] = "TOOL_CALL_START";
+  EventType2["TOOL_CALL_ARGS"] = "TOOL_CALL_ARGS";
+  EventType2["TOOL_CALL_END"] = "TOOL_CALL_END";
+  EventType2["TOOL_CALL_CHUNK"] = "TOOL_CALL_CHUNK";
+  EventType2["TOOL_CALL_RESULT"] = "TOOL_CALL_RESULT";
+  EventType2["THINKING_START"] = "THINKING_START";
+  EventType2["THINKING_END"] = "THINKING_END";
+  EventType2["THINKING_TEXT_MESSAGE_START"] = "THINKING_TEXT_MESSAGE_START";
+  EventType2["THINKING_TEXT_MESSAGE_CONTENT"] = "THINKING_TEXT_MESSAGE_CONTENT";
+  EventType2["THINKING_TEXT_MESSAGE_END"] = "THINKING_TEXT_MESSAGE_END";
+  EventType2["STATE_SNAPSHOT"] = "STATE_SNAPSHOT";
+  EventType2["STATE_DELTA"] = "STATE_DELTA";
+  EventType2["MESSAGES_SNAPSHOT"] = "MESSAGES_SNAPSHOT";
+  EventType2["ACTIVITY_SNAPSHOT"] = "ACTIVITY_SNAPSHOT";
+  EventType2["ACTIVITY_DELTA"] = "ACTIVITY_DELTA";
+  EventType2["RAW"] = "RAW";
+  EventType2["CUSTOM"] = "CUSTOM";
+  EventType2["RUN_STARTED"] = "RUN_STARTED";
+  EventType2["RUN_FINISHED"] = "RUN_FINISHED";
+  EventType2["RUN_ERROR"] = "RUN_ERROR";
+  EventType2["STEP_STARTED"] = "STEP_STARTED";
+  EventType2["STEP_FINISHED"] = "STEP_FINISHED";
+  EventType2["REASONING_START"] = "REASONING_START";
+  EventType2["REASONING_MESSAGE_START"] = "REASONING_MESSAGE_START";
+  EventType2["REASONING_MESSAGE_CONTENT"] = "REASONING_MESSAGE_CONTENT";
+  EventType2["REASONING_MESSAGE_END"] = "REASONING_MESSAGE_END";
+  EventType2["REASONING_MESSAGE_CHUNK"] = "REASONING_MESSAGE_CHUNK";
+  EventType2["REASONING_END"] = "REASONING_END";
+  EventType2["REASONING_ENCRYPTED_VALUE"] = "REASONING_ENCRYPTED_VALUE";
+  return EventType2;
+})(EventType || {});
+export {
+  BatchStrategy,
+  CompositeStrategy,
+  EventType,
+  ImmediateStrategy,
+  PartialJSONParser,
+  PunctuationStrategy,
+  StreamProcessor,
+  WordBoundaryStrategy,
+  convertMessagesToModelMessages,
+  convertSchemaToJsonSchema,
+  defaultJSONParser,
+  generateMessageId,
+  modelMessageToUIMessage,
+  modelMessagesToUIMessages,
+  normalizeToUIMessage,
+  parsePartialJSON,
+  toolDefinition,
+  uiMessageToModelMessages,
+  uiMessagesToWire
+};
+//# sourceMappingURL=client.js.map

package/dist/esm/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sources":["../../src/client.ts"],"sourcesContent":["export enum EventType {\n  TEXT_MESSAGE_START = 'TEXT_MESSAGE_START',\n  TEXT_MESSAGE_CONTENT = 'TEXT_MESSAGE_CONTENT',\n  TEXT_MESSAGE_END = 'TEXT_MESSAGE_END',\n  TEXT_MESSAGE_CHUNK = 'TEXT_MESSAGE_CHUNK',\n  TOOL_CALL_START = 'TOOL_CALL_START',\n  TOOL_CALL_ARGS = 'TOOL_CALL_ARGS',\n  TOOL_CALL_END = 'TOOL_CALL_END',\n  TOOL_CALL_CHUNK = 'TOOL_CALL_CHUNK',\n  TOOL_CALL_RESULT = 'TOOL_CALL_RESULT',\n  THINKING_START = 'THINKING_START',\n  THINKING_END = 'THINKING_END',\n  THINKING_TEXT_MESSAGE_START = 'THINKING_TEXT_MESSAGE_START',\n  THINKING_TEXT_MESSAGE_CONTENT = 'THINKING_TEXT_MESSAGE_CONTENT',\n  THINKING_TEXT_MESSAGE_END = 'THINKING_TEXT_MESSAGE_END',\n  STATE_SNAPSHOT = 'STATE_SNAPSHOT',\n  STATE_DELTA = 'STATE_DELTA',\n  MESSAGES_SNAPSHOT = 'MESSAGES_SNAPSHOT',\n  ACTIVITY_SNAPSHOT = 'ACTIVITY_SNAPSHOT',\n  ACTIVITY_DELTA = 'ACTIVITY_DELTA',\n  RAW = 'RAW',\n  CUSTOM = 'CUSTOM',\n  RUN_STARTED = 'RUN_STARTED',\n  RUN_FINISHED = 'RUN_FINISHED',\n  RUN_ERROR = 'RUN_ERROR',\n  STEP_STARTED = 'STEP_STARTED',\n  STEP_FINISHED = 'STEP_FINISHED',\n  REASONING_START = 'REASONING_START',\n  REASONING_MESSAGE_START = 'REASONING_MESSAGE_START',\n  REASONING_MESSAGE_CONTENT = 'REASONING_MESSAGE_CONTENT',\n  REASONING_MESSAGE_END = 'REASONING_MESSAGE_END',\n  REASONING_MESSAGE_CHUNK = 'REASONING_MESSAGE_CHUNK',\n  REASONING_END = 'REASONING_END',\n  REASONING_ENCRYPTED_VALUE = 'REASONING_ENCRYPTED_VALUE',\n}\n\nexport {\n  toolDefinition,\n  type AnyClientTool,\n  type ClientTool,\n  type InferToolInput,\n  type InferToolName,\n  type InferToolOutput,\n  type ToolDefinition,\n  type ToolDefinitionConfig,\n  type ToolDefinitionInstance,\n} from './activities/chat/tools/tool-definition'\n\nexport { convertSchemaToJsonSchema } from './activities/chat/tools/schema-converter'\n\nexport {\n  convertMessagesToModelMessages,\n  generateMessageId,\n  modelMessageToUIMessage,\n  modelMessagesToUIMessages,\n  normalizeToUIMessage,\n  uiMessageToModelMessages,\n} from './activities/chat/messages'\n\nexport {\n  BatchStrategy,\n  CompositeStrategy,\n  defaultJSONParser,\n  ImmediateStrategy,\n  parsePartialJSON,\n  PartialJSONParser,\n  PunctuationStrategy,\n  StreamProcessor,\n  WordBoundaryStrategy,\n} from './activities/chat/stream/index'\nexport type {\n  ChunkRecording,\n  ChunkStrategy,\n  InternalToolCallState,\n  JSONParser,\n  ProcessorResult,\n  ProcessorState,\n  StreamProcessorEvents,\n  StreamProcessorOptions,\n  ToolCallState,\n  ToolResultState,\n} from './activities/chat/stream/index'\n\nexport { uiMessagesToWire } from './utilities/ag-ui-wire'\nexport type { WireMessage } from './utilities/ag-ui-wire'\n\nexport type {\n  AudioPart,\n  ContentPart,\n  ContentPartDataSource,\n  ContentPartSource,\n  ContentPartUrlSource,\n  CustomEvent,\n  DocumentPart,\n  ImagePart,\n  MessagePart,\n  ModelMessage,\n  RunErrorEvent,\n  RunFinishedEvent,\n  SchemaInput,\n  StreamChunk,\n  StructuredOutputPart,\n  TextPart,\n  ThinkingPart,\n  ToolCall,\n  ToolCallPart,\n  ToolResultPart,\n  UIMessage,\n  VideoPart,\n  InferSchemaType,\n} from './types'\n\nexport type {\n  AudioVisualization,\n  RealtimeError,\n  RealtimeErrorCode,\n  RealtimeEvent,\n  RealtimeEventHandler,\n  RealtimeEventPayloads,\n  RealtimeMessage,\n  RealtimeMessagePart,\n  RealtimeMode,\n  RealtimeSessionConfig,\n  RealtimeStatus,\n  RealtimeToken,\n  RealtimeAudioPart,\n  RealtimeImagePart,\n  RealtimeTextPart,\n  RealtimeToolCallPart,\n  RealtimeToolResultPart,\n  VADConfig,\n} from './realtime/types'\n"],"names":["EventType"],"mappings":";;;;;;;AAAO,IAAK,8BAAAA,eAAL;AACLA,aAAA,oBAAA,IAAqB;AACrBA,aAAA,sBAAA,IAAuB;AACvBA,aAAA,kBAAA,IAAmB;AACnBA,aAAA,oBAAA,IAAqB;AACrBA,aAAA,iBAAA,IAAkB;AAClBA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,eAAA,IAAgB;AAChBA,aAAA,iBAAA,IAAkB;AAClBA,aAAA,kBAAA,IAAmB;AACnBA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,cAAA,IAAe;AACfA,aAAA,6BAAA,IAA8B;AAC9BA,aAAA,+BAAA,IAAgC;AAChCA,aAAA,2BAAA,IAA4B;AAC5BA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,aAAA,IAAc;AACdA,aAAA,mBAAA,IAAoB;AACpBA,aAAA,mBAAA,IAAoB;AACpBA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,KAAA,IAAM;AACNA,aAAA,QAAA,IAAS;AACTA,aAAA,aAAA,IAAc;AACdA,aAAA,cAAA,IAAe;AACfA,aAAA,WAAA,IAAY;AACZA,aAAA,cAAA,IAAe;AACfA,aAAA,eAAA,IAAgB;AAChBA,aAAA,iBAAA,IAAkB;AAClBA,aAAA,yBAAA,IAA0B;AAC1BA,aAAA,2BAAA,IAA4B;AAC5BA,aAAA,uBAAA,IAAwB;AACxBA,aAAA,yBAAA,IAA0B;AAC1BA,aAAA,eAAA,IAAgB;AAChBA,aAAA,2BAAA,IAA4B;AAjClB,SAAAA;AAAA,GAAA,aAAA,CAAA,CAAA;"}

package/dist/esm/types.d.ts

@@ -759,6 +759,37 @@ export interface RunStartedEvent extends AGUIRunStartedEvent {
     /** Model identifier for multi-model support */
     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.
  *
@@ -770,12 +801,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;
 }
 /**
  * Emitted when an error occurs during a run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.22.1",
+  "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",
@@ -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.4.0"
+    "@tanstack/ai-event-client": "0.4.1"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

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'
 
@@ -264,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
@@ -285,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/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
 }
 
 /**