@tambo-ai/react 0.69.1 → 0.71.0

package/esm/v1/utils/event-accumulator.js

@@ -0,0 +1,708 @@
+/**
+ * Event Accumulation Logic for v1 Streaming API
+ *
+ * Implements a reducer that transforms AG-UI event streams into React state.
+ * Used with useReducer to accumulate events into thread state.
+ */
+import { EventType } from "@ag-ui/core";
+import { asTamboCustomEvent, } from "../types/event";
+import { applyJsonPatch } from "./json-patch";
+/**
+ * Error thrown when an unreachable case is reached in a switch statement.
+ * This indicates a programming error where not all cases were handled.
+ */
+export class UnreachableCaseError extends Error {
+    constructor(value) {
+        super(`Unreachable case: ${JSON.stringify(value)}`);
+        this.name = "UnreachableCaseError";
+    }
+}
+/**
+ * Initial streaming state.
+ */
+const initialStreamingState = {
+    status: "idle",
+};
+/**
+ * Create initial thread state for a new thread.
+ * @param threadId - Unique thread identifier
+ * @returns Initial thread state
+ */
+export function createInitialThreadState(threadId) {
+    const now = new Date().toISOString();
+    return {
+        thread: {
+            id: threadId,
+            messages: [],
+            status: "idle",
+            createdAt: now,
+            updatedAt: now,
+        },
+        streaming: initialStreamingState,
+        accumulatingToolArgs: new Map(),
+    };
+}
+/**
+ * Create initial stream state with empty threadMap.
+ * @returns Initial stream state
+ */
+export function createInitialState() {
+    return {
+        threadMap: {},
+        currentThreadId: null,
+    };
+}
+/**
+ * Replace a message at a specific index immutably.
+ * @param messages - Current messages array
+ * @param index - Index of message to replace
+ * @param updatedMessage - New message to insert
+ * @returns New messages array with the message replaced
+ */
+function updateMessageAtIndex(messages, index, updatedMessage) {
+    return [
+        ...messages.slice(0, index),
+        updatedMessage,
+        ...messages.slice(index + 1),
+    ];
+}
+/**
+ * Replace a content block at a specific index within a message's content immutably.
+ * @param content - Current content array
+ * @param index - Index of content to replace
+ * @param updatedContent - New content to insert
+ * @returns New content array with the content replaced
+ */
+function updateContentAtIndex(content, index, updatedContent) {
+    return [
+        ...content.slice(0, index),
+        updatedContent,
+        ...content.slice(index + 1),
+    ];
+}
+/**
+ * Find a content block by ID across all messages, searching from most recent.
+ *
+ * TODO: This is O(n*m) where n = messages and m = content blocks per message.
+ * For high-frequency streaming with many messages, consider maintaining an
+ * index map of contentId -> {messageIndex, contentIndex} that gets updated
+ * when content blocks are created.
+ * @param messages - Messages to search
+ * @param contentType - Type of content to find ("component" or "tool_use")
+ * @param contentId - ID of the content block
+ * @param eventName - Name of the event (for error messages)
+ * @returns Location of the content block
+ * @throws {Error} If content not found
+ */
+function findContentById(messages, contentType, contentId, eventName) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const idx = messages[i].content.findIndex((c) => c.type === contentType && c.id === contentId);
+        if (idx !== -1) {
+            return { messageIndex: i, contentIndex: idx };
+        }
+    }
+    throw new Error(`${contentType} ${contentId} not found for ${eventName}`);
+}
+/**
+ * Create updated thread state with new messages.
+ * @param threadState - Current thread state
+ * @param messages - New messages array
+ * @returns Updated thread state
+ */
+function updateThreadMessages(threadState, messages) {
+    return {
+        ...threadState,
+        thread: {
+            ...threadState.thread,
+            messages,
+            updatedAt: new Date().toISOString(),
+        },
+    };
+}
+/**
+ * Stream reducer that accumulates events into thread state.
+ *
+ * This reducer handles all AG-UI events and Tambo custom events,
+ * transforming them into immutable state updates per thread.
+ * @param state - Current stream state
+ * @param action - Action to process
+ * @returns Updated stream state
+ */
+export function streamReducer(state, action) {
+    // Handle non-event actions first
+    switch (action.type) {
+        case "INIT_THREAD": {
+            const { threadId, initialThread } = action;
+            // Don't overwrite existing thread
+            if (state.threadMap[threadId]) {
+                return state;
+            }
+            const baseState = createInitialThreadState(threadId);
+            const threadState = initialThread
+                ? {
+                    ...baseState,
+                    thread: {
+                        ...baseState.thread,
+                        ...initialThread,
+                        id: threadId,
+                    },
+                }
+                : baseState;
+            return {
+                ...state,
+                threadMap: {
+                    ...state.threadMap,
+                    [threadId]: threadState,
+                },
+            };
+        }
+        case "SET_CURRENT_THREAD": {
+            return {
+                ...state,
+                currentThreadId: action.threadId,
+            };
+        }
+        case "START_NEW_THREAD": {
+            // Atomic action: initialize thread AND set as current in one reducer pass
+            // This prevents race conditions when multiple startNewThread() calls happen
+            const { threadId, initialThread } = action;
+            // Don't overwrite existing thread
+            if (state.threadMap[threadId]) {
+                return {
+                    ...state,
+                    currentThreadId: threadId,
+                };
+            }
+            const baseState = createInitialThreadState(threadId);
+            const threadState = initialThread
+                ? {
+                    ...baseState,
+                    thread: {
+                        ...baseState.thread,
+                        ...initialThread,
+                        id: threadId,
+                    },
+                }
+                : baseState;
+            return {
+                ...state,
+                threadMap: {
+                    ...state.threadMap,
+                    [threadId]: threadState,
+                },
+                currentThreadId: threadId,
+            };
+        }
+        case "EVENT":
+            // Fall through to event handling below
+            break;
+    }
+    // Handle EVENT action
+    const { event, threadId } = action;
+    // Get the current thread state, auto-initializing if needed
+    // Auto-initialization handles the case where events arrive before explicit thread init
+    // (e.g., when creating a new thread and RUN_STARTED is the first event)
+    let threadState = state.threadMap[threadId];
+    let updatedState = state;
+    if (!threadState) {
+        // Auto-initialize the thread to avoid dropping events
+        threadState = createInitialThreadState(threadId);
+        updatedState = {
+            ...state,
+            threadMap: {
+                ...state.threadMap,
+                [threadId]: threadState,
+            },
+        };
+    }
+    // Process the event for this specific thread
+    let updatedThreadState;
+    // Switch on event.type - AGUIEvent is a discriminated union so TypeScript
+    // automatically narrows the type in each case branch
+    switch (event.type) {
+        case EventType.RUN_STARTED:
+            updatedThreadState = handleRunStarted(threadState, event);
+            break;
+        case EventType.RUN_FINISHED:
+            updatedThreadState = handleRunFinished(threadState, event);
+            break;
+        case EventType.RUN_ERROR:
+            updatedThreadState = handleRunError(threadState, event);
+            break;
+        case EventType.TEXT_MESSAGE_START:
+            updatedThreadState = handleTextMessageStart(threadState, event);
+            break;
+        case EventType.TEXT_MESSAGE_CONTENT:
+            updatedThreadState = handleTextMessageContent(threadState, event);
+            break;
+        case EventType.TEXT_MESSAGE_END:
+            updatedThreadState = handleTextMessageEnd(threadState, event);
+            break;
+        case EventType.TOOL_CALL_START:
+            updatedThreadState = handleToolCallStart(threadState, event);
+            break;
+        case EventType.TOOL_CALL_ARGS:
+            updatedThreadState = handleToolCallArgs(threadState, event);
+            break;
+        case EventType.TOOL_CALL_END:
+            updatedThreadState = handleToolCallEnd(threadState, event);
+            break;
+        case EventType.TOOL_CALL_RESULT:
+            updatedThreadState = handleToolCallResult(threadState, event);
+            break;
+        case EventType.CUSTOM:
+            updatedThreadState = handleCustomEvent(threadState, event);
+            break;
+        // Unsupported AG-UI event types - may be added in future phases
+        case EventType.TEXT_MESSAGE_CHUNK:
+        case EventType.THINKING_TEXT_MESSAGE_START:
+        case EventType.THINKING_TEXT_MESSAGE_CONTENT:
+        case EventType.THINKING_TEXT_MESSAGE_END:
+        case EventType.TOOL_CALL_CHUNK:
+        case EventType.THINKING_START:
+        case EventType.THINKING_END:
+        case EventType.STATE_SNAPSHOT:
+        case EventType.STATE_DELTA:
+        case EventType.MESSAGES_SNAPSHOT:
+        case EventType.ACTIVITY_SNAPSHOT:
+        case EventType.ACTIVITY_DELTA:
+        case EventType.RAW:
+        case EventType.STEP_STARTED:
+        case EventType.STEP_FINISHED:
+            // Log warning - these events are being ignored
+            console.warn(`[StreamReducer] Received unsupported event type: ${event.type}. ` +
+                `This event will be ignored.`);
+            return updatedState;
+        default: {
+            // Exhaustiveness check: if a new event type is added to AGUIEvent
+            // and not handled above, TypeScript will error here
+            const _exhaustiveCheck = event;
+            throw new UnreachableCaseError(_exhaustiveCheck);
+        }
+    }
+    // Return updated state with modified thread
+    return {
+        ...updatedState,
+        threadMap: {
+            ...updatedState.threadMap,
+            [threadId]: updatedThreadState,
+        },
+    };
+}
+/**
+ * Handle RUN_STARTED event.
+ * @param threadState - Current thread state
+ * @param event - Run started event
+ * @returns Updated thread state
+ */
+function handleRunStarted(threadState, event) {
+    return {
+        ...threadState,
+        thread: {
+            ...threadState.thread,
+            status: "streaming",
+            updatedAt: new Date().toISOString(),
+        },
+        streaming: {
+            status: "streaming",
+            runId: event.runId,
+            startTime: event.timestamp ?? Date.now(),
+        },
+    };
+}
+/**
+ * Handle RUN_FINISHED event.
+ * @param threadState - Current thread state
+ * @param _event - Run finished event (unused)
+ * @returns Updated thread state
+ */
+function handleRunFinished(threadState, _event) {
+    return {
+        ...threadState,
+        thread: {
+            ...threadState.thread,
+            status: "complete",
+            updatedAt: new Date().toISOString(),
+        },
+        streaming: {
+            ...threadState.streaming,
+            status: "complete",
+        },
+    };
+}
+/**
+ * Handle RUN_ERROR event.
+ * @param threadState - Current thread state
+ * @param event - Run error event
+ * @returns Updated thread state
+ */
+function handleRunError(threadState, event) {
+    return {
+        ...threadState,
+        thread: {
+            ...threadState.thread,
+            status: "error",
+            updatedAt: new Date().toISOString(),
+        },
+        streaming: {
+            ...threadState.streaming,
+            status: "error",
+            error: {
+                message: event.message,
+                code: event.code,
+            },
+        },
+    };
+}
+/**
+ * Handle TEXT_MESSAGE_START event.
+ * Creates a new message in the thread.
+ * @param threadState - Current thread state
+ * @param event - Text message start event
+ * @returns Updated thread state
+ */
+function handleTextMessageStart(threadState, event) {
+    const newMessage = {
+        id: event.messageId,
+        role: event.role === "user" ? "user" : "assistant",
+        content: [],
+        createdAt: new Date().toISOString(),
+    };
+    return {
+        ...threadState,
+        thread: {
+            ...threadState.thread,
+            messages: [...threadState.thread.messages, newMessage],
+            updatedAt: new Date().toISOString(),
+        },
+        streaming: {
+            ...threadState.streaming,
+            messageId: event.messageId,
+        },
+    };
+}
+/**
+ * Handle TEXT_MESSAGE_CONTENT event.
+ * Appends text content to the current message.
+ * @param threadState - Current thread state
+ * @param event - Text message content event
+ * @returns Updated thread state
+ */
+function handleTextMessageContent(threadState, event) {
+    const messageId = event.messageId;
+    const messages = threadState.thread.messages;
+    // Find the message to update
+    const messageIndex = messages.findIndex((m) => m.id === messageId);
+    if (messageIndex === -1) {
+        throw new Error(`Message ${messageId} not found for TEXT_MESSAGE_CONTENT event`);
+    }
+    const message = messages[messageIndex];
+    const content = message.content;
+    // Find or create text content block
+    const lastContent = content[content.length - 1];
+    const isTextBlock = lastContent?.type === "text";
+    const updatedContent = isTextBlock
+        ? [
+            ...content.slice(0, -1),
+            {
+                ...lastContent,
+                text: lastContent.text + event.delta,
+            },
+        ]
+        : [
+            ...content,
+            {
+                type: "text",
+                text: event.delta,
+            },
+        ];
+    const updatedMessage = {
+        ...message,
+        content: updatedContent,
+    };
+    return updateThreadMessages(threadState, updateMessageAtIndex(messages, messageIndex, updatedMessage));
+}
+/**
+ * Handle TEXT_MESSAGE_END event.
+ * Marks the message as complete.
+ * @param threadState - Current thread state
+ * @param event - Text message end event
+ * @returns Updated thread state
+ */
+function handleTextMessageEnd(threadState, event) {
+    const activeMessageId = threadState.streaming.messageId;
+    if (activeMessageId && event.messageId !== activeMessageId) {
+        throw new Error(`TEXT_MESSAGE_END messageId mismatch (thread ${threadState.thread.id}): expected ${activeMessageId}, got ${event.messageId}`);
+    }
+    return {
+        ...threadState,
+        streaming: {
+            ...threadState.streaming,
+            messageId: undefined,
+        },
+    };
+}
+/**
+ * Handle TOOL_CALL_START event.
+ * Adds a tool use content block to the current message.
+ * @param threadState - Current thread state
+ * @param event - Tool call start event
+ * @returns Updated thread state
+ */
+function handleToolCallStart(threadState, event) {
+    const messageId = event.parentMessageId;
+    const messages = threadState.thread.messages;
+    // If no parent message ID, use the last message
+    const messageIndex = messageId
+        ? messages.findIndex((m) => m.id === messageId)
+        : messages.length - 1;
+    if (messageIndex === -1) {
+        throw new Error(messageId
+            ? `Message ${messageId} not found for TOOL_CALL_START event`
+            : `No messages exist for TOOL_CALL_START event`);
+    }
+    const message = messages[messageIndex];
+    const newContent = {
+        type: "tool_use",
+        id: event.toolCallId,
+        name: event.toolCallName,
+        input: {},
+    };
+    const updatedMessage = {
+        ...message,
+        content: [...message.content, newContent],
+    };
+    return updateThreadMessages(threadState, updateMessageAtIndex(messages, messageIndex, updatedMessage));
+}
+/**
+ * Handle TOOL_CALL_ARGS event.
+ * Accumulates JSON string deltas for tool call arguments.
+ * The accumulated string will be parsed at TOOL_CALL_END.
+ * @param threadState - Current thread state
+ * @param event - Tool call args event
+ * @returns Updated thread state
+ */
+function handleToolCallArgs(threadState, event) {
+    const toolCallId = event.toolCallId;
+    // Accumulate the JSON string delta
+    const accumulatedArgs = threadState.accumulatingToolArgs;
+    const existingArgs = accumulatedArgs.get(toolCallId) ?? "";
+    const newAccumulatedArgs = new Map(accumulatedArgs);
+    newAccumulatedArgs.set(toolCallId, existingArgs + event.delta);
+    return {
+        ...threadState,
+        accumulatingToolArgs: newAccumulatedArgs,
+    };
+}
+/**
+ * Handle TOOL_CALL_END event.
+ * Parses the accumulated JSON arguments and updates the tool_use content block.
+ * @param threadState - Current thread state
+ * @param event - Tool call end event
+ * @returns Updated thread state
+ */
+function handleToolCallEnd(threadState, event) {
+    const toolCallId = event.toolCallId;
+    const messages = threadState.thread.messages;
+    // Get accumulated JSON args string
+    const accumulatedJson = threadState.accumulatingToolArgs.get(toolCallId);
+    if (!accumulatedJson) {
+        // No args accumulated - tool call has empty input
+        return threadState;
+    }
+    // Parse the accumulated JSON
+    let parsedInput;
+    try {
+        parsedInput = JSON.parse(accumulatedJson);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse tool call arguments for ${toolCallId}: ${error instanceof Error ? error.message : String(error)}. JSON: ${accumulatedJson}`);
+    }
+    // Find the tool_use content block
+    const { messageIndex, contentIndex } = findContentById(messages, "tool_use", toolCallId, "TOOL_CALL_END event");
+    const message = messages[messageIndex];
+    const toolUseContent = message.content[contentIndex];
+    if (toolUseContent.type !== "tool_use") {
+        throw new Error(`Content at index ${contentIndex} is not a tool_use block for TOOL_CALL_END event`);
+    }
+    // Update the tool_use content with parsed input
+    const updatedContent = {
+        ...toolUseContent,
+        input: parsedInput,
+    };
+    const updatedMessage = {
+        ...message,
+        content: updateContentAtIndex(message.content, contentIndex, updatedContent),
+    };
+    // Clear accumulated args for this tool call
+    const newAccumulatingToolArgs = new Map(threadState.accumulatingToolArgs);
+    newAccumulatingToolArgs.delete(toolCallId);
+    return {
+        ...updateThreadMessages(threadState, updateMessageAtIndex(messages, messageIndex, updatedMessage)),
+        accumulatingToolArgs: newAccumulatingToolArgs,
+    };
+}
+/**
+ * Handle TOOL_CALL_RESULT event.
+ * Adds tool result to the message.
+ * @param threadState - Current thread state
+ * @param event - Tool call result event
+ * @returns Updated thread state
+ */
+function handleToolCallResult(threadState, event) {
+    const messageId = event.messageId;
+    const messages = threadState.thread.messages;
+    // Find the message
+    const messageIndex = messages.findIndex((m) => m.id === messageId);
+    if (messageIndex === -1) {
+        throw new Error(`Message ${messageId} not found for TOOL_CALL_RESULT event`);
+    }
+    const message = messages[messageIndex];
+    // Add tool result content
+    const newContent = {
+        type: "tool_result",
+        toolUseId: event.toolCallId,
+        content: [
+            {
+                type: "text",
+                text: event.content,
+            },
+        ],
+    };
+    const updatedMessage = {
+        ...message,
+        content: [...message.content, newContent],
+    };
+    return updateThreadMessages(threadState, updateMessageAtIndex(messages, messageIndex, updatedMessage));
+}
+/**
+ * Handle custom events (Tambo-specific).
+ * @param threadState - Current thread state
+ * @param event - Custom event (already narrowed from AGUIEvent)
+ * @returns Updated thread state
+ */
+function handleCustomEvent(threadState, event) {
+    // Use centralized casting function to get properly typed Tambo event
+    const customEvent = asTamboCustomEvent(event);
+    if (!customEvent) {
+        // Unknown custom event - log and return unchanged
+        console.warn(`[StreamReducer] Unknown custom event name: ${event.name}`);
+        return threadState;
+    }
+    switch (customEvent.name) {
+        case "tambo.component.start":
+            return handleComponentStart(threadState, customEvent);
+        case "tambo.component.props_delta":
+            return handleComponentDelta(threadState, customEvent, "props");
+        case "tambo.component.state_delta":
+            return handleComponentDelta(threadState, customEvent, "state");
+        case "tambo.component.end":
+            return handleComponentEnd(threadState, customEvent);
+        case "tambo.run.awaiting_input":
+            return handleRunAwaitingInput(threadState, customEvent);
+        default: {
+            // Exhaustiveness check: if a new event type is added to TamboCustomEvent
+            // and not handled here, TypeScript will error
+            const _exhaustiveCheck = customEvent;
+            throw new UnreachableCaseError(_exhaustiveCheck);
+        }
+    }
+}
+/**
+ * Handle tambo.component.start event.
+ * Adds a component content block to the message.
+ * @param threadState - Current thread state
+ * @param event - Component start event
+ * @returns Updated thread state
+ */
+function handleComponentStart(threadState, event) {
+    const messageId = event.value.messageId;
+    const messages = threadState.thread.messages;
+    // Find the message
+    const messageIndex = messages.findIndex((m) => m.id === messageId);
+    if (messageIndex === -1) {
+        throw new Error(`Message ${messageId} not found for tambo.component.start event`);
+    }
+    const message = messages[messageIndex];
+    // Add component content block
+    const newContent = {
+        type: "component",
+        id: event.value.componentId,
+        name: event.value.componentName,
+        props: {},
+    };
+    const updatedMessage = {
+        ...message,
+        content: [...message.content, newContent],
+    };
+    return updateThreadMessages(threadState, updateMessageAtIndex(messages, messageIndex, updatedMessage));
+}
+/**
+ * Handle component delta events (both props_delta and state_delta).
+ * Applies JSON Patch to the specified field.
+ * @param threadState - Current thread state
+ * @param event - Component delta event (props or state)
+ * @param field - Which field to update ('props' or 'state')
+ * @returns Updated thread state
+ */
+function handleComponentDelta(threadState, event, field) {
+    const componentId = event.value.componentId;
+    const operations = event.value.operations;
+    const messages = threadState.thread.messages;
+    const eventName = `tambo.component.${field}_delta`;
+    // Find the component content block
+    const { messageIndex, contentIndex } = findContentById(messages, "component", componentId, `${eventName} event`);
+    const message = messages[messageIndex];
+    const componentContent = message.content[contentIndex];
+    if (componentContent.type !== "component") {
+        throw new Error(`Content at index ${contentIndex} is not a component block for ${eventName} event`);
+    }
+    // Get current value (state defaults to {} if undefined)
+    const currentValue = field === "props"
+        ? componentContent.props
+        : (componentContent.state ?? {});
+    // Apply JSON Patch
+    const updatedValue = applyJsonPatch(currentValue, operations);
+    const updatedContent = {
+        ...componentContent,
+        [field]: updatedValue,
+    };
+    const updatedMessage = {
+        ...message,
+        content: updateContentAtIndex(message.content, contentIndex, updatedContent),
+    };
+    return updateThreadMessages(threadState, updateMessageAtIndex(messages, messageIndex, updatedMessage));
+}
+/**
+ * Handle tambo.component.end event.
+ * Marks component as complete.
+ * @param threadState - Current thread state
+ * @param _event - Component end event (unused)
+ * @returns Updated thread state
+ */
+function handleComponentEnd(threadState, _event) {
+    // For now, this doesn't change state
+    return threadState;
+}
+/**
+ * Handle tambo.run.awaiting_input event.
+ * Sets thread status to waiting for client-side tool execution.
+ * @param threadState - Current thread state
+ * @param _event - Run awaiting input event (unused)
+ * @returns Updated thread state
+ */
+function handleRunAwaitingInput(threadState, _event) {
+    return {
+        ...threadState,
+        thread: {
+            ...threadState.thread,
+            status: "waiting",
+            updatedAt: new Date().toISOString(),
+        },
+        streaming: {
+            ...threadState.streaming,
+            status: "waiting",
+        },
+    };
+}
+//# sourceMappingURL=event-accumulator.js.map