booths 1.1.0 → 1.3.0

package/README.md

@@ -42,7 +42,7 @@ graph TD
 1.  **Application Layer**: Your application integrates the Booths framework to handle conversational AI interactions.
 2.  **`CoreBooth`**: The framework foundation that provides global functionality, instructions, and infrastructure that applies to all booths. It manages the overall system configuration and coordinates the interaction flow.
 3.  **`InteractionProcessor`**: The engine that drives the conversation. It takes user input, runs it through the plugin lifecycle, sends it to the LLM (via the adapter), and processes the response.
-4.  **`LLMAdapter`**: A component that handles communication with the specific LLM provider (e.g., OpenAI). It translates requests and responses between the Booths system and the LLM's API.
+4.  **`LLMAdapter`**: A component that handles communication with the specific LLM provider (e.g., OpenAI). It translates requests and responses between the Booths system and the LLM's API. Supports both traditional and streaming response modes.
 5.  **Registries**: These are responsible for managing the different components of the system:
     *   `BoothRegistry`: Manages `BoothConfig` objects that define the behavior of different AI agents.
     *   `ToolRegistry`: Manages the tools (functions) that booths can use.
@@ -124,7 +124,13 @@ The `CoreBooth` requires an `LLMAdapter` to communicate with your chosen languag
 
 ```typescript
 // in OpenAIAdapter.ts
-import type { LLMAdapter, ResponseCreateParamsNonStreaming, Response } from 'booths';
+import type { 
+  LLMAdapter, 
+  ResponseCreateParamsNonStreaming, 
+  ResponseCreateParamsStreaming,
+  Response,
+  StreamEvent
+} from 'booths';
 import OpenAI from 'openai';
 
 export class OpenAIAdapter implements LLMAdapter<Response> {
@@ -141,6 +147,24 @@ export class OpenAIAdapter implements LLMAdapter<Response> {
   async interpret(response: Response): Promise<Response> {
     return response;
   }
+
+  // Optional: Add streaming support
+  async *invokeStream(params: ResponseCreateParamsStreaming): AsyncIterable<Response> {
+    const stream = this.openai.responses.create({ ...params, model: 'gpt-4o', stream: true });
+    for await (const chunk of stream) {
+      yield chunk;
+    }
+  }
+
+  async interpretStream(chunk: Response): Promise<StreamEvent> {
+    // Convert OpenAI stream chunks to StreamEvents
+    // Implementation depends on your streaming format
+    return {
+      type: 'text_delta',
+      delta: chunk.choices?.[0]?.delta?.content || '',
+      content: chunk.choices?.[0]?.delta?.content || ''
+    };
+  }
 }
 ```
 
@@ -195,6 +219,7 @@ Plugins are classes that implement the `BoothPlugin` interface. They can execute
 - `onBeforeToolCall`: Before each individual tool call is executed _(allows modification of tool parameters, validation, and logging)_.
 - `onAfterToolCall`: After each individual tool call is successfully executed _(allows result processing, caching, and transformation)_.
 - `onToolCallError`: When a tool call encounters an error _(allows custom error handling and recovery)_.
+- `onStreamEvent`: _(Optional)_ During streaming response generation, called for each stream event _(enables real-time processing and UI updates)_.
 - `shouldEndInteractionLoop`: To determine if the conversation turn is over.
 - `onAfterInteractionLoopEnd`: After the main loop has finished.
 
@@ -227,3 +252,245 @@ The `InteractionProcessor` is the engine of the system. It manages the interacti
 5. Runs the `onResponseReceived` plugin hooks to process the response (e.g., execute tools).
 6. Repeats this loop until a plugin's `shouldEndInteractionLoop` returns `true`.
 7. Runs the `onAfter...` plugin hooks for cleanup.
+
+## Streaming Support
+
+The Booths framework includes comprehensive streaming support that enables real-time response generation while preserving the full plugin ecosystem and backward compatibility.
+
+### Overview
+
+Streaming allows the LLM's response to be processed and displayed in real-time as it's being generated, providing a more responsive user experience. The framework handles streaming at multiple levels:
+
+- **Real-time Events**: Stream events are emitted as content arrives
+- **Plugin Integration**: Plugins can hook into streaming events for real-time processing
+- **Complete Responses**: Existing plugins continue to receive complete responses
+- **Automatic Fallback**: Graceful fallback to non-streaming if streaming fails
+
+### Enabling Streaming
+
+Streaming can be enabled simply by setting a boolean flag when creating the `InteractionProcessor`:
+
+```typescript
+import { InteractionProcessor, type InteractionProcessorOptions } from 'booths';
+
+const options: InteractionProcessorOptions = {
+  streaming: true,                    // Enable streaming
+  fallbackToNonStreaming: true       // Optional: fallback if streaming fails
+};
+
+const processor = new InteractionProcessor(
+  boothRegistry,
+  pluginRegistry, 
+  toolRegistry,
+  llmAdapter,      // Must implement streaming methods
+  options
+);
+```
+
+### Stream Events
+
+The streaming system emits different types of events as the response is generated:
+
+```typescript
+export interface StreamEvent {
+  type: 'text_delta' | 'tool_call_start' | 'tool_call_end' | 'response_start' | 'response_end';
+  content?: string;      // Full content for text events
+  delta?: string;        // Incremental text for text_delta events  
+  toolCall?: object;     // Tool call information
+  metadata?: any;        // Additional event metadata
+}
+```
+
+**Event Types:**
+- `response_start`: Streaming begins
+- `text_delta`: Incremental text content arrives
+- `tool_call_start`: LLM begins a tool call
+- `tool_call_end`: Tool call completes
+- `response_end`: Streaming completes
+
+### Streaming Plugin Hooks
+
+Plugins can implement the optional `onStreamEvent` hook to process stream events in real-time:
+
+```typescript
+import type { BoothPlugin, StreamEvent, StreamContext, RepositoryUtilities } from 'booths';
+
+export class MyStreamingPlugin implements BoothPlugin {
+  id = 'my-streaming-plugin';
+  name = 'My Streaming Plugin';
+  description = 'Handles streaming events';
+
+  async onStreamEvent(
+    utilities: RepositoryUtilities,
+    streamEvent: StreamEvent,
+    context: StreamContext
+  ): Promise<StreamEvent> {
+    // Process the stream event
+    if (streamEvent.type === 'text_delta') {
+      console.log(`Received text: ${streamEvent.delta}`);
+      
+      // Optionally transform the event
+      return {
+        ...streamEvent,
+        delta: streamEvent.delta?.toUpperCase()  // Example transformation
+      };
+    }
+    
+    return streamEvent;  // Pass through unchanged
+  }
+
+  async shouldEndInteractionLoop(): Promise<boolean> {
+    return false;
+  }
+}
+```
+
+### Built-in Streaming Plugins
+
+The framework includes example streaming plugins:
+
+#### StreamingLoggerPlugin
+
+Logs streaming events in real-time for debugging and monitoring:
+
+```typescript
+import { StreamingLoggerPlugin } from 'booths';
+
+const logger = new StreamingLoggerPlugin('[MyApp]');
+pluginRegistry.registerPlugins([logger]);
+```
+
+#### StreamingUIPlugin  
+
+Provides real-time UI updates with customizable callbacks:
+
+```typescript
+import { StreamingUIPlugin } from 'booths';
+
+const uiPlugin = new StreamingUIPlugin((event, context) => {
+  if (event.type === 'text_delta') {
+    // Update your UI with the new text
+    document.getElementById('response').textContent += event.delta;
+  }
+});
+
+pluginRegistry.registerPlugins([uiPlugin]);
+```
+
+### LLM Adapter Streaming Implementation
+
+To support streaming, your LLM adapter should implement the optional streaming methods:
+
+```typescript
+export class MyStreamingAdapter implements LLMAdapter<MyResponse> {
+  // Required methods
+  async invoke(params: ResponseCreateParamsNonStreaming): Promise<MyResponse> {
+    // Non-streaming implementation
+  }
+
+  async interpret(response: MyResponse): Promise<Response> {
+    // Convert to standard format
+  }
+
+  // Optional streaming methods
+  async *invokeStream(params: ResponseCreateParamsStreaming): AsyncIterable<MyResponse> {
+    // Yield streaming chunks
+    const stream = await this.llm.createStreamingResponse(params);
+    for await (const chunk of stream) {
+      yield chunk;
+    }
+  }
+
+  async interpretStream(chunk: MyResponse): Promise<StreamEvent> {
+    // Convert chunk to StreamEvent
+    return {
+      type: 'text_delta',
+      delta: chunk.delta,
+      content: chunk.content
+    };
+  }
+}
+```
+
+### Stream Context
+
+Plugins receive context information about the streaming session:
+
+```typescript
+export interface StreamContext {
+  responseParams: ResponseCreateParamsNonStreaming;  // Original request
+  streamIndex: number;                               // Event index in stream  
+  totalExpectedEvents?: number;                      // Expected total (if known)
+  accumulatedResponse: Partial<Response>;            // Response built so far
+}
+```
+
+### Error Handling
+
+The streaming system includes robust error handling:
+
+- **Plugin Error Isolation**: Errors in streaming plugins don't break the stream
+- **Automatic Fallback**: Can fallback to non-streaming mode on errors
+- **Graceful Degradation**: System continues operating if streaming fails
+
+### Backward Compatibility
+
+Streaming support is fully backward compatible:
+
+- **Existing Plugins**: Continue to work unchanged
+- **Complete Responses**: Plugins still receive full `Response` objects  
+- **Optional Implementation**: Adapters don't require streaming support
+- **Default Behavior**: Non-streaming mode by default
+
+### Example: Complete Streaming Setup
+
+Here's a complete example showing streaming integration:
+
+```typescript
+import { 
+  InteractionProcessor,
+  BoothRegistry,
+  BoothPluginRegistry,
+  ToolRegistry,
+  StreamingLoggerPlugin, 
+  StreamingUIPlugin,
+  type InteractionProcessorOptions 
+} from 'booths';
+
+// 1. Create streaming-enabled adapter (implement streaming methods)
+const streamingAdapter = new MyStreamingLLMAdapter(apiKey);
+
+// 2. Set up registries and booth
+const testBooth = { id: 'chat-booth', role: 'Assistant', description: 'Helpful assistant' };
+const boothRegistry = new BoothRegistry(testBooth);
+const pluginRegistry = new BoothPluginRegistry();
+const toolRegistry = new ToolRegistry();
+
+// 3. Set up streaming plugins
+const logger = new StreamingLoggerPlugin('[Chat]');
+const uiUpdater = new StreamingUIPlugin((event) => {
+  if (event.type === 'text_delta') {
+    document.getElementById('chat').textContent += event.delta;
+  }
+});
+
+pluginRegistry.registerPlugins([logger, uiUpdater]);
+
+// 4. Enable streaming
+const streamingOptions: InteractionProcessorOptions = {
+  streaming: true,
+  fallbackToNonStreaming: true
+};
+
+const processor = new InteractionProcessor(
+  boothRegistry,
+  pluginRegistry, 
+  toolRegistry,
+  streamingAdapter,
+  streamingOptions
+);
+
+// 5. Send message with real-time streaming
+const response = await processor.send('Hello, stream this response!');
+// User sees content appear in real-time, plugins receive complete response
+```

package/dist/index.d.ts

@@ -150,6 +150,15 @@ 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>;
 }
 
 /**
@@ -191,6 +200,15 @@ export declare class BoothPluginRegistry {
      * @returns The plugin instance if found, undefined otherwise
      */
     getPluginById(pluginId: string): BoothPlugin | undefined;
+    /**
+     * Finds and returns multiple plugins by their IDs.
+     * Throws an error if any plugin ID is not found.
+     *
+     * @param pluginIds - Array of unique identifiers of the plugins to retrieve
+     * @returns Array of plugin instances
+     * @throws Error if any plugin ID is not registered
+     */
+    getPluginsByIds(pluginIds: string[]): BoothPlugin[];
     /**
      * Removes a plugin from the registry by its ID.
      * Throws an error if the plugin doesn't exist.
@@ -284,6 +302,17 @@ 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>;
 }
 
 /**
@@ -384,6 +413,15 @@ export declare class BoothRegistry {
      * @returns The booth configuration if found, undefined otherwise
      */
     getBoothById(boothId: string): BoothConfig | undefined;
+    /**
+     * Finds and returns multiple booth configurations by their IDs.
+     * Throws an error if any booth ID is not found.
+     *
+     * @param boothIds - Array of unique identifiers of the booths to retrieve
+     * @returns Array of booth configurations
+     * @throws Error if any booth ID is not registered
+     */
+    getBoothsByIds(boothIds: string[]): BoothConfig[];
     /**
      * Returns all registered booth configurations.
      *
@@ -747,7 +785,22 @@ export declare class InteractionProcessor<T> {
     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
@@ -763,6 +816,36 @@ export declare class InteractionProcessor<T> {
      * @private
      */
     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;
+    /**
+     * 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.
@@ -777,8 +860,9 @@ 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>);
+    constructor(boothRegistry: BoothRegistry, boothPlugins: BoothPluginRegistry, toolRegistry: ToolRegistry, llmAdapter: LLMAdapter<T>, options?: InteractionProcessorOptions);
     /**
      * 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.
@@ -788,9 +872,23 @@ export declare class InteractionProcessor<T> {
     send(input: string | ResponseInput): Promise<Response_2>;
 }
 
+/**
+ * Configuration options for the InteractionProcessor.
+ */
+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>;
     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>;
 }
 
 /**
@@ -814,8 +912,24 @@ 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.
  */
@@ -836,6 +950,93 @@ 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.
  */
@@ -986,6 +1187,15 @@ export declare class ToolRegistry {
      * @returns The tool instance if found, undefined otherwise
      */
     getTool(toolName: string): ToolModule;
+    /**
+     * Finds and returns multiple tools by their names.
+     * Throws an error if any tool name is not found (via getTool method).
+     *
+     * @param toolNames - Array of unique names of the tools to retrieve
+     * @returns Array of tool instances
+     * @throws Error if any tool name is not registered
+     */
+    getToolsByNames(toolNames: string[]): ToolModule[];
     getGlobalTools(): ToolModule[];
     /**
      * Returns all registered tools as an array.

package/dist/index.js

@@ -1,3 +1,4 @@
+import { randomUUID as R } from "crypto";
 class p {
   /**
    * Collection of registered plugins.
@@ -41,6 +42,24 @@ class p {
   getPluginById(t) {
     return this.plugins.find((o) => o.id === t);
   }
+  /**
+   * Finds and returns multiple plugins by their IDs.
+   * Throws an error if any plugin ID is not found.
+   *
+   * @param pluginIds - Array of unique identifiers of the plugins to retrieve
+   * @returns Array of plugin instances
+   * @throws Error if any plugin ID is not registered
+   */
+  getPluginsByIds(t) {
+    const o = [];
+    for (const e of t) {
+      const r = this.getPluginById(e);
+      if (!r)
+        throw new Error(`Plugin with ID ${e} is not registered.`);
+      o.push(r);
+    }
+    return o;
+  }
   /**
    * Removes a plugin from the registry by its ID.
    * Throws an error if the plugin doesn't exist.
@@ -162,8 +181,8 @@ class p {
    */
   async runAfterToolCall(t, o, e, r) {
     let s = e;
-    for (const l of this.plugins)
-      l.onAfterToolCall && (s = await l.onAfterToolCall(t, o, s, r));
+    for (const i of this.plugins)
+      i.onAfterToolCall && (s = await i.onAfterToolCall(t, o, s, r));
     return s;
   }
   /**
@@ -179,10 +198,32 @@ class p {
    */
   async runToolCallError(t, o, e, r) {
     let s = `Error: ${e.message}`;
-    for (const l of this.plugins)
-      l.onToolCallError && (s = await l.onToolCallError(t, o, e, r));
+    for (const i of this.plugins)
+      i.onToolCallError && (s = await i.onToolCallError(t, o, e, r));
     return s;
   }
+  /**
+   * 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
+   */
+  async runStreamEvent(t, o, e) {
+    let r = o;
+    for (const s of this.plugins)
+      if (s.onStreamEvent)
+        try {
+          const i = await s.onStreamEvent(t, r, e);
+          i && (r = i);
+        } catch (i) {
+          console.error(`Error in plugin ${s.id} during stream event processing:`, i);
+        }
+    return r;
+  }
 }
 const u = {
   id: "orchestrator",
@@ -219,7 +260,7 @@ const u = {
     - User: "I need help" → "What specifically would you like help with?" → then route based on response
   `
 };
-class R {
+class B {
   /**
    * Creates a new booth registry with a specified base booth configuration.
    *
@@ -340,6 +381,24 @@ class R {
   getBoothById(t) {
     return this.booths[t];
   }
+  /**
+   * Finds and returns multiple booth configurations by their IDs.
+   * Throws an error if any booth ID is not found.
+   *
+   * @param boothIds - Array of unique identifiers of the booths to retrieve
+   * @returns Array of booth configurations
+   * @throws Error if any booth ID is not registered
+   */
+  getBoothsByIds(t) {
+    const o = [];
+    for (const e of t) {
+      const r = this.getBoothById(e);
+      if (!r)
+        throw new Error(`Booth with ID ${e} is not registered.`);
+      o.push(r);
+    }
+    return o;
+  }
   /**
    * Returns all registered booth configurations.
    *
@@ -398,18 +457,54 @@ class R {
     ).length <= 1 && this.hasOrchestrator && this.disableMultiBoothMode();
   }
 }
-class B {
+class T {
   /**
    * 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 llmAdapter - The adapter for interacting with the LLM.
+   * @param options - Configuration options for streaming and other behaviors.
    */
-  constructor(t, o, e, r) {
-    this.boothRegistry = t, this.boothPlugins = o, this.toolRegistry = e, this.llmAdapter = r;
+  constructor(t, o, e, r, s) {
+    this.boothRegistry = t, this.boothPlugins = o, this.toolRegistry = e, this.llmAdapter = r, this.options = {
+      streaming: !1,
+      fallbackToNonStreaming: !0,
+      ...s
+    };
+  }
+  /**
+   * 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
+   */
+  generateId(t) {
+    return `${t}_${Date.now()}_${R()}`;
+  }
+  /**
+   * Creates a standardized message object for responses.
+   * @param text - The text content for the message
+   * @returns A formatted message object
+   * @private
+   */
+  createMessage(t) {
+    return {
+      id: this.generateId("msg"),
+      content: [
+        {
+          type: "output_text",
+          text: t,
+          annotations: []
+        }
+      ],
+      role: "assistant",
+      status: "completed",
+      type: "message"
+    };
   }
   loopLimit = 10;
+  options;
   /**
    * Creates a synthetic error response with proper structure and error details.
    * @param error - The error that occurred
@@ -425,7 +520,7 @@ class B {
     if (r && (s.code = r), o.model === void 0)
       throw new Error("Model must be specified in response parameters for error handling.");
     return {
-      id: `error_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+      id: this.generateId("error"),
       created_at: Math.floor(Date.now() / 1e3),
       output_text: "An error occurred while communicating with the language model.",
       error: s,
@@ -435,19 +530,7 @@ class B {
       model: o.model,
       object: "response",
       output: [
-        {
-          id: `msg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
-          content: [
-            {
-              type: "output_text",
-              text: `Error: ${e}. Please try again or contact support if the issue persists.`,
-              annotations: []
-            }
-          ],
-          role: "assistant",
-          status: "completed",
-          type: "message"
-        }
+        this.createMessage(`Error: ${e}. Please try again or contact support if the issue persists.`)
       ],
       parallel_tool_calls: o.parallel_tool_calls || !1,
       temperature: o.temperature || null,
@@ -464,6 +547,21 @@ class B {
    * @private
    */
   async callLLM(t) {
+    if (this.options.streaming && this.llmAdapter.invokeStream && this.llmAdapter.interpretStream)
+      try {
+        return await this.callLLMStreaming(t);
+      } catch (o) {
+        return console.error("Error calling LLM with streaming:", o), this.options.fallbackToNonStreaming ? (console.warn("Falling back to non-streaming mode"), await this.callLLMNonStreaming(t)) : this.createErrorResponse(o, t);
+      }
+    return await this.callLLMNonStreaming(t);
+  }
+  /**
+   * 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
+   */
+  async callLLMNonStreaming(t) {
     try {
       const o = await this.llmAdapter.invoke(t);
       return await this.llmAdapter.interpret(o);
@@ -471,6 +569,91 @@ class B {
       return console.error("Error calling LLM:", o), this.createErrorResponse(o, t);
     }
   }
+  /**
+   * 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
+   */
+  async callLLMStreaming(t) {
+    if (!this.llmAdapter.invokeStream || !this.llmAdapter.interpretStream)
+      throw new Error("Adapter does not support streaming");
+    const o = {
+      ...t,
+      stream: !0
+    }, e = this.llmAdapter.invokeStream(o);
+    let r = {
+      output: [],
+      output_text: ""
+    }, s = 0;
+    for await (const i of e) {
+      const l = await this.llmAdapter.interpretStream(i), h = {
+        responseParams: t,
+        streamIndex: s,
+        accumulatedResponse: r
+      }, a = await this.boothPlugins.runStreamEvent(
+        {
+          toolRegistry: this.toolRegistry,
+          boothRegistry: this.boothRegistry,
+          pluginRegistry: this.boothPlugins,
+          llmAdapter: this.llmAdapter
+        },
+        l,
+        h
+      );
+      r = this.mergeStreamEvent(r, a), s++;
+    }
+    return this.finalizeAccumulatedResponse(r, t);
+  }
+  /**
+   * 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
+   */
+  mergeStreamEvent(t, o) {
+    if (!o || !o.type)
+      return t;
+    switch (o.type) {
+      case "text_delta":
+        o.delta && (t.output_text = (t.output_text || "") + o.delta);
+        break;
+      case "tool_call_start":
+        o.toolCall && (t.output = t.output || [], t.output.push(o.toolCall));
+        break;
+    }
+    return t;
+  }
+  /**
+   * 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
+   */
+  finalizeAccumulatedResponse(t, o) {
+    return {
+      id: this.generateId("stream"),
+      created_at: Math.floor(Date.now() / 1e3),
+      output_text: t.output_text || "",
+      error: null,
+      incomplete_details: null,
+      instructions: null,
+      metadata: null,
+      model: o.model || "unknown",
+      object: "response",
+      output: t.output || [
+        this.createMessage(t.output_text || "")
+      ],
+      parallel_tool_calls: o.parallel_tool_calls || !1,
+      temperature: o.temperature || null,
+      tool_choice: o.tool_choice || "auto",
+      tools: o.tools || [],
+      top_p: o.top_p || null,
+      status: "completed"
+    };
+  }
   /**
    * Runs the main interaction loop, sending messages to the LLM and processing
    * the responses through the registered plugins.
@@ -552,7 +735,7 @@ class B {
     ), r;
   }
 }
-const T = {
+const I = {
   id: "summarizer",
   role: 'You are a highly skilled summarization AI. Your task is to read a conversation history and provide a concise, neutral, and objective summary. The summary should capture the key points, decisions made, and any unresolved questions. It must be written from a third-person perspective and should be clear enough for another AI assistant to understand the full context and continue the conversation seamlessly without needing the original transcript. Do not add any conversational fluff or introductory phrases like "Here is the summary:".',
   description: "A specialized booth for summarizing conversation histories."
@@ -608,7 +791,7 @@ ${o}
     }
   };
 }
-class v {
+class x {
   /**
    * The sessionHistory variable stores the conversation history between the user and the booth system.
    * It is initialized as an empty array and will be populated with messages exchanged during the interaction.
@@ -704,13 +887,13 @@ class v {
   async onResponseReceived(t, o, e) {
     let s = [...o.input, ...e?.output ?? []];
     if (this.responseContainsBoothChange(e)) {
-      const i = `Please summarize the following conversation history:
+      const l = `Please summarize the following conversation history:
 
-${JSON.stringify(this.sessionHistory)}`, d = (await A(t.llmAdapter, T).callProcessor.send(i)).output_text, g = s.filter((h) => "role" in h && h.role === "user").pop(), b = {
+${JSON.stringify(this.sessionHistory)}`, g = (await M(t.llmAdapter, I).callProcessor.send(l)).output_text, d = s.filter((c) => "role" in c && c.role === "user").pop(), b = {
         role: "developer",
-        content: `A conversation summary up to this point: ${d}`
-      }, _ = s.filter((h) => !("role" in h && h.role === "user" || "type" in h && h.type === "message"));
-      this.sessionHistory = g ? [..._, b, g] : [..._, b], s = this.sessionHistory;
+        content: `A conversation summary up to this point: ${g}`
+      }, _ = s.filter((c) => !("role" in c && c.role === "user" || "type" in c && c.type === "message"));
+      this.sessionHistory = d ? [..._, b, d] : [..._, b], s = this.sessionHistory;
     } else
       this.sessionHistory = s;
     return {
@@ -728,7 +911,7 @@ ${JSON.stringify(this.sessionHistory)}`, d = (await A(t.llmAdapter, T).callProce
     return !1;
   }
 }
-class E {
+class S {
   /**
    * Unique identifier for this plugin instance.
    * @private
@@ -774,12 +957,12 @@ class E {
     const e = t.boothRegistry;
     let s = e.baseBoothConfig.description;
     if (e.isMultiBoothMode) {
-      const l = e.orchestratorBoothConfig, i = e.currentContextBoothConfig;
+      const i = e.orchestratorBoothConfig, l = e.currentContextBoothConfig;
       s += `
 
- ${l.description}`, i.id !== l.id && (s += `
+ ${i.description}`, l.id !== i.id && (s += `
 
- ${i.description}`);
+ ${l.description}`);
     }
     return { ...o, instructions: s };
   }
@@ -831,6 +1014,22 @@ class w {
       throw new Error(`Tool with name ${t} is not registered.`);
     return o;
   }
+  /**
+   * Finds and returns multiple tools by their names.
+   * Throws an error if any tool name is not found (via getTool method).
+   *
+   * @param toolNames - Array of unique names of the tools to retrieve
+   * @returns Array of tool instances
+   * @throws Error if any tool name is not registered
+   */
+  getToolsByNames(t) {
+    const o = [];
+    for (const e of t) {
+      const r = this.getTool(e);
+      o.push(r);
+    }
+    return o;
+  }
   getGlobalTools() {
     return Array.from(this.tools.values()).filter((t) => t.global);
   }
@@ -873,7 +1072,7 @@ class w {
     this.tools.delete(t);
   }
 }
-function C(n) {
+function v(n) {
   switch (n.type) {
     case "function":
       return `function:${n.name}`;
@@ -896,15 +1095,15 @@ function C(n) {
       return `${n.type}:${JSON.stringify(n)}`;
   }
 }
-function I(n) {
+function C(n) {
   const t = /* @__PURE__ */ new Set(), o = [];
   for (const e of n) {
-    const r = C(e);
+    const r = v(e);
     t.has(r) || (t.add(r), o.push(e));
   }
   return o;
 }
-class x {
+class E {
   description = "A plugin to aggregate and provide tools from base and context booths.";
   id = "tool-provider";
   name = "Tool Provider Plugin";
@@ -917,18 +1116,18 @@ class x {
    * @returns The updated response parameters with the aggregated list of tools.
    */
   async onBeforeMessageSend(t, o) {
-    const e = t.boothRegistry.baseBoothConfig, r = t.boothRegistry.currentContextBoothConfig, i = [...e.tools || [], ...r?.tools || []].filter((a, d, g) => g.indexOf(a) === d).map(
+    const e = t.boothRegistry.baseBoothConfig, r = t.boothRegistry.currentContextBoothConfig, l = [...e.tools || [], ...r?.tools || []].filter((a, g, d) => d.indexOf(a) === g).map(
       (a) => t.toolRegistry.getTool(a)
     );
-    if (e.mcp && i.push(...e.mcp), r?.mcp && i.push(...r.mcp), t.boothRegistry.isMultiBoothMode) {
+    if (e.mcp && l.push(...e.mcp), r?.mcp && l.push(...r.mcp), t.boothRegistry.isMultiBoothMode) {
       const a = y(t.boothRegistry);
-      i.push(a);
+      l.push(a);
     }
-    i.push(...t.toolRegistry.getGlobalTools());
-    const c = I(i);
+    l.push(...t.toolRegistry.getGlobalTools());
+    const h = C(l);
     return {
       ...o,
-      tools: c
+      tools: h
     };
   }
   /**
@@ -971,16 +1170,16 @@ class m {
           call_id: r.call_id,
           output: `Error: Tool '${r.name}' does not have an 'execute' method.`
         };
-      const l = await s.execute(JSON.parse(r.arguments)), i = await t.pluginRegistry.runAfterToolCall(
+      const i = await s.execute(JSON.parse(r.arguments)), l = await t.pluginRegistry.runAfterToolCall(
         t,
         r,
-        l,
+        i,
         e
       );
       return {
         type: "function_call_output",
         call_id: r.call_id,
-        output: JSON.stringify(i)
+        output: JSON.stringify(l)
       };
     } catch (r) {
       console.error(`Error executing tool ${o.name}:`, r);
@@ -1015,22 +1214,22 @@ class m {
     const r = e?.output ?? [], s = m.extractFunctionCalls(r);
     if (!s.length)
       return o;
-    const l = [];
-    for (let i = 0; i < s.length; i++) {
-      const c = s[i];
-      if (t.toolRegistry.isLocalTool(c.name))
+    const i = [];
+    for (let l = 0; l < s.length; l++) {
+      const h = s[l];
+      if (t.toolRegistry.isLocalTool(h.name))
         continue;
       const a = {
         responseParams: o,
         response: e,
-        toolCallIndex: i,
+        toolCallIndex: l,
         totalToolCalls: s.length
-      }, d = await this.executeToolCall(t, c, a);
-      l.push(d);
+      }, g = await this.executeToolCall(t, h, a);
+      i.push(g);
     }
     return {
       ...o,
-      input: [...o.input, ...l]
+      input: [...o.input, ...i]
     };
   }
   /**
@@ -1042,7 +1241,7 @@ class m {
     return !1;
   }
 }
-class M {
+class A {
   description = "A plugin to ensure the interaction loop can be finished.";
   id = "finish-turn-plugin";
   name = "Finish Turn Plugin";
@@ -1099,16 +1298,99 @@ class M {
     return o;
   }
 }
-function A(n, t) {
-  const o = new R(t), e = new w(), r = new p();
-  return new P({
+class $ {
+  id = "streaming-logger";
+  name = "Streaming Logger Plugin";
+  description = "Logs streaming events in real-time for debugging and monitoring";
+  logPrefix;
+  constructor(t = "[StreamingLogger]") {
+    this.logPrefix = t;
+  }
+  /**
+   * Handle individual stream events as they arrive.
+   * This allows for real-time processing and logging of streaming content.
+   */
+  async onStreamEvent(t, o, e) {
+    switch (o.type) {
+      case "response_start":
+        console.log(`${this.logPrefix} Stream started`);
+        break;
+      case "text_delta":
+        console.log(`${this.logPrefix} Text chunk [${e.streamIndex}]: "${o.delta}"`);
+        break;
+      case "tool_call_start":
+        console.log(`${this.logPrefix} Tool call started: ${o.toolCall?.name}`);
+        break;
+      case "tool_call_end":
+        console.log(`${this.logPrefix} Tool call completed: ${o.toolCall?.name}`);
+        break;
+      case "response_end":
+        console.log(`${this.logPrefix} Stream completed after ${e.streamIndex} events`);
+        break;
+      default:
+        console.log(`${this.logPrefix} Stream event [${e.streamIndex}]: ${o.type}`);
+    }
+    return o;
+  }
+  /**
+   * Required method - determines whether to end the interaction loop.
+   * For a logging plugin, we never want to end the loop ourselves.
+   */
+  async shouldEndInteractionLoop() {
+    return !1;
+  }
+}
+class k {
+  id = "streaming-ui";
+  name = "Streaming UI Plugin";
+  description = "Provides real-time UI updates during streaming responses";
+  onStreamCallback;
+  constructor(t) {
+    this.onStreamCallback = t;
+  }
+  /**
+   * Handle individual stream events and emit them to the UI layer.
+   * This enables real-time updates to the user interface.
+   */
+  async onStreamEvent(t, o, e) {
+    this.onStreamCallback && o.type === "text_delta" && this.onStreamCallback(o, e);
+    let r = o;
+    return o.type === "text_delta" && o.delta && (r = {
+      ...o,
+      // Example: add HTML escaping (though this should be done in the UI layer)
+      delta: o.delta
+    }), r;
+  }
+  /**
+   * Set or update the stream callback for UI updates.
+   */
+  setStreamCallback(t) {
+    this.onStreamCallback = t;
+  }
+  /**
+   * Remove the stream callback.
+   */
+  removeStreamCallback() {
+    this.onStreamCallback = void 0;
+  }
+  /**
+   * Required method - determines whether to end the interaction loop.
+   * For a UI plugin, we never want to end the loop ourselves.
+   */
+  async shouldEndInteractionLoop() {
+    return !1;
+  }
+}
+function M(n, t) {
+  const o = new B(t), e = new w(), r = new p();
+  return new L({
     llmAdapter: n,
     booths: o,
     tools: e,
     boothPlugins: r
   });
 }
-class P {
+class L {
   /**
    * Represents a registry that maintains a collection of plugins for a booth system.
    * The boothPluginRegistry is used to manage and access plugins that enhance
@@ -1175,12 +1457,12 @@ class P {
       this.toolRegistry.registerTools([o]);
     }
     this.systemPluginsRegistry = new p(), this.systemPluginsRegistry.registerPlugins([
-      new v(t.sessionHistory),
+      new x(t.sessionHistory),
+      new S(),
       new E(),
-      new x(),
       new m(),
-      new M()
-    ]), this.systemPluginsRegistry.registerPlugins(this.boothPluginRegistry.getPlugins()), this.callProcessor = new B(
+      new A()
+    ]), this.systemPluginsRegistry.registerPlugins(this.boothPluginRegistry.getPlugins()), this.callProcessor = new T(
       this.boothRegistry,
       this.systemPluginsRegistry,
       this.toolRegistry,
@@ -1190,15 +1472,17 @@ class P {
 }
 export {
   p as BoothPluginRegistry,
-  R as BoothRegistry,
-  E as ContextProviderPlugin,
-  v as ConversationHistoryPlugin,
-  P as CoreBooth,
-  M as FinishTurnPlugin,
-  B as InteractionProcessor,
+  B as BoothRegistry,
+  S as ContextProviderPlugin,
+  x as ConversationHistoryPlugin,
+  L as CoreBooth,
+  A as FinishTurnPlugin,
+  T as InteractionProcessor,
+  $ as StreamingLoggerPlugin,
+  k as StreamingUIPlugin,
   m as ToolExecutorPlugin,
-  x as ToolProviderPlugin,
+  E as ToolProviderPlugin,
   w as ToolRegistry,
-  A as createCoreBooth,
+  M as createCoreBooth,
   y as createRouteToBoothTool
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "booths",
   "private": false,
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,14 +16,20 @@
     }
   },
   "scripts": {
-    "build-pack": "npm install --package-lock-only && npm run build && npm pack",
+    "build:pack": "npm install --package-lock-only && npm run build && npm pack",
     "build": "tsc && vite build",
     "format": "prettier --write \"src/**/*.{js,ts,json,css,scss,md}\"",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage"
   },
   "devDependencies": {
     "@eslint/js": "^9.30.1",
     "@types/node": "^24.0.11",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
     "dotenv": "^17.2.0",
     "eslint": "^9.30.1",
     "eslint-config-prettier": "^10.1.5",
@@ -33,9 +39,11 @@
     "ts-node": "^10.9.2",
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.36.0",
+    "vi-fetch": "^0.8.0",
     "vite": "^6.3.5",
     "vite-plugin-dts": "^4.5.4",
-    "vite-tsconfig-paths": "^5.1.4"
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4"
   },
   "peerDependencies": {
     "openai": "^5.8.2"