booths 2.0.0-2 → 2.0.0-4

package/README.md

@@ -591,6 +591,68 @@ Plugins implement `BoothPlugin` and can influence request/response flow and tool
 * `ToolExecutorPlugin` – executes tool calls with per-call hooks
 * `FinishTurnPlugin` – decides when a turn is complete
 
+#### ConversationHistoryPlugin with Compact Hooks
+
+The `ConversationHistoryPlugin` manages conversation history and automatically compacts (summarizes) it when token limits are reached or when routing between booths. You can monitor and respond to compaction events using callback hooks:
+
+```ts
+import { ConversationHistoryPlugin } from 'booths';
+
+// Create plugin with compact event monitoring
+const historyPlugin = new ConversationHistoryPlugin(
+  [],  // Initial history (optional)
+  () => {
+    // Called when history compaction starts
+    console.log('📦 Compacting conversation history...');
+    // Show loading indicator, log metrics, etc.
+  },
+  () => {
+    // Called when history compaction completes
+    console.log('✅ History compaction complete');
+    // Hide loading indicator, log completion, etc.
+  },
+  960000  // Token threshold for compaction (optional, default: 960,000)
+);
+
+// Register the plugin (done automatically by createCoreBooth)
+coreBooth.pluginRegistry.register(historyPlugin);
+
+// Access conversation history at any time
+const currentHistory = historyPlugin.history;
+console.log(`History has ${currentHistory.length} entries`);
+```
+
+**Compaction triggers:**
+- Input tokens exceed the threshold (default: 960,000 tokens)
+- Routing between booths via `route_to_booth` tool call
+- Booth change occurs with 25%+ of threshold used
+
+**During compaction, the plugin:**
+1. Summarizes the conversation using a specialized summarizer booth
+2. Removes resolved function call pairs (call + output)
+3. Preserves unresolved function calls (waiting for output)
+4. Keeps the last user message
+5. Rebuilds history with the summary as a developer message
+
+```ts
+// Example: Lower threshold for more frequent compaction
+const aggressiveHistoryPlugin = new ConversationHistoryPlugin(
+  [],
+  () => console.log('Compacting...'),
+  () => console.log('Done!'),
+  500000  // Compact at 500K tokens instead of 960K
+);
+```
+
+**Use cases for compact hooks:**
+- Show loading indicators during summarization
+- Log compaction events for monitoring
+- Track token usage metrics
+- Implement custom caching strategies
+- Notify users of long-running conversations
+
+For more details on the ConversationHistoryPlugin, see [src/plugins.md](src/plugins.md#conversationhistoryplugin-deep-dive).
+
 ---
 
 ## Best Practices