@tanstack/ai 0.2.2 → 0.3.0

package/src/index.ts

@@ -73,8 +73,8 @@ export {
 // All types
 export * from './types'
 
-// Event client
-export { aiEventClient } from './event-client'
+// Event client + event types
+export * from './event-client'
 
 // Message converters
 export {
@@ -106,7 +106,6 @@ export type {
   ProcessorResult,
   ProcessorState,
   StreamProcessorEvents,
-  StreamProcessorHandlers,
   StreamProcessorOptions,
   ToolCallState,
   ToolResultState,

package/src/stream-to-response.ts

@@ -3,7 +3,7 @@ import type { StreamChunk } from './types'
 /**
  * Collect all text content from a StreamChunk async iterable and return as a string.
  *
- * This function consumes the entire stream, accumulating content from 'content' type chunks,
+ * This function consumes the entire stream, accumulating content from TEXT_MESSAGE_CONTENT events,
  * and returns the final concatenated text.
  *
  * @param stream - AsyncIterable of StreamChunks from chat()
@@ -26,7 +26,7 @@ export async function streamToText(
   let accumulatedContent = ''
 
   for await (const chunk of stream) {
-    if (chunk.type === 'content' && chunk.delta) {
+    if (chunk.type === 'TEXT_MESSAGE_CONTENT' && chunk.delta) {
       accumulatedContent += chunk.delta
     }
   }
@@ -77,11 +77,12 @@ export function toServerSentEventsStream(
           return
         }
 
-        // Send error chunk
+        // Send error event (AG-UI RUN_ERROR)
         controller.enqueue(
           encoder.encode(
             `data: ${JSON.stringify({
-              type: 'error',
+              type: 'RUN_ERROR',
+              timestamp: Date.now(),
               error: {
                 message: error.message || 'Unknown error occurred',
                 code: error.code,
@@ -198,11 +199,12 @@ export function toHttpStream(
           return
         }
 
-        // Send error chunk
+        // Send error event (AG-UI RUN_ERROR)
         controller.enqueue(
           encoder.encode(
             `${JSON.stringify({
-              type: 'error',
+              type: 'RUN_ERROR',
+              timestamp: Date.now(),
               error: {
                 message: error.message || 'Unknown error occurred',
                 code: error.code,

package/src/types.ts

@@ -649,52 +649,75 @@ export interface TextOptions<
   abortController?: AbortController
 }
 
-export type StreamChunkType =
-  | 'content'
-  | 'tool_call'
-  | 'tool_result'
-  | 'done'
-  | 'error'
-  | 'approval-requested'
-  | 'tool-input-available'
-  | 'thinking'
-
-export interface BaseStreamChunk {
-  type: StreamChunkType
-  id: string
-  model: string
-  timestamp: number
-}
+// ============================================================================
+// AG-UI Protocol Event Types
+// ============================================================================
 
-export interface ContentStreamChunk extends BaseStreamChunk {
-  type: 'content'
-  delta: string // The incremental content token
-  content: string // Full accumulated content so far
-  role?: 'assistant'
-}
+/**
+ * AG-UI Protocol event types.
+ * Based on the AG-UI specification for agent-user interaction.
+ * @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'
+  | 'STATE_SNAPSHOT'
+  | 'STATE_DELTA'
+  | 'CUSTOM'
 
-export interface ToolCallStreamChunk extends BaseStreamChunk {
-  type: 'tool_call'
-  toolCall: {
-    id: string
-    type: 'function'
-    function: {
-      name: string
-      arguments: string // Incremental JSON arguments
-    }
-  }
-  index: number
+/**
+ * Stream chunk/event types (AG-UI protocol).
+ */
+export type StreamChunkType = AGUIEventType
+
+/**
+ * Base structure for AG-UI events.
+ * Extends AG-UI spec with TanStack AI additions (model field).
+ */
+export interface BaseAGUIEvent {
+  type: AGUIEventType
+  timestamp: number
+  /** Model identifier for multi-model support */
+  model?: string
+  /** Original provider event for debugging/advanced use cases */
+  rawEvent?: unknown
 }
 
-export interface ToolResultStreamChunk extends BaseStreamChunk {
-  type: 'tool_result'
-  toolCallId: string
-  content: string
+// ============================================================================
+// AG-UI Event Interfaces
+// ============================================================================
+
+/**
+ * Emitted when a run starts.
+ * This is the first event in any streaming response.
+ */
+export interface RunStartedEvent extends BaseAGUIEvent {
+  type: 'RUN_STARTED'
+  /** Unique identifier for this run */
+  runId: string
+  /** Optional thread/conversation ID */
+  threadId?: string
 }
 
-export interface DoneStreamChunk extends BaseStreamChunk {
-  type: 'done'
+/**
+ * Emitted when a run completes successfully.
+ */
+export interface RunFinishedEvent extends BaseAGUIEvent {
+  type: 'RUN_FINISHED'
+  /** Run identifier */
+  runId: string
+  /** Why the generation stopped */
   finishReason: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null
+  /** Token usage statistics */
   usage?: {
     promptTokens: number
     completionTokens: number
@@ -702,50 +725,171 @@ export interface DoneStreamChunk extends BaseStreamChunk {
   }
 }
 
-export interface ErrorStreamChunk extends BaseStreamChunk {
-  type: 'error'
+/**
+ * Emitted when an error occurs during a run.
+ */
+export interface RunErrorEvent extends BaseAGUIEvent {
+  type: 'RUN_ERROR'
+  /** Run identifier (if available) */
+  runId?: string
+  /** Error details */
   error: {
     message: string
     code?: string
   }
 }
 
-export interface ApprovalRequestedStreamChunk extends BaseStreamChunk {
-  type: 'approval-requested'
+/**
+ * Emitted when a text message starts.
+ */
+export interface TextMessageStartEvent extends BaseAGUIEvent {
+  type: 'TEXT_MESSAGE_START'
+  /** Unique identifier for this message */
+  messageId: string
+  /** Role is always assistant for generated messages */
+  role: 'assistant'
+}
+
+/**
+ * Emitted when text content is generated (streaming tokens).
+ */
+export interface TextMessageContentEvent extends BaseAGUIEvent {
+  type: 'TEXT_MESSAGE_CONTENT'
+  /** Message identifier */
+  messageId: string
+  /** The incremental content token */
+  delta: string
+  /** Full accumulated content so far */
+  content?: string
+}
+
+/**
+ * Emitted when a text message completes.
+ */
+export interface TextMessageEndEvent extends BaseAGUIEvent {
+  type: 'TEXT_MESSAGE_END'
+  /** Message identifier */
+  messageId: string
+}
+
+/**
+ * Emitted when a tool call starts.
+ */
+export interface ToolCallStartEvent extends BaseAGUIEvent {
+  type: 'TOOL_CALL_START'
+  /** Unique identifier for this tool call */
   toolCallId: string
+  /** Name of the tool being called */
   toolName: string
-  input: any
-  approval: {
-    id: string
-    needsApproval: true
-  }
+  /** Index for parallel tool calls */
+  index?: number
+}
+
+/**
+ * Emitted when tool call arguments are streaming.
+ */
+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 */
+  args?: string
 }
 
-export interface ToolInputAvailableStreamChunk extends BaseStreamChunk {
-  type: 'tool-input-available'
+/**
+ * Emitted when a tool call completes.
+ */
+export interface ToolCallEndEvent extends BaseAGUIEvent {
+  type: 'TOOL_CALL_END'
+  /** Tool call identifier */
   toolCallId: string
+  /** Name of the tool */
   toolName: string
-  input: any
+  /** Final parsed input arguments */
+  input?: unknown
+  /** Tool execution result (if executed) */
+  result?: string
 }
 
-export interface ThinkingStreamChunk extends BaseStreamChunk {
-  type: 'thinking'
-  delta?: string // The incremental thinking token
-  content: string // Full accumulated thinking content so far
+/**
+ * Emitted when a thinking/reasoning step starts.
+ */
+export interface StepStartedEvent extends BaseAGUIEvent {
+  type: 'STEP_STARTED'
+  /** Unique identifier for this step */
+  stepId: string
+  /** Type of step (e.g., 'thinking', 'planning') */
+  stepType?: string
+}
+
+/**
+ * Emitted when a thinking/reasoning step finishes.
+ */
+export interface StepFinishedEvent extends BaseAGUIEvent {
+  type: 'STEP_FINISHED'
+  /** Step identifier */
+  stepId: string
+  /** Incremental thinking content */
+  delta?: string
+  /** Full accumulated thinking content */
+  content?: string
+}
+
+/**
+ * Emitted to provide a full state snapshot.
+ */
+export interface StateSnapshotEvent extends BaseAGUIEvent {
+  type: 'STATE_SNAPSHOT'
+  /** The complete state object */
+  state: Record<string, unknown>
+}
+
+/**
+ * Emitted to provide an incremental state update.
+ */
+export interface StateDeltaEvent extends BaseAGUIEvent {
+  type: 'STATE_DELTA'
+  /** The state changes to apply */
+  delta: Record<string, unknown>
 }
 
 /**
- * Chunk returned by the sdk during streaming chat completions.
+ * Custom event for extensibility.
+ */
+export interface CustomEvent extends BaseAGUIEvent {
+  type: 'CUSTOM'
+  /** Custom event name */
+  name: string
+  /** Custom event data */
+  data?: unknown
+}
+
+/**
+ * Union of all AG-UI events.
+ */
+export type AGUIEvent =
+  | RunStartedEvent
+  | RunFinishedEvent
+  | RunErrorEvent
+  | TextMessageStartEvent
+  | TextMessageContentEvent
+  | TextMessageEndEvent
+  | ToolCallStartEvent
+  | ToolCallArgsEvent
+  | ToolCallEndEvent
+  | StepStartedEvent
+  | StepFinishedEvent
+  | StateSnapshotEvent
+  | StateDeltaEvent
+  | CustomEvent
+
+/**
+ * Chunk returned by the SDK during streaming chat completions.
+ * Uses the AG-UI protocol event format.
  */
-export type StreamChunk =
-  | ContentStreamChunk
-  | ToolCallStreamChunk
-  | ToolResultStreamChunk
-  | DoneStreamChunk
-  | ErrorStreamChunk
-  | ApprovalRequestedStreamChunk
-  | ToolInputAvailableStreamChunk
-  | ThinkingStreamChunk
+export type StreamChunk = AGUIEvent
 
 // Simple streaming format for basic text completions
 // Converted to StreamChunk format by convertTextCompletionStream()