@tanstack/ai 0.36.0 → 0.37.0

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

@@ -0,0 +1,439 @@
+import { ChunkRecording, ChunkStrategy, ProcessorResult, ProcessorState, ToolCallState } from './types.js';
+import { ContentPart, ModelMessage, StreamChunk, 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;
+    onCustomEvent?: (eventType: string, data: unknown, context: {
+        toolCallId?: string;
+    }) => void;
+    onTextUpdate?: (messageId: string, content: string) => void;
+    onToolCallStateChange?: (messageId: string, toolCallId: string, state: ToolCallState, args: string) => void;
+    onThinkingUpdate?: (messageId: string, 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;
+}
+/**
+ * Options for StreamProcessor
+ */
+export interface StreamProcessorOptions {
+    chunkStrategy?: ChunkStrategy;
+    /** Event-driven handlers */
+    events?: StreamProcessorEvents;
+    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.
+ * Trusts the adapter contract: adapters emit clean AG-UI events in the
+ * correct order.
+ *
+ * State tracking:
+ * - Full message array
+ * - Per-message stream state (text, tool calls, thinking)
+ * - Multiple concurrent message streams
+ * - Tool call completion via TOOL_CALL_END events
+ *
+ * @see docs/chat-architecture.md#streamprocessor-internal-state — State field reference
+ * @see docs/chat-architecture.md#adapter-contract — What this class expects from adapters
+ */
+export declare class StreamProcessor {
+    private readonly chunkStrategy;
+    private readonly events;
+    private readonly jsonParser;
+    private recordingEnabled;
+    private messages;
+    private readonly messageStates;
+    private readonly activeMessageIds;
+    private readonly toolCallToMessage;
+    private pendingManualMessageId;
+    private pendingThinkingStepId;
+    private readonly structuredMessageIds;
+    private readonly structuredOutputUpdateBatches;
+    private readonly activeRuns;
+    private finishReason;
+    private hasError;
+    private isDone;
+    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.
+     * Supports both simple string content and multimodal content arrays.
+     *
+     * @param content - The message content (string or array of content parts)
+     * @param id - Optional custom message ID (generated if not provided)
+     * @returns The created UIMessage
+     *
+     * @example
+     * ```ts
+     * // Simple text message
+     * processor.addUserMessage('Hello!')
+     *
+     * // Multimodal message with image
+     * processor.addUserMessage([
+     *   { type: 'text', content: 'What is in this image?' },
+     *   { type: 'image', source: { type: 'url', value: 'https://example.com/photo.jpg' } }
+     * ])
+     *
+     * // With custom ID
+     * processor.addUserMessage('Hello!', 'custom-id-123')
+     * ```
+     */
+    addUserMessage(content: string | Array<ContentPart>, id?: string): UIMessage;
+    /**
+     * Prepare for a new assistant message stream.
+     * Does NOT create the message immediately -- the message is created lazily
+     * when the first content-bearing chunk arrives via ensureAssistantMessage().
+     * This prevents empty assistant messages from flickering in the UI when
+     * auto-continuation produces no content.
+     */
+    prepareAssistantMessage(): void;
+    /**
+     * @deprecated Use prepareAssistantMessage() instead. This eagerly creates
+     * an assistant message which can cause empty message flicker.
+     */
+    startAssistantMessage(messageId?: string): string;
+    /**
+     * Get the current assistant message ID (if one has been created).
+     * Returns null if prepareAssistantMessage() was called but no content
+     * has arrived yet.
+     */
+    getCurrentAssistantMessageId(): string | null;
+    /**
+     * 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.
+     *
+     * Central dispatch for all AG-UI events. Each event type maps to a specific
+     * handler. Events not listed in the switch are intentionally ignored
+     * (STEP_STARTED, STATE_SNAPSHOT, STATE_DELTA).
+     *
+     * @see docs/chat-architecture.md#adapter-contract — Expected event types and ordering
+     */
+    processChunk(chunk: StreamChunk): void;
+    /**
+     * Create a new MessageStreamState for a message
+     */
+    private createMessageState;
+    /**
+     * Get the MessageStreamState for a message
+     */
+    private getMessageState;
+    /**
+     * Promote a pending stepId from a STEP_STARTED that fired before the
+     * assistant message existed onto the given message state, so the next
+     * thinking event (STEP_FINISHED or REASONING_MESSAGE_CONTENT) attributes
+     * to the correct step.
+     */
+    private consumePendingThinkingStep;
+    /**
+     * Get the most recent active assistant message ID.
+     * Used as fallback for events that don't include a messageId.
+     */
+    private getActiveAssistantMessageId;
+    /**
+     * Ensure an active assistant message exists, creating one if needed.
+     * Used for backward compat when events arrive without prior TEXT_MESSAGE_START.
+     *
+     * On reconnect/resume, a TEXT_MESSAGE_CONTENT may arrive for a message that
+     * already exists in this.messages (e.g. from initialMessages or a prior
+     * MESSAGES_SNAPSHOT) but whose transient state was cleared. In that case we
+     * hydrate state from the existing message rather than creating a duplicate.
+     */
+    private ensureAssistantMessage;
+    /**
+     * Handle TEXT_MESSAGE_START event
+     */
+    private handleTextMessageStartEvent;
+    /**
+     * Handle TEXT_MESSAGE_END event
+     */
+    private handleTextMessageEndEvent;
+    /**
+     * Handle MESSAGES_SNAPSHOT event
+     */
+    private handleMessagesSnapshotEvent;
+    /**
+     * Handle TEXT_MESSAGE_CONTENT event.
+     *
+     * Accumulates delta into both currentSegmentText (for UI emission) and
+     * totalTextContent (for ProcessorResult). Lazily creates the assistant
+     * UIMessage on first content. Uses updateTextPart() which replaces the
+     * last TextPart or creates a new one depending on part ordering.
+     *
+     * @see docs/chat-architecture.md#single-shot-text-response — Text accumulation step-by-step
+     * @see docs/chat-architecture.md#uimessage-part-ordering-invariants — Replace vs. push logic
+     */
+    private handleTextMessageContentEvent;
+    /**
+     * Handle TOOL_CALL_START event.
+     *
+     * Creates a new InternalToolCallState entry in the toolCalls Map and appends
+     * a ToolCallPart to the UIMessage. Duplicate toolCallId is a no-op.
+     *
+     * CRITICAL: This MUST be received before any TOOL_CALL_ARGS for the same
+     * toolCallId. Args for unknown IDs are silently dropped.
+     *
+     * @see docs/chat-architecture.md#single-shot-tool-call-response — Tool call state transitions
+     * @see docs/chat-architecture.md#parallel-tool-calls-single-shot — Parallel tracking by ID
+     * @see docs/chat-architecture.md#adapter-contract — Ordering requirements
+     */
+    private handleToolCallStartEvent;
+    /**
+     * Handle TOOL_CALL_ARGS event.
+     *
+     * Appends the delta to the tool call's accumulated arguments string.
+     * Transitions state from awaiting-input → input-streaming on first non-empty delta.
+     * Attempts partial JSON parse on each update for UI preview.
+     *
+     * If toolCallId is not found in the Map (no preceding TOOL_CALL_START),
+     * this event is silently dropped.
+     *
+     * @see docs/chat-architecture.md#single-shot-tool-call-response — Step-by-step tool call processing
+     */
+    private handleToolCallArgsEvent;
+    /**
+     * Handle TOOL_CALL_END event — authoritative signal that a tool call's input is finalized.
+     *
+     * This event has a DUAL ROLE:
+     * - Without `result`: Signals arguments are done (from adapter). Transitions to input-complete.
+     * - With `result`: Signals tool was executed and result is available (from TextEngine).
+     *   Creates both output on the tool-call part AND a tool-result part.
+     *
+     * If `input` is provided, it overrides the accumulated string parse as the
+     * canonical parsed arguments.
+     *
+     * @see docs/chat-architecture.md#tool-results-and-the-tool_call_end-dual-role — Full explanation
+     * @see docs/chat-architecture.md#single-shot-tool-call-response — End-to-end flow
+     */
+    private handleToolCallEndEvent;
+    private extractToolResultError;
+    /**
+     * Handle TOOL_CALL_RESULT event (AG-UI spec).
+     *
+     * Creates a tool-result part and updates the tool-call output field,
+     * mirroring the logic from TOOL_CALL_END when it carries a result.
+     * This is the spec-compliant path for delivering tool results to the client.
+     */
+    private handleToolCallResultEvent;
+    /**
+     * Handle RUN_STARTED event.
+     *
+     * Registers the run so that RUN_FINISHED can determine whether other
+     * runs are still active before finalizing.
+     */
+    private handleRunStartedEvent;
+    /**
+     * Handle RUN_FINISHED event.
+     *
+     * Records the finishReason and removes the run from activeRuns.
+     * Only finalizes when no more runs are active, so that concurrent
+     * runs don't interfere with each other.
+     *
+     * @see docs/chat-architecture.md#single-shot-tool-call-response — finishReason semantics
+     * @see docs/chat-architecture.md#adapter-contract — Why RUN_FINISHED is mandatory
+     */
+    private handleRunFinishedEvent;
+    /**
+     * Handle RUN_ERROR event
+     */
+    private handleRunErrorEvent;
+    /**
+     * Handle STEP_STARTED event (for thinking/reasoning content).
+     *
+     * Records the stepId so that subsequent STEP_FINISHED deltas accumulate
+     * into their own ThinkingPart. Does not create a message — the message
+     * is lazily created when the first STEP_FINISHED content arrives.
+     */
+    private handleStepStartedEvent;
+    /**
+     * Handle STEP_FINISHED event (for thinking/reasoning content).
+     *
+     * Accumulates delta into the current thinking step's content and updates
+     * the corresponding ThinkingPart in the UIMessage.
+     *
+     * @see docs/chat-architecture.md#thinkingreasoning-content — Thinking flow
+     */
+    private handleStepFinishedEvent;
+    /**
+     * Handle REASONING_MESSAGE_CONTENT event (AG-UI reasoning protocol).
+     *
+     * Accumulates reasoning delta into thinking content and updates the
+     * corresponding ThinkingPart in the UIMessage.
+     */
+    private handleReasoningMessageContentEvent;
+    /**
+     * Handle CUSTOM event.
+     *
+     * Handles special custom events emitted by the TextEngine (not adapters):
+     * - 'tool-input-available': Client tool needs execution. Fires onToolCall.
+     * - 'approval-requested': Tool needs user approval. Updates tool-call part
+     *   state and fires onApprovalRequest.
+     *
+     * @see docs/chat-architecture.md#client-tools-and-approval-flows — Full flow details
+     */
+    private handleCustomEvent;
+    /**
+     * Detect if an incoming content chunk represents a NEW text segment
+     */
+    private isNewTextSegment;
+    /**
+     * Complete all tool calls across all active messages — safety net for stream termination.
+     *
+     * Called by RUN_FINISHED and finalizeStream(). Force-transitions any tool call
+     * not yet in input-complete state. Handles cases where TOOL_CALL_END was
+     * missed (adapter bug, network error, aborted stream).
+     *
+     * @see docs/chat-architecture.md#single-shot-tool-call-response — Safety net behavior
+     */
+    private completeAllToolCalls;
+    /**
+     * Complete all tool calls for a specific message
+     */
+    private completeAllToolCallsForMessage;
+    /**
+     * Mark a tool call as complete and emit event
+     */
+    private completeToolCall;
+    /**
+     * Whether the rendered tool-call part for the given id has reached the
+     * terminal 'error' state. Used to prevent the completion safety net from
+     * downgrading a failed call back to 'input-complete'.
+     */
+    private isToolCallPartErrored;
+    /**
+     * Emit pending text update for a specific message.
+     *
+     * Calls updateTextPart() which has critical append-vs-replace logic:
+     * - If last UIMessage part is TextPart → replaces its content (same segment).
+     * - If last part is anything else → pushes new TextPart (new segment after tools).
+     *
+     * @see docs/chat-architecture.md#uimessage-part-ordering-invariants — Replace vs. push logic
+     */
+    private emitTextUpdateForMessage;
+    private queueStructuredOutputUpdate;
+    private flushStructuredOutputUpdate;
+    private emitStructuredOutputChange;
+    /**
+     * Emit messages change event
+     */
+    private emitMessagesChange;
+    /**
+     * Finalize the stream — complete all pending operations.
+     *
+     * Called when the async iterable ends (stream closed). Acts as the final
+     * safety net: completes any remaining tool calls, flushes un-emitted text,
+     * and fires onStreamEnd.
+     *
+     * @see docs/chat-architecture.md#single-shot-text-response — Finalization step
+     */
+    finalizeStream(): void;
+    /**
+     * Get completed tool calls in API format (aggregated across all messages)
+     */
+    private getCompletedToolCalls;
+    /**
+     * Get current result (aggregated across all messages)
+     */
+    private getResult;
+    /**
+     * Get current processor state (aggregated across all messages)
+     */
+    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;
+    /**
+     * Check if a message contains only whitespace text and no other meaningful parts
+     * (no tool calls, tool results, thinking, etc.)
+     */
+    private isWhitespaceOnlyMessage;
+    /**
+     * 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>;