booths 1.3.1 → 1.4.1

package/dist/index.d.ts

@@ -120,9 +120,9 @@ export declare interface BoothPlugin {
      * @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.
+     * @returns The potentially modified tool call result, otherwise the original result.
      */
-    onAfterToolCall?: (utilities: RepositoryUtilities, toolCall: ResponseFunctionToolCall, result: unknown, context: ToolCallContext) => Promise<unknown>;
+    onAfterToolCall?: (utilities: RepositoryUtilities, toolCall: ResponseFunctionToolCall, result: unknown, context: ToolCallContext) => Promise<typeof result>;
     /**
      * Called when an individual tool call encounters an error during execution.
      * This allows for custom error handling or recovery.
@@ -150,15 +150,6 @@ export declare interface BoothPlugin {
      * @returns The potentially modified final response.
      */
     onAfterInteractionLoopEnd?: (interactionLoopEndArgs: RepositoryUtilities, response: Response_2) => Promise<Response_2>;
-    /**
-     * Called for each streaming event as it arrives during response generation.
-     * This is optional and only called when streaming is enabled.
-     * @param utilities - Utilities for accessing repositories.
-     * @param streamEvent - The streaming event that was received.
-     * @param context - Context information about the streaming session.
-     * @returns The potentially modified stream event, or void to pass through unchanged.
-     */
-    onStreamEvent?: (utilities: RepositoryUtilities, streamEvent: StreamEvent, context: StreamContext) => Promise<StreamEvent | void>;
 }
 
 /**
@@ -302,17 +293,6 @@ export declare class BoothPluginRegistry {
      * @returns Error result or recovery value after all plugins have processed it
      */
     runToolCallError(utilities: RepositoryUtilities, toolCall: ResponseFunctionToolCall, error: Error, context: ToolCallContext): Promise<any>;
-    /**
-     * Sequentially invokes every plugin's onStreamEvent hook.
-     * This is called for each streaming event during response generation,
-     * allowing plugins to process or modify stream events in real-time.
-     *
-     * @param utilities - Context information including booth and tool registries
-     * @param streamEvent - The streaming event that was received
-     * @param context - Context information about the streaming session
-     * @returns Modified stream event after all plugins have processed it
-     */
-    runStreamEvent(utilities: RepositoryUtilities, streamEvent: StreamEvent, context: StreamContext): Promise<StreamEvent>;
 }
 
 /**
@@ -428,6 +408,13 @@ export declare class BoothRegistry {
      * @returns Record of all booth configurations indexed by their IDs
      */
     getAllBooths(): Record<string, BoothConfig>;
+    /**
+     * Returns only booths that should be available for routing (excludes core and orchestrator booths).
+     * This prevents double context issues by ensuring system booths are not selectable.
+     *
+     * @returns Record of selectable booth configurations indexed by their IDs
+     */
+    getSelectableBooths(): Record<string, BoothConfig>;
     toArray(): BoothConfig[];
     /**
      * Enables multi-booth mode by registering the orchestrator and setting it as current context.
@@ -695,6 +682,7 @@ export declare class CoreBooth<T> {
         tools?: ToolRegistry;
         llmAdapter: LLMAdapter<T>;
         sessionHistory?: ResponseInput;
+        endInteractionLoopMarker?: string;
     });
 }
 
@@ -724,12 +712,14 @@ export declare function createRouteToBoothTool(boothRegistry: BoothRegistry): To
  * in the LLM's response. It also cleans up this marker before the final output is returned.
  */
 export declare class FinishTurnPlugin implements BoothPlugin {
+    private marker;
     description: string;
     id: string;
     name: string;
+    constructor(marker?: 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.
+     * specific marker 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.
@@ -759,7 +749,7 @@ export declare class FinishTurnPlugin implements BoothPlugin {
     }>;
     /**
      * 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.
+     * 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.
@@ -767,7 +757,7 @@ export declare class FinishTurnPlugin implements BoothPlugin {
      */
     shouldEndInteractionLoop(_: RepositoryUtilities, __: ResponseCreateParamsNonStreaming, response: Response_2): Promise<boolean>;
     /**
-     * After the interaction loop ends, this hook removes the `__awaiting_user_response__` marker
+     * After the interaction loop ends, this hook removes the `marker` marker
      * from the final response before it is returned.
      * @param _ - Unused repository utilities.
      * @param response - The final response from the LLM.
@@ -777,30 +767,19 @@ export declare class FinishTurnPlugin implements BoothPlugin {
 }
 
 /**
- * The InteractionProcessor class orchestrates the conversation with the LLM,
- * managing the interaction loop, plugin execution, and message passing.
+ * A class responsible for processing interactions with a language learning model (LLM)
+ * by delegating tasks to a plugin-enabled architecture.
+ * This class manages the process of sending messages to an LLM,
+ * invoking plugins, handling errors, and iterating through responses.
+ *
+ * @template T The type used in the LLMAdapter for communicating with the LLM.
  */
 export declare class InteractionProcessor<T> {
     private boothRegistry;
     private boothPlugins;
     private toolRegistry;
     private llmAdapter;
-    /**
-     * Generates a consistent ID for responses and messages.
-     * @param prefix - The prefix for the ID (e.g., 'stream', 'error', 'msg')
-     * @returns A unique ID string
-     * @private
-     */
-    private generateId;
-    /**
-     * Creates a standardized message object for responses.
-     * @param text - The text content for the message
-     * @returns A formatted message object
-     * @private
-     */
-    private createMessage;
     private loopLimit;
-    private options;
     /**
      * Creates a synthetic error response with proper structure and error details.
      * @param error - The error that occurred
@@ -810,64 +789,13 @@ export declare class InteractionProcessor<T> {
      */
     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
+     * Calls the LLM adapter to invoke and interpret the response for the given parameters.
+     *
+     * @param {ResponseCreateParamsNonStreaming} responseCreateParams - The parameters for creating the response.
+     * @param {RepositoryUtilities} prepareInitialMessagesArgs - The arguments required to prepare initial messages.
+     * @return {Promise<Response>} A promise that resolves to the interpreted response or an error response in case of failure.
      */
     private callLLM;
-    /**
-     * Calls the LLM in non-streaming mode.
-     * @param responseCreateParams - The parameters for creating the response.
-     * @returns A promise that resolves with the LLM's response.
-     * @private
-     */
-    private callLLMNonStreaming;
-    /**
-     * Calls the LLM in streaming mode, accumulating stream events into a complete response.
-     * @param responseCreateParams - The parameters for creating the response.
-     * @returns A promise that resolves with the accumulated response.
-     * @private
-     */
-    private callLLMStreaming;
-    /**
-     * Type guard to check if an output item has a function property (tool call).
-     * @param output - The output item to check
-     * @returns True if the output item is a tool call with a function
-     * @private
-     */
-    private isToolCall;
-    /**
-     * Helper function to safely update tool call arguments.
-     * @param accumulated - The accumulated response
-     * @param callId - The tool call ID to update
-     * @param delta - The argument delta to append
-     * @private
-     */
-    private updateToolCallArguments;
-    /**
-     * Helper function to safely update a tool call with final data.
-     * @param accumulated - The accumulated response
-     * @param toolCallData - The final tool call data
-     * @private
-     */
-    private updateToolCallFunction;
-    /**
-     * Merges a stream event into the accumulated response.
-     * @param accumulated - The current accumulated response.
-     * @param streamEvent - The stream event to merge.
-     * @returns The updated accumulated response.
-     * @private
-     */
-    private mergeStreamEvent;
-    /**
-     * Creates a complete Response object from accumulated stream data.
-     * @param accumulated - The accumulated response data.
-     * @param originalParams - The original request parameters.
-     * @returns A complete Response object.
-     * @private
-     */
-    private finalizeAccumulatedResponse;
     /**
      * Runs the main interaction loop, sending messages to the LLM and processing
      * the responses through the registered plugins.
@@ -882,9 +810,8 @@ export declare class InteractionProcessor<T> {
      * @param boothPlugins - The registry for booth plugins.
      * @param toolRegistry - The registry for available tools.
      * @param llmAdapter - The adapter for interacting with the LLM.
-     * @param options - Configuration options for streaming and other behaviors.
      */
-    constructor(boothRegistry: BoothRegistry, boothPlugins: BoothPluginRegistry, toolRegistry: ToolRegistry, llmAdapter: LLMAdapter<T>, options?: InteractionProcessorOptions);
+    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.
@@ -895,22 +822,14 @@ export declare class InteractionProcessor<T> {
 }
 
 /**
- * Configuration options for the InteractionProcessor.
+ * Interface representing a Large Language Model (LLM) Adapter that provides methods
+ * to interact with and interpret responses from an LLM.
+ *
+ * @template LLMResponse The type of the raw response returned by the LLM. Defaults to `any`.
  */
-export declare interface InteractionProcessorOptions {
-    /** Enable streaming mode for LLM responses */
-    streaming?: boolean;
-    /** Fallback to non-streaming if streaming fails */
-    fallbackToNonStreaming?: boolean;
-}
-
 export declare interface LLMAdapter<LLMResponse = any> {
-    invoke: (responseParams: ResponseCreateParamsNonStreaming) => Promise<LLMResponse>;
+    invoke: (responseParams: ResponseCreateParamsNonStreaming, prepareInitialMessagesArgs: RepositoryUtilities) => Promise<LLMResponse>;
     interpret: (response: LLMResponse) => Promise<Response_2>;
-    /** Optional method for streaming LLM responses */
-    invokeStream?: (responseParams: ResponseCreateParamsStreaming) => AsyncIterable<LLMResponse>;
-    /** Optional method for interpreting individual stream chunks into StreamEvents */
-    interpretStream?: (streamChunk: LLMResponse) => Promise<StreamEvent>;
 }
 
 /**
@@ -934,24 +853,8 @@ export declare type RepositoryUtilities = {
     llmAdapter: LLMAdapter<unknown>;
 };
 
-export { Response_2 as Response }
-
 export { ResponseCreateParamsNonStreaming }
 
-/**
- * Response parameters for streaming requests.
- * This creates a new type that has all the properties of ResponseCreateParamsNonStreaming
- * but with stream: true instead of stream: false.
- */
-export declare type ResponseCreateParamsStreaming = Omit<ResponseCreateParamsNonStreaming, 'stream'> & {
-    /** Must be true for streaming requests */
-    stream: true;
-};
-
-export { ResponseInput }
-
-export { ResponseInputItem }
-
 /**
  * Represents the result of processing a single tool call.
  */
@@ -972,93 +875,6 @@ export declare type SingleToolProcessingResult = {
     toolExecuted: boolean;
 };
 
-/**
- * Context information provided during streaming event processing.
- */
-export declare interface StreamContext {
-    /** The current response parameters being processed */
-    responseParams: ResponseCreateParamsNonStreaming;
-    /** Index of this stream event in the sequence */
-    streamIndex: number;
-    /** Total expected number of events (if known) */
-    totalExpectedEvents?: number;
-    /** Accumulated response content so far */
-    accumulatedResponse: Partial<Response_2>;
-}
-
-/**
- * Represents a streaming event emitted during LLM response generation.
- */
-export declare interface StreamEvent {
-    /** Type of stream event */
-    type: 'text_delta' | 'tool_call_start' | 'tool_call_end' | 'response_start' | 'response_end';
-    /** Text content for text_delta events */
-    content?: string;
-    /** Incremental text delta for text_delta events */
-    delta?: string;
-    /** Tool call information for tool-related events */
-    toolCall?: ResponseFunctionToolCall;
-    /** Additional metadata for the event */
-    metadata?: Record<string, unknown>;
-}
-
-/**
- * Callback function type for handling stream events in the UI.
- */
-export declare type StreamEventCallback = (event: StreamEvent, context: StreamContext) => void;
-
-/**
- * Example streaming plugin that logs stream events in real-time.
- * This demonstrates how to implement streaming hooks in plugins.
- */
-export declare class StreamingLoggerPlugin implements BoothPlugin {
-    readonly id = "streaming-logger";
-    readonly name = "Streaming Logger Plugin";
-    readonly description = "Logs streaming events in real-time for debugging and monitoring";
-    private logPrefix;
-    constructor(logPrefix?: string);
-    /**
-     * Handle individual stream events as they arrive.
-     * This allows for real-time processing and logging of streaming content.
-     */
-    onStreamEvent(_utilities: RepositoryUtilities, streamEvent: StreamEvent, context: StreamContext): Promise<StreamEvent>;
-    /**
-     * Required method - determines whether to end the interaction loop.
-     * For a logging plugin, we never want to end the loop ourselves.
-     */
-    shouldEndInteractionLoop(): Promise<boolean>;
-}
-
-/**
- * Example streaming plugin that provides real-time UI updates.
- * This plugin demonstrates how to emit stream events to the UI layer.
- */
-export declare class StreamingUIPlugin implements BoothPlugin {
-    readonly id = "streaming-ui";
-    readonly name = "Streaming UI Plugin";
-    readonly description = "Provides real-time UI updates during streaming responses";
-    private onStreamCallback?;
-    constructor(onStreamCallback?: StreamEventCallback);
-    /**
-     * Handle individual stream events and emit them to the UI layer.
-     * This enables real-time updates to the user interface.
-     */
-    onStreamEvent(_utilities: RepositoryUtilities, streamEvent: StreamEvent, context: StreamContext): Promise<StreamEvent>;
-    /**
-     * Set or update the stream callback for UI updates.
-     */
-    setStreamCallback(callback: StreamEventCallback): void;
-    /**
-     * Remove the stream callback.
-     */
-    removeStreamCallback(): void;
-    /**
-     * Required method - determines whether to end the interaction loop.
-     * For a UI plugin, we never want to end the loop ourselves.
-     */
-    shouldEndInteractionLoop(): Promise<boolean>;
-}
-
 /**
  * Context information provided during tool call execution.
  */
@@ -1090,6 +906,12 @@ export declare class ToolExecutorPlugin implements BoothPlugin {
      * @private
      */
     private executeToolCall;
+    /**
+     * Extracts function call objects from an array of response output items.
+     *
+     * @param {ResponseOutputItem[]} output - The array of response output items to filter.
+     * @return {ResponseFunctionToolCall[]} An array containing only the function call objects from the input.
+     */
     static extractFunctionCalls(output: ResponseOutputItem[]): ResponseFunctionToolCall[];
     /**
      * After a response is received from the LLM, this hook checks for tool calls. If any are found,