@tanstack/ai 0.10.3 → 0.11.0

package/src/types.ts

@@ -1,4 +1,30 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
+import type {
+  BaseEvent as AGUIBaseEvent,
+  CustomEvent as AGUICustomEvent,
+  MessagesSnapshotEvent as AGUIMessagesSnapshotEvent,
+  ReasoningEncryptedValueEvent as AGUIReasoningEncryptedValueEvent,
+  ReasoningEndEvent as AGUIReasoningEndEvent,
+  ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent,
+  ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent,
+  ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent,
+  ReasoningStartEvent as AGUIReasoningStartEvent,
+  RunErrorEvent as AGUIRunErrorEvent,
+  RunFinishedEvent as AGUIRunFinishedEvent,
+  RunStartedEvent as AGUIRunStartedEvent,
+  StateDeltaEvent as AGUIStateDeltaEvent,
+  StateSnapshotEvent as AGUIStateSnapshotEvent,
+  StepFinishedEvent as AGUIStepFinishedEvent,
+  StepStartedEvent as AGUIStepStartedEvent,
+  TextMessageContentEvent as AGUITextMessageContentEvent,
+  TextMessageEndEvent as AGUITextMessageEndEvent,
+  TextMessageStartEvent as AGUITextMessageStartEvent,
+  ToolCallArgsEvent as AGUIToolCallArgsEvent,
+  ToolCallEndEvent as AGUIToolCallEndEvent,
+  ToolCallResultEvent as AGUIToolCallResultEvent,
+  ToolCallStartEvent as AGUIToolCallStartEvent,
+  EventType,
+} from '@ag-ui/core'
 
 /**
  * Tool call states - track the lifecycle of a tool call
@@ -712,50 +738,53 @@ export interface TextOptions<
    * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortController
    */
   abortController?: AbortController
+  /**
+   * Thread ID for AG-UI protocol run correlation.
+   * When provided, this will be used in RunStartedEvent and RunFinishedEvent.
+   */
+  threadId?: string
+  /**
+   * Run ID for AG-UI protocol run correlation.
+   * When provided, this will be used in RunStartedEvent and RunFinishedEvent.
+   * If not provided, a unique ID will be generated.
+   */
+  runId?: string
 }
 
 // ============================================================================
 // AG-UI Protocol Event Types
 // ============================================================================
 
+/**
+ * Re-export EventType enum from @ag-ui/core for use in event creation.
+ * Use `EventType.RUN_STARTED` etc. when constructing event objects.
+ */
+export { EventType } from '@ag-ui/core'
+
 /**
  * AG-UI Protocol event types.
- * Based on the AG-UI specification for agent-user interaction.
+ * @deprecated Use `EventType` enum from `@ag-ui/core` instead. This type alias
+ * is kept for backward compatibility but will be removed in a future version.
  * @see https://docs.ag-ui.com/concepts/events
  */
-export type AGUIEventType =
-  | 'RUN_STARTED'
-  | 'RUN_FINISHED'
-  | 'RUN_ERROR'
-  | 'TEXT_MESSAGE_START'
-  | 'TEXT_MESSAGE_CONTENT'
-  | 'TEXT_MESSAGE_END'
-  | 'TOOL_CALL_START'
-  | 'TOOL_CALL_ARGS'
-  | 'TOOL_CALL_END'
-  | 'STEP_STARTED'
-  | 'STEP_FINISHED'
-  | 'MESSAGES_SNAPSHOT'
-  | 'STATE_SNAPSHOT'
-  | 'STATE_DELTA'
-  | 'CUSTOM'
+export type AGUIEventType = `${EventType}`
 
 /**
  * Stream chunk/event types (AG-UI protocol).
+ * @deprecated Use `EventType` enum instead.
  */
 export type StreamChunkType = AGUIEventType
 
 /**
  * Base structure for AG-UI events.
- * Extends AG-UI spec with TanStack AI additions (model field).
+ * Extends @ag-ui/core BaseEvent with TanStack AI additions.
+ *
+ * @ag-ui/core provides: `type`, `timestamp?`, `rawEvent?`
+ * TanStack AI adds: `model?`
  */
-export interface BaseAGUIEvent {
-  type: AGUIEventType
-  timestamp: number
+export interface BaseAGUIEvent extends AGUIBaseEvent {
   /** Model identifier for multi-model support */
   model?: string
-  /** Original provider event for debugging/advanced use cases */
-  rawEvent?: unknown
 }
 
 // ============================================================================
@@ -765,24 +794,26 @@ export interface BaseAGUIEvent {
 /**
  * Emitted when a run starts.
  * This is the first event in any streaming response.
+ *
+ * @ag-ui/core provides: `threadId`, `runId`, `parentRunId?`, `input?`
+ * TanStack AI adds: `model?`
  */
-export interface RunStartedEvent extends BaseAGUIEvent {
-  type: 'RUN_STARTED'
-  /** Unique identifier for this run */
-  runId: string
-  /** Optional thread/conversation ID */
-  threadId?: string
+export interface RunStartedEvent extends AGUIRunStartedEvent {
+  /** Model identifier for multi-model support */
+  model?: string
 }
 
 /**
  * Emitted when a run completes successfully.
+ *
+ * @ag-ui/core provides: `threadId`, `runId`, `result?`
+ * TanStack AI adds: `model?`, `finishReason?`, `usage?`
  */
-export interface RunFinishedEvent extends BaseAGUIEvent {
-  type: 'RUN_FINISHED'
-  /** Run identifier */
-  runId: string
+export interface RunFinishedEvent extends AGUIRunFinishedEvent {
+  /** Model identifier for multi-model support */
+  model?: string
   /** Why the generation stopped */
-  finishReason: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null
+  finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null
   /** Token usage statistics */
   usage?: {
     promptTokens: number
@@ -793,13 +824,18 @@ export interface RunFinishedEvent extends BaseAGUIEvent {
 
 /**
  * Emitted when an error occurs during a run.
+ *
+ * @ag-ui/core provides: `message`, `code?`
+ * TanStack AI adds: `model?`, `error?` (deprecated nested form)
  */
-export interface RunErrorEvent extends BaseAGUIEvent {
-  type: 'RUN_ERROR'
-  /** Run identifier (if available) */
-  runId?: string
-  /** Error details */
-  error: {
+export interface RunErrorEvent extends AGUIRunErrorEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+  /**
+   * @deprecated Use top-level `message` and `code` fields instead.
+   * Kept for backward compatibility.
+   */
+  error?: {
     message: string
     code?: string
   }
@@ -807,48 +843,53 @@ export interface RunErrorEvent extends BaseAGUIEvent {
 
 /**
  * Emitted when a text message starts.
+ *
+ * @ag-ui/core provides: `messageId`, `role?`, `name?`
+ * TanStack AI adds: `model?`
  */
-export interface TextMessageStartEvent extends BaseAGUIEvent {
-  type: 'TEXT_MESSAGE_START'
-  /** Unique identifier for this message */
-  messageId: string
-  /** Role of the message sender */
-  role: 'user' | 'assistant' | 'system' | 'tool'
+export interface TextMessageStartEvent extends AGUITextMessageStartEvent {
+  /** Model identifier for multi-model support */
+  model?: string
 }
 
 /**
  * Emitted when text content is generated (streaming tokens).
+ *
+ * @ag-ui/core provides: `messageId`, `delta`
+ * TanStack AI adds: `model?`, `content?` (accumulated)
  */
-export interface TextMessageContentEvent extends BaseAGUIEvent {
-  type: 'TEXT_MESSAGE_CONTENT'
-  /** Message identifier */
-  messageId: string
-  /** The incremental content token */
-  delta: string
-  /** Full accumulated content so far (optional, for debugging) */
+export interface TextMessageContentEvent extends AGUITextMessageContentEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+  /** Full accumulated content so far (TanStack AI internal, for debugging) */
   content?: string
 }
 
 /**
  * Emitted when a text message completes.
+ *
+ * @ag-ui/core provides: `messageId`
+ * TanStack AI adds: `model?`
  */
-export interface TextMessageEndEvent extends BaseAGUIEvent {
-  type: 'TEXT_MESSAGE_END'
-  /** Message identifier */
-  messageId: string
+export interface TextMessageEndEvent extends AGUITextMessageEndEvent {
+  /** Model identifier for multi-model support */
+  model?: string
 }
 
 /**
  * Emitted when a tool call starts.
+ *
+ * @ag-ui/core provides: `toolCallId`, `toolCallName`, `parentMessageId?`
+ * TanStack AI adds: `model?`, `toolName` (deprecated alias), `index?`, `providerMetadata?`
  */
-export interface ToolCallStartEvent extends BaseAGUIEvent {
-  type: 'TOOL_CALL_START'
-  /** Unique identifier for this tool call */
-  toolCallId: string
-  /** Name of the tool being called */
+export interface ToolCallStartEvent extends AGUIToolCallStartEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+  /**
+   * @deprecated Use `toolCallName` instead (from @ag-ui/core spec).
+   * Kept for backward compatibility.
+   */
   toolName: string
-  /** ID of the parent message that initiated this tool call */
-  parentMessageId?: string
   /** Index for parallel tool calls */
   index?: number
   /** Provider-specific metadata to carry into the ToolCall */
@@ -857,53 +898,85 @@ export interface ToolCallStartEvent extends BaseAGUIEvent {
 
 /**
  * Emitted when tool call arguments are streaming.
+ *
+ * @ag-ui/core provides: `toolCallId`, `delta`
+ * TanStack AI adds: `model?`, `args?` (accumulated)
  */
-export interface ToolCallArgsEvent extends BaseAGUIEvent {
-  type: 'TOOL_CALL_ARGS'
-  /** Tool call identifier */
-  toolCallId: string
-  /** Incremental JSON arguments delta */
-  delta: string
-  /** Full accumulated arguments so far */
+export interface ToolCallArgsEvent extends AGUIToolCallArgsEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+  /** Full accumulated arguments so far (TanStack AI internal) */
   args?: string
 }
 
 /**
  * Emitted when a tool call completes.
+ *
+ * @ag-ui/core provides: `toolCallId`
+ * TanStack AI adds: `model?`, `toolCallName?`, `toolName?` (deprecated), `input?`, `result?`
  */
-export interface ToolCallEndEvent extends BaseAGUIEvent {
-  type: 'TOOL_CALL_END'
-  /** Tool call identifier */
-  toolCallId: string
-  /** Name of the tool */
-  toolName: string
-  /** Final parsed input arguments */
+export interface ToolCallEndEvent extends AGUIToolCallEndEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+  /** Name of the tool that completed */
+  toolCallName?: string
+  /**
+   * @deprecated Use `toolCallName` instead.
+   * Kept for backward compatibility.
+   */
+  toolName?: string
+  /** Final parsed input arguments (TanStack AI internal) */
   input?: unknown
-  /** Tool execution result (if executed) */
+  /** Tool execution result (TanStack AI internal) */
   result?: string
 }
 
+/**
+ * Emitted when a tool call result is available.
+ *
+ * @ag-ui/core provides: `messageId`, `toolCallId`, `content`, `role?`
+ * TanStack AI adds: `model?`
+ */
+export interface ToolCallResultEvent extends AGUIToolCallResultEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+}
+
 /**
  * Emitted when a thinking/reasoning step starts.
+ *
+ * @ag-ui/core provides: `stepName`
+ * TanStack AI adds: `model?`, `stepId?` (deprecated alias), `stepType?`
  */
-export interface StepStartedEvent extends BaseAGUIEvent {
-  type: 'STEP_STARTED'
-  /** Unique identifier for this step */
-  stepId: string
+export interface StepStartedEvent extends AGUIStepStartedEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+  /**
+   * @deprecated Use `stepName` instead (from @ag-ui/core spec).
+   * Kept for backward compatibility.
+   */
+  stepId?: string
   /** Type of step (e.g., 'thinking', 'planning') */
   stepType?: string
 }
 
 /**
  * Emitted when a thinking/reasoning step finishes.
+ *
+ * @ag-ui/core provides: `stepName`
+ * TanStack AI adds: `model?`, `stepId?` (deprecated alias), `delta?`, `content?`
  */
-export interface StepFinishedEvent extends BaseAGUIEvent {
-  type: 'STEP_FINISHED'
-  /** Step identifier */
-  stepId: string
-  /** Incremental thinking content */
-  delta: string
-  /** Full accumulated thinking content (optional, for debugging) */
+export interface StepFinishedEvent extends AGUIStepFinishedEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+  /**
+   * @deprecated Use `stepName` instead (from @ag-ui/core spec).
+   * Kept for backward compatibility.
+   */
+  stepId?: string
+  /** Incremental thinking content (TanStack AI internal) */
+  delta?: string
+  /** Full accumulated thinking content (TanStack AI internal) */
   content?: string
 }
 
@@ -912,43 +985,130 @@ export interface StepFinishedEvent extends BaseAGUIEvent {
  *
  * Unlike StateSnapshot (which carries arbitrary application state),
  * MessagesSnapshot specifically delivers the conversation transcript.
- * This is a first-class AG-UI event type.
+ *
+ * @ag-ui/core provides: `messages` (as @ag-ui/core Message[])
+ * TanStack AI adds: `model?`
+ *
+ * Note: The `messages` field uses the @ag-ui/core Message type.
+ * Use converters to transform to/from TanStack UIMessage format.
  */
-export interface MessagesSnapshotEvent extends BaseAGUIEvent {
-  type: 'MESSAGES_SNAPSHOT'
-  /** Complete array of messages in the conversation */
-  messages: Array<UIMessage>
+export interface MessagesSnapshotEvent extends AGUIMessagesSnapshotEvent {
+  /** Model identifier for multi-model support */
+  model?: string
 }
 
 /**
  * Emitted to provide a full state snapshot.
+ *
+ * @ag-ui/core provides: `snapshot` (any)
+ * TanStack AI adds: `model?`, `state?` (deprecated alias for snapshot)
  */
-export interface StateSnapshotEvent extends BaseAGUIEvent {
-  type: 'STATE_SNAPSHOT'
-  /** The complete state object */
-  state: Record<string, unknown>
+export interface StateSnapshotEvent extends AGUIStateSnapshotEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+  /**
+   * @deprecated Use `snapshot` instead (from @ag-ui/core spec).
+   * Kept for backward compatibility.
+   */
+  state?: Record<string, unknown>
 }
 
 /**
  * Emitted to provide an incremental state update.
+ *
+ * @ag-ui/core provides: `delta` (any[] - JSON Patch RFC 6902)
+ * TanStack AI adds: `model?`
  */
-export interface StateDeltaEvent extends BaseAGUIEvent {
-  type: 'STATE_DELTA'
-  /** The state changes to apply */
-  delta: Record<string, unknown>
+export interface StateDeltaEvent extends AGUIStateDeltaEvent {
+  /** Model identifier for multi-model support */
+  model?: string
 }
 
 /**
  * Custom event for extensibility.
+ *
+ * @ag-ui/core provides: `name`, `value`
+ * TanStack AI adds: `model?`
  */
-export interface CustomEvent extends BaseAGUIEvent {
-  type: 'CUSTOM'
-  /** Custom event name */
-  name: string
-  /** Custom event value */
-  value?: unknown
+export interface CustomEvent extends AGUICustomEvent {
+  /** Model identifier for multi-model support */
+  model?: string
 }
 
+// ============================================================================
+// AG-UI Reasoning Event Interfaces
+// ============================================================================
+
+/**
+ * Emitted when reasoning starts for a message.
+ *
+ * @ag-ui/core provides: `messageId`
+ * TanStack AI adds: `model?`
+ */
+export interface ReasoningStartEvent extends AGUIReasoningStartEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+}
+
+/**
+ * Emitted when a reasoning message starts.
+ *
+ * @ag-ui/core provides: `messageId`, `role` ("reasoning")
+ * TanStack AI adds: `model?`
+ */
+export interface ReasoningMessageStartEvent extends AGUIReasoningMessageStartEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+}
+
+/**
+ * Emitted when reasoning message content is generated.
+ *
+ * @ag-ui/core provides: `messageId`, `delta`
+ * TanStack AI adds: `model?`
+ */
+export interface ReasoningMessageContentEvent extends AGUIReasoningMessageContentEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+}
+
+/**
+ * Emitted when a reasoning message ends.
+ *
+ * @ag-ui/core provides: `messageId`
+ * TanStack AI adds: `model?`
+ */
+export interface ReasoningMessageEndEvent extends AGUIReasoningMessageEndEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+}
+
+/**
+ * Emitted when reasoning ends for a message.
+ *
+ * @ag-ui/core provides: `messageId`
+ * TanStack AI adds: `model?`
+ */
+export interface ReasoningEndEvent extends AGUIReasoningEndEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+}
+
+/**
+ * Emitted for encrypted reasoning values.
+ *
+ * @ag-ui/core provides: `subtype`, `entityId`, `encryptedValue`
+ * TanStack AI adds: `model?`
+ */
+export interface ReasoningEncryptedValueEvent extends AGUIReasoningEncryptedValueEvent {
+  /** Model identifier for multi-model support */
+  model?: string
+}
+
+// ============================================================================
+// AG-UI Event Union
+// ============================================================================
+
 /**
  * Union of all AG-UI events.
  */
@@ -962,12 +1122,19 @@ export type AGUIEvent =
   | ToolCallStartEvent
   | ToolCallArgsEvent
   | ToolCallEndEvent
+  | ToolCallResultEvent
   | StepStartedEvent
   | StepFinishedEvent
   | MessagesSnapshotEvent
   | StateSnapshotEvent
   | StateDeltaEvent
   | CustomEvent
+  | ReasoningStartEvent
+  | ReasoningMessageStartEvent
+  | ReasoningMessageContentEvent
+  | ReasoningMessageEndEvent
+  | ReasoningEndEvent
+  | ReasoningEncryptedValueEvent
 
 /**
  * Chunk returned by the SDK during streaming chat completions.