@tanstack/ai 0.0.1

package/dist/esm/stream/processor.d.ts

@@ -0,0 +1,242 @@
+import { ChunkRecording, ChunkStrategy, ProcessorResult, ProcessorState, ToolCallState, ToolResultState } from './types.js';
+import { ModelMessage, StreamChunk, ToolCall, UIMessage } from '../types.js';
+/**
+ * Events emitted by the StreamProcessor
+ */
+export interface StreamProcessorEvents {
+    onMessagesChange?: (messages: Array<UIMessage>) => void;
+    onStreamStart?: () => void;
+    onStreamEnd?: (message: UIMessage) => void;
+    onError?: (error: Error) => void;
+    onToolCall?: (args: {
+        toolCallId: string;
+        toolName: string;
+        input: any;
+    }) => void;
+    onApprovalRequest?: (args: {
+        toolCallId: string;
+        toolName: string;
+        input: any;
+        approvalId: string;
+    }) => void;
+    onTextUpdate?: (messageId: string, content: string) => void;
+    onToolCallStateChange?: (messageId: string, toolCallId: string, state: ToolCallState, args: string) => void;
+    onThinkingUpdate?: (messageId: string, content: string) => void;
+}
+/**
+ * Legacy handlers for backward compatibility
+ * These are the old callback-style handlers
+ */
+export interface StreamProcessorHandlers {
+    onTextUpdate?: (content: string) => void;
+    onThinkingUpdate?: (content: string) => void;
+    onToolCallStart?: (index: number, id: string, name: string) => void;
+    onToolCallDelta?: (index: number, args: string) => void;
+    onToolCallComplete?: (index: number, id: string, name: string, args: string) => void;
+    onToolCallStateChange?: (index: number, id: string, name: string, state: ToolCallState, args: string, parsedArgs?: any) => void;
+    onToolResultStateChange?: (toolCallId: string, content: string, state: ToolResultState, error?: string) => void;
+    onApprovalRequested?: (toolCallId: string, toolName: string, input: any, approvalId: string) => void;
+    onToolInputAvailable?: (toolCallId: string, toolName: string, input: any) => void;
+    onStreamEnd?: (content: string, toolCalls?: Array<ToolCall>) => void;
+    onError?: (error: {
+        message: string;
+        code?: string;
+    }) => void;
+}
+/**
+ * Options for StreamProcessor
+ */
+export interface StreamProcessorOptions {
+    chunkStrategy?: ChunkStrategy;
+    /** New event-driven handlers */
+    events?: StreamProcessorEvents;
+    /** Legacy callback handlers (for backward compatibility) */
+    handlers?: StreamProcessorHandlers;
+    jsonParser?: {
+        parse: (jsonString: string) => any;
+    };
+    /** Enable recording for replay testing */
+    recording?: boolean;
+    /** Initial messages to populate the processor */
+    initialMessages?: Array<UIMessage>;
+}
+/**
+ * StreamProcessor - State machine for processing AI response streams
+ *
+ * Manages the full UIMessage[] conversation and emits events on changes.
+ *
+ * State tracking:
+ * - Full message array
+ * - Current assistant message being streamed
+ * - Text content accumulation
+ * - Multiple parallel tool calls
+ * - Tool call completion detection
+ *
+ * Tool call completion is detected when:
+ * 1. A new tool call starts at a different index
+ * 2. Text content arrives
+ * 3. Stream ends
+ */
+export declare class StreamProcessor {
+    private chunkStrategy;
+    private events;
+    private handlers;
+    private jsonParser;
+    private recordingEnabled;
+    private messages;
+    private currentAssistantMessageId;
+    private totalTextContent;
+    private currentSegmentText;
+    private lastEmittedText;
+    private thinkingContent;
+    private toolCalls;
+    private toolCallOrder;
+    private finishReason;
+    private isDone;
+    private hasToolCallsSinceTextStart;
+    private recording;
+    private recordingStartTime;
+    constructor(options?: StreamProcessorOptions);
+    /**
+     * Set the messages array (e.g., from persisted state)
+     */
+    setMessages(messages: Array<UIMessage>): void;
+    /**
+     * Add a user message to the conversation
+     */
+    addUserMessage(content: string): UIMessage;
+    /**
+     * Start streaming a new assistant message
+     * Returns the message ID
+     */
+    startAssistantMessage(): string;
+    /**
+     * Add a tool result (called by client after handling onToolCall)
+     */
+    addToolResult(toolCallId: string, output: any, error?: string): void;
+    /**
+     * Add an approval response (called by client after handling onApprovalRequest)
+     */
+    addToolApprovalResponse(approvalId: string, approved: boolean): void;
+    /**
+     * Get the conversation as ModelMessages (for sending to LLM)
+     */
+    toModelMessages(): Array<ModelMessage>;
+    /**
+     * Get current messages
+     */
+    getMessages(): Array<UIMessage>;
+    /**
+     * Check if all tool calls in the last assistant message are complete
+     * Useful for auto-continue logic
+     */
+    areAllToolsComplete(): boolean;
+    /**
+     * Remove messages after a certain index (for reload/retry)
+     */
+    removeMessagesAfter(index: number): void;
+    /**
+     * Clear all messages
+     */
+    clearMessages(): void;
+    /**
+     * Process a stream and emit events through handlers
+     */
+    process(stream: AsyncIterable<any>): Promise<ProcessorResult>;
+    /**
+     * Process a single chunk from the stream
+     */
+    processChunk(chunk: StreamChunk): void;
+    /**
+     * Handle a content chunk
+     */
+    private handleContentChunk;
+    /**
+     * Handle a tool call chunk
+     */
+    private handleToolCallChunk;
+    /**
+     * Handle a tool result chunk
+     */
+    private handleToolResultChunk;
+    /**
+     * Handle a done chunk
+     */
+    private handleDoneChunk;
+    /**
+     * Handle an error chunk
+     */
+    private handleErrorChunk;
+    /**
+     * Handle a thinking chunk
+     */
+    private handleThinkingChunk;
+    /**
+     * Handle an approval-requested chunk
+     */
+    private handleApprovalRequestedChunk;
+    /**
+     * Handle a tool-input-available chunk
+     */
+    private handleToolInputAvailableChunk;
+    /**
+     * Detect if an incoming content chunk represents a NEW text segment
+     */
+    private isNewTextSegment;
+    /**
+     * Complete all tool calls
+     */
+    private completeAllToolCalls;
+    /**
+     * Mark a tool call as complete and emit event
+     */
+    private completeToolCall;
+    /**
+     * Emit pending text update
+     */
+    private emitTextUpdate;
+    /**
+     * Emit messages change event
+     */
+    private emitMessagesChange;
+    /**
+     * Finalize the stream - complete all pending operations
+     */
+    finalizeStream(): void;
+    /**
+     * Get completed tool calls in API format
+     */
+    private getCompletedToolCalls;
+    /**
+     * Get current result
+     */
+    private getResult;
+    /**
+     * Get current processor state (legacy)
+     */
+    getState(): ProcessorState;
+    /**
+     * Start recording chunks
+     */
+    startRecording(): void;
+    /**
+     * Get the current recording
+     */
+    getRecording(): ChunkRecording | null;
+    /**
+     * Reset stream state (but keep messages)
+     */
+    private resetStreamState;
+    /**
+     * Full reset (including messages)
+     */
+    reset(): void;
+    /**
+     * Replay a recording through the processor
+     */
+    static replay(recording: ChunkRecording, options?: StreamProcessorOptions): Promise<ProcessorResult>;
+}
+/**
+ * Create an async iterable from a recording
+ */
+export declare function createReplayStream(recording: ChunkRecording): AsyncIterable<StreamChunk>;