@tambo-ai/client 0.0.1

package/dist/tambo-client.js

@@ -0,0 +1,508 @@
+"use strict";
+/**
+ * TamboClient - Framework-agnostic client for Tambo AI
+ *
+ * Main entry point for the `@tambo-ai/client` package. Manages threads,
+ * tool registration, streaming, and state. Compatible with
+ * useSyncExternalStore for React integration.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TamboClient = void 0;
+const typescript_sdk_1 = __importDefault(require("@tambo-ai/typescript-sdk"));
+const mcp_server_info_1 = require("./model/mcp-server-info");
+const mcp_client_1 = require("./mcp/mcp-client");
+const event_accumulator_1 = require("./utils/event-accumulator");
+const tambo_stream_1 = require("./tambo-stream");
+/**
+ * TamboClient manages threads, tool execution, streaming, and state.
+ *
+ * Compatible with `useSyncExternalStore(client.subscribe, client.getState)`
+ * for React integration.
+ * @example
+ * ```typescript
+ * const client = new TamboClient({ apiKey: "your-api-key" });
+ *
+ * // Stream mode
+ * const stream = client.run("Hello, AI!");
+ * for await (const { event, snapshot } of stream) {
+ *   console.log(snapshot.messages);
+ * }
+ *
+ * // Promise mode
+ * const thread = await client.run("Hello, AI!").thread;
+ * console.log(thread.messages);
+ * ```
+ */
+class TamboClient {
+    sdkClient;
+    state;
+    listeners = new Set();
+    pendingNotification = false;
+    toolRegistry = {};
+    componentList = {};
+    mcpClients = new Map();
+    activeRuns = {};
+    contextHelpers = new Map();
+    options;
+    /**
+     * Create a new TamboClient.
+     * @param options - Client configuration.
+     */
+    constructor(options) {
+        if (options.tamboUrl && options.environment) {
+            throw new Error("Cannot specify both 'tamboUrl' and 'environment'. Choose one.");
+        }
+        if (options.userKey && options.userToken) {
+            throw new Error("Cannot specify both 'userKey' and 'userToken'. Choose one.");
+        }
+        this.options = options;
+        this.state = (0, event_accumulator_1.createInitialState)();
+        // Resolve base URL
+        const baseURL = options.tamboUrl ?? this.resolveBaseUrl(options.environment);
+        this.sdkClient = new typescript_sdk_1.default({
+            apiKey: options.apiKey,
+            baseURL,
+        });
+        // Register initial tools
+        if (options.tools) {
+            for (const tool of options.tools) {
+                this.toolRegistry[tool.name] = tool;
+            }
+        }
+        // Connect MCP servers (fire-and-forget)
+        if (options.mcpServers) {
+            for (const server of options.mcpServers) {
+                void this.connectMcpServer(server).catch((err) => {
+                    console.error(`[TamboClient] Failed to connect MCP server:`, err);
+                });
+            }
+        }
+    }
+    // -- Core operations --
+    /**
+     * Start a new run with a message. Returns a TamboStream immediately.
+     *
+     * The stream's processing loop runs in the background. Use async iteration
+     * to observe events, or `await stream.thread` to get the final result.
+     * @param message - The message string or InputMessage object.
+     * @param options - Run configuration.
+     * @returns A TamboStream for observing the response.
+     */
+    run(message, options = {}) {
+        const { threadId, autoExecuteTools = true, maxSteps = 10, toolChoice, debug = false, additionalContext, signal, userMessageText, } = options;
+        // Resolve the actual thread ID
+        const resolvedThreadId = threadId && !(0, event_accumulator_1.isPlaceholderThreadId)(threadId) ? threadId : undefined;
+        // Check for concurrent runs
+        if (resolvedThreadId && this.activeRuns[resolvedThreadId]) {
+            throw new Error(`A run is already active on thread "${resolvedThreadId}". Wait for it to complete or abort it first.`);
+        }
+        // Normalize message to InputMessage
+        const inputMessage = typeof message === "string"
+            ? { role: "user", content: [{ type: "text", text: message }] }
+            : message;
+        // If userMessageText not provided, extract from string messages
+        const resolvedUserMessageText = userMessageText ?? (typeof message === "string" ? message : undefined);
+        // Get previousRunId from thread state
+        const threadState = resolvedThreadId
+            ? this.state.threadMap[resolvedThreadId]
+            : undefined;
+        const previousRunId = threadState?.streaming.runId ?? threadState?.lastCompletedRunId;
+        // Collect context helpers and beforeRun in the stream's processing loop
+        const streamOptions = {
+            client: this.sdkClient,
+            message: inputMessage,
+            threadId: resolvedThreadId,
+            userMessageText: resolvedUserMessageText,
+            componentList: this.componentList,
+            toolRegistry: this.toolRegistry,
+            userKey: this.options.userKey,
+            previousRunId,
+            additionalContext: this.mergeContextForRun(additionalContext),
+            toolChoice,
+            autoExecuteTools,
+            maxSteps,
+            debug,
+            signal,
+            dispatch: (action) => this.dispatch(action),
+            getThreadSnapshot: (tid) => this.getThread(tid),
+        };
+        const stream = new tambo_stream_1.TamboStream(streamOptions);
+        // Track active run
+        if (resolvedThreadId) {
+            this.activeRuns[resolvedThreadId] = stream;
+        }
+        // Clean up active run tracking when stream completes
+        void stream.thread
+            .catch(() => {
+            // Error handled by stream consumer
+        })
+            .finally(() => {
+            if (resolvedThreadId) {
+                delete this.activeRuns[resolvedThreadId];
+            }
+        });
+        return stream;
+    }
+    // -- Thread management --
+    /**
+     * Switch to an existing thread. Fetches thread data from the API.
+     * @param threadId - The thread ID to switch to.
+     */
+    async switchThread(threadId) {
+        await this.fetchThread(threadId);
+        this.dispatch({ type: "SET_CURRENT_THREAD", threadId });
+    }
+    /**
+     * Start a new thread. Returns the new thread ID.
+     * @returns The new placeholder thread ID.
+     */
+    startNewThread() {
+        const threadId = event_accumulator_1.PLACEHOLDER_THREAD_ID;
+        this.dispatch({ type: "START_NEW_THREAD", threadId });
+        return threadId;
+    }
+    /**
+     * Get a thread from local state.
+     * @param threadId - The thread ID.
+     * @returns The thread, or undefined if not found.
+     */
+    getThread(threadId) {
+        return this.state.threadMap[threadId]?.thread;
+    }
+    /**
+     * List all threads from the API.
+     * @returns An array of TamboThread objects.
+     */
+    async listThreads() {
+        const response = await this.sdkClient.threads.list({
+            userKey: this.options.userKey,
+        });
+        // Convert SDK response to TamboThread format
+        return response.threads.map((apiThread) => ({
+            id: apiThread.id,
+            name: apiThread.name ?? undefined,
+            messages: [],
+            status: "idle",
+            metadata: apiThread.metadata ?? undefined,
+            createdAt: apiThread.createdAt,
+            updatedAt: apiThread.updatedAt,
+            lastRunCancelled: false,
+        }));
+    }
+    /**
+     * Fetch a thread from the API and hydrate it into local state.
+     * @param threadId - The thread ID to fetch.
+     * @returns The fetched thread.
+     */
+    async fetchThread(threadId) {
+        const apiThread = await this.sdkClient.threads.retrieve(threadId);
+        // Initialize thread state if not present
+        if (!this.state.threadMap[threadId]) {
+            this.dispatch({ type: "INIT_THREAD", threadId });
+        }
+        // Load messages from the API response
+        if (apiThread.messages && apiThread.messages.length > 0) {
+            this.dispatch({
+                type: "LOAD_THREAD_MESSAGES",
+                threadId,
+                messages: apiThread.messages.map((msg) => ({
+                    id: msg.id,
+                    role: msg.role,
+                    content: msg.content,
+                    createdAt: msg.createdAt,
+                    threadId,
+                })),
+            });
+        }
+        // Set lastCompletedRunId if available
+        if (apiThread.lastCompletedRunId) {
+            this.dispatch({
+                type: "SET_LAST_COMPLETED_RUN_ID",
+                threadId,
+                lastCompletedRunId: apiThread.lastCompletedRunId,
+            });
+        }
+        // Update thread name if available
+        if (apiThread.name) {
+            this.dispatch({
+                type: "UPDATE_THREAD_NAME",
+                threadId,
+                name: apiThread.name,
+            });
+        }
+        const thread = this.getThread(threadId);
+        if (!thread) {
+            throw new Error(`Failed to hydrate thread ${threadId}`);
+        }
+        return thread;
+    }
+    // -- Registration --
+    /**
+     * Register a single tool.
+     * @param tool - The tool to register.
+     */
+    registerTool(tool) {
+        this.toolRegistry[tool.name] = tool;
+    }
+    /**
+     * Register multiple tools at once.
+     * @param tools - The tools to register.
+     */
+    registerTools(tools) {
+        for (const tool of tools) {
+            this.toolRegistry[tool.name] = tool;
+        }
+    }
+    /**
+     * Register a component.
+     * @param name - Component name.
+     * @param component - The registered component.
+     */
+    registerComponent(name, component) {
+        this.componentList[name] = component;
+    }
+    // -- State access (useSyncExternalStore-compatible) --
+    /**
+     * Get the current client state snapshot.
+     * @returns The current client state.
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Subscribe to state changes.
+     * @param listener - Callback invoked on state change.
+     * @returns Unsubscribe function.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    // -- Auth --
+    /**
+     * Compute and return the current auth state. Not stored in state;
+     * computed on each call from config.
+     * @returns The current auth state.
+     */
+    getAuthState() {
+        const { userKey, userToken } = this.options;
+        if (userKey && userToken) {
+            return { status: "invalid" };
+        }
+        if (userKey) {
+            return { status: "identified", source: "userKey" };
+        }
+        if (userToken) {
+            // Token exchange would happen here in full implementation
+            return { status: "exchanging" };
+        }
+        return { status: "unauthenticated" };
+    }
+    // -- Run control --
+    /**
+     * Cancel the active run on a thread.
+     * @param threadId - The thread whose run to cancel. Defaults to current thread.
+     */
+    async cancelRun(threadId) {
+        const tid = threadId ?? this.state.currentThreadId;
+        const activeStream = this.activeRuns[tid];
+        if (activeStream) {
+            activeStream.abort();
+        }
+        // Also try server-side cancellation
+        const threadState = this.state.threadMap[tid];
+        const runId = threadState?.streaming.runId;
+        if (runId && tid) {
+            try {
+                await this.sdkClient.threads.runs.delete(runId, { threadId: tid });
+            }
+            catch (_error) {
+                // Server-side cancellation is best-effort
+            }
+        }
+    }
+    // -- Thread naming --
+    /**
+     * Update a thread's name via the API.
+     * @param threadId - The thread ID.
+     * @param name - The new name.
+     */
+    async updateThreadName(threadId, name) {
+        await this.sdkClient.threads.update(threadId, { name });
+        this.dispatch({ type: "UPDATE_THREAD_NAME", threadId, name });
+    }
+    /**
+     * Generate a thread name via the API.
+     * @param threadId - The thread ID.
+     * @returns The generated name.
+     */
+    async generateThreadName(threadId) {
+        const threadWithName = await this.sdkClient.beta.threads.generateName(threadId);
+        const name = threadWithName.name ?? "";
+        if (name) {
+            this.dispatch({ type: "UPDATE_THREAD_NAME", threadId, name });
+        }
+        return name;
+    }
+    // -- MCP --
+    /**
+     * Connect to an MCP server.
+     * @param serverInfo - The MCP server configuration.
+     * @returns The connected MCPClient.
+     */
+    async connectMcpServer(serverInfo) {
+        const key = (0, mcp_server_info_1.getMcpServerUniqueKey)(serverInfo);
+        const existing = this.mcpClients.get(key);
+        if (existing) {
+            return existing;
+        }
+        const mcpClient = await mcp_client_1.MCPClient.create(serverInfo.url, serverInfo.transport, serverInfo.customHeaders, undefined, // authProvider
+        undefined);
+        this.mcpClients.set(key, mcpClient);
+        return mcpClient;
+    }
+    /**
+     * Disconnect from an MCP server.
+     * @param serverKey - The server key (from getMcpServerUniqueKey).
+     */
+    async disconnectMcpServer(serverKey) {
+        const client = this.mcpClients.get(serverKey);
+        if (client) {
+            await client.close();
+            this.mcpClients.delete(serverKey);
+        }
+    }
+    /**
+     * Get all connected MCP clients.
+     * @returns Record of server key to MCPClient.
+     */
+    getMcpClients() {
+        return Object.fromEntries(this.mcpClients.entries());
+    }
+    /**
+     * Get an MCP token for a context key.
+     * @param contextKey - The context key.
+     * @param threadId - Optional thread ID for session-bound tokens.
+     * @returns The MCP access token response.
+     */
+    async getMcpToken(contextKey, threadId) {
+        const response = await this.sdkClient.beta.auth.getMcpToken({
+            contextKey,
+            threadId,
+        });
+        return {
+            mcpAccessToken: response.mcpAccessToken,
+            expiresAt: response.expiresAt,
+            hasSession: response.hasSession,
+        };
+    }
+    // -- Suggestions --
+    /**
+     * List suggestions for a message.
+     * @param messageId - The message ID.
+     * @param threadId - The thread ID.
+     * @returns Array of suggestions.
+     */
+    async listSuggestions(messageId, threadId) {
+        const response = await this.sdkClient.beta.threads.suggestions.list(messageId, { id: threadId });
+        return response;
+    }
+    /**
+     * Generate suggestions for a message.
+     * @param messageId - The message ID.
+     * @param threadId - The thread ID.
+     * @param options - Generation options.
+     * @param options.maxSuggestions - Maximum number of suggestions to generate.
+     * @returns Array of generated suggestions.
+     */
+    async generateSuggestions(messageId, threadId, options) {
+        const response = await this.sdkClient.beta.threads.suggestions.generate(messageId, {
+            id: threadId,
+            maxSuggestions: options?.maxSuggestions,
+        });
+        return response;
+    }
+    // -- Context helpers --
+    /**
+     * Add a context helper that provides additional context on each run.
+     * @param name - Unique name for the helper.
+     * @param fn - Function returning context data.
+     */
+    addContextHelper(name, fn) {
+        this.contextHelpers.set(name, fn);
+    }
+    /**
+     * Remove a context helper.
+     * @param name - The helper name to remove.
+     */
+    removeContextHelper(name) {
+        this.contextHelpers.delete(name);
+    }
+    /**
+     * Get the underlying SDK client (for advanced use cases).
+     * @returns The TamboAI SDK client.
+     */
+    getSdkClient() {
+        return this.sdkClient;
+    }
+    // -- Private methods --
+    /**
+     * Dispatch an action to the state reducer and notify listeners.
+     * @param action - The action to dispatch.
+     */
+    dispatch(action) {
+        this.state = (0, event_accumulator_1.streamReducer)(this.state, action);
+        this.notifyListeners();
+    }
+    /**
+     * Batch subscriber notifications via queueMicrotask to reduce
+     * re-renders during high-frequency streaming.
+     */
+    notifyListeners() {
+        if (!this.pendingNotification) {
+            this.pendingNotification = true;
+            queueMicrotask(() => {
+                this.pendingNotification = false;
+                for (const listener of this.listeners) {
+                    listener();
+                }
+            });
+        }
+    }
+    /**
+     * Resolve the base URL from an environment preset.
+     * @param environment - The environment to resolve.
+     * @returns The resolved base URL.
+     */
+    resolveBaseUrl(environment) {
+        switch (environment) {
+            case "staging":
+                return "https://api.staging.tambo.co";
+            case "production":
+            default:
+                return "https://api.tambo.co";
+        }
+    }
+    /**
+     * Merge context from registered context helpers with provided additional context.
+     * @param additionalContext - Context provided by the caller.
+     * @returns Merged context object.
+     */
+    mergeContextForRun(additionalContext) {
+        if (this.contextHelpers.size === 0 && !additionalContext) {
+            return undefined;
+        }
+        // Context helpers are gathered synchronously here for the initial merge.
+        // Async helpers are not supported in this synchronous path — they should
+        // be awaited in the stream processing loop via beforeRun.
+        const merged = { ...additionalContext };
+        return merged;
+    }
+}
+exports.TamboClient = TamboClient;
+//# sourceMappingURL=tambo-client.js.map

package/dist/tambo-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tambo-client.js","sourceRoot":"","sources":["../src/tambo-client.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * TamboClient - Framework-agnostic client for Tambo AI\n *\n * Main entry point for the `@tambo-ai/client` package. Manages threads,\n * tool registration, streaming, and state. Compatible with\n * useSyncExternalStore for React integration.\n */\n\nimport TamboAI from \"@tambo-ai/typescript-sdk\";\nimport type { Suggestion } from \"@tambo-ai/typescript-sdk/resources/beta/threads/suggestions\";\n\nimport type { TamboThread } from \"./types/thread\";\nimport type { TamboAuthState } from \"./types/auth\";\nimport type { ToolChoice } from \"./types/tool-choice\";\nimport type { InputMessage } from \"./types/message\";\nimport type {\n  TamboTool,\n  ComponentRegistry,\n  TamboToolRegistry,\n} from \"./model/component-metadata\";\nimport type { McpServerInfo } from \"./model/mcp-server-info\";\nimport { getMcpServerUniqueKey } from \"./model/mcp-server-info\";\nimport { MCPClient } from \"./mcp/mcp-client\";\nimport {\n  streamReducer,\n  createInitialState,\n  isPlaceholderThreadId,\n  PLACEHOLDER_THREAD_ID,\n  type StreamState,\n  type StreamAction,\n  type ThreadState,\n} from \"./utils/event-accumulator\";\nimport { TamboStream, type TamboStreamOptions } from \"./tambo-stream\";\n\n/**\n * Function that returns context to be merged into additionalContext before each run.\n */\nexport type ContextHelperFn = () =>\n  | Record<string, unknown>\n  | Promise<Record<string, unknown>>;\n\n/**\n * Callback invoked before each run starts.\n */\nexport interface BeforeRunContext {\n  /** Thread ID (undefined for new threads). */\n  threadId: string | undefined;\n  /** The message being sent. */\n  message: InputMessage;\n  /** Frozen copy of registered tools (cannot mutate). */\n  tools: Readonly<Record<string, TamboTool>>;\n}\n\n/**\n * Options for configuring TamboClient.\n */\nexport interface TamboClientOptions {\n  /** API key for authentication. */\n  apiKey: string;\n  /** Custom Tambo API URL. Conflicts with `environment`. */\n  tamboUrl?: string;\n  /** Environment preset. Conflicts with `tamboUrl`. */\n  environment?: \"production\" | \"staging\";\n  /** User key for identifying the user. */\n  userKey?: string;\n  /** User token for token-based auth. */\n  userToken?: string;\n  /** Tools to register on creation. */\n  tools?: TamboTool[];\n  /** MCP servers to connect on init. */\n  mcpServers?: McpServerInfo[];\n  /** Callback invoked before each run. */\n  beforeRun?: (context: BeforeRunContext) => void | Promise<void>;\n}\n\n/**\n * Options for the `run()` method.\n */\nexport interface RunOptions {\n  /** Thread ID to run on. If omitted, creates a new thread. */\n  threadId?: string;\n  /** Whether to auto-execute tools when the model requests them. */\n  autoExecuteTools?: boolean;\n  /** Max tool execution rounds (default 10). */\n  maxSteps?: number;\n  /** How the model should select tools. */\n  toolChoice?: ToolChoice;\n  /** Enable debug logging. */\n  debug?: boolean;\n  /** Additional context merged into the message. */\n  additionalContext?: Record<string, unknown>;\n  /** AbortSignal for cancellation. */\n  signal?: AbortSignal;\n  /** User message text for optimistic display. */\n  userMessageText?: string;\n}\n\n/**\n * Public client state exposed via `getState()`.\n */\nexport interface ClientState {\n  /** Map of thread ID to thread state. */\n  threadMap: Record<string, ThreadState>;\n  /** Currently active thread ID. */\n  currentThreadId: string;\n}\n\n// Track active runs per thread to prevent concurrent runs\ntype ActiveRuns = Record<string, TamboStream>;\n\n/**\n * TamboClient manages threads, tool execution, streaming, and state.\n *\n * Compatible with `useSyncExternalStore(client.subscribe, client.getState)`\n * for React integration.\n * @example\n * ```typescript\n * const client = new TamboClient({ apiKey: \"your-api-key\" });\n *\n * // Stream mode\n * const stream = client.run(\"Hello, AI!\");\n * for await (const { event, snapshot } of stream) {\n *   console.log(snapshot.messages);\n * }\n *\n * // Promise mode\n * const thread = await client.run(\"Hello, AI!\").thread;\n * console.log(thread.messages);\n * ```\n */\nexport class TamboClient {\n  private sdkClient: TamboAI;\n  private state: StreamState;\n  private listeners = new Set<() => void>();\n  private pendingNotification = false;\n  private toolRegistry: TamboToolRegistry = {};\n  private componentList: ComponentRegistry = {};\n  private mcpClients = new Map<string, MCPClient>();\n  private activeRuns: ActiveRuns = {};\n  private contextHelpers = new Map<string, ContextHelperFn>();\n  private readonly options: TamboClientOptions;\n\n  /**\n   * Create a new TamboClient.\n   * @param options - Client configuration.\n   */\n  constructor(options: TamboClientOptions) {\n    if (options.tamboUrl && options.environment) {\n      throw new Error(\n        \"Cannot specify both 'tamboUrl' and 'environment'. Choose one.\",\n      );\n    }\n\n    if (options.userKey && options.userToken) {\n      throw new Error(\n        \"Cannot specify both 'userKey' and 'userToken'. Choose one.\",\n      );\n    }\n\n    this.options = options;\n    this.state = createInitialState();\n\n    // Resolve base URL\n    const baseURL =\n      options.tamboUrl ?? this.resolveBaseUrl(options.environment);\n\n    this.sdkClient = new TamboAI({\n      apiKey: options.apiKey,\n      baseURL,\n    });\n\n    // Register initial tools\n    if (options.tools) {\n      for (const tool of options.tools) {\n        this.toolRegistry[tool.name] = tool;\n      }\n    }\n\n    // Connect MCP servers (fire-and-forget)\n    if (options.mcpServers) {\n      for (const server of options.mcpServers) {\n        void this.connectMcpServer(server).catch((err) => {\n          console.error(`[TamboClient] Failed to connect MCP server:`, err);\n        });\n      }\n    }\n  }\n\n  // -- Core operations --\n\n  /**\n   * Start a new run with a message. Returns a TamboStream immediately.\n   *\n   * The stream's processing loop runs in the background. Use async iteration\n   * to observe events, or `await stream.thread` to get the final result.\n   * @param message - The message string or InputMessage object.\n   * @param options - Run configuration.\n   * @returns A TamboStream for observing the response.\n   */\n  run(message: string | InputMessage, options: RunOptions = {}): TamboStream {\n    const {\n      threadId,\n      autoExecuteTools = true,\n      maxSteps = 10,\n      toolChoice,\n      debug = false,\n      additionalContext,\n      signal,\n      userMessageText,\n    } = options;\n\n    // Resolve the actual thread ID\n    const resolvedThreadId =\n      threadId && !isPlaceholderThreadId(threadId) ? threadId : undefined;\n\n    // Check for concurrent runs\n    if (resolvedThreadId && this.activeRuns[resolvedThreadId]) {\n      throw new Error(\n        `A run is already active on thread \"${resolvedThreadId}\". Wait for it to complete or abort it first.`,\n      );\n    }\n\n    // Normalize message to InputMessage\n    const inputMessage: InputMessage =\n      typeof message === \"string\"\n        ? { role: \"user\", content: [{ type: \"text\", text: message }] }\n        : message;\n\n    // If userMessageText not provided, extract from string messages\n    const resolvedUserMessageText =\n      userMessageText ?? (typeof message === \"string\" ? message : undefined);\n\n    // Get previousRunId from thread state\n    const threadState = resolvedThreadId\n      ? this.state.threadMap[resolvedThreadId]\n      : undefined;\n    const previousRunId =\n      threadState?.streaming.runId ?? threadState?.lastCompletedRunId;\n\n    // Collect context helpers and beforeRun in the stream's processing loop\n    const streamOptions: TamboStreamOptions = {\n      client: this.sdkClient,\n      message: inputMessage,\n      threadId: resolvedThreadId,\n      userMessageText: resolvedUserMessageText,\n      componentList: this.componentList,\n      toolRegistry: this.toolRegistry,\n      userKey: this.options.userKey,\n      previousRunId,\n      additionalContext: this.mergeContextForRun(additionalContext),\n      toolChoice,\n      autoExecuteTools,\n      maxSteps,\n      debug,\n      signal,\n      dispatch: (action) => this.dispatch(action),\n      getThreadSnapshot: (tid) => this.getThread(tid),\n    };\n\n    const stream = new TamboStream(streamOptions);\n\n    // Track active run\n    if (resolvedThreadId) {\n      this.activeRuns[resolvedThreadId] = stream;\n    }\n\n    // Clean up active run tracking when stream completes\n    void stream.thread\n      .catch(() => {\n        // Error handled by stream consumer\n      })\n      .finally(() => {\n        if (resolvedThreadId) {\n          delete this.activeRuns[resolvedThreadId];\n        }\n      });\n\n    return stream;\n  }\n\n  // -- Thread management --\n\n  /**\n   * Switch to an existing thread. Fetches thread data from the API.\n   * @param threadId - The thread ID to switch to.\n   */\n  async switchThread(threadId: string): Promise<void> {\n    await this.fetchThread(threadId);\n    this.dispatch({ type: \"SET_CURRENT_THREAD\", threadId });\n  }\n\n  /**\n   * Start a new thread. Returns the new thread ID.\n   * @returns The new placeholder thread ID.\n   */\n  startNewThread(): string {\n    const threadId = PLACEHOLDER_THREAD_ID;\n    this.dispatch({ type: \"START_NEW_THREAD\", threadId });\n    return threadId;\n  }\n\n  /**\n   * Get a thread from local state.\n   * @param threadId - The thread ID.\n   * @returns The thread, or undefined if not found.\n   */\n  getThread(threadId: string): TamboThread | undefined {\n    return this.state.threadMap[threadId]?.thread;\n  }\n\n  /**\n   * List all threads from the API.\n   * @returns An array of TamboThread objects.\n   */\n  async listThreads(): Promise<TamboThread[]> {\n    const response = await this.sdkClient.threads.list({\n      userKey: this.options.userKey,\n    });\n\n    // Convert SDK response to TamboThread format\n    return response.threads.map((apiThread) => ({\n      id: apiThread.id,\n      name: apiThread.name ?? undefined,\n      messages: [],\n      status: \"idle\" as const,\n      metadata: (apiThread.metadata as Record<string, unknown>) ?? undefined,\n      createdAt: apiThread.createdAt,\n      updatedAt: apiThread.updatedAt,\n      lastRunCancelled: false,\n    }));\n  }\n\n  /**\n   * Fetch a thread from the API and hydrate it into local state.\n   * @param threadId - The thread ID to fetch.\n   * @returns The fetched thread.\n   */\n  async fetchThread(threadId: string): Promise<TamboThread> {\n    const apiThread = await this.sdkClient.threads.retrieve(threadId);\n\n    // Initialize thread state if not present\n    if (!this.state.threadMap[threadId]) {\n      this.dispatch({ type: \"INIT_THREAD\", threadId });\n    }\n\n    // Load messages from the API response\n    if (apiThread.messages && apiThread.messages.length > 0) {\n      this.dispatch({\n        type: \"LOAD_THREAD_MESSAGES\",\n        threadId,\n        messages: apiThread.messages.map((msg) => ({\n          id: msg.id,\n          role: msg.role,\n          content: msg.content as TamboThread[\"messages\"][0][\"content\"],\n          createdAt: msg.createdAt,\n          threadId,\n        })),\n      });\n    }\n\n    // Set lastCompletedRunId if available\n    if (apiThread.lastCompletedRunId) {\n      this.dispatch({\n        type: \"SET_LAST_COMPLETED_RUN_ID\",\n        threadId,\n        lastCompletedRunId: apiThread.lastCompletedRunId,\n      });\n    }\n\n    // Update thread name if available\n    if (apiThread.name) {\n      this.dispatch({\n        type: \"UPDATE_THREAD_NAME\",\n        threadId,\n        name: apiThread.name,\n      });\n    }\n\n    const thread = this.getThread(threadId);\n    if (!thread) {\n      throw new Error(`Failed to hydrate thread ${threadId}`);\n    }\n    return thread;\n  }\n\n  // -- Registration --\n\n  /**\n   * Register a single tool.\n   * @param tool - The tool to register.\n   */\n  registerTool(tool: TamboTool): void {\n    this.toolRegistry[tool.name] = tool;\n  }\n\n  /**\n   * Register multiple tools at once.\n   * @param tools - The tools to register.\n   */\n  registerTools(tools: TamboTool[]): void {\n    for (const tool of tools) {\n      this.toolRegistry[tool.name] = tool;\n    }\n  }\n\n  /**\n   * Register a component.\n   * @param name - Component name.\n   * @param component - The registered component.\n   */\n  registerComponent(name: string, component: ComponentRegistry[string]): void {\n    this.componentList[name] = component;\n  }\n\n  // -- State access (useSyncExternalStore-compatible) --\n\n  /**\n   * Get the current client state snapshot.\n   * @returns The current client state.\n   */\n  getState(): ClientState {\n    return this.state;\n  }\n\n  /**\n   * Subscribe to state changes.\n   * @param listener - Callback invoked on state change.\n   * @returns Unsubscribe function.\n   */\n  subscribe(listener: () => void): () => void {\n    this.listeners.add(listener);\n    return () => {\n      this.listeners.delete(listener);\n    };\n  }\n\n  // -- Auth --\n\n  /**\n   * Compute and return the current auth state. Not stored in state;\n   * computed on each call from config.\n   * @returns The current auth state.\n   */\n  getAuthState(): TamboAuthState {\n    const { userKey, userToken } = this.options;\n\n    if (userKey && userToken) {\n      return { status: \"invalid\" };\n    }\n    if (userKey) {\n      return { status: \"identified\", source: \"userKey\" };\n    }\n    if (userToken) {\n      // Token exchange would happen here in full implementation\n      return { status: \"exchanging\" };\n    }\n    return { status: \"unauthenticated\" };\n  }\n\n  // -- Run control --\n\n  /**\n   * Cancel the active run on a thread.\n   * @param threadId - The thread whose run to cancel. Defaults to current thread.\n   */\n  async cancelRun(threadId?: string): Promise<void> {\n    const tid = threadId ?? this.state.currentThreadId;\n    const activeStream = this.activeRuns[tid];\n    if (activeStream) {\n      activeStream.abort();\n    }\n\n    // Also try server-side cancellation\n    const threadState = this.state.threadMap[tid];\n    const runId = threadState?.streaming.runId;\n    if (runId && tid) {\n      try {\n        await this.sdkClient.threads.runs.delete(runId, { threadId: tid });\n      } catch (_error) {\n        // Server-side cancellation is best-effort\n      }\n    }\n  }\n\n  // -- Thread naming --\n\n  /**\n   * Update a thread's name via the API.\n   * @param threadId - The thread ID.\n   * @param name - The new name.\n   */\n  async updateThreadName(threadId: string, name: string): Promise<void> {\n    await this.sdkClient.threads.update(threadId, { name });\n    this.dispatch({ type: \"UPDATE_THREAD_NAME\", threadId, name });\n  }\n\n  /**\n   * Generate a thread name via the API.\n   * @param threadId - The thread ID.\n   * @returns The generated name.\n   */\n  async generateThreadName(threadId: string): Promise<string> {\n    const threadWithName =\n      await this.sdkClient.beta.threads.generateName(threadId);\n    const name = threadWithName.name ?? \"\";\n    if (name) {\n      this.dispatch({ type: \"UPDATE_THREAD_NAME\", threadId, name });\n    }\n    return name;\n  }\n\n  // -- MCP --\n\n  /**\n   * Connect to an MCP server.\n   * @param serverInfo - The MCP server configuration.\n   * @returns The connected MCPClient.\n   */\n  async connectMcpServer(serverInfo: McpServerInfo): Promise<MCPClient> {\n    const key = getMcpServerUniqueKey(serverInfo);\n    const existing = this.mcpClients.get(key);\n    if (existing) {\n      return existing;\n    }\n\n    const mcpClient = await MCPClient.create(\n      serverInfo.url,\n      serverInfo.transport,\n      serverInfo.customHeaders,\n      undefined, // authProvider\n      undefined, // sessionId\n    );\n    this.mcpClients.set(key, mcpClient);\n    return mcpClient;\n  }\n\n  /**\n   * Disconnect from an MCP server.\n   * @param serverKey - The server key (from getMcpServerUniqueKey).\n   */\n  async disconnectMcpServer(serverKey: string): Promise<void> {\n    const client = this.mcpClients.get(serverKey);\n    if (client) {\n      await client.close();\n      this.mcpClients.delete(serverKey);\n    }\n  }\n\n  /**\n   * Get all connected MCP clients.\n   * @returns Record of server key to MCPClient.\n   */\n  getMcpClients(): Record<string, MCPClient> {\n    return Object.fromEntries(this.mcpClients.entries());\n  }\n\n  /**\n   * Get an MCP token for a context key.\n   * @param contextKey - The context key.\n   * @param threadId - Optional thread ID for session-bound tokens.\n   * @returns The MCP access token response.\n   */\n  async getMcpToken(\n    contextKey?: string,\n    threadId?: string,\n  ): Promise<{\n    mcpAccessToken?: string;\n    expiresAt?: number;\n    hasSession?: boolean;\n  }> {\n    const response = await this.sdkClient.beta.auth.getMcpToken({\n      contextKey,\n      threadId,\n    });\n    return {\n      mcpAccessToken: response.mcpAccessToken,\n      expiresAt: response.expiresAt,\n      hasSession: response.hasSession,\n    };\n  }\n\n  // -- Suggestions --\n\n  /**\n   * List suggestions for a message.\n   * @param messageId - The message ID.\n   * @param threadId - The thread ID.\n   * @returns Array of suggestions.\n   */\n  async listSuggestions(\n    messageId: string,\n    threadId: string,\n  ): Promise<Suggestion[]> {\n    const response = await this.sdkClient.beta.threads.suggestions.list(\n      messageId,\n      { id: threadId },\n    );\n    return response;\n  }\n\n  /**\n   * Generate suggestions for a message.\n   * @param messageId - The message ID.\n   * @param threadId - The thread ID.\n   * @param options - Generation options.\n   * @param options.maxSuggestions - Maximum number of suggestions to generate.\n   * @returns Array of generated suggestions.\n   */\n  async generateSuggestions(\n    messageId: string,\n    threadId: string,\n    options?: { maxSuggestions?: number },\n  ): Promise<Suggestion[]> {\n    const response = await this.sdkClient.beta.threads.suggestions.generate(\n      messageId,\n      {\n        id: threadId,\n        maxSuggestions: options?.maxSuggestions,\n      },\n    );\n    return response;\n  }\n\n  // -- Context helpers --\n\n  /**\n   * Add a context helper that provides additional context on each run.\n   * @param name - Unique name for the helper.\n   * @param fn - Function returning context data.\n   */\n  addContextHelper(name: string, fn: ContextHelperFn): void {\n    this.contextHelpers.set(name, fn);\n  }\n\n  /**\n   * Remove a context helper.\n   * @param name - The helper name to remove.\n   */\n  removeContextHelper(name: string): void {\n    this.contextHelpers.delete(name);\n  }\n\n  /**\n   * Get the underlying SDK client (for advanced use cases).\n   * @returns The TamboAI SDK client.\n   */\n  getSdkClient(): TamboAI {\n    return this.sdkClient;\n  }\n\n  // -- Private methods --\n\n  /**\n   * Dispatch an action to the state reducer and notify listeners.\n   * @param action - The action to dispatch.\n   */\n  private dispatch(action: StreamAction): void {\n    this.state = streamReducer(this.state, action);\n    this.notifyListeners();\n  }\n\n  /**\n   * Batch subscriber notifications via queueMicrotask to reduce\n   * re-renders during high-frequency streaming.\n   */\n  private notifyListeners(): void {\n    if (!this.pendingNotification) {\n      this.pendingNotification = true;\n      queueMicrotask(() => {\n        this.pendingNotification = false;\n        for (const listener of this.listeners) {\n          listener();\n        }\n      });\n    }\n  }\n\n  /**\n   * Resolve the base URL from an environment preset.\n   * @param environment - The environment to resolve.\n   * @returns The resolved base URL.\n   */\n  private resolveBaseUrl(environment?: \"production\" | \"staging\"): string {\n    switch (environment) {\n      case \"staging\":\n        return \"https://api.staging.tambo.co\";\n      case \"production\":\n      default:\n        return \"https://api.tambo.co\";\n    }\n  }\n\n  /**\n   * Merge context from registered context helpers with provided additional context.\n   * @param additionalContext - Context provided by the caller.\n   * @returns Merged context object.\n   */\n  private mergeContextForRun(\n    additionalContext?: Record<string, unknown>,\n  ): Record<string, unknown> | undefined {\n    if (this.contextHelpers.size === 0 && !additionalContext) {\n      return undefined;\n    }\n\n    // Context helpers are gathered synchronously here for the initial merge.\n    // Async helpers are not supported in this synchronous path — they should\n    // be awaited in the stream processing loop via beforeRun.\n    const merged: Record<string, unknown> = { ...additionalContext };\n    return merged;\n  }\n}\n"]}