booths 1.3.1 → 1.4.1

package/README.md

@@ -1,93 +1,72 @@
 # Booths
 
-Booths is a modular and extensible framework for building and managing conversational AI agents. It provides a structured way to define the capabilities, context, and tools for different AI-powered conversational flows.
+[![Check Build on Pull Request](https://github.com/phoneburner/booths/actions/workflows/build-check.yml/badge.svg)](https://github.com/phoneburner/booths/actions/workflows/build-check.yml)
+[![Format Check](https://github.com/phoneburner/booths/actions/workflows/format-check.yml/badge.svg)](https://github.com/phoneburner/booths/actions/workflows/format-check.yml)
+[![Publish to NPM on Release](https://github.com/phoneburner/booths/actions/workflows/release.yml/badge.svg)](https://github.com/phoneburner/booths/actions/workflows/release.yml)
+[![Test Suite](https://github.com/phoneburner/booths/actions/workflows/test.yml/badge.svg)](https://github.com/phoneburner/booths/actions/workflows/test.yml)
 
-The system is designed around a central `CoreBooth` class that orchestrates interactions between users and a Large Language Model (LLM), leveraging a system of registries and plugins to manage the conversational state and capabilities.
+*A modular, extensible framework for building and managing conversational AI agents in TypeScript.*
 
-## Architecture Overview
+> Booths provides a structured way to define agent capabilities, context, and tools, orchestrated by a `CoreBooth` that manages the interaction loop with your LLM and a rich plugin lifecycle.
 
-The Booths framework is built around a few key concepts that work together to create a powerful and flexible conversational AI system.
+---
 
-```mermaid
-graph TD
-    subgraph Application Layer
-        A[Your Application]
-    end
+## Table of Contents
 
-    subgraph Booth Service Layer
-        C(CoreBooth)
-    end
+* [Installation](#installation)
+* [Quick Start Guide](#quick-start-guide)
+* [Architecture Overview](#architecture-overview)
+* [API Reference](#api-reference)
 
-    subgraph Core Components
-        D[Interaction Processor]
-        E[LLM Adapter]
-        F[Registries]
-        G[Plugins]
-    end
+    * [createCoreBooth](#createcorebooth)
 
-    A -- "initializes and calls" --> C
-    C -- "delegates to" --> D
-    D -- "uses" --> E
-    D -- "uses" --> F
-    D -- "executes" --> G
-    E -- "communicates with" --> H((LLM))
-    F -- "manages" --> I{Booths}
-    F -- "manages" --> J{Tools}
-    F -- "manages" --> K{Plugins}
-    G -- "hook into" --> D
+        * [Options](#options)
+        * [Examples](#examples)
+    * [InteractionProcessor](#interactionprocessor)
 
-    style C fill:#f9f,stroke:#333,stroke-width:2px
-```
+        * [Flow](#flow)
+        * [Important Constraints](#important-constraints)
+    * [Registries](#registries)
 
-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. 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.
-    *   `BoothPluginRegistry`: Manages the plugins that hook into the conversational lifecycle.
-6.  **Plugins**: These are modules that add functionality to the system by hooking into the `InteractionProcessor`'s lifecycle (e.g., managing conversation history, providing context to the LLM, executing tools).
+        * [BoothRegistry](#boothregistry)
+        * [ToolRegistry](#toolregistry)
+        * [BoothPluginRegistry](#boothpluginregistry)
+    * [Plugins](#plugins)
 
-## Getting Started
+        * [Lifecycle Hooks](#lifecycle-hooks)
+* [Best Practices](#best-practices)
+* [Advanced Usage](#advanced-usage)
 
-The Booths framework is designed as a TypeScript library for building conversational AI systems. This repository contains the core framework implementation.
+    * [Customizing the end-of-turn marker](#customizing-the-end-of-turn-marker)
+    * [Per-tool interception & error recovery](#per-tool-interception--error-recovery)
+* [Types](#types)
+* [Session & State Management](#session--state-management)
+* [Error Handling](#error-handling)
+* [License](#license)
 
-### Installation
+---
+
+## Installation
 
 ```bash
 npm install booths
 ```
 
-### Prerequisites
-
--   Node.js and npm installed
--   An LLM provider API key (e.g., OpenAI)
+**Prerequisites**
 
-### Development
+* Node.js and npm
+* An API key for your LLM provider (e.g., OpenAI)
 
-To build the library:
-
-```bash
-npm run build
-```
-
-To check types:
-
-```bash
-npm run typecheck
-```
+---
 
 ## Quick Start Guide
 
-Here is a lightweight example of how to set up and use the Core Booth system manually.
-
-### 1. Define a Booth
+A minimal setup that defines a booth, a tool, an adapter, and starts a conversation.
 
-First, define a booth configuration. This object specifies the booth's identity, role, and the tools it can use.
+### 1) Define a Booth
 
-```typescript
-// in my-booths.ts
+```ts
+// my-booths.ts
 import type { BoothConfig } from 'booths';
 
 export const pirateBooth: BoothConfig = {
@@ -99,12 +78,10 @@ export const pirateBooth: BoothConfig = {
 };
 ```
 
-### 2. Define a Tool
+### 2) Define a Tool
 
-Next, create a tool that the booth can use. A tool is a function that the LLM can decide to call.
-
-```typescript
-// in my-tools.ts
+```ts
+// my-tools.ts
 import type { ToolModule } from 'booths';
 
 export const tellPirateJokeTool: ToolModule = {
@@ -113,384 +90,256 @@ export const tellPirateJokeTool: ToolModule = {
   description: 'Tells a classic pirate joke.',
   parameters: { type: 'object', properties: {} },
   execute: async () => {
-    return { joke: "Why are pirates called pirates? Because they arrrr!" };
+    return { joke: 'Why are pirates called pirates? Because they arrrr!' };
   },
 };
 ```
 
-### 3. Implement the LLM Adapter
-
-The `CoreBooth` requires an `LLMAdapter` to communicate with your chosen language model. Here is a minimal example for OpenAI.
+### 3) Implement a simple LLM Adapter
 
-```typescript
-// in OpenAIAdapter.ts
-import type { 
-  LLMAdapter, 
-  ResponseCreateParamsNonStreaming, 
-  ResponseCreateParamsStreaming,
+```ts
+// OpenAIAdapter.ts
+import type {
+  LLMAdapter,
+  ResponseCreateParamsNonStreaming,
   Response,
-  StreamEvent
 } from 'booths';
 import OpenAI from 'openai';
 
 export class OpenAIAdapter implements LLMAdapter<Response> {
   private openai: OpenAI;
-
   constructor(apiKey: string) {
     this.openai = new OpenAI({ apiKey });
   }
-
   async invoke(params: ResponseCreateParamsNonStreaming): Promise<Response> {
     return this.openai.responses.create({ ...params, model: 'gpt-4o' });
   }
-
   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 || ''
-    };
-  }
 }
 ```
 
-### 4. Initialize the CoreBooth
-
-Finally, use the `createCoreBooth` factory to instantiate the system.
+### 4) Initialize and talk to the booth
 
-```typescript
-// in main.ts
+```ts
+// main.ts
 import { createCoreBooth } from 'booths';
 import { pirateBooth } from './my-booths';
 import { tellPirateJokeTool } from './my-tools';
-import { OpenAIAdapter } from './openAIAdapter';
+import { OpenAIAdapter } from './OpenAIAdapter';
 
-// 1. Create the LLM adapter
-const llmAdapter = new OpenAIAdapter('your-openai-api-key');
+const llmAdapter = new OpenAIAdapter(process.env.OPENAI_API_KEY!);
+const coreBooth = createCoreBooth(llmAdapter, pirateBooth /*, { endInteractionLoopMarker: '__custom_marker__' }*/);
 
-// 2. Create the CoreBooth instance
-const coreBooth = createCoreBooth(llmAdapter, pirateBooth);
-
-// 3. Register the tool (this step will be improved in future versions)
+// Register tools (available to the current booth)
 coreBooth.toolRegistry.registerTools([tellPirateJokeTool]);
 
-// 4. Send a message and get a response
-async function haveConversation() {
-  const userInput = 'Tell me a pirate joke.';
-  const response = await coreBooth.callProcessor.send(userInput);
-
+// Send a message and read the result
+async function run() {
+  const response = await coreBooth.callProcessor.send('Tell me a pirate joke.');
   console.log(response.output_text);
-  // Expected output: "Why are pirates called pirates? Because they arrrr!"
 }
-
-haveConversation();
+run();
 ```
-## How It Works
 
-The Core Booth system is comprised of several key components that work together to process user input and generate contextual responses.
+---
 
-### 1. Registries
+## Architecture Overview
 
-- **`BoothRegistry`**: Manages the collection of `BoothConfig` objects. Each booth represents a specialized agent with a specific role, description, and set of tools. It also keeps track of the "current context booth" to ensure the conversation stays on topic.
-- **`ToolRegistry`**: Manages the tools that can be made available to the LLM. Tools are functions that the AI can decide to call to perform actions or retrieve information.
-- **`BoothPluginRegistry`**: Manages plugins that hook into the interaction lifecycle. This allows for modular and reusable functionality to be added to the system.
+```mermaid
+graph TD
+    subgraph Application Layer
+        A[Your Application]
+    end
 
-### 2. Plugins
+    subgraph Booth Service Layer
+        C(CoreBooth)
+    end
 
-Plugins are classes that implement the `BoothPlugin` interface. They can execute logic at different stages of the conversation:
+    subgraph Core Components
+        D[Interaction Processor]
+        E[LLM Adapter]
+        F[Registries]
+        G[Plugins]
+    end
 
-- `onBeforeInteractionLoopStart`: Before the main loop begins.
-- `onBeforeMessageSend`: Before a message is sent to the LLM.
-- `onResponseReceived`: After a response is received from the LLM.
-- `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.
+    A -- "initializes and calls" --> C
+    C -- "delegates to" --> D
+    D -- "uses" --> E
+    D -- "uses" --> F
+    D -- "executes" --> G
+    E -- "communicates with" --> H((LLM))
+    F -- "manages" --> I{Booths}
+    F -- "manages" --> J{Tools}
+    F -- "manages" --> K{Plugins}
+    G -- "hook into" --> D
+```
 
-The system includes several core plugins by default:
+---
 
-- `ConversationHistoryPlugin`: Maintains the history of the conversation.
-- `ContextProviderPlugin`: Provides the LLM with the context of the current booth.
-- `ToolProviderPlugin`: Provides the LLM with the available tools for the current booth.
-- `ToolExecutorPlugin`: Executes tool calls requested by the LLM with granular hook support for individual tool call interception.
-- `FinishTurnPlugin`: Determines when the LLM's turn is finished and it's waiting for user input.
+## API Reference
 
-#### Enhanced Tool Call Management
+### createCoreBooth
 
-The plugin system now provides granular control over individual tool executions through three new hooks:
+Factory that wires an `LLMAdapter`, a `BoothConfig`, and internal registries/plugins into a working `CoreBooth` instance.
 
-- **`onBeforeToolCall`**: Intercept and modify tool calls before execution (parameter validation, authorization, logging)
-- **`onAfterToolCall`**: Process and transform tool results after successful execution (caching, metadata addition, data transformation)
-- **`onToolCallError`**: Handle tool execution errors with custom recovery logic (fallback responses, error logging, graceful degradation)
+```ts
+function createCoreBooth(
+  adapter: LLMAdapter<any>,
+  booth: BoothConfig,
+  options?: { endInteractionLoopMarker?: string }
+): CoreBooth
+```
 
-This enables sophisticated tool management patterns like authentication, caching, audit logging, and error recovery at the individual tool level.
+#### Options
 
-### 3. Interaction Processor
+| Name                       | Type     |                        Default | Description                                           |
+| -------------------------- | -------- | -----------------------------: | ----------------------------------------------------- |
+| `endInteractionLoopMarker` | `string` | `"__awaiting_user_response__"` | Marker used by plugins to determine when a turn ends. |
 
-The `InteractionProcessor` is the engine of the system. It manages the interaction loop with the LLM:
+#### Examples
 
-1. It takes user input.
-2. Runs the `onBefore...` plugin hooks.
-3. Sends the payload to the LLM.
-4. Receives the response.
-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.
+**Basic**
 
-## Streaming Support
+```ts
+const coreBooth = createCoreBooth(adapter, pirateBooth);
+```
 
-The Booths framework includes comprehensive streaming support that enables real-time response generation while preserving the full plugin ecosystem and backward compatibility.
+**Custom end-of-turn marker**
 
-### Overview
+```ts
+const coreBooth = createCoreBooth(adapter, pirateBooth, {
+  endInteractionLoopMarker: '__custom_marker__',
+});
+```
 
-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
+### InteractionProcessor
 
-### Enabling Streaming
+Engine that manages the interaction loop with the LLM and the plugin lifecycle.
 
-Streaming can be enabled simply by setting a boolean flag when creating the `InteractionProcessor`:
+#### Flow
 
-```typescript
-import { InteractionProcessor, type InteractionProcessorOptions } from 'booths';
+1. Take user input
+2. Run `onBefore...` plugin hooks
+3. Send payload via `LLMAdapter`
+4. Receive response
+5. Run `onResponseReceived` hooks (e.g., execute tools)
+6. Repeat until `shouldEndInteractionLoop` returns `true`
+7. Run `onAfter...` hooks for cleanup
 
-const options: InteractionProcessorOptions = {
-  streaming: true,                    // Enable streaming
-  fallbackToNonStreaming: true       // Optional: fallback if streaming fails
-};
+#### Important Constraints
 
-const processor = new InteractionProcessor(
-  boothRegistry,
-  pluginRegistry, 
-  toolRegistry,
-  llmAdapter,      // Must implement streaming methods
-  options
-);
-```
+* **Ordering matters**: tool execution and hook order follow the loop above.
+* **End-of-turn detection** relies on the configured `endInteractionLoopMarker`.
 
-### Stream Events
+---
 
-The streaming system emits different types of events as the response is generated:
+### Registries
 
-```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
-}
-```
+Booths uses three registries to manage the system’s moving parts.
 
-**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
-  }
+#### BoothRegistry
 
-  async shouldEndInteractionLoop(): Promise<boolean> {
-    return false;
-  }
-}
-```
+* Manages `BoothConfig` objects (each is a specialized agent: role, description, tools, examples).
+* Tracks the current context booth.
 
-### Built-in Streaming Plugins
+#### ToolRegistry
 
-The framework includes example streaming plugins:
+* Stores tools available to the LLM (as `ToolModule`).
+* Provides registration helpers like `registerTools([...])`.
 
-#### StreamingLoggerPlugin
+#### BoothPluginRegistry
 
-Logs streaming events in real-time for debugging and monitoring:
+* Manages plugins that hook into the interaction lifecycle.
+* Enables modular capabilities like conversation history, context provisioning, tool provisioning/execution, and turn-finalization.
 
-```typescript
-import { StreamingLoggerPlugin } from 'booths';
+---
 
-const logger = new StreamingLoggerPlugin('[MyApp]');
-pluginRegistry.registerPlugins([logger]);
-```
+### Plugins
 
-#### StreamingUIPlugin  
+Plugins implement `BoothPlugin` and can influence request/response flow and tool execution.
 
-Provides real-time UI updates with customizable callbacks:
+#### Lifecycle Hooks
 
-```typescript
-import { StreamingUIPlugin } from 'booths';
+* `onBeforeInteractionLoopStart`
+* `onBeforeMessageSend`
+* `onResponseReceived`
+* `onBeforeToolCall`
+* `onAfterToolCall`
+* `onToolCallError`
+* `shouldEndInteractionLoop`
+* `onAfterInteractionLoopEnd`
 
-const uiPlugin = new StreamingUIPlugin((event, context) => {
-  if (event.type === 'text_delta') {
-    // Update your UI with the new text
-    document.getElementById('response').textContent += event.delta;
-  }
-});
+**Built-in plugin capabilities (typical set)**
 
-pluginRegistry.registerPlugins([uiPlugin]);
-```
+* `ConversationHistoryPlugin` – maintains conversation history
+* `ContextProviderPlugin` – supplies booth context to the LLM
+* `ToolProviderPlugin` – exposes available tools
+* `ToolExecutorPlugin` – executes tool calls with per-call hooks
+* `FinishTurnPlugin` – decides when a turn is complete
 
-### LLM Adapter Streaming Implementation
+---
 
-To support streaming, your LLM adapter should implement the optional streaming methods:
+## Best Practices
 
-```typescript
-export class MyStreamingAdapter implements LLMAdapter<MyResponse> {
-  // Required methods
-  async invoke(params: ResponseCreateParamsNonStreaming): Promise<MyResponse> {
-    // Non-streaming implementation
-  }
+* Keep tools **pure** and **idempotent** when possible; return structured results.
+* Favor **small, composable plugins**; use `onBeforeToolCall`/`onAfterToolCall`/`onToolCallError` to isolate auth, caching, and audit.
+* Clearly separate **global tools** vs **booth-specific tools** and document access rules.
+* Centralize **end-of-turn logic** to avoid inconsistent session behavior.
 
-  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;
-    }
-  }
+## Advanced Usage
 
-  async interpretStream(chunk: MyResponse): Promise<StreamEvent> {
-    // Convert chunk to StreamEvent
-    return {
-      type: 'text_delta',
-      delta: chunk.delta,
-      content: chunk.content
-    };
-  }
-}
+### Customizing the end-of-turn marker
+
+```ts
+createCoreBooth(adapter, booth, { endInteractionLoopMarker: '__custom__' });
 ```
 
-### Stream Context
+Use this to coordinate UI or multi-agent systems that rely on explicit “awaiting user” signals.
 
-Plugins receive context information about the streaming session:
+### Per-tool interception & error recovery
 
-```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
+```ts
+class AuditPlugin implements BoothPlugin {
+  async onBeforeToolCall(ctx) { /* validate or redact */ }
+  async onAfterToolCall(ctx) { /* persist results */ }
+  async onToolCallError(ctx, err) { /* fallback or retry */ }
 }
 ```
 
-### Error Handling
+These hooks enable authentication, caching, and graceful degradation at the **individual tool** level.
 
-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
+## Types
 
-### Backward Compatibility
+Core concepts you’ll interact with most:
 
-Streaming support is fully backward compatible:
+* `BoothConfig`: identity, role, description, `tools: string[]`, sample `examples`
+* `ToolModule`: `{ type: 'function' | ..., name, description, parameters, execute }`
+* `LLMAdapter<TResponse>`: `{ invoke(params): Promise<TResponse>; interpret(response): Promise<TResponse> }`
 
-- **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
+## Session & State Management
 
-Here's a complete example showing streaming integration:
+* Conversation continuity (history, context booth) is typically maintained by plugins.
+* Tool calls may emit intermediate results/messages; design UI to handle “in-progress” states.
 
-```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();
+## Error Handling
 
-// 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;
-  }
-});
+* Surface adapter/transport errors from `invoke`.
+* Prefer plugin-level `onToolCallError` for tool failures; use retries or fallback responses.
 
-pluginRegistry.registerPlugins([logger, uiUpdater]);
+---
 
-// 4. Enable streaming
-const streamingOptions: InteractionProcessorOptions = {
-  streaming: true,
-  fallbackToNonStreaming: true
-};
+## License
 
-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
-```
+Distributed under the project’s LICENSE file.