@llmrtc/llmrtc-core 1.0.0

package/dist/playbook-engine.js

@@ -0,0 +1,390 @@
+/**
+ * Playbook Engine
+ *
+ * Evaluates transition rules and manages stage transitions in a playbook.
+ */
+import { PLAYBOOK_TRANSITION_TOOL } from './playbook.js';
+/**
+ * Playbook Engine - Evaluates transitions and manages playbook state
+ */
+export class PlaybookEngine {
+    constructor(playbook, options = {}) {
+        Object.defineProperty(this, "playbook", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "state", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "sessionMetadata", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        this.playbook = playbook;
+        this.options = options;
+        // Initialize state
+        const initialStage = playbook.stages.find(s => s.id === playbook.initialStage);
+        if (!initialStage) {
+            throw new Error(`Initial stage '${playbook.initialStage}' not found in playbook`);
+        }
+        this.state = {
+            currentStage: initialStage,
+            turnCount: 0,
+            stageEnteredAt: Date.now(),
+            conversationContext: {},
+            transitionHistory: [],
+            isComplete: false
+        };
+    }
+    /**
+     * Get current playbook state
+     */
+    getState() {
+        return { ...this.state };
+    }
+    /**
+     * Get current stage
+     */
+    getCurrentStage() {
+        return this.state.currentStage;
+    }
+    /**
+     * Get the playbook
+     */
+    getPlaybook() {
+        return this.playbook;
+    }
+    /**
+     * Set session metadata
+     */
+    setSessionMetadata(metadata) {
+        this.sessionMetadata = { ...this.sessionMetadata, ...metadata };
+    }
+    /**
+     * Update conversation context
+     */
+    updateContext(updates) {
+        this.state.conversationContext = {
+            ...this.state.conversationContext,
+            ...updates
+        };
+    }
+    /**
+     * Subscribe to playbook events
+     */
+    on(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /**
+     * Emit an event to all listeners
+     */
+    async emit(event) {
+        for (const listener of this.listeners) {
+            await listener(event);
+        }
+    }
+    /**
+     * Log a debug message
+     */
+    log(level, msg, ...args) {
+        if (this.options.logger) {
+            this.options.logger[level](msg, ...args);
+        }
+        else if (this.options.debug && level !== 'debug') {
+            console[level](`[PlaybookEngine] ${msg}`, ...args);
+        }
+    }
+    /**
+     * Build transition context for evaluation
+     */
+    buildTransitionContext(lastAssistantMessage, lastToolCalls) {
+        return {
+            currentStage: this.state.currentStage.id,
+            turnCount: this.state.turnCount,
+            timeInStage: Date.now() - this.state.stageEnteredAt,
+            lastAssistantMessage,
+            lastToolCalls,
+            conversationContext: this.state.conversationContext,
+            sessionMetadata: this.sessionMetadata
+        };
+    }
+    /**
+     * Evaluate a single transition condition
+     */
+    async evaluateCondition(condition, context) {
+        switch (condition.type) {
+            case 'tool_call':
+                return context.lastToolCalls?.some(tc => tc.name === condition.toolName) ?? false;
+            case 'intent':
+                // Intent detection would typically be done by the LLM or a classifier
+                // For now, check if the intent is in the conversation context
+                const detectedIntent = context.conversationContext.detectedIntent;
+                if (!detectedIntent)
+                    return false;
+                if (condition.confidence !== undefined) {
+                    const confidence = context.conversationContext.intentConfidence;
+                    return detectedIntent === condition.intent && (confidence ?? 0) >= condition.confidence;
+                }
+                return detectedIntent === condition.intent;
+            case 'keyword':
+                const message = context.lastAssistantMessage?.toLowerCase() ?? '';
+                return condition.keywords.some(kw => message.includes(kw.toLowerCase()));
+            case 'llm_decision':
+                // LLM decision is handled via the playbook_transition tool
+                // Check if the LLM called the transition tool
+                return context.lastToolCalls?.some(tc => tc.name === 'playbook_transition') ?? false;
+            case 'max_turns':
+                return context.turnCount >= condition.count;
+            case 'timeout':
+                return context.timeInStage >= condition.durationMs;
+            case 'custom':
+                return await condition.evaluate(context);
+            default:
+                this.log('warn', `Unknown transition condition type: ${condition.type}`);
+                return false;
+        }
+    }
+    /**
+     * Evaluate all applicable transitions and return the highest priority match
+     */
+    async evaluateTransitions(lastAssistantMessage, lastToolCalls) {
+        const context = this.buildTransitionContext(lastAssistantMessage, lastToolCalls);
+        // Get transitions applicable to current stage (sorted by priority)
+        const applicableTransitions = this.playbook.transitions
+            .filter(t => t.from === '*' || t.from === this.state.currentStage.id)
+            .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        for (const transition of applicableTransitions) {
+            const matches = await this.evaluateCondition(transition.condition, context);
+            if (matches) {
+                this.log('debug', `Transition '${transition.id}' matched`, {
+                    from: this.state.currentStage.id,
+                    to: transition.action.targetStage,
+                    condition: transition.condition.type
+                });
+                return {
+                    shouldTransition: true,
+                    transition,
+                    reason: `Condition '${transition.condition.type}' matched for transition '${transition.id}'`
+                };
+            }
+        }
+        return {
+            shouldTransition: false,
+            reason: 'No transition conditions matched'
+        };
+    }
+    /**
+     * Check if a specific transition should be triggered (e.g., from playbook_transition tool)
+     */
+    async evaluateExplicitTransition(targetStage, reason, data) {
+        // Verify target stage exists
+        const target = this.playbook.stages.find(s => s.id === targetStage);
+        if (!target) {
+            return {
+                shouldTransition: false,
+                reason: `Target stage '${targetStage}' not found in playbook`
+            };
+        }
+        // Find an LLM decision transition or create an implicit one
+        const llmTransition = this.playbook.transitions.find(t => (t.from === '*' || t.from === this.state.currentStage.id) &&
+            t.condition.type === 'llm_decision' &&
+            t.action.targetStage === targetStage);
+        if (llmTransition) {
+            return {
+                shouldTransition: true,
+                transition: llmTransition,
+                reason: `LLM requested transition: ${reason}`
+            };
+        }
+        // Allow implicit LLM-initiated transitions if no explicit rule exists
+        return {
+            shouldTransition: true,
+            transition: {
+                id: `implicit_llm_${Date.now()}`,
+                from: this.state.currentStage.id,
+                condition: { type: 'llm_decision' },
+                action: {
+                    targetStage,
+                    data
+                }
+            },
+            reason: `LLM requested implicit transition: ${reason}`
+        };
+    }
+    /**
+     * Execute a stage transition
+     */
+    async executeTransition(transition, overrideData) {
+        const fromStage = this.state.currentStage;
+        const toStage = this.playbook.stages.find(s => s.id === transition.action.targetStage);
+        if (!toStage) {
+            throw new Error(`Target stage '${transition.action.targetStage}' not found`);
+        }
+        this.log('info', `Transitioning from '${fromStage.id}' to '${toStage.id}'`);
+        // Build stage context for hooks
+        const exitContext = {
+            stage: fromStage,
+            otherStage: toStage,
+            transitionData: overrideData ?? transition.action.data,
+            sessionMetadata: this.sessionMetadata,
+            conversationContext: this.state.conversationContext
+        };
+        // Call exit hook
+        if (fromStage.onExit) {
+            await fromStage.onExit(exitContext);
+        }
+        // Emit exit event
+        await this.emit({ type: 'stage_exit', stage: fromStage, nextStage: toStage });
+        // Clear history if requested
+        if (transition.action.clearHistory) {
+            this.state.conversationContext = {};
+        }
+        // Record transition in history
+        this.state.transitionHistory.push({
+            from: fromStage.id,
+            to: toStage.id,
+            transitionId: transition.id,
+            timestamp: Date.now()
+        });
+        // Update state
+        this.state.currentStage = toStage;
+        this.state.turnCount = 0;
+        this.state.stageEnteredAt = Date.now();
+        // Merge transition data into context
+        if (transition.action.data || overrideData) {
+            this.state.conversationContext = {
+                ...this.state.conversationContext,
+                transitionData: overrideData ?? transition.action.data
+            };
+        }
+        // Build enter context
+        const enterContext = {
+            stage: toStage,
+            otherStage: fromStage,
+            transitionData: overrideData ?? transition.action.data,
+            sessionMetadata: this.sessionMetadata,
+            conversationContext: this.state.conversationContext
+        };
+        // Call enter hook
+        if (toStage.onEnter) {
+            await toStage.onEnter(enterContext);
+        }
+        // Emit events
+        await this.emit({ type: 'transition', transition, from: fromStage, to: toStage });
+        await this.emit({ type: 'stage_enter', stage: toStage, previousStage: fromStage });
+    }
+    /**
+     * Increment turn count and emit event
+     */
+    async completeTurn() {
+        this.state.turnCount++;
+        await this.emit({
+            type: 'turn_complete',
+            stage: this.state.currentStage,
+            turnCount: this.state.turnCount
+        });
+    }
+    /**
+     * Mark playbook as complete
+     */
+    async complete() {
+        this.state.isComplete = true;
+        await this.emit({
+            type: 'playbook_complete',
+            finalStage: this.state.currentStage
+        });
+    }
+    /**
+     * Get the effective system prompt for current stage
+     * (combines global prompt with stage-specific prompt)
+     */
+    getEffectiveSystemPrompt() {
+        const parts = [];
+        if (this.playbook.globalSystemPrompt) {
+            parts.push(this.playbook.globalSystemPrompt);
+        }
+        parts.push(this.state.currentStage.systemPrompt);
+        // Add available transitions context for LLM
+        const availableTransitions = this.playbook.transitions
+            .filter(t => t.from === '*' || t.from === this.state.currentStage.id)
+            .filter(t => t.condition.type === 'llm_decision');
+        if (availableTransitions.length > 0) {
+            const transitionDescriptions = availableTransitions.map(t => {
+                const targetStage = this.playbook.stages.find(s => s.id === t.action.targetStage);
+                return `- ${t.action.targetStage}: ${targetStage?.description ?? t.description ?? 'No description'}`;
+            });
+            parts.push(`\nYou can transition to the following stages when appropriate:\n${transitionDescriptions.join('\n')}`);
+        }
+        return parts.join('\n\n');
+    }
+    /**
+     * Get all tools available in current stage
+     * (combines global tools with stage-specific tools)
+     */
+    getAvailableTools() {
+        const tools = [];
+        // Add global tools
+        if (this.playbook.globalTools) {
+            tools.push(...this.playbook.globalTools);
+        }
+        // Add stage-specific tools
+        if (this.state.currentStage.tools) {
+            tools.push(...this.state.currentStage.tools);
+        }
+        // Add playbook_transition tool if LLM decision transitions exist
+        const hasLLMTransitions = this.playbook.transitions.some(t => (t.from === '*' || t.from === this.state.currentStage.id) &&
+            t.condition.type === 'llm_decision');
+        if (hasLLMTransitions) {
+            tools.push(PLAYBOOK_TRANSITION_TOOL);
+        }
+        return tools;
+    }
+    /**
+     * Get effective LLM config for current stage
+     */
+    getEffectiveLLMConfig() {
+        return {
+            ...this.playbook.defaultLLMConfig,
+            ...this.state.currentStage.llmConfig
+        };
+    }
+    /**
+     * Reset engine to initial state
+     */
+    reset() {
+        const initialStage = this.playbook.stages.find(s => s.id === this.playbook.initialStage);
+        if (!initialStage) {
+            throw new Error(`Initial stage '${this.playbook.initialStage}' not found`);
+        }
+        this.state = {
+            currentStage: initialStage,
+            turnCount: 0,
+            stageEnteredAt: Date.now(),
+            conversationContext: {},
+            transitionHistory: [],
+            isComplete: false
+        };
+        this.sessionMetadata = {};
+    }
+}
+//# sourceMappingURL=playbook-engine.js.map

package/dist/playbook-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook-engine.js","sourceRoot":"","sources":["../src/playbook-engine.ts"],"names":[],"mappings":"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"}

package/dist/playbook-orchestrator.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Playbook Orchestrator
+ *
+ * Orchestrates turn execution with two-phase model:
+ * - Phase 1: Tool loop - LLM can call tools repeatedly until it decides to respond
+ * - Phase 2: Final answer - Generate the user-facing response
+ *
+ * Integrates with STT/TTS for voice-based interactions.
+ */
+import type { LLMProvider, LLMResult, Message, VisionAttachment } from './types.js';
+import type { ToolDefinition, ToolCallRequest, ToolCallResult } from './tools.js';
+import { ToolRegistry } from './tools.js';
+import { PlaybookEngine, PlaybookEvent } from './playbook-engine.js';
+import type { Playbook, Stage, Transition } from './playbook.js';
+/**
+ * Options for the playbook orchestrator
+ */
+export interface PlaybookOrchestratorOptions {
+    /** Maximum number of tool calls per turn in Phase 1 */
+    maxToolCallsPerTurn?: number;
+    /** Timeout for Phase 1 tool loop (ms) */
+    phase1TimeoutMs?: number;
+    /** Number of LLM retry attempts on failure (default: 3) */
+    llmRetries?: number;
+    /** Maximum conversation history messages to retain (default: 50) */
+    historyLimit?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom logger */
+    logger?: {
+        debug: (msg: string, ...args: unknown[]) => void;
+        info: (msg: string, ...args: unknown[]) => void;
+        warn: (msg: string, ...args: unknown[]) => void;
+        error: (msg: string, ...args: unknown[]) => void;
+    };
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Result of a single turn execution
+ */
+export interface TurnResult {
+    /** The final assistant response */
+    response: string;
+    /** All tool calls made during the turn */
+    toolCalls: Array<{
+        request: ToolCallRequest;
+        result: ToolCallResult;
+    }>;
+    /** Whether a stage transition occurred */
+    transitioned: boolean;
+    /** The transition that was triggered (if any) */
+    transition?: Transition;
+    /** New stage after transition (if any) */
+    newStage?: Stage;
+    /** Raw LLM responses */
+    llmResponses: LLMResult[];
+    /** Stop reason from final LLM call */
+    stopReason?: string;
+}
+/**
+ * Event emitted during turn execution
+ */
+export type OrchestratorEvent = {
+    type: 'phase1_start';
+} | {
+    type: 'tool_call_start';
+    call: ToolCallRequest;
+} | {
+    type: 'tool_call_complete';
+    call: ToolCallRequest;
+    result: ToolCallResult;
+} | {
+    type: 'phase1_complete';
+    toolCallCount: number;
+} | {
+    type: 'phase2_start';
+} | {
+    type: 'phase2_complete';
+    response: string;
+} | {
+    type: 'transition_triggered';
+    transition: Transition;
+} | PlaybookEvent;
+/**
+ * Listener for orchestrator events
+ */
+export type OrchestratorEventListener = (event: OrchestratorEvent) => void | Promise<void>;
+/**
+ * Playbook Orchestrator - Manages two-phase turn execution
+ */
+export declare class PlaybookOrchestrator {
+    private readonly llmProvider;
+    private readonly engine;
+    private readonly toolRegistry;
+    private readonly toolExecutor;
+    private readonly options;
+    private readonly listeners;
+    private conversationHistory;
+    private turnLock;
+    private isExecutingTurn;
+    constructor(llmProvider: LLMProvider, playbook: Playbook, toolRegistry: ToolRegistry, options?: PlaybookOrchestratorOptions);
+    /**
+     * Register the built-in playbook_transition tool
+     */
+    private registerTransitionTool;
+    /**
+     * Get the playbook engine
+     */
+    getEngine(): PlaybookEngine;
+    /**
+     * Get current conversation history
+     */
+    getHistory(): Message[];
+    /**
+     * Clear conversation history
+     */
+    clearHistory(): void;
+    /**
+     * Subscribe to orchestrator events
+     */
+    on(listener: OrchestratorEventListener): () => void;
+    /**
+     * Emit an event to all listeners
+     */
+    private emit;
+    /**
+     * Log a message
+     */
+    private log;
+    /**
+     * Add message to history with automatic cleanup when limit exceeded.
+     * Uses smart trimming to preserve tool call/result pairs (required by OpenAI API).
+     */
+    private pushHistory;
+    /**
+     * Check if an error is retryable.
+     * Non-retryable: client errors (400, 401, 403, 404) except rate limits.
+     * Retryable: rate limits (429), server errors (5xx), timeouts.
+     */
+    private isRetryableError;
+    /**
+     * Call LLM with smart retry and exponential backoff.
+     * Only retries on retryable errors (rate limits, server errors, timeouts).
+     */
+    private callLLMWithRetry;
+    /**
+     * Build LLM request for current state
+     */
+    private buildLLMRequest;
+    /**
+     * Execute Phase 1: Tool loop
+     * LLM can call tools repeatedly until it decides to respond
+     */
+    private executePhase1;
+    /**
+     * Execute Phase 2: Generate final response
+     */
+    private executePhase2;
+    /**
+     * Execute a complete turn with user input.
+     * This method is serialized - concurrent calls will be queued.
+     * @param userMessage - The user's message text
+     * @param attachments - Optional vision attachments (images)
+     */
+    executeTurn(userMessage: string, attachments?: VisionAttachment[]): Promise<TurnResult>;
+    /**
+     * Internal turn execution logic
+     */
+    private _executeTurnInternal;
+    /**
+     * Execute a turn with streaming response.
+     * This method is serialized - concurrent calls will be queued.
+     * @param userMessage - The user's message text
+     * @param attachments - Optional vision attachments (images)
+     */
+    streamTurn(userMessage: string, attachments?: VisionAttachment[]): AsyncIterable<{
+        type: 'tool_call' | 'content' | 'done';
+        data: ToolCallRequest | string | TurnResult;
+    }>;
+    /**
+     * Internal streaming turn logic
+     */
+    private _streamTurnInternal;
+    /**
+     * Reset orchestrator to initial state
+     */
+    reset(): void;
+}
+/**
+ * Create a simple playbook with a single stage
+ */
+export declare function createSimplePlaybook(id: string, systemPrompt: string, tools?: ToolDefinition[]): Playbook;