booths 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,917 @@
+import { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+import { EasyInputMessage } from 'openai/resources/responses/responses';
+import { FunctionTool } from 'openai/resources/responses/responses';
+import { Metadata } from 'openai/resources/shared.mjs';
+import { Reasoning } from 'openai/resources/shared.mjs';
+import { Response as Response_2 } from 'openai/resources/responses/responses';
+import { ResponseCodeInterpreterToolCall } from 'openai/resources/responses/responses';
+import { ResponseComputerToolCall } from 'openai/resources/responses/responses';
+import { ResponseCreateParamsNonStreaming } from 'openai/resources/responses/responses';
+import { ResponseFileSearchToolCall } from 'openai/resources/responses/responses';
+import { ResponseFunctionToolCall } from 'openai/resources/responses/responses';
+import { ResponseFunctionWebSearch } from 'openai/resources/responses/responses';
+import { ResponseIncludable } from 'openai/resources/responses/responses';
+import { ResponseInput } from 'openai/resources/responses/responses';
+import { ResponseInputItem } from 'openai/resources/responses/responses';
+import { ResponseOutputMessage } from 'openai/resources/responses/responses';
+import { ResponsePrompt } from 'openai/resources/responses/responses';
+import { ResponseReasoningItem } from 'openai/resources/responses/responses';
+import { ResponsesModel } from 'openai/resources/shared.mjs';
+import { ResponseTextConfig } from 'openai/resources/responses/responses';
+import { Tool } from 'openai/resources/responses/responses';
+import { ToolChoiceFunction } from 'openai/resources/responses/responses';
+import { ToolChoiceOptions } from 'openai/resources/responses/responses';
+import { ToolChoiceTypes } from 'openai/resources/responses/responses';
+
+/**
+ * Defines the configuration for a booth. Each booth must have a unique ID,
+ * a defined role, and a set of capabilities.
+ */
+export declare interface BoothConfig {
+    /** A unique identifier for the booth. */
+    id: string;
+    /** The role or persona of the booth (e.g., "Customer Support Agent"). */
+    role: string;
+    /** A description of the booth's purpose and capabilities. */
+    description: string;
+    /** The developer or team responsible for the booth. */
+    developer?: string;
+    /** A list of tool names that this booth is authorized to use. */
+    tools: string[];
+    /**
+     * A list of tools in the format expected by the Multi-Category Peppercorn (MCP) system.
+     * This is likely for more complex tool definitions.
+     */
+    mcp?: Tool[];
+    /** An optional flow definition for orchestrating complex, multi-step behaviors. */
+    flow?: string;
+    /**
+     * Specifies the formatting rules and provides examples for the booth's responses.
+     * This can help ensure consistent and parsable output.
+     */
+    responseFormat?: string;
+    /** A list of example queries or inputs that the booth is designed to handle. */
+    examples: string[];
+    /**
+     * Defines fallback behavior for when the booth receives a query that is out of scope.
+     */
+    fallback?: {
+        /**
+         * Specifies the action to take when the booth is out of scope.
+         * Currently, the only supported action is to route to another booth.
+         */
+        onOutOfScope: {
+            action: 'route_to_booth';
+            target: string;
+        };
+    };
+}
+
+/**
+ * Defines the structure of a booth plugin, which can hook into various stages
+ * of the interaction lifecycle to extend or modify the behavior of the booth engine.
+ */
+export declare interface BoothPlugin {
+    /** A unique identifier for the plugin. */
+    id: string;
+    /** The name of the plugin. */
+    name: string;
+    /** A description of what the plugin does. */
+    description: string;
+    /**
+     * Called before the interaction loop starts. This can be used for setup tasks
+     * or to modify the initial request parameters.
+     * @param prepareInitialMessagesArgs - Utilities for accessing repositories.
+     * @param responseParams - The initial parameters for the response creation.
+     * @returns The potentially modified response parameters.
+     */
+    onBeforeInteractionLoopStart?: (prepareInitialMessagesArgs: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming, initialInput: string) => Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Called before a message is sent to the AI. This allows for modification
+     * of the message or its parameters.
+     * @param prepareInitialMessagesArgs - Utilities for accessing repositories.
+     * @param responseParams - The parameters for the response creation.
+     * @returns The potentially modified response parameters.
+     */
+    onBeforeMessageSend?: (prepareInitialMessagesArgs: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming) => Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Called after a response is received from the AI. This can be used to process
+     * the response or to decide on further actions.
+     * @param messageReceivedArgs - Utilities for accessing repositories.
+     * @param responseParams - The parameters used for the response creation.
+     * @param response - The response received from the AI.
+     * @returns The potentially modified response parameters.
+     */
+    onResponseReceived?: (messageReceivedArgs: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming, response: Response_2) => Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Called before an individual tool call is executed. This allows for modification
+     * of the tool call parameters or early termination.
+     * @param utilities - Utilities for accessing repositories.
+     * @param toolCall - The tool call that is about to be executed.
+     * @param context - Context information about the tool call execution.
+     * @returns The potentially modified tool call.
+     */
+    onBeforeToolCall?: (utilities: RepositoryUtilities, toolCall: ResponseFunctionToolCall, context: ToolCallContext) => Promise<ResponseFunctionToolCall>;
+    /**
+     * Called after an individual tool call is successfully executed. This allows for
+     * processing or modifying the tool call result.
+     * @param utilities - Utilities for accessing repositories.
+     * @param toolCall - The tool call that was executed.
+     * @param result - The result returned by the tool execution.
+     * @param context - Context information about the tool call execution.
+     * @returns The potentially modified tool call result.
+     */
+    onAfterToolCall?: (utilities: RepositoryUtilities, toolCall: ResponseFunctionToolCall, result: any, context: ToolCallContext) => Promise<any>;
+    /**
+     * Called when an individual tool call encounters an error during execution.
+     * This allows for custom error handling or recovery.
+     * @param utilities - Utilities for accessing repositories.
+     * @param toolCall - The tool call that failed.
+     * @param error - The error that occurred during tool execution.
+     * @param context - Context information about the tool call execution.
+     * @returns The error result or a recovery value to use instead.
+     */
+    onToolCallError?: (utilities: RepositoryUtilities, toolCall: ResponseFunctionToolCall, error: Error, context: ToolCallContext) => Promise<any>;
+    /**
+     * Determines whether the interaction loop should end. This is a mandatory method
+     * for all plugins.
+     * @param prepareInitialMessagesArgs - Utilities for accessing repositories.
+     * @param responseParams - The parameters for the response creation.
+     * @param response - The latest response from the AI.
+     * @returns A boolean indicating whether to end the interaction loop.
+     */
+    shouldEndInteractionLoop: (prepareInitialMessagesArgs: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming, response: Response_2) => Promise<boolean>;
+    /**
+     * Called after the interaction loop has ended. This can be used for cleanup
+     * or to perform final actions.
+     * @param interactionLoopEndArgs - Utilities for accessing repositories.
+     * @param response - The final response from the AI.
+     * @returns The potentially modified final response.
+     */
+    onAfterInteractionLoopEnd?: (interactionLoopEndArgs: RepositoryUtilities, response: Response_2) => Promise<Response_2>;
+}
+
+/**
+ * The BoothPluginRegistry manages the collection of plugins within the booth system.
+ *
+ * This registry is responsible for maintaining the set of available plugins, providing
+ * methods for registering, retrieving, and managing plugins. It also orchestrates the
+ * execution of plugin hooks at various stages of the interaction lifecycle.
+ */
+export declare class BoothPluginRegistry {
+    /**
+     * Collection of registered plugins.
+     * @private
+     */
+    private plugins;
+    /**
+     * Registers a single plugin in the registry.
+     * Throws an error if a plugin with the same ID already exists.
+     *
+     * @param plugin - The plugin instance to register
+     */
+    registerPlugin(plugin: BoothPlugin): void;
+    /**
+     * Returns all registered plugins.
+     *
+     * @returns Array of registered plugin instances
+     */
+    getPlugins(): BoothPlugin[];
+    /**
+     * Registers multiple plugins at once.
+     *
+     * @param plugins - Array of plugin instances to register
+     */
+    registerPlugins(plugins: BoothPlugin[]): void;
+    /**
+     * Finds and returns a plugin by its ID.
+     *
+     * @param pluginId - The unique identifier of the plugin to retrieve
+     * @returns The plugin instance if found, undefined otherwise
+     */
+    getPluginById(pluginId: string): BoothPlugin | undefined;
+    /**
+     * Removes a plugin from the registry by its ID.
+     * Throws an error if the plugin doesn't exist.
+     *
+     * @param pluginId - The unique identifier of the plugin to remove
+     */
+    unregisterPlugin(pluginId: string): void;
+    /**
+     * Sequentially invokes every plugin's onBeforeInteractionLoopStart hook.
+     * Each plugin receives the accumulated response parameters from previous plugins,
+     * allowing them to build upon each other's modifications.
+     *
+     * @param prepareArgs - Context information including booth registry and current booth ID
+     * @param initialParams - Initial response parameters to be modified by plugins
+     * @param initialInput
+     * @returns Modified response parameters after all plugins have processed them
+     */
+    runBeforeInteractionLoopStart(prepareArgs: RepositoryUtilities, initialParams: ResponseCreateParamsNonStreaming, initialInput: string): Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Sequentially invokes every plugin's onBeforeMessageSend hook.
+     * This is called immediately before sending a message to the LLM,
+     * allowing plugins to modify the request parameters.
+     *
+     * @param prepareArgs - Context information including booth registry and current booth ID
+     * @param initialParams - Response parameters to be modified before sending to LLM
+     * @returns Modified response parameters after all plugins have processed them
+     */
+    runBeforeMessageSend(prepareArgs: RepositoryUtilities, initialParams: ResponseCreateParamsNonStreaming): Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Sequentially invokes every plugin's onResponseReceived hook.
+     * This is called after receiving a response from the LLM,
+     * allowing plugins to process or modify the response.
+     *
+     * @param messageArgs - Context information including the LLM response, booth registry, and current booth ID
+     * @param initialParams - Response parameters to be potentially modified based on the received response
+     * @param response - The actual response received from the LLM
+     * @returns Modified response parameters after all plugins have processed them
+     */
+    runResponseReceived(messageArgs: RepositoryUtilities, initialParams: ResponseCreateParamsNonStreaming, response: Response_2): Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Checks if any plugin wants to end the interaction loop.
+     * Returns true as soon as any plugin indicates the loop should end.
+     *
+     * @param prepareArgs - Context information including booth registry and current booth ID
+     * @param responseParams - Current response parameters
+     * @param response - The response received from the LLM
+     * @returns True if any plugin indicates the loop should end, false otherwise
+     */
+    runShouldEndInteractionLoop(prepareArgs: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming, response: Response_2): Promise<boolean>;
+    /**
+     * Sequentially invokes every plugin's onAfterInteractionLoopEnd hook.
+     * This is called when the interaction loop has completed,
+     * allowing plugins to perform cleanup or final processing.
+     *
+     * @param endArgs - Context information including booth registry and current booth ID
+     * @param finalResponse - The final response from the LLM
+     */
+    runAfterInteractionLoopEnd(endArgs: RepositoryUtilities, finalResponse: Response_2): Promise<Response_2>;
+    /**
+     * Sequentially invokes every plugin's onBeforeToolCall hook.
+     * This is called before executing an individual tool call,
+     * allowing plugins to modify the tool call parameters.
+     *
+     * @param utilities - Context information including booth and tool registries
+     * @param toolCall - The tool call that is about to be executed
+     * @param context - Context information about the tool call execution
+     * @returns Modified tool call after all plugins have processed it
+     */
+    runBeforeToolCall(utilities: RepositoryUtilities, toolCall: ResponseFunctionToolCall, context: ToolCallContext): Promise<ResponseFunctionToolCall>;
+    /**
+     * Sequentially invokes every plugin's onAfterToolCall hook.
+     * This is called after successfully executing an individual tool call,
+     * allowing plugins to process or modify the tool call result.
+     *
+     * @param utilities - Context information including booth and tool registries
+     * @param toolCall - The tool call that was executed
+     * @param result - The result returned by the tool execution
+     * @param context - Context information about the tool call execution
+     * @returns Modified result after all plugins have processed it
+     */
+    runAfterToolCall(utilities: RepositoryUtilities, toolCall: ResponseFunctionToolCall, result: any, context: ToolCallContext): Promise<any>;
+    /**
+     * Sequentially invokes every plugin's onToolCallError hook.
+     * This is called when an individual tool call encounters an error during execution,
+     * allowing plugins to handle or recover from the error.
+     *
+     * @param utilities - Context information including booth and tool registries
+     * @param toolCall - The tool call that failed
+     * @param error - The error that occurred during tool execution
+     * @param context - Context information about the tool call execution
+     * @returns Error result or recovery value after all plugins have processed it
+     */
+    runToolCallError(utilities: RepositoryUtilities, toolCall: ResponseFunctionToolCall, error: Error, context: ToolCallContext): Promise<any>;
+}
+
+/**
+ * The BoothRegistry manages the collection of booth configurations within the system.
+ *
+ * This registry maintains a catalog of available booths and provides methods for
+ * registering, retrieving, and managing booth configurations. It also maintains
+ * a reference to the base booth configuration that all other booths extend from.
+ */
+export declare class BoothRegistry {
+    private baseBooth;
+    /**
+     * Collection of registered booth configurations, indexed by their IDs.
+     * @private
+     */
+    private booths;
+    /**
+     * The current context booth ID, defaulting to the orchestrator context.
+     * @private
+     */
+    private currentContextId;
+    /**
+     * Creates a new booth registry with a specified base booth configuration.
+     *
+     * @param baseBooth - The base booth configuration that all other booths extend from
+     * @param currentContextId - The initial current context booth ID (default is 'orchestrator')
+     */
+    constructor(baseBooth: BoothConfig, currentContextId?: string);
+    /**
+     * Gets the current context booth ID.
+     *
+     * @returns The current context ID.
+     */
+    getCurrentContextId(): string;
+    /**
+     * Sets the current context booth ID.
+     * Throws an error if the provided ID is not registered.
+     *
+     * @param contextId - The booth ID to set as current context.
+     */
+    setCurrentContextId(contextId: string): void;
+    /**
+     * Returns the current context booth configuration.
+     * Throws an error if the current context booth is not registered.
+     *
+     * @returns The current context booth configuration.
+     */
+    get currentContextBoothConfig(): BoothConfig;
+    /**
+     * Registers a single booth configuration in the registry.
+     * Throws an error if a booth with the same ID already exists.
+     *
+     * @param boothConfig - The booth configuration to register
+     */
+    registerBooth(boothConfig: BoothConfig): void;
+    /**
+     * Returns the base booth configuration that was provided during initialization.
+     * This configuration serves as the foundation for all booth interactions.
+     *
+     * @returns The base booth configuration
+     */
+    get baseBoothConfig(): BoothConfig;
+    /**
+     * Returns the orchestrator booth configuration.
+     * The orchestrator booth is responsible for managing booth routing and coordination.
+     * Throws an error if the orchestrator booth is not registered.
+     *
+     * @returns The orchestrator booth configuration
+     */
+    get orchestratorBoothConfig(): BoothConfig;
+    /**
+     * Registers multiple booth configurations at once.
+     *
+     * @param boothConfigs - Array of booth configurations to register
+     */
+    registerBooths(boothConfigs: BoothConfig[]): void;
+    /**
+     * Finds and returns a booth configuration by its ID.
+     *
+     * @param boothId - The unique identifier of the booth to retrieve
+     * @returns The booth configuration if found, undefined otherwise
+     */
+    getBoothById(boothId: string): BoothConfig | undefined;
+    /**
+     * Returns all registered booth configurations.
+     *
+     * @returns Record of all booth configurations indexed by their IDs
+     */
+    getAllBooths(): Record<string, BoothConfig>;
+    /**
+     * Removes a booth configuration from the registry by its ID.
+     * Throws an error if the booth doesn't exist.
+     *
+     * @param boothId - The unique identifier of the booth to remove
+     */
+    unregisterBooth(boothId: string): void;
+}
+
+/**
+ * The ContextProviderPlugin provides contextual information to booths during interaction loops.
+ *
+ * This plugin enriches the interaction by adding booth-specific context from both the base booth
+ * and the current context booth. It ensures that LLM responses are appropriately informed by
+ * the specific booth context the user is interacting with.
+ */
+export declare class ContextProviderPlugin implements BoothPlugin {
+    /**
+     * Unique identifier for this plugin instance.
+     * @private
+     */
+    private readonly plugin_id;
+    /**
+     * Display the name for this plugin.
+     * @private
+     */
+    private readonly plugin_name;
+    /**
+     * Brief description of the plugin's purpose and functionality.
+     * @private
+     */
+    private readonly plugin_description;
+    /**
+     * Returns the plugin's unique identifier.
+     */
+    get id(): string;
+    /**
+     * Returns the plugin's display name.
+     */
+    get name(): string;
+    /**
+     * Returns the plugin's description.
+     */
+    get description(): string;
+    /**
+     * Executes before the interaction loop starts, adding context from both the base booth
+     * and the current context booth to the response parameters.
+     *
+     * @param prepareInitialMessagesArgs - Object containing the booth registry and current context booth ID
+     * @param responseParams - Current parameters for the LLM response creation
+     * @returns Updated response parameters with added instructions containing booth context
+     */
+    onBeforeMessageSend(prepareInitialMessagesArgs: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming): Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Determines whether the interaction loop should end.
+     * This implementation always returns false, indicating the loop should continue.
+     *
+     * @returns A promise resolving to false, indicating the interaction should continue
+     */
+    shouldEndInteractionLoop(): Promise<boolean>;
+}
+
+/**
+ * The ConversationHistoryPlugin manages the conversation history between users and the booth system.
+ *
+ * This plugin is responsible for maintaining a continuous conversation context by tracking
+ * and preserving all messages exchanged between the user and the LLM. It ensures that each new
+ * interaction has access to the full conversation history, enabling contextual responses.
+ */
+export declare class ConversationHistoryPlugin implements BoothPlugin {
+    /**
+     * Unique identifier for this plugin instance.
+     * @private
+     */
+    private readonly plugin_id;
+    /**
+     * Display name for this plugin.
+     * @private
+     */
+    private readonly plugin_name;
+    /**
+     * Brief description of the plugin's purpose and functionality.
+     * @private
+     */
+    private readonly plugin_description;
+    /**
+     * Returns the plugin's unique identifier.
+     */
+    get id(): string;
+    /**
+     * Returns the plugin's display name.
+     */
+    get name(): string;
+    /**
+     * Returns the plugin's description.
+     */
+    get description(): string;
+    /**
+     * Executes before the interaction loop starts, adding the current user input to the
+     * conversation history and updating the response parameters with the complete history.
+     *
+     * @param _ - Object containing the booth registry and context booth ID (unused in this method)
+     * @param responseParams - Current parameters for the LLM response creation
+     * @returns Updated response parameters with the complete conversation history
+     */
+    onBeforeInteractionLoopStart(_: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming): Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Executes after receiving a response from the LLM, adding the response content
+     * to the conversation history for future reference.
+     *
+     * @param _
+     * @param responseParams - Current parameters for the LLM response creation
+     * @param response
+     * @returns Unmodified response parameters
+     */
+    onResponseReceived(_: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming, response: Response_2): Promise<{
+        input: ( ResponseFunctionToolCall | EasyInputMessage | ResponseOutputMessage | ResponseFileSearchToolCall | ResponseComputerToolCall | ResponseInputItem.ComputerCallOutput | ResponseFunctionWebSearch | ResponseInputItem.FunctionCallOutput | ResponseReasoningItem | ResponseInputItem.ImageGenerationCall | ResponseCodeInterpreterToolCall | ResponseInputItem.LocalShellCall | ResponseInputItem.LocalShellCallOutput | ResponseInputItem.McpListTools | ResponseInputItem.McpApprovalRequest | ResponseInputItem.McpApprovalResponse | ResponseInputItem.McpCall | ResponseInputItem.ItemReference)[];
+        stream?: false | null;
+        background?: boolean | null;
+        include?: Array< ResponseIncludable> | null;
+        instructions?: string | null;
+        max_output_tokens?: number | null;
+        metadata?: Metadata | null;
+        model?: ResponsesModel;
+        parallel_tool_calls?: boolean | null;
+        previous_response_id?: string | null;
+        prompt?: ResponsePrompt | null;
+        reasoning?: Reasoning | null;
+        service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;
+        store?: boolean | null;
+        temperature?: number | null;
+        text?: ResponseTextConfig;
+        tool_choice?: ToolChoiceOptions | ToolChoiceTypes | ToolChoiceFunction;
+        tools?: Array< Tool>;
+        top_p?: number | null;
+        truncation?: "auto" | "disabled" | null;
+        user?: string;
+    }>;
+    /**
+     * Determines whether the interaction loop should end.
+     * This implementation always returns false, indicating the loop should continue.
+     *
+     * @returns A promise resolving to false, indicating the interaction should continue
+     */
+    shouldEndInteractionLoop(): Promise<boolean>;
+}
+
+/**
+ * CoreBooth is a class that serves as the central manager for a booth system,
+ * handling the integration of plugins, the registration of booth instances,
+ * and the processing of interactions using the configured plugins.
+ */
+export declare class CoreBooth<T> {
+    /**
+     * Represents a registry that maintains a collection of plugins for a booth system.
+     * The boothPluginRegistry is used to manage and access plugins that enhance
+     * or extend the booth's behavior or features.
+     *
+     * This variable is intended to provide a central location for plugin registration,
+     * retrieval, and management.
+     *
+     * @type {BoothPluginRegistry}
+     */
+    private boothPluginRegistry;
+    /**
+     * Registry for managing booth configurations across the system.
+     * This registry maintains a collection of booth definitions that can be
+     * accessed by their unique identifiers.
+     *
+     * @type {BoothRegistry}
+     */
+    private readonly boothRegistry;
+    /**
+     * Primary processor for handling interactions between users and the booth system.
+     * Responsible for sending messages to the LLM, processing responses, and managing
+     * the interaction loop through plugins.
+     *
+     * @type {InteractionProcessor}
+     */
+    callProcessor: InteractionProcessor<T>;
+    /**
+     * Registry dedicated to system-level plugins that are always available.
+     * This includes core functionality plugins like conversation history and context providers,
+     * as well as any user-defined plugins from the boothPluginRegistry.
+     *
+     * @type {BoothPluginRegistry}
+     */
+    private readonly systemPluginsRegistry;
+    /**
+     * A variable that represents a registry for managing and maintaining a collection of tools.
+     * `toolRegistry` is an instance of the `ToolRegistry` class, which provides functionalities
+     * for adding, removing, and retrieving tools.
+     *
+     * The `ToolRegistry` class typically serves as a centralized storage or management
+     * solution for tools that are used in a specific context or application.
+     */
+    private readonly toolRegistry;
+    /**
+     * Initializes a new instance of the CoreBooth class.
+     * Sets up the plugin registries, system plugins, and interaction processor.
+     *
+     * @param {Object} options - Configuration options for the CoreBooth
+     * @param {BoothPluginRegistry} options.boothPlugins - Registry containing user-defined plugins
+     * @param {BoothRegistry} options.booths - Registry containing booth configurations
+     * @param {ToolRegistry} options.tools - Registry containing tool configurations
+     */
+    constructor(options: {
+        boothPlugins: BoothPluginRegistry;
+        booths: BoothRegistry;
+        tools: ToolRegistry;
+        llmAdapter: LLMAdapter<T>;
+    });
+}
+
+/**
+ * Creates a `route_to_booth` tool module that can be used by the LLM to switch the conversation
+ * context to a different booth. The tool's definition is dynamically generated based on the
+ * available booths in the provided `boothRegistry`.
+ *
+ * @param boothRegistry - The registry containing all available booth configurations.
+ * @returns A `ToolModule` definition for the `route_to_booth` tool.
+ */
+export declare function createRouteToBoothTool(boothRegistry: BoothRegistry): ToolModule;
+
+/**
+ * The FinishTurnPlugin manages the end of a conversational turn by checking for a specific marker
+ * in the LLM's response. It also cleans up this marker before the final output is returned.
+ */
+export declare class FinishTurnPlugin implements BoothPlugin {
+    description: string;
+    id: string;
+    name: string;
+    /**
+     * Before sending a message, this hook adds an instruction to the LLM to include a
+     * specific marker (`__awaiting_user_response__`) when it expects a user response.
+     * @param _ - Unused repository utilities.
+     * @param responseParams - The parameters for the response creation.
+     * @returns The updated response parameters with the added instruction.
+     */
+    onBeforeMessageSend(_: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming): Promise<{
+        instructions: string;
+        stream?: false | null;
+        background?: boolean | null;
+        include?: Array< ResponseIncludable> | null;
+        input?: string | ResponseInput;
+        max_output_tokens?: number | null;
+        metadata?: Metadata | null;
+        model?: ResponsesModel;
+        parallel_tool_calls?: boolean | null;
+        previous_response_id?: string | null;
+        prompt?: ResponsePrompt | null;
+        reasoning?: Reasoning | null;
+        service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;
+        store?: boolean | null;
+        temperature?: number | null;
+        text?: ResponseTextConfig;
+        tool_choice?: ToolChoiceOptions | ToolChoiceTypes | ToolChoiceFunction;
+        tools?: Array< Tool>;
+        top_p?: number | null;
+        truncation?: "auto" | "disabled" | null;
+        user?: string;
+    }>;
+    /**
+     * Determines whether the interaction loop should end by checking for the presence of the
+     * `__awaiting_user_response__` marker in the response text or if there's an error response.
+     * @param _ - Unused repository utilities.
+     * @param __ - Unused response parameters.
+     * @param response - The response from the LLM.
+     * @returns A boolean indicating whether the loop should end.
+     */
+    shouldEndInteractionLoop(_: RepositoryUtilities, __: ResponseCreateParamsNonStreaming, response: Response_2): Promise<boolean>;
+    /**
+     * After the interaction loop ends, this hook removes the `__awaiting_user_response__` marker
+     * from the final response before it is returned.
+     * @param _ - Unused repository utilities.
+     * @param response - The final response from the LLM.
+     * @returns The cleaned response.
+     */
+    onAfterInteractionLoopEnd(_: RepositoryUtilities, response: Response_2): Promise<Response_2>;
+}
+
+/**
+ * The InteractionProcessor class orchestrates the conversation with the LLM,
+ * managing the interaction loop, plugin execution, and message passing.
+ */
+export declare class InteractionProcessor<T> {
+    private boothRegistry;
+    private boothPlugins;
+    private toolRegistry;
+    private llmAdapter;
+    private loopLimit;
+    /**
+     * Creates a synthetic error response with proper structure and error details.
+     * @param error - The error that occurred
+     * @param responseCreateParams - The original request parameters
+     * @returns A properly structured Response object representing the error
+     * @private
+     */
+    private createErrorResponse;
+    /**
+     * Calls the LLM with the given parameters.
+     * @param responseCreateParams - The parameters for creating the response.
+     * @returns A promise that resolves with the LLM's response.
+     * @private
+     */
+    private callLLM;
+    /**
+     * Runs the main interaction loop, sending messages to the LLM and processing
+     * the responses through the registered plugins.
+     * @param initialResponseParams - The initial parameters for the response.
+     * @returns A promise that resolves with the final response from the LLM.
+     * @private
+     */
+    private runInteractionLoop;
+    /**
+     * Creates an instance of InteractionProcessor.
+     * @param boothRegistry - The registry for booth configurations.
+     * @param boothPlugins - The registry for booth plugins.
+     * @param toolRegistry - The registry for available tools.
+     * @param openAIClient - The OpenAI client instance.
+     */
+    constructor(boothRegistry: BoothRegistry, boothPlugins: BoothPluginRegistry, toolRegistry: ToolRegistry, llmAdapter: LLMAdapter<T>);
+    /**
+     * Sends a message to the LLM and processes the response through the interaction loop.
+     * This involves running pre-loop, pre-send, response-received, and post-loop plugin hooks.
+     * @param input The input message to send.
+     * @returns The processed response from the LLM.
+     */
+    send(input: string): Promise<Response_2>;
+}
+
+export declare interface LLMAdapter<LLMResponse> {
+    invoke: (responseParams: ResponseCreateParamsNonStreaming) => Promise<LLMResponse>;
+    interpret: (response: LLMResponse) => Promise<Response_2>;
+}
+
+/**
+ * Defines the unique identifier for the orchestrator booth, which is responsible
+ * for routing and coordinating other booths.
+ */
+export declare type ORCHESTRATOR_BOOTH_ID = 'orchestrator';
+
+/**
+ * Provides a collection of repository utilities that can be used by plugins
+ * to access shared resources like booth and tool registries.
+ */
+export declare type RepositoryUtilities = {
+    /** An instance of the BoothRegistry for managing booth configurations. */
+    boothRegistry: BoothRegistry;
+    /** An instance of the ToolRegistry for managing available tools. */
+    toolRegistry: ToolRegistry;
+    /** An instance of the BoothPluginRegistry for managing and coordinating plugins. */
+    pluginRegistry: BoothPluginRegistry;
+};
+
+export { ResponseCreateParamsNonStreaming }
+
+/**
+ * Represents the result of processing a single tool call.
+ */
+export declare type SingleToolProcessingResult = {
+    /**
+     * If set, indicates that the tool processing should exit early and return a specific value.
+     */
+    earlyExit?: {
+        returnValue: any;
+    };
+    /**
+     * An optional new message to be added to the chat history as a result of the tool execution.
+     */
+    newMessage?: ChatCompletionMessageParam;
+    /**
+     * A boolean indicating whether the tool was successfully executed.
+     */
+    toolExecuted: boolean;
+};
+
+/**
+ * Context information provided during tool call execution.
+ */
+export declare type ToolCallContext = {
+    /** The current response parameters being processed. */
+    responseParams: ResponseCreateParamsNonStreaming;
+    /** The response from the LLM that contained this tool call. */
+    response: Response_2;
+    /** Index of this tool call in the current batch of tool calls. */
+    toolCallIndex: number;
+    /** Total number of tool calls in the current batch. */
+    totalToolCalls: number;
+};
+
+/**
+ * The ToolExecutorPlugin checks LLM responses for tool call requests, executes the corresponding
+ * tools, and appends the results to the message history for the next interaction loop.
+ */
+export declare class ToolExecutorPlugin implements BoothPlugin {
+    id: string;
+    name: string;
+    description: string;
+    /**
+     * Executes a single tool call with proper hook integration.
+     * @param utilities - Repository utilities for accessing registries.
+     * @param toolCall - The tool call to execute.
+     * @param context - Context information about the tool call execution.
+     * @returns The function call output item for the response.
+     * @private
+     */
+    private executeToolCall;
+    /**
+     * After a response is received from the LLM, this hook checks for tool calls. If any are found,
+     * it executes them using the `toolRegistry` and appends their outputs to the response parameters'
+     * input history.
+     * @param utilities - The repository utilities containing available tools.
+     * @param responseParams - The parameters for the response creation.
+     * @param response - The response from the LLM.
+     * @returns The updated response parameters, potentially with tool call outputs added to the input.
+     */
+    onResponseReceived(utilities: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming, response: Response_2): Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Determines whether the interaction loop should end. This plugin always returns false,
+     * as tool execution is part of an ongoing conversation.
+     * @returns A boolean indicating that the loop should not end.
+     */
+    shouldEndInteractionLoop(): Promise<boolean>;
+}
+
+/**
+ * Represents a tool module, extending the OpenAI `FunctionTool` with an `execute` method.
+ * This allows for a consistent interface for executing tools.
+ */
+export declare type ToolModule = FunctionTool & {
+    /**
+     * The function to be executed when the tool is called.
+     * @param input - The input parameters for the tool, typically parsed from a JSON string.
+     * @returns A promise that resolves with the result of the tool's execution.
+     */
+    execute: (input: any) => Promise<any>;
+};
+
+/**
+ * Represents the result of processing a tool, including whether to return a value,
+ * the updated messages, and which tool was executed.
+ */
+export declare type ToolProcessingResult = {
+    /**
+     * If true, indicates that the interaction loop should terminate and return `returnValue`.
+     */
+    shouldReturn?: boolean;
+    /**
+     * The value to be returned if `shouldReturn` is true.
+     */
+    returnValue?: any;
+    /**
+     * A boolean indicating whether the tool was executed.
+     */
+    toolExecuted: boolean;
+    /**
+     * The list of chat messages updated after the tool execution.
+     */
+    updatedMessages: ChatCompletionMessageParam[];
+    /**
+     * The unique identifier of the tool that was executed.
+     */
+    toolId: string;
+};
+
+/**
+ * The ToolProviderPlugin collects tool definitions from the base and current context booths,
+ * ensuring that the LLM has access to the correct set of tools for the current interaction.
+ */
+export declare class ToolProviderPlugin implements BoothPlugin {
+    description: string;
+    id: string;
+    name: string;
+    /**
+     * Before a message is sent, this hook gathers the tool keys from both the base and context booths,
+     * retrieves the corresponding tool definitions from the `toolRegistry`, and adds them to the
+     * response parameters. It also checks for duplicate tool keys.
+     * @param prepareInitialMessagesArgs - Utilities for accessing booth and tool registries.
+     * @param responseParams - The parameters for the response creation.
+     * @returns The updated response parameters with the aggregated list of tools.
+     */
+    onBeforeMessageSend(prepareInitialMessagesArgs: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming): Promise<ResponseCreateParamsNonStreaming>;
+    /**
+     * Determines whether the interaction loop should end. This plugin always returns false,
+     * as providing tools is part of setting up the interaction, not concluding it.
+     * @returns A boolean indicating that the loop should not end.
+     */
+    shouldEndInteractionLoop(): Promise<boolean>;
+}
+
+/**
+ * The ToolRegistry manages the collection of OpenAI tools within the booth system.
+ *
+ * It provides methods for registering, retrieving, and managing
+ * tools that can be used by OpenAI's APIs during interactions.
+ *
+ * @example
+ * // Create an instance
+ * const toolRegistry = new ToolRegistry();
+ *
+ * // Register a tool
+ * toolRegistry.registerTool('calculator', calculatorTool);
+ */
+export declare class ToolRegistry {
+    private tools;
+    /**
+     * Initializes an empty Map to store tools.
+     */
+    constructor();
+    registerTools(tools: ToolModule[]): void;
+    /**
+     * Registers a single tool in the registry.
+     * Throws an error if a tool with the same ID already exists.
+     *
+     * @param tool - The OpenAI Tool instance to register
+     * @throws Error if a tool with the same ID is already registered
+     */
+    registerTool(tool: ToolModule): void;
+    /**
+     * Finds and returns a tool by its ID.
+     *
+     * @param toolName - The unique identifier of the tool to retrieve
+     * @returns The tool instance if found, undefined otherwise
+     */
+    getTool(toolName: string): ToolModule;
+    /**
+     * Returns all registered tools as an array.
+     *
+     * @returns Array of all registered Tool instances
+     */
+    getAllTools(): ToolModule[];
+    /**
+     * Removes a tool from the registry by its ID.
+     * Throws an error if the tool doesn't exist.
+     *
+     * @param toolName - The unique identifier of the tool to remove
+     * @throws Error if the tool with the specified ID does not exist
+     */
+    unregisterTool(toolName: string): void;
+}
+
+export { }