@riotprompt/riotprompt 0.0.7 → 0.0.9

package/dist/riotprompt.cjs

@@ -5,9 +5,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const zod = require('zod');
 const fs = require('fs/promises');
 const path = require('path');
+const crypto = require('crypto');
+const tiktoken = require('tiktoken');
 const fs$1 = require('fs');
 const glob = require('glob');
-const crypto = require('crypto');
 
 function _interopNamespaceDefault(e) {
     const n = Object.create(null, { [Symbol.toStringTag]: { value: 'Module' } });
@@ -387,7 +388,7 @@ const FormatOptionsSchema = zod.z.object({
     sectionTitleProperty: SectionTitlePropertySchema,
     sectionTitlePrefix: zod.z.string().optional(),
     sectionTitleSeparator: zod.z.string().optional(),
-    sectionDepth: zod.z.number().default(1)
+    sectionDepth: zod.z.number().default(0)
 });
 const OptionSchema$1 = zod.z.object({
     logger: zod.z.any().optional().default(DEFAULT_LOGGER),
@@ -448,7 +449,7 @@ const create$5 = (formatterOptions)=>{
                 var _section_title, _section_title1;
                 return `<${(_section_title = section.title) !== null && _section_title !== void 0 ? _section_title : "section"}>\n${formattedItems}\n</${(_section_title1 = section.title) !== null && _section_title1 !== void 0 ? _section_title1 : "section"}>`;
             } else {
-                // Default depth to 1 if not provided, resulting in H2 (##) matching the test case.
+                // Use the current section depth for heading level
                 const headingLevel = currentSectionDepth;
                 const hashes = '#'.repeat(headingLevel);
                 logger.silly(`\t\tHeading level: ${headingLevel}`);
@@ -1376,235 +1377,3496 @@ const builder = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
     create
 }, Symbol.toStringTag, { value: 'Module' }));
 
-// ===== CONFIGURATION SCHEMAS =====
-const ContentItemSchema = zod.z.union([
-    zod.z.string(),
-    zod.z.object({
-        content: zod.z.string(),
-        title: zod.z.string().optional(),
-        weight: zod.z.number().optional()
-    }),
-    zod.z.object({
-        path: zod.z.string(),
-        title: zod.z.string().optional(),
-        weight: zod.z.number().optional()
-    }),
-    zod.z.object({
-        directories: zod.z.array(zod.z.string()),
-        title: zod.z.string().optional(),
-        weight: zod.z.number().optional()
-    })
-]);
-const RecipeConfigSchema = zod.z.object({
-    // Core settings
-    basePath: zod.z.string(),
-    logger: zod.z.any().optional().default(DEFAULT_LOGGER),
-    overridePaths: zod.z.array(zod.z.string()).optional().default([
-        "./"
-    ]),
-    overrides: zod.z.boolean().optional().default(false),
-    parameters: ParametersSchema.optional().default({}),
-    // Content sections
-    persona: ContentItemSchema.optional(),
-    instructions: zod.z.array(ContentItemSchema).optional().default([]),
-    content: zod.z.array(ContentItemSchema).optional().default([]),
-    context: zod.z.array(ContentItemSchema).optional().default([]),
-    // Templates and inheritance
-    extends: zod.z.string().optional(),
-    template: zod.z.string().optional()
-});
-// User-customizable template registry
-let TEMPLATES = {};
+function _define_property$7(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
 /**
- * Register custom templates with the recipes system
- * 
+ * ContextManager tracks and manages dynamically injected context.
+ *
+ * Features:
+ * - Track all injected context with metadata
+ * - Deduplication by ID, hash, or content
+ * - Category-based organization
+ * - Query context state
+ * - Context statistics
+ *
  * @example
  * ```typescript
- * // Register your own templates
- * registerTemplates({
- *   myWorkflow: {
- *     persona: { path: "personas/my-persona.md" },
- *     instructions: [{ path: "instructions/my-instructions.md" }]
- *   },
- *   anotherTemplate: {
- *     persona: { content: "You are a helpful assistant" },
- *     instructions: [{ content: "Follow these steps..." }]
- *   }
- * });
+ * const manager = new ContextManager();
+ *
+ * // Track injected context
+ * manager.track({
+ *   id: 'file:main.ts',
+ *   content: fileContent,
+ *   title: 'Main File',
+ *   category: 'source-code'
+ * }, 5);
+ *
+ * // Check for duplicates
+ * if (manager.hasContext('file:main.ts')) {
+ *   console.log('Already provided');
+ * }
+ *
+ * // Query by category
+ * const sourceFiles = manager.getByCategory('source-code');
  * ```
- */ const registerTemplates = (templates)=>{
-    TEMPLATES = {
-        ...TEMPLATES,
-        ...templates
-    };
-};
-/**
- * Get currently registered templates
- */ const getTemplates = ()=>({
-        ...TEMPLATES
-    });
-/**
- * Clear all registered templates
- */ const clearTemplates = ()=>{
-    TEMPLATES = {};
-};
-// ===== CORE RECIPE ENGINE =====
-const cook = async (config)=>{
-    // Parse and validate configuration with defaults
-    const validatedConfig = RecipeConfigSchema.parse({
-        overridePaths: [
-            "./"
-        ],
-        overrides: false,
-        parameters: {},
-        instructions: [],
-        content: [],
-        context: [],
-        ...config
-    });
-    // Handle template inheritance
-    let finalConfig = {
-        ...validatedConfig
-    };
-    if (validatedConfig.template) {
-        const template = TEMPLATES[validatedConfig.template];
-        if (template) {
-            finalConfig = {
-                ...validatedConfig,
-                persona: validatedConfig.persona || template.persona,
-                instructions: [
-                    ...template.instructions || [],
-                    ...validatedConfig.instructions || []
-                ],
-                content: [
-                    ...template.content || [],
-                    ...validatedConfig.content || []
-                ],
-                context: [
-                    ...template.context || [],
-                    ...validatedConfig.context || []
-                ]
-            };
+ */ class ContextManager {
+    /**
+     * Track a context item
+     */ track(item, position) {
+        const id = item.id || this.generateId();
+        const hash = this.hashContent(item.content);
+        const trackedItem = {
+            ...item,
+            id,
+            hash,
+            position,
+            injectedAt: new Date(),
+            timestamp: item.timestamp || new Date(),
+            priority: item.priority || 'medium'
+        };
+        this.items.set(id, trackedItem);
+        this.hashes.add(hash);
+        this.logger.debug('Tracked context item', {
+            id,
+            category: item.category,
+            position
+        });
+    }
+    /**
+     * Check if context with given ID exists
+     */ hasContext(id) {
+        return this.items.has(id);
+    }
+    /**
+     * Check if content with given hash exists
+     */ hasContentHash(content) {
+        const hash = this.hashContent(content);
+        return this.hashes.has(hash);
+    }
+    /**
+     * Check if similar content exists (fuzzy match)
+     */ hasSimilarContent(content) {
+        const normalized = this.normalizeContent(content);
+        for (const item of this.items.values()){
+            const itemNormalized = this.normalizeContent(item.content || '');
+            // Exact match
+            if (normalized === itemNormalized) {
+                return true;
+            }
+            // Substring match (one contains the other)
+            if (normalized.includes(itemNormalized) || itemNormalized.includes(normalized)) {
+                return true;
+            }
         }
+        return false;
     }
-    // Setup internal services
-    const logger = wrapLogger(finalConfig.logger, 'Recipe');
-    const parser$1 = create$4({
-        logger
-    });
-    const override$1 = create$1({
-        logger,
-        configDirs: finalConfig.overridePaths || [
-            "./"
-        ],
-        overrides: finalConfig.overrides || false
-    });
-    const loader$1 = create$2({
-        logger
-    });
-    // Create sections
-    const personaSection = create$8({
-        title: "Persona"
-    });
-    const instructionSection = create$8({
-        title: "Instruction"
-    });
-    const contentSection = create$8({
-        title: "Content"
-    });
-    const contextSection = create$8({
-        title: "Context"
-    });
-    // Process persona
-    if (finalConfig.persona) {
-        await processContentItem(finalConfig.persona, personaSection, 'persona', {
-            basePath: finalConfig.basePath,
-            parser: parser$1,
-            override: override$1,
-            loader: loader$1,
-            parameters: finalConfig.parameters});
+    /**
+     * Get context item by ID
+     */ get(id) {
+        return this.items.get(id);
     }
-    // Process instructions
-    for (const item of finalConfig.instructions || []){
-        await processContentItem(item, instructionSection, 'instruction', {
-            basePath: finalConfig.basePath,
-            parser: parser$1,
-            override: override$1,
-            loader: loader$1,
-            parameters: finalConfig.parameters});
+    /**
+     * Get all tracked context items
+     */ getAll() {
+        return Array.from(this.items.values());
     }
-    // Process content
-    for (const item of finalConfig.content || []){
-        await processContentItem(item, contentSection, 'content', {
-            basePath: finalConfig.basePath,
-            parser: parser$1,
-            override: override$1,
-            loader: loader$1,
-            parameters: finalConfig.parameters});
+    /**
+     * Get context items by category
+     */ getByCategory(category) {
+        return this.getAll().filter((item)=>item.category === category);
     }
-    // Process context
-    for (const item of finalConfig.context || []){
-        await processContentItem(item, contextSection, 'context', {
-            basePath: finalConfig.basePath,
-            parser: parser$1,
-            override: override$1,
-            loader: loader$1,
-            parameters: finalConfig.parameters});
+    /**
+     * Get context items by priority
+     */ getByPriority(priority) {
+        return this.getAll().filter((item)=>item.priority === priority);
     }
-    // Build and return prompt
-    return create$6({
-        persona: personaSection,
-        instructions: instructionSection,
-        contents: contentSection,
-        contexts: contextSection
-    });
-};
-const processContentItem = async (item, section, type, ctx)=>{
-    const sectionOptions = {
-        parameters: ctx.parameters
-    };
-    if (typeof item === 'string') {
-        // Simple string content
-        const parsedSection = await ctx.parser.parse(item, sectionOptions);
-        section.add(parsedSection);
-    } else if ('content' in item) {
-        // Inline content with options
-        const parsedSection = await ctx.parser.parse(item.content, {
-            ...sectionOptions,
-            title: item.title,
-            weight: item.weight
-        });
-        section.add(parsedSection);
-    } else if ('path' in item) {
-        // File path
-        const fullPath = path.join(ctx.basePath, item.path);
-        const parsedSection = await ctx.parser.parseFile(fullPath, {
-            ...sectionOptions,
-            title: item.title,
-            weight: item.weight
+    /**
+     * Get context items by source
+     */ getBySource(source) {
+        return this.getAll().filter((item)=>item.source === source);
+    }
+    /**
+     * Get all categories
+     */ getCategories() {
+        const categories = new Set();
+        this.items.forEach((item)=>{
+            if (item.category) {
+                categories.add(item.category);
+            }
         });
-        const overrideSection = await ctx.override.customize(item.path, parsedSection, sectionOptions);
-        section.add(overrideSection);
-    } else if ('directories' in item) {
-        // Directory loading
-        const sections = await ctx.loader.load(item.directories, {
-            ...sectionOptions,
-            title: item.title,
-            weight: item.weight
+        return Array.from(categories).sort();
+    }
+    /**
+     * Get context statistics
+     */ getStats() {
+        const byCategory = new Map();
+        const byPriority = new Map();
+        const bySource = new Map();
+        let oldestTimestamp;
+        let newestTimestamp;
+        this.items.forEach((item)=>{
+            // Category stats
+            if (item.category) {
+                byCategory.set(item.category, (byCategory.get(item.category) || 0) + 1);
+            }
+            // Priority stats
+            const priority = item.priority || 'medium';
+            byPriority.set(priority, (byPriority.get(priority) || 0) + 1);
+            // Source stats
+            if (item.source) {
+                bySource.set(item.source, (bySource.get(item.source) || 0) + 1);
+            }
+            // Timestamp stats
+            if (item.timestamp) {
+                if (!oldestTimestamp || item.timestamp < oldestTimestamp) {
+                    oldestTimestamp = item.timestamp;
+                }
+                if (!newestTimestamp || item.timestamp > newestTimestamp) {
+                    newestTimestamp = item.timestamp;
+                }
+            }
         });
-        section.add(sections);
+        return {
+            totalItems: this.items.size,
+            byCategory,
+            byPriority,
+            bySource,
+            oldestTimestamp,
+            newestTimestamp
+        };
     }
-};
-// ===== FLUENT RECIPE BUILDER =====
-const recipe = (basePath)=>{
-    const config = {
-        basePath
-    };
-    const builder = {
-        template: (name)=>{
-            config.template = name;
-            return builder;
-        },
+    /**
+     * Remove context item by ID
+     */ remove(id) {
+        const item = this.items.get(id);
+        if (item) {
+            this.items.delete(id);
+            this.hashes.delete(item.hash);
+            this.logger.debug('Removed context item', {
+                id
+            });
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Clear all tracked context
+     */ clear() {
+        this.items.clear();
+        this.hashes.clear();
+        this.logger.debug('Cleared all context');
+    }
+    /**
+     * Generate unique ID for context item
+     */ generateId() {
+        return `ctx-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    }
+    /**
+     * Hash content for deduplication
+     */ hashContent(content) {
+        return crypto.createHash('sha256').update(content).digest('hex').substring(0, 16);
+    }
+    /**
+     * Normalize content for comparison
+     */ normalizeContent(content) {
+        return content.replace(/\s+/g, ' ').trim().toLowerCase();
+    }
+    constructor(logger){
+        _define_property$7(this, "items", void 0);
+        _define_property$7(this, "hashes", void 0);
+        _define_property$7(this, "logger", void 0);
+        this.items = new Map();
+        this.hashes = new Set();
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'ContextManager');
+    }
+}
+
+function _define_property$6(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+// ===== CONVERSATION LOGGER =====
+/**
+ * ConversationLogger logs conversations to various formats.
+ *
+ * Features:
+ * - Multiple formats (JSON, Markdown, JSONL)
+ * - Automatic timestamping
+ * - Metadata tracking
+ * - Sensitive data redaction
+ * - Streaming support (JSONL)
+ *
+ * @example
+ * ```typescript
+ * const logger = new ConversationLogger({
+ *   enabled: true,
+ *   outputPath: 'logs/conversations',
+ *   format: 'json',
+ *   includeMetadata: true
+ * });
+ *
+ * logger.onConversationStart({ model: 'gpt-4o', startTime: new Date() });
+ * logger.onMessageAdded(message);
+ * const path = await logger.save();
+ * ```
+ */ class ConversationLogger {
+    /**
+     * Start conversation logging
+     */ onConversationStart(metadata) {
+        this.metadata = {
+            ...this.metadata,
+            ...metadata,
+            startTime: this.startTime
+        };
+        this.logger.debug('Conversation logging started', {
+            id: this.conversationId
+        });
+    }
+    /**
+     * Log a message
+     */ onMessageAdded(message, metadata) {
+        let content = message.content;
+        // Redact sensitive data if enabled
+        if (this.config.redactSensitive && content && typeof content === 'string') {
+            content = this.redactContent(content);
+        }
+        const loggedMessage = {
+            index: this.messageIndex++,
+            timestamp: new Date().toISOString(),
+            role: message.role,
+            content,
+            tool_calls: message.tool_calls,
+            tool_call_id: message.tool_call_id,
+            metadata
+        };
+        this.messages.push(loggedMessage);
+        // For JSONL format, append immediately
+        if (this.config.format === 'jsonl') {
+            this.appendToJSONL(loggedMessage).catch(this.config.onError);
+        }
+    }
+    /**
+     * Log a tool call
+     */ onToolCall(callId, toolName, iteration, args, result, duration, success, error) {
+        this.toolCalls.push({
+            callId,
+            toolName,
+            timestamp: new Date().toISOString(),
+            iteration,
+            arguments: args,
+            result,
+            duration,
+            success,
+            error
+        });
+    }
+    /**
+     * End conversation logging
+     */ onConversationEnd(_summary) {
+        this.metadata.endTime = new Date();
+        this.metadata.duration = this.metadata.endTime.getTime() - this.startTime.getTime();
+        this.logger.debug('Conversation logging ended', {
+            messages: this.messages.length,
+            duration: this.metadata.duration
+        });
+    }
+    /**
+     * Save conversation to disk
+     */ async save() {
+        if (!this.config.enabled) {
+            return '';
+        }
+        try {
+            const outputPath = await this.getOutputPath();
+            switch(this.config.format){
+                case 'json':
+                    await this.saveAsJSON(outputPath);
+                    break;
+                case 'markdown':
+                    await this.saveAsMarkdown(outputPath);
+                    break;
+                case 'jsonl':
+                    break;
+            }
+            this.config.onSaved(outputPath);
+            this.logger.info('Conversation saved', {
+                path: outputPath
+            });
+            return outputPath;
+        } catch (error) {
+            this.config.onError(error);
+            this.logger.error('Failed to save conversation', {
+                error
+            });
+            throw error;
+        }
+    }
+    /**
+     * Get logged conversation object
+     */ getConversation() {
+        return {
+            id: this.conversationId,
+            metadata: this.metadata,
+            messages: this.messages,
+            summary: {
+                totalMessages: this.messages.length,
+                toolCallsExecuted: this.toolCalls.length,
+                iterations: 0,
+                success: true
+            }
+        };
+    }
+    /**
+     * Generate unique conversation ID
+     */ generateId() {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const random = Math.random().toString(36).substring(2, 8);
+        return `conv-${timestamp}-${random}`;
+    }
+    /**
+     * Get output file path
+     */ async getOutputPath() {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const filename = this.config.filenameTemplate.replace('{timestamp}', timestamp).replace('{id}', this.conversationId).replace('{template}', this.metadata.template || 'default');
+        const ext = this.config.format === 'markdown' ? '.md' : '.json';
+        const fullPath = path.join(this.config.outputPath, filename + ext);
+        // Ensure directory exists
+        await fs.mkdir(path.dirname(fullPath), {
+            recursive: true
+        });
+        return fullPath;
+    }
+    /**
+     * Save as JSON
+     */ async saveAsJSON(outputPath) {
+        const data = {
+            id: this.conversationId,
+            metadata: this.metadata,
+            messages: this.messages,
+            summary: {
+                totalMessages: this.messages.length,
+                toolCallsExecuted: this.toolCalls.length,
+                iterations: 0,
+                success: true
+            }
+        };
+        await fs.writeFile(outputPath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    /**
+     * Save as Markdown
+     */ async saveAsMarkdown(outputPath) {
+        let markdown = `# Conversation Log\n\n`;
+        markdown += `**ID**: ${this.conversationId}\n`;
+        markdown += `**Started**: ${this.metadata.startTime.toISOString()}\n`;
+        if (this.metadata.duration) {
+            markdown += `**Duration**: ${(this.metadata.duration / 1000).toFixed(1)}s\n`;
+        }
+        markdown += `**Model**: ${this.metadata.model}\n`;
+        if (this.metadata.template) {
+            markdown += `**Template**: ${this.metadata.template}\n`;
+        }
+        markdown += `\n## Conversation\n\n`;
+        for (const msg of this.messages){
+            const time = new Date(msg.timestamp).toLocaleTimeString();
+            markdown += `### Message ${msg.index + 1} (${time}) - ${msg.role}\n\n`;
+            if (msg.content) {
+                markdown += `\`\`\`\n${msg.content}\n\`\`\`\n\n`;
+            }
+            if (msg.tool_calls) {
+                markdown += `**Tool Calls:**\n`;
+                for (const call of msg.tool_calls){
+                    markdown += `- ${call.function.name}: \`${call.function.arguments}\`\n`;
+                }
+                markdown += `\n`;
+            }
+            if (msg.metadata) {
+                markdown += `*Metadata: ${JSON.stringify(msg.metadata)}*\n\n`;
+            }
+        }
+        markdown += `## Summary\n\n`;
+        markdown += `- **Total Messages**: ${this.messages.length}\n`;
+        markdown += `- **Tool Calls**: ${this.toolCalls.length}\n`;
+        await fs.writeFile(outputPath, markdown, 'utf-8');
+    }
+    /**
+     * Append to JSONL file (streaming)
+     */ async appendToJSONL(message) {
+        const outputPath = await this.getOutputPath();
+        const line = JSON.stringify(message) + '\n';
+        await fs.appendFile(outputPath, line, 'utf-8');
+    }
+    /**
+     * Redact sensitive content
+     */ redactContent(content) {
+        let redacted = content;
+        // Apply custom patterns
+        for (const pattern of this.config.redactPatterns){
+            redacted = redacted.replace(pattern, '[REDACTED]');
+        }
+        // Default patterns
+        const defaultPatterns = [
+            /api[_-]?key[\s:="']+[\w-]+/gi,
+            /password[\s:="']+[\w-]+/gi,
+            /Bearer\s+[\w-]+/gi,
+            /sk-[a-zA-Z0-9]{48}/g
+        ];
+        for (const pattern of defaultPatterns){
+            redacted = redacted.replace(pattern, '[REDACTED]');
+        }
+        return redacted;
+    }
+    constructor(config, logger){
+        _define_property$6(this, "config", void 0);
+        _define_property$6(this, "conversationId", void 0);
+        _define_property$6(this, "metadata", void 0);
+        _define_property$6(this, "messages", void 0);
+        _define_property$6(this, "toolCalls", void 0);
+        _define_property$6(this, "startTime", void 0);
+        _define_property$6(this, "logger", void 0);
+        _define_property$6(this, "messageIndex", void 0);
+        this.config = {
+            outputPath: 'logs/conversations',
+            format: 'json',
+            filenameTemplate: 'conversation-{timestamp}',
+            includeMetadata: true,
+            includePrompt: false,
+            redactSensitive: false,
+            redactPatterns: [],
+            onSaved: ()=>{},
+            onError: ()=>{},
+            ...config
+        };
+        this.conversationId = this.generateId();
+        this.messages = [];
+        this.toolCalls = [];
+        this.startTime = new Date();
+        this.messageIndex = 0;
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'ConversationLogger');
+        this.metadata = {
+            startTime: this.startTime,
+            model: 'unknown'
+        };
+    }
+}
+/**
+ * ConversationReplayer loads and replays logged conversations.
+ *
+ * Features:
+ * - Load from various formats
+ * - Replay conversations
+ * - Compare replays with originals
+ * - Export to different formats
+ *
+ * @example
+ * ```typescript
+ * const replayer = await ConversationReplayer.load('logs/conv.json');
+ *
+ * console.log('Messages:', replayer.messages.length);
+ * console.log('Tool calls:', replayer.getToolCalls().length);
+ *
+ * const timeline = replayer.getTimeline();
+ * console.log('Events:', timeline.length);
+ * ```
+ */ class ConversationReplayer {
+    /**
+     * Load conversation from file
+     */ static async load(filePath, logger) {
+        const wlogger = wrapLogger(logger || DEFAULT_LOGGER, 'ConversationReplayer');
+        wlogger.debug('Loading conversation', {
+            path: filePath
+        });
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            // Determine format by extension
+            if (filePath.endsWith('.json')) {
+                const data = JSON.parse(content);
+                return new ConversationReplayer(data, logger);
+            } else if (filePath.endsWith('.jsonl')) {
+                const lines = content.trim().split('\n');
+                const messages = lines.map((line)=>JSON.parse(line));
+                const conversation = {
+                    id: `replayer-${Date.now()}`,
+                    metadata: {
+                        startTime: new Date(),
+                        model: 'unknown'
+                    },
+                    messages,
+                    summary: {
+                        totalMessages: messages.length,
+                        toolCallsExecuted: 0,
+                        iterations: 0,
+                        success: true
+                    }
+                };
+                return new ConversationReplayer(conversation, logger);
+            } else {
+                throw new Error(`Unsupported format: ${filePath}`);
+            }
+        } catch (error) {
+            wlogger.error('Failed to load conversation', {
+                path: filePath,
+                error
+            });
+            throw error;
+        }
+    }
+    /**
+     * Load latest conversation from directory
+     */ static async loadLatest(directory, logger) {
+        const files = await fs.readdir(directory);
+        const jsonFiles = files.filter((f)=>f.endsWith('.json')).sort().reverse();
+        if (jsonFiles.length === 0) {
+            throw new Error(`No conversation logs found in ${directory}`);
+        }
+        const latestPath = path.join(directory, jsonFiles[0]);
+        return ConversationReplayer.load(latestPath, logger);
+    }
+    /**
+     * Get all messages
+     */ get messages() {
+        return this.conversation.messages;
+    }
+    /**
+     * Get conversation metadata
+     */ getMetadata() {
+        return {
+            ...this.conversation.metadata
+        };
+    }
+    /**
+     * Get tool calls
+     */ getToolCalls() {
+        const toolCalls = [];
+        for (const msg of this.conversation.messages){
+            if (msg.tool_calls) {
+                for (const call of msg.tool_calls){
+                    toolCalls.push({
+                        callId: call.id,
+                        toolName: call.function.name,
+                        timestamp: msg.timestamp,
+                        iteration: 0,
+                        arguments: JSON.parse(call.function.arguments),
+                        result: null,
+                        duration: 0,
+                        success: true
+                    });
+                }
+            }
+        }
+        return toolCalls;
+    }
+    /**
+     * Get message at index
+     */ getMessageAt(index) {
+        return this.conversation.messages[index];
+    }
+    /**
+     * Get timeline of events
+     */ getTimeline() {
+        const events = [];
+        for (const msg of this.conversation.messages){
+            events.push({
+                timestamp: msg.timestamp,
+                iteration: 0,
+                type: 'message',
+                description: `${msg.role} message`
+            });
+        }
+        return events;
+    }
+    /**
+     * Export to format
+     */ async exportToFormat(format, outputPath) {
+        this.logger.debug('Exporting to format', {
+            format,
+            path: outputPath
+        });
+        switch(format){
+            case 'json':
+                await fs.writeFile(outputPath, JSON.stringify(this.conversation, null, 2), 'utf-8');
+                break;
+            case 'markdown':
+                await this.exportMarkdown(outputPath);
+                break;
+            case 'jsonl':
+                {
+                    const lines = this.messages.map((m)=>JSON.stringify(m)).join('\n');
+                    await fs.writeFile(outputPath, lines, 'utf-8');
+                    break;
+                }
+        }
+        return outputPath;
+    }
+    /**
+     * Export as markdown
+     */ async exportMarkdown(outputPath) {
+        let markdown = `# Conversation Log\n\n`;
+        markdown += `**ID**: ${this.conversation.id}\n`;
+        const startTime = typeof this.conversation.metadata.startTime === 'string' ? this.conversation.metadata.startTime : this.conversation.metadata.startTime.toISOString();
+        markdown += `**Started**: ${startTime}\n\n`;
+        for (const msg of this.conversation.messages){
+            markdown += `## ${msg.role.toUpperCase()} (${msg.index})\n\n`;
+            if (msg.content) {
+                markdown += `${msg.content}\n\n`;
+            }
+        }
+        await fs.writeFile(outputPath, markdown, 'utf-8');
+    }
+    constructor(conversation, logger){
+        _define_property$6(this, "conversation", void 0);
+        _define_property$6(this, "logger", void 0);
+        this.conversation = conversation;
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'ConversationReplayer');
+    }
+}
+
+function _define_property$5(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * MessageBuilder provides semantic, type-safe message construction.
+ *
+ * Features:
+ * - Semantic message types (system, user, assistant, tool)
+ * - Model-specific role handling (system vs developer)
+ * - Structured content composition
+ * - Metadata attachment
+ * - Format-aware building
+ *
+ * @example
+ * ```typescript
+ * const message = MessageBuilder.system()
+ *   .withContent('You are a helpful assistant')
+ *   .withInstructions(instructionSection)
+ *   .buildForModel('gpt-4o');
+ *
+ * const toolMessage = MessageBuilder.tool('call_123')
+ *   .withResult(result)
+ *   .withMetadata({ duration: 45 })
+ *   .build();
+ * ```
+ */ class MessageBuilder {
+    /**
+     * Create system message builder
+     */ static system(logger) {
+        return new MessageBuilder('system', logger);
+    }
+    /**
+     * Create user message builder
+     */ static user(logger) {
+        return new MessageBuilder('user', logger);
+    }
+    /**
+     * Create assistant message builder
+     */ static assistant(logger) {
+        return new MessageBuilder('assistant', logger);
+    }
+    /**
+     * Create tool message builder
+     */ static tool(callId, logger) {
+        const builder = new MessageBuilder('tool', logger);
+        builder.toolCallId = callId;
+        return builder;
+    }
+    /**
+     * Create developer message builder (for o1 models)
+     */ static developer(logger) {
+        return new MessageBuilder('developer', logger);
+    }
+    /**
+     * Add content to message
+     */ withContent(content) {
+        if (typeof content === 'string') {
+            this.contentParts.push(content);
+        } else {
+            // Format section
+            const formatter$1 = this.formatter || create$5();
+            this.contentParts.push(formatter$1.format(content));
+        }
+        return this;
+    }
+    /**
+     * Add persona section (typically for system messages)
+     */ withPersona(persona) {
+        const formatter$1 = this.formatter || create$5();
+        this.contentParts.push(formatter$1.format(persona));
+        return this;
+    }
+    /**
+     * Add instructions section
+     */ withInstructions(instructions) {
+        if (Array.isArray(instructions)) {
+            this.contentParts.push(instructions.join('\n'));
+        } else {
+            const formatter$1 = this.formatter || create$5();
+            this.contentParts.push(formatter$1.format(instructions));
+        }
+        return this;
+    }
+    /**
+     * Add context section
+     */ withContext(context) {
+        if (Array.isArray(context)) {
+            const contextStr = context.map((c)=>c.title ? `## ${c.title}\n\n${c.content}` : c.content).join('\n\n');
+            this.contentParts.push(contextStr);
+        } else {
+            const formatter$1 = this.formatter || create$5();
+            this.contentParts.push(formatter$1.format(context));
+        }
+        return this;
+    }
+    /**
+     * Set tool call ID (for tool messages)
+     */ withCallId(id) {
+        this.toolCallId = id;
+        return this;
+    }
+    /**
+     * Set tool result (for tool messages)
+     */ withResult(result) {
+        const resultStr = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+        this.contentParts.push(resultStr);
+        return this;
+    }
+    /**
+     * Add tool calls (for assistant messages)
+     */ withToolCalls(calls) {
+        this.toolCalls = calls;
+        return this;
+    }
+    /**
+     * Add metadata
+     */ withMetadata(metadata) {
+        this.metadata = {
+            ...this.metadata,
+            ...metadata
+        };
+        return this;
+    }
+    /**
+     * Add timestamp to metadata
+     */ withTimestamp() {
+        this.metadata.timestamp = new Date();
+        return this;
+    }
+    /**
+     * Set priority in metadata
+     */ withPriority(priority) {
+        this.metadata.priority = priority;
+        return this;
+    }
+    /**
+     * Set formatter for section rendering
+     */ withFormatter(formatter) {
+        this.formatter = formatter;
+        return this;
+    }
+    /**
+     * Build message with semantic role
+     */ build() {
+        const content = this.contentParts.join('\n\n');
+        const message = {
+            role: this.semanticRole,
+            content: content || null
+        };
+        // Add tool-specific fields
+        if (this.semanticRole === 'tool' && this.toolCallId) {
+            message.tool_call_id = this.toolCallId;
+        }
+        if (this.toolCalls) {
+            message.tool_calls = this.toolCalls;
+        }
+        return message;
+    }
+    /**
+     * Build message with model-specific role
+     */ buildForModel(model) {
+        const message = this.build();
+        // Handle model-specific role requirements
+        if (this.semanticRole === 'system') {
+            // O1 models use 'developer' instead of 'system'
+            if (model.startsWith('o1') || model.startsWith('o3') || model === 'o1-pro') {
+                message.role = 'developer';
+            }
+        }
+        return message;
+    }
+    constructor(role, logger){
+        _define_property$5(this, "semanticRole", void 0);
+        _define_property$5(this, "contentParts", void 0);
+        _define_property$5(this, "metadata", void 0);
+        _define_property$5(this, "formatter", void 0);
+        _define_property$5(this, "toolCallId", void 0);
+        _define_property$5(this, "toolCalls", void 0);
+        _define_property$5(this, "logger", void 0);
+        this.semanticRole = role;
+        this.contentParts = [];
+        this.metadata = {};
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'MessageBuilder');
+    }
+}
+/**
+ * Message template functions for common patterns
+ */ const MessageTemplates = {
+    /**
+     * System message for agentic tasks
+     */ agenticSystem: (persona, instructions)=>{
+        const builder = MessageBuilder.system();
+        if (persona) {
+            builder.withContent(persona);
+        }
+        if (instructions) {
+            builder.withInstructions(instructions);
+        }
+        return builder;
+    },
+    /**
+     * User query with optional context
+     */ userQuery: (query, context)=>{
+        const builder = MessageBuilder.user().withContent(query);
+        if (context) {
+            builder.withContext(context);
+        }
+        return builder;
+    },
+    /**
+     * Tool result with metadata
+     */ toolResult: (callId, result, metadata)=>{
+        const builder = MessageBuilder.tool(callId).withResult(result).withTimestamp();
+        if (metadata) {
+            builder.withMetadata(metadata);
+        }
+        return builder;
+    },
+    /**
+     * Tool success result
+     */ toolSuccess: (callId, result, duration)=>{
+        return MessageBuilder.tool(callId).withResult(result).withMetadata({
+            success: true,
+            duration
+        }).withTimestamp();
+    },
+    /**
+     * Tool failure result
+     */ toolFailure: (callId, error)=>{
+        return MessageBuilder.tool(callId).withResult({
+            error: error.message,
+            stack: error.stack
+        }).withMetadata({
+            success: false,
+            errorName: error.name
+        }).withTimestamp();
+    }
+};
+
+function _define_property$4(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+// ===== TOKEN COUNTER =====
+/**
+ * TokenCounter counts tokens using tiktoken for accurate model-specific counting.
+ *
+ * Features:
+ * - Model-specific token counting
+ * - Message overhead calculation
+ * - Tool call token estimation
+ * - Response token estimation
+ *
+ * @example
+ * ```typescript
+ * const counter = new TokenCounter('gpt-4o');
+ *
+ * const tokens = counter.count('Hello, world!');
+ * console.log(`Text uses ${tokens} tokens`);
+ *
+ * const messageTokens = counter.countMessage({
+ *   role: 'user',
+ *   content: 'What is the weather?'
+ * });
+ * ```
+ */ class TokenCounter {
+    /**
+     * Count tokens in text
+     */ count(text) {
+        if (!text) return 0;
+        return this.encoder.encode(text).length;
+    }
+    /**
+     * Count tokens in a single message
+     */ countMessage(message) {
+        let tokens = 4; // Base overhead per message
+        // Content tokens
+        if (message.content) {
+            tokens += this.count(message.content);
+        }
+        // Role tokens
+        tokens += 1;
+        // Tool call tokens
+        if (message.tool_calls) {
+            for (const toolCall of message.tool_calls){
+                tokens += this.count(JSON.stringify(toolCall));
+                tokens += 3; // Tool call overhead
+            }
+        }
+        // Tool result tokens
+        if (message.tool_call_id) {
+            tokens += this.count(message.tool_call_id);
+            tokens += 2; // Tool result overhead
+        }
+        return tokens;
+    }
+    /**
+     * Count tokens in entire conversation
+     */ countConversation(messages) {
+        let total = 3; // Conversation start overhead
+        for (const message of messages){
+            total += this.countMessage(message);
+        }
+        return total;
+    }
+    /**
+     * Count with additional overhead estimation
+     */ countWithOverhead(messages, includeToolOverhead = false) {
+        let total = this.countConversation(messages);
+        // Add tool definition overhead if tools are present
+        if (includeToolOverhead) {
+            const hasTools = messages.some((m)=>m.tool_calls && m.tool_calls.length > 0);
+            if (hasTools) {
+                total += 100; // Estimated tool definition overhead
+            }
+        }
+        return total;
+    }
+    /**
+     * Estimate tokens needed for response
+     */ estimateResponseTokens(messages) {
+        // Heuristic: average response is about 20% of input
+        const inputTokens = this.countConversation(messages);
+        return Math.max(500, Math.floor(inputTokens * 0.2));
+    }
+    /**
+     * Map RiotPrompt model to Tiktoken model
+     */ mapToTiktokenModel(model) {
+        switch(model){
+            case 'gpt-4o':
+            case 'gpt-4o-mini':
+                return 'gpt-4o';
+            case 'o1-preview':
+            case 'o1-mini':
+            case 'o1':
+            case 'o3-mini':
+            case 'o1-pro':
+                // O1 models use gpt-4o tokenization
+                return 'gpt-4o';
+            default:
+                return 'gpt-4o';
+        }
+    }
+    /**
+     * Free encoder resources
+     */ dispose() {
+        this.encoder.free();
+    }
+    constructor(model, logger){
+        _define_property$4(this, "encoder", void 0);
+        _define_property$4(this, "model", void 0);
+        _define_property$4(this, "logger", void 0);
+        this.model = model;
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'TokenCounter');
+        // Map RiotPrompt models to Tiktoken models
+        const tiktokenModel = this.mapToTiktokenModel(model);
+        this.encoder = tiktoken.encoding_for_model(tiktokenModel);
+        this.logger.debug('Created TokenCounter', {
+            model
+        });
+    }
+}
+// ===== TOKEN BUDGET MANAGER =====
+/**
+ * TokenBudgetManager manages token budgets and compression strategies.
+ *
+ * Features:
+ * - Monitor token usage
+ * - Automatic compression when budget exceeded
+ * - Multiple compression strategies
+ * - Priority-based message retention
+ * - Usage statistics and callbacks
+ *
+ * @example
+ * ```typescript
+ * const manager = new TokenBudgetManager({
+ *   max: 8000,
+ *   reserveForResponse: 1000,
+ *   strategy: 'priority-based',
+ *   onBudgetExceeded: 'compress'
+ * }, 'gpt-4o');
+ *
+ * // Check if message can be added
+ * if (manager.canAddMessage(message)) {
+ *   messages.push(message);
+ * } else {
+ *   // Compress conversation
+ *   messages = manager.compress(messages);
+ *   messages.push(message);
+ * }
+ * ```
+ */ class TokenBudgetManager {
+    /**
+     * Get current token usage
+     */ getCurrentUsage(messages) {
+        const used = this.counter.countConversation(messages);
+        const max = this.config.max;
+        const remaining = Math.max(0, max - used - this.config.reserveForResponse);
+        const percentage = used / max * 100;
+        return {
+            used,
+            max,
+            remaining,
+            percentage
+        };
+    }
+    /**
+     * Get remaining tokens available
+     */ getRemainingTokens(messages) {
+        return this.getCurrentUsage(messages).remaining;
+    }
+    /**
+     * Check if near token limit
+     */ isNearLimit(messages, threshold) {
+        const usage = this.getCurrentUsage(messages);
+        const checkThreshold = threshold !== null && threshold !== void 0 ? threshold : this.config.warningThreshold;
+        const isNear = usage.percentage >= checkThreshold * 100;
+        if (isNear) {
+            var _this_config_onWarning, _this_config;
+            (_this_config_onWarning = (_this_config = this.config).onWarning) === null || _this_config_onWarning === void 0 ? void 0 : _this_config_onWarning.call(_this_config, usage);
+        }
+        return isNear;
+    }
+    /**
+     * Check if a message can be added without exceeding budget
+     */ canAddMessage(message, currentMessages) {
+        const currentTokens = this.counter.countConversation(currentMessages);
+        const messageTokens = this.counter.countMessage(message);
+        const total = currentTokens + messageTokens + this.config.reserveForResponse;
+        return total <= this.config.max;
+    }
+    /**
+     * Compress messages according to strategy
+     */ compress(messages) {
+        var _this_config_onCompression, _this_config;
+        const before = messages.length;
+        const tokensBefore = this.counter.countConversation(messages);
+        const targetTokens = this.config.max - this.config.reserveForResponse;
+        this.logger.debug('Compressing messages', {
+            before,
+            tokensBefore,
+            targetTokens,
+            strategy: this.config.strategy
+        });
+        // No compression needed
+        if (tokensBefore <= targetTokens) {
+            return messages;
+        }
+        let compressed;
+        switch(this.config.strategy){
+            case 'priority-based':
+                compressed = this.compressByPriority(messages, targetTokens);
+                break;
+            case 'fifo':
+                compressed = this.compressFIFO(messages, targetTokens);
+                break;
+            case 'adaptive':
+                compressed = this.compressAdaptive(messages, targetTokens);
+                break;
+            case 'summarize':
+                // For now, fall back to FIFO (summarization would require LLM call)
+                compressed = this.compressFIFO(messages, targetTokens);
+                break;
+            default:
+                compressed = this.compressFIFO(messages, targetTokens);
+        }
+        const tokensAfter = this.counter.countConversation(compressed);
+        const stats = {
+            messagesBefore: before,
+            messagesAfter: compressed.length,
+            tokensBefore,
+            tokensAfter,
+            tokensSaved: tokensBefore - tokensAfter,
+            strategy: this.config.strategy
+        };
+        (_this_config_onCompression = (_this_config = this.config).onCompression) === null || _this_config_onCompression === void 0 ? void 0 : _this_config_onCompression.call(_this_config, stats);
+        this.logger.info('Compressed conversation', stats);
+        return compressed;
+    }
+    /**
+     * Compress by priority (keep high-priority messages)
+     */ compressByPriority(messages, targetTokens) {
+        // Calculate priority for each message
+        const withPriority = messages.map((msg, idx)=>({
+                message: msg,
+                priority: this.calculatePriority(msg, idx, messages.length),
+                tokens: this.counter.countMessage(msg),
+                index: idx
+            }));
+        // Sort by priority (descending)
+        withPriority.sort((a, b)=>b.priority - a.priority);
+        // Keep highest priority messages that fit in budget
+        const kept = [];
+        let totalTokens = 0;
+        for (const item of withPriority){
+            if (totalTokens + item.tokens <= targetTokens) {
+                kept.push(item);
+                totalTokens += item.tokens;
+            }
+        }
+        // Sort back to original order
+        kept.sort((a, b)=>a.index - b.index);
+        return kept.map((item)=>item.message);
+    }
+    /**
+     * Compress using FIFO (remove oldest first)
+     */ compressFIFO(messages, targetTokens) {
+        var _this_config_preserveRecent;
+        const preserved = [];
+        let totalTokens = 0;
+        // Always preserve system messages if configured
+        const systemMessages = messages.filter((m)=>m.role === 'system');
+        if (this.config.preserveSystem) {
+            for (const msg of systemMessages){
+                preserved.push(msg);
+                totalTokens += this.counter.countMessage(msg);
+            }
+        }
+        // Preserve recent messages
+        const recentCount = (_this_config_preserveRecent = this.config.preserveRecent) !== null && _this_config_preserveRecent !== void 0 ? _this_config_preserveRecent : 3;
+        const recentMessages = messages.slice(-recentCount).filter((m)=>m.role !== 'system');
+        for (const msg of recentMessages){
+            if (!preserved.includes(msg)) {
+                const tokens = this.counter.countMessage(msg);
+                if (totalTokens + tokens <= targetTokens) {
+                    preserved.push(msg);
+                    totalTokens += tokens;
+                }
+            }
+        }
+        // Add older messages if space available
+        const otherMessages = messages.filter((m)=>!preserved.includes(m) && m.role !== 'system');
+        for(let i = otherMessages.length - 1; i >= 0; i--){
+            const msg = otherMessages[i];
+            const tokens = this.counter.countMessage(msg);
+            if (totalTokens + tokens <= targetTokens) {
+                preserved.unshift(msg);
+                totalTokens += tokens;
+            } else {
+                break;
+            }
+        }
+        // Sort to maintain conversation order
+        return messages.filter((m)=>preserved.includes(m));
+    }
+    /**
+     * Adaptive compression based on conversation phase
+     */ compressAdaptive(messages, targetTokens) {
+        const messageCount = messages.length;
+        // Early phase: minimal compression (keep most messages)
+        if (messageCount <= 5) {
+            return this.compressFIFO(messages, targetTokens);
+        }
+        // Mid phase: moderate compression
+        if (messageCount <= 15) {
+            // Use FIFO but preserve more recent messages
+            const modifiedConfig = {
+                ...this.config,
+                preserveRecent: 5
+            };
+            const tempManager = new TokenBudgetManager(modifiedConfig, 'gpt-4o', this.logger);
+            return tempManager.compressFIFO(messages, targetTokens);
+        }
+        // Late phase: aggressive compression (priority-based)
+        return this.compressByPriority(messages, targetTokens);
+    }
+    /**
+     * Calculate message priority for compression
+     */ calculatePriority(message, index, total) {
+        let priority = 1.0;
+        // System messages: highest priority
+        if (message.role === 'system') {
+            priority = 10.0;
+        }
+        // Recent messages: higher priority
+        const recencyBonus = index / total;
+        priority += recencyBonus * 2;
+        // Tool results: moderate priority
+        if (message.role === 'tool') {
+            priority += 0.5;
+        }
+        // Messages with tool calls: keep for context
+        if (message.tool_calls && message.tool_calls.length > 0) {
+            priority += 0.8;
+        }
+        return priority;
+    }
+    /**
+     * Truncate to exact number of messages
+     */ truncate(messages, maxMessages) {
+        if (messages.length <= maxMessages) {
+            return messages;
+        }
+        // Keep system messages + recent messages
+        const systemMessages = messages.filter((m)=>m.role === 'system');
+        const otherMessages = messages.filter((m)=>m.role !== 'system');
+        const recentOther = otherMessages.slice(-(maxMessages - systemMessages.length));
+        return [
+            ...systemMessages,
+            ...recentOther
+        ];
+    }
+    /**
+     * Dispose resources
+     */ dispose() {
+        this.counter.dispose();
+    }
+    constructor(config, model, logger){
+        _define_property$4(this, "config", void 0);
+        _define_property$4(this, "counter", void 0);
+        _define_property$4(this, "logger", void 0);
+        this.config = {
+            warningThreshold: 0.8,
+            preserveRecent: 3,
+            preserveSystem: true,
+            preserveHighPriority: true,
+            onWarning: ()=>{},
+            onCompression: ()=>{},
+            ...config
+        };
+        this.counter = new TokenCounter(model, logger);
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'TokenBudgetManager');
+        this.logger.debug('Created TokenBudgetManager', {
+            max: this.config.max,
+            strategy: this.config.strategy
+        });
+    }
+}
+
+function _define_property$3(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+// ===== SCHEMAS =====
+const ConversationBuilderConfigSchema = zod.z.object({
+    model: zod.z.string(),
+    formatter: zod.z.any().optional(),
+    trackContext: zod.z.boolean().optional().default(true),
+    deduplicateContext: zod.z.boolean().optional().default(true)
+});
+// ===== CONVERSATION BUILDER =====
+/**
+ * ConversationBuilder manages multi-turn conversations with full lifecycle support.
+ *
+ * Features:
+ * - Initialize from RiotPrompt prompts
+ * - Add messages of any type (system, user, assistant, tool)
+ * - Handle tool calls and results
+ * - Inject dynamic context
+ * - Clone for parallel exploration
+ * - Serialize/deserialize for persistence
+ *
+ * @example
+ * ```typescript
+ * // Create from prompt
+ * const conversation = ConversationBuilder.create()
+ *   .fromPrompt(prompt, 'gpt-4o')
+ *   .build();
+ *
+ * // Add messages
+ * conversation.addUserMessage('Analyze this code');
+ *
+ * // Handle tool calls
+ * conversation.addAssistantWithToolCalls(null, toolCalls);
+ * conversation.addToolResult(toolCallId, result);
+ *
+ * // Export
+ * const messages = conversation.toMessages();
+ * ```
+ */ class ConversationBuilder {
+    /**
+     * Create a new ConversationBuilder instance
+     */ static create(config, logger) {
+        const defaultConfig = {
+            model: 'gpt-4o',
+            trackContext: true,
+            deduplicateContext: true,
+            ...config
+        };
+        return new ConversationBuilder(defaultConfig, logger);
+    }
+    /**
+     * Initialize conversation from a RiotPrompt prompt
+     */ fromPrompt(prompt, model) {
+        const targetModel = model || this.config.model;
+        this.logger.debug('Initializing from prompt', {
+            model: targetModel
+        });
+        // Use formatter (provided or create new one)
+        const formatter$1 = this.config.formatter || create$5();
+        const request = formatter$1.formatPrompt(targetModel, prompt);
+        // Add all messages from formatted request
+        request.messages.forEach((msg)=>{
+            this.state.messages.push(msg);
+        });
+        this.updateMetadata();
+        this.logger.debug('Initialized from prompt', {
+            messageCount: this.state.messages.length
+        });
+        return this;
+    }
+    /**
+     * Add a system message
+     */ addSystemMessage(content) {
+        this.logger.debug('Adding system message');
+        let messageContent;
+        if (typeof content === 'string') {
+            messageContent = content;
+        } else {
+            // Format section using formatter
+            const formatter$1 = this.config.formatter || create$5();
+            messageContent = formatter$1.format(content);
+        }
+        this.state.messages.push({
+            role: 'system',
+            content: messageContent
+        });
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Add a user message (with automatic budget management)
+     */ addUserMessage(content) {
+        this.logger.debug('Adding user message');
+        let messageContent;
+        if (typeof content === 'string') {
+            messageContent = content;
+        } else {
+            // Format section using formatter
+            const formatter$1 = this.config.formatter || create$5();
+            messageContent = formatter$1.format(content);
+        }
+        const message = {
+            role: 'user',
+            content: messageContent
+        };
+        // Check budget if enabled
+        if (this.budgetManager) {
+            if (!this.budgetManager.canAddMessage(message, this.state.messages)) {
+                this.logger.warn('Budget exceeded, compressing conversation');
+                this.state.messages = this.budgetManager.compress(this.state.messages);
+            }
+        }
+        this.state.messages.push(message);
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Add an assistant message
+     */ addAssistantMessage(content) {
+        this.logger.debug('Adding assistant message');
+        this.state.messages.push({
+            role: 'assistant',
+            content: content || ''
+        });
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Add an assistant message with tool calls
+     */ addAssistantWithToolCalls(content, toolCalls) {
+        this.logger.debug('Adding assistant message with tool calls', {
+            toolCount: toolCalls.length
+        });
+        this.state.messages.push({
+            role: 'assistant',
+            content: content,
+            tool_calls: toolCalls
+        });
+        this.state.metadata.toolCallCount += toolCalls.length;
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Add a tool result message
+     */ addToolResult(toolCallId, content, toolName) {
+        this.logger.debug('Adding tool result', {
+            toolCallId,
+            toolName
+        });
+        const message = {
+            role: 'tool',
+            tool_call_id: toolCallId,
+            content: content
+        };
+        if (toolName) {
+            message.name = toolName;
+        }
+        this.state.messages.push(message);
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Alias for addToolResult (more intuitive naming)
+     */ addToolMessage(toolCallId, content, toolName) {
+        return this.addToolResult(toolCallId, content, toolName);
+    }
+    /**
+     * Inject context into the conversation with advanced options
+     *
+     * @param context - Array of content items to inject
+     * @param options - Injection options (position, format, deduplication, etc.)
+     */ injectContext(context, options) {
+        var _this_config_deduplicateContext;
+        const opts = {
+            position: 'end',
+            format: 'structured',
+            deduplicate: (_this_config_deduplicateContext = this.config.deduplicateContext) !== null && _this_config_deduplicateContext !== void 0 ? _this_config_deduplicateContext : true,
+            deduplicateBy: 'id',
+            priority: 'medium',
+            weight: 1.0,
+            category: undefined,
+            source: undefined,
+            ...options
+        };
+        this.logger.debug('Injecting context', {
+            itemCount: context.length,
+            options: opts
+        });
+        // Filter out duplicates if enabled
+        const itemsToAdd = [];
+        for (const item of context){
+            const enrichedItem = {
+                ...item,
+                priority: item.priority || opts.priority,
+                weight: item.weight || opts.weight,
+                category: item.category || opts.category,
+                source: item.source || opts.source,
+                timestamp: item.timestamp || new Date()
+            };
+            // Check deduplication
+            if (opts.deduplicate) {
+                let skip = false;
+                switch(opts.deduplicateBy){
+                    case 'id':
+                        if (enrichedItem.id && this.state.contextManager.hasContext(enrichedItem.id)) {
+                            this.logger.debug('Skipping duplicate context by ID', {
+                                id: enrichedItem.id
+                            });
+                            skip = true;
+                        }
+                        break;
+                    case 'hash':
+                        if (this.state.contextManager.hasContentHash(enrichedItem.content)) {
+                            this.logger.debug('Skipping duplicate context by hash');
+                            skip = true;
+                        }
+                        break;
+                    case 'content':
+                        if (this.state.contextManager.hasSimilarContent(enrichedItem.content)) {
+                            this.logger.debug('Skipping duplicate context by content');
+                            skip = true;
+                        }
+                        break;
+                }
+                if (skip) {
+                    continue;
+                }
+            }
+            itemsToAdd.push(enrichedItem);
+        }
+        // Only proceed if we have items to add
+        if (itemsToAdd.length === 0) {
+            return this;
+        }
+        // Calculate position
+        const position = this.calculatePosition(opts.position);
+        // Format and inject
+        for (const item of itemsToAdd){
+            const formatted = this.formatContextItem(item, opts.format);
+            const contextMessage = {
+                role: 'user',
+                content: formatted
+            };
+            this.state.messages.splice(position, 0, contextMessage);
+            // Track in context manager
+            this.state.contextManager.track(item, position);
+        }
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Inject system-level context
+     */ injectSystemContext(context) {
+        this.logger.debug('Injecting system context');
+        let messageContent;
+        if (typeof context === 'string') {
+            messageContent = context;
+        } else {
+            const formatter$1 = this.config.formatter || create$5();
+            messageContent = formatter$1.format(context);
+        }
+        this.state.messages.push({
+            role: 'system',
+            content: messageContent
+        });
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Get the number of messages in the conversation
+     */ getMessageCount() {
+        return this.state.messages.length;
+    }
+    /**
+     * Get the last message in the conversation
+     */ getLastMessage() {
+        return this.state.messages[this.state.messages.length - 1];
+    }
+    /**
+     * Get all messages
+     */ getMessages() {
+        return [
+            ...this.state.messages
+        ];
+    }
+    /**
+     * Check if conversation has any tool calls
+     */ hasToolCalls() {
+        return this.state.metadata.toolCallCount > 0;
+    }
+    /**
+     * Get conversation metadata
+     */ getMetadata() {
+        return {
+            ...this.state.metadata
+        };
+    }
+    /**
+     * Export messages in OpenAI format
+     */ toMessages() {
+        return this.state.messages.map((msg)=>({
+                ...msg
+            }));
+    }
+    /**
+     * Serialize conversation to JSON
+     */ toJSON() {
+        const serialized = {
+            messages: this.state.messages,
+            metadata: {
+                ...this.state.metadata,
+                created: this.state.metadata.created.toISOString(),
+                lastModified: this.state.metadata.lastModified.toISOString()
+            },
+            contextProvided: Array.from(this.state.contextProvided)
+        };
+        return JSON.stringify(serialized, null, 2);
+    }
+    /**
+     * Restore conversation from JSON
+     */ static fromJSON(json, config, logger) {
+        const parsed = JSON.parse(json);
+        const builder = ConversationBuilder.create({
+            model: parsed.metadata.model,
+            ...config
+        }, logger);
+        // Restore state
+        builder.state.messages = parsed.messages;
+        builder.state.metadata = {
+            ...parsed.metadata,
+            created: new Date(parsed.metadata.created),
+            lastModified: new Date(parsed.metadata.lastModified)
+        };
+        builder.state.contextProvided = new Set(parsed.contextProvided);
+        return builder;
+    }
+    /**
+     * Clone the conversation for parallel exploration
+     */ clone() {
+        this.logger.debug('Cloning conversation');
+        const cloned = ConversationBuilder.create({
+            ...this.config
+        }, this.logger);
+        // Deep copy state (note: contextManager is already created in constructor)
+        cloned.state.messages = this.state.messages.map((msg)=>({
+                ...msg
+            }));
+        cloned.state.metadata = {
+            ...this.state.metadata
+        };
+        cloned.state.contextProvided = new Set(this.state.contextProvided);
+        // Copy context manager state
+        const allContext = this.state.contextManager.getAll();
+        allContext.forEach((item)=>{
+            cloned.state.contextManager.track(item, item.position);
+        });
+        return cloned;
+    }
+    /**
+     * Truncate conversation to last N messages
+     */ truncate(maxMessages) {
+        this.logger.debug('Truncating conversation', {
+            maxMessages,
+            current: this.state.messages.length
+        });
+        if (this.state.messages.length > maxMessages) {
+            this.state.messages = this.state.messages.slice(-maxMessages);
+            this.updateMetadata();
+        }
+        return this;
+    }
+    /**
+     * Remove all messages of a specific type
+     */ removeMessagesOfType(role) {
+        this.logger.debug('Removing messages of type', {
+            role
+        });
+        this.state.messages = this.state.messages.filter((msg)=>msg.role !== role);
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Get the context manager
+     */ getContextManager() {
+        return this.state.contextManager;
+    }
+    /**
+     * Get conversation state (for conditional injection)
+     */ getState() {
+        return {
+            messages: [
+                ...this.state.messages
+            ],
+            metadata: {
+                ...this.state.metadata
+            },
+            contextProvided: new Set(this.state.contextProvided),
+            contextManager: this.state.contextManager
+        };
+    }
+    // ===== SEMANTIC MESSAGE METHODS (Feature 5) =====
+    /**
+     * Add a system message using semantic builder
+     */ asSystem(content) {
+        const message = MessageBuilder.system(this.logger).withContent(content).withFormatter(this.config.formatter || create$5()).buildForModel(this.config.model);
+        this.state.messages.push(message);
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Add a user message using semantic builder
+     */ asUser(content) {
+        const message = MessageBuilder.user(this.logger).withContent(content).withFormatter(this.config.formatter || create$5()).buildForModel(this.config.model);
+        // Check budget if enabled
+        if (this.budgetManager) {
+            if (!this.budgetManager.canAddMessage(message, this.state.messages)) {
+                this.logger.warn('Budget exceeded, compressing conversation');
+                this.state.messages = this.budgetManager.compress(this.state.messages);
+            }
+        }
+        this.state.messages.push(message);
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Add an assistant message using semantic builder
+     */ asAssistant(content, toolCalls) {
+        const builder = MessageBuilder.assistant(this.logger).withFormatter(this.config.formatter || create$5());
+        if (content) {
+            builder.withContent(content);
+        }
+        if (toolCalls) {
+            builder.withToolCalls(toolCalls);
+        }
+        const message = builder.buildForModel(this.config.model);
+        if (toolCalls) {
+            this.state.metadata.toolCallCount += toolCalls.length;
+        }
+        this.state.messages.push(message);
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Add a tool result message using semantic builder
+     */ asTool(callId, result, metadata) {
+        const builder = MessageBuilder.tool(callId, this.logger).withResult(result);
+        if (metadata) {
+            builder.withMetadata(metadata);
+        }
+        const message = builder.buildForModel(this.config.model);
+        this.state.messages.push(message);
+        this.updateMetadata();
+        return this;
+    }
+    /**
+     * Configure token budget
+     */ withTokenBudget(config) {
+        this.logger.debug('Configuring token budget', {
+            max: config.max
+        });
+        this.budgetManager = new TokenBudgetManager(config, this.config.model, this.logger);
+        return this;
+    }
+    /**
+     * Configure conversation logging
+     */ withLogging(config) {
+        this.logger.debug('Configuring conversation logging');
+        this.conversationLogger = new ConversationLogger(config, this.logger);
+        this.conversationLogger.onConversationStart({
+            model: this.config.model,
+            startTime: new Date()
+        });
+        return this;
+    }
+    /**
+     * Save conversation log
+     */ async saveLog() {
+        if (!this.conversationLogger) {
+            throw new Error('Logging not enabled. Call withLogging() first.');
+        }
+        this.conversationLogger.onConversationEnd({
+            totalMessages: this.state.messages.length,
+            toolCallsExecuted: this.state.metadata.toolCallCount,
+            iterations: 0,
+            success: true
+        });
+        return await this.conversationLogger.save();
+    }
+    /**
+     * Get current token usage
+     */ getTokenUsage() {
+        if (!this.budgetManager) {
+            return {
+                used: 0,
+                max: Infinity,
+                remaining: Infinity,
+                percentage: 0
+            };
+        }
+        return this.budgetManager.getCurrentUsage(this.state.messages);
+    }
+    /**
+     * Manually compress conversation
+     */ compress(_strategy) {
+        if (this.budgetManager) {
+            this.state.messages = this.budgetManager.compress(this.state.messages);
+        }
+        return this;
+    }
+    /**
+     * Build and return the builder (for fluent API compatibility)
+     */ build() {
+        return this;
+    }
+    /**
+     * Calculate position for context injection
+     */ calculatePosition(position) {
+        if (typeof position === 'number') {
+            return Math.max(0, Math.min(position, this.state.messages.length));
+        }
+        switch(position){
+            case 'end':
+                return this.state.messages.length;
+            case 'before-last':
+                return Math.max(0, this.state.messages.length - 1);
+            case 'after-system':
+                {
+                    // Find last system message (reverse search for compatibility)
+                    let lastSystemIdx = -1;
+                    for(let i = this.state.messages.length - 1; i >= 0; i--){
+                        if (this.state.messages[i].role === 'system') {
+                            lastSystemIdx = i;
+                            break;
+                        }
+                    }
+                    return lastSystemIdx >= 0 ? lastSystemIdx + 1 : 0;
+                }
+            default:
+                return this.state.messages.length;
+        }
+    }
+    /**
+     * Format context item based on format option
+     */ formatContextItem(item, format) {
+        switch(format){
+            case 'structured':
+                {
+                    let result = `## ${item.title || 'Context'}\n\n${item.content}`;
+                    // Add metadata if available
+                    const metadata = [];
+                    if (item.source) {
+                        metadata.push(`Source: ${item.source}`);
+                    }
+                    if (item.timestamp) {
+                        metadata.push(`Timestamp: ${item.timestamp.toISOString()}`);
+                    }
+                    if (metadata.length > 0) {
+                        result += `\n\n_${metadata.join(' | ')}_`;
+                    }
+                    return result;
+                }
+            case 'inline':
+                return `Note: ${item.title ? `${item.title}: ` : ''}${item.content}`;
+            case 'reference':
+                return `[Context Reference: ${item.id || 'unknown'}]\nSee attached context${item.title ? ` for ${item.title}` : ''}`;
+            default:
+                return item.content;
+        }
+    }
+    /**
+     * Update metadata after state changes
+     */ updateMetadata() {
+        this.state.metadata.messageCount = this.state.messages.length;
+        this.state.metadata.lastModified = new Date();
+    }
+    constructor(config, logger){
+        _define_property$3(this, "state", void 0);
+        _define_property$3(this, "config", void 0);
+        _define_property$3(this, "logger", void 0);
+        _define_property$3(this, "budgetManager", void 0);
+        _define_property$3(this, "conversationLogger", void 0);
+        this.config = ConversationBuilderConfigSchema.parse(config);
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'ConversationBuilder');
+        this.state = {
+            messages: [],
+            metadata: {
+                model: this.config.model,
+                created: new Date(),
+                lastModified: new Date(),
+                messageCount: 0,
+                toolCallCount: 0
+            },
+            contextProvided: new Set(),
+            contextManager: new ContextManager(logger)
+        };
+        this.logger.debug('Created ConversationBuilder', {
+            model: this.config.model
+        });
+    }
+}
+
+function _define_property$2(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+// ===== VALIDATION SCHEMAS =====
+// Simplified parameter schema - just validate structure, not deep nesting
+const ToolSchema = zod.z.object({
+    name: zod.z.string().min(1),
+    description: zod.z.string().min(1),
+    parameters: zod.z.object({
+        type: zod.z.literal('object'),
+        properties: zod.z.record(zod.z.string(), zod.z.any()).default({}),
+        required: zod.z.array(zod.z.string()).optional()
+    }).passthrough(),
+    execute: zod.z.custom((val)=>typeof val === 'function', {
+        message: 'execute must be a function'
+    }),
+    category: zod.z.string().optional(),
+    cost: zod.z.enum([
+        'cheap',
+        'moderate',
+        'expensive'
+    ]).optional(),
+    examples: zod.z.array(zod.z.object({
+        scenario: zod.z.string(),
+        params: zod.z.any(),
+        expectedResult: zod.z.string()
+    })).optional()
+}).passthrough(); // Allow additional fields at tool level too
+// ===== TOOL REGISTRY =====
+/**
+ * ToolRegistry manages tool definitions and execution.
+ *
+ * Features:
+ * - Register and manage tools
+ * - Execute tools with context
+ * - Track usage statistics
+ * - Export to different formats (OpenAI, Anthropic)
+ * - Filter by category
+ *
+ * @example
+ * ```typescript
+ * const registry = ToolRegistry.create({
+ *   workingDirectory: process.cwd(),
+ *   logger: myLogger
+ * });
+ *
+ * registry.register({
+ *   name: 'read_file',
+ *   description: 'Read a file',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: {
+ *       path: { type: 'string', description: 'File path' }
+ *     },
+ *     required: ['path']
+ *   },
+ *   execute: async ({ path }) => {
+ *     return await fs.readFile(path, 'utf-8');
+ *   }
+ * });
+ *
+ * const result = await registry.execute('read_file', { path: 'test.txt' });
+ * ```
+ */ class ToolRegistry {
+    /**
+     * Create a new ToolRegistry instance
+     */ static create(context, logger) {
+        return new ToolRegistry(context, logger);
+    }
+    /**
+     * Register a single tool
+     */ register(tool) {
+        // Validate tool
+        try {
+            ToolSchema.parse(tool);
+        } catch (error) {
+            throw new Error(`Invalid tool definition for "${tool.name}": ${error}`);
+        }
+        if (this.tools.has(tool.name)) {
+            this.logger.warn(`Tool "${tool.name}" already registered, overwriting`);
+        }
+        this.tools.set(tool.name, tool);
+        this.usageStats.set(tool.name, {
+            calls: 0,
+            failures: 0,
+            totalDuration: 0
+        });
+        this.logger.debug('Registered tool', {
+            name: tool.name,
+            category: tool.category
+        });
+    }
+    /**
+     * Register multiple tools at once
+     */ registerAll(tools) {
+        this.logger.debug('Registering multiple tools', {
+            count: tools.length
+        });
+        tools.forEach((tool)=>this.register(tool));
+    }
+    /**
+     * Get a tool by name
+     */ get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Get all registered tools
+     */ getAll() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Get tools by category
+     */ getByCategory(category) {
+        return this.getAll().filter((tool)=>tool.category === category);
+    }
+    /**
+     * Check if a tool is registered
+     */ has(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Get number of registered tools
+     */ count() {
+        return this.tools.size;
+    }
+    /**
+     * Execute a tool by name
+     */ async execute(name, params) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new Error(`Tool "${name}" not found`);
+        }
+        this.logger.debug('Executing tool', {
+            name,
+            params
+        });
+        const startTime = Date.now();
+        const stats = this.usageStats.get(name);
+        stats.calls++;
+        try {
+            const result = await tool.execute(params, this.context);
+            const duration = Date.now() - startTime;
+            stats.totalDuration += duration;
+            this.logger.debug('Tool execution succeeded', {
+                name,
+                duration
+            });
+            return result;
+        } catch (error) {
+            stats.failures++;
+            this.logger.error('Tool execution failed', {
+                name,
+                error
+            });
+            throw error;
+        }
+    }
+    /**
+     * Execute multiple tools in sequence
+     */ async executeBatch(calls) {
+        this.logger.debug('Executing batch', {
+            count: calls.length
+        });
+        const results = [];
+        for (const call of calls){
+            try {
+                const result = await this.execute(call.name, call.params);
+                results.push(result);
+            } catch (error) {
+                results.push({
+                    error: String(error)
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Export tools in OpenAI format
+     */ toOpenAIFormat() {
+        return this.getAll().map((tool)=>({
+                type: 'function',
+                function: {
+                    name: tool.name,
+                    description: tool.description,
+                    parameters: {
+                        type: 'object',
+                        properties: tool.parameters.properties,
+                        required: tool.parameters.required
+                    }
+                }
+            }));
+    }
+    /**
+     * Export tools in Anthropic format
+     */ toAnthropicFormat() {
+        return this.getAll().map((tool)=>({
+                name: tool.name,
+                description: tool.description,
+                input_schema: {
+                    type: 'object',
+                    properties: tool.parameters.properties,
+                    required: tool.parameters.required
+                }
+            }));
+    }
+    /**
+     * Get tool definitions (without execute function)
+     */ getDefinitions() {
+        return this.getAll().map((tool)=>({
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.parameters,
+                category: tool.category,
+                cost: tool.cost,
+                examples: tool.examples
+            }));
+    }
+    /**
+     * Get usage statistics for all tools
+     */ getUsageStats() {
+        const stats = new Map();
+        this.usageStats.forEach((rawStats, name)=>{
+            stats.set(name, {
+                calls: rawStats.calls,
+                failures: rawStats.failures,
+                successRate: rawStats.calls > 0 ? (rawStats.calls - rawStats.failures) / rawStats.calls : 0,
+                averageDuration: rawStats.calls > 0 ? rawStats.totalDuration / rawStats.calls : undefined
+            });
+        });
+        return stats;
+    }
+    /**
+     * Get most frequently used tools
+     */ getMostUsed(limit = 5) {
+        const sorted = Array.from(this.usageStats.entries()).sort((a, b)=>b[1].calls - a[1].calls).slice(0, limit).map(([name])=>this.tools.get(name)).filter((tool)=>tool !== undefined);
+        return sorted;
+    }
+    /**
+     * Get list of all categories
+     */ getCategories() {
+        const categories = new Set();
+        this.getAll().forEach((tool)=>{
+            if (tool.category) {
+                categories.add(tool.category);
+            }
+        });
+        return Array.from(categories).sort();
+    }
+    /**
+     * Update execution context
+     */ updateContext(context) {
+        this.context = {
+            ...this.context,
+            ...context
+        };
+        this.logger.debug('Updated context', {
+            keys: Object.keys(context)
+        });
+    }
+    /**
+     * Get current context
+     */ getContext() {
+        return {
+            ...this.context
+        };
+    }
+    /**
+     * Clear all tools
+     */ clear() {
+        this.logger.debug('Clearing all tools');
+        this.tools.clear();
+        this.usageStats.clear();
+    }
+    /**
+     * Unregister a specific tool
+     */ unregister(name) {
+        if (this.tools.has(name)) {
+            this.tools.delete(name);
+            this.usageStats.delete(name);
+            this.logger.debug('Unregistered tool', {
+                name
+            });
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Reset usage statistics
+     */ resetStats() {
+        this.logger.debug('Resetting usage statistics');
+        this.usageStats.forEach((stats)=>{
+            stats.calls = 0;
+            stats.failures = 0;
+            stats.totalDuration = 0;
+        });
+    }
+    constructor(context = {}, logger){
+        _define_property$2(this, "tools", void 0);
+        _define_property$2(this, "context", void 0);
+        _define_property$2(this, "logger", void 0);
+        _define_property$2(this, "usageStats", void 0);
+        this.tools = new Map();
+        this.context = context;
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'ToolRegistry');
+        this.usageStats = new Map();
+        this.logger.debug('Created ToolRegistry');
+    }
+}
+
+function _define_property$1(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+// ===== METRICS COLLECTOR =====
+/**
+ * MetricsCollector gathers execution metrics during agentic execution.
+ *
+ * @example
+ * ```typescript
+ * const collector = new MetricsCollector();
+ *
+ * collector.recordToolCall('read_file', iteration, duration, true);
+ * collector.recordToolCall('search_code', iteration, duration, false, error);
+ *
+ * const metrics = collector.getMetrics(messages);
+ * ```
+ */ class MetricsCollector {
+    /**
+     * Record a tool execution
+     */ recordToolCall(name, iteration, duration, success, error, inputSize, outputSize) {
+        this.toolMetrics.push({
+            name,
+            iteration,
+            timestamp: new Date().toISOString(),
+            duration,
+            success,
+            error,
+            inputSize,
+            outputSize
+        });
+    }
+    /**
+     * Increment iteration count
+     */ incrementIteration() {
+        this.iterationCount++;
+    }
+    /**
+     * Get complete metrics
+     */ getMetrics(messages, model) {
+        const endTime = new Date();
+        const totalDuration = endTime.getTime() - this.startTime.getTime();
+        // Calculate tool statistics
+        const toolStats = this.calculateToolStats();
+        // Count unique tools
+        const uniqueTools = new Set(this.toolMetrics.map((m)=>m.name));
+        // Calculate investigation depth
+        const totalTools = this.toolMetrics.length;
+        const investigationDepth = totalTools < 3 ? 'shallow' : totalTools < 8 ? 'moderate' : 'deep';
+        // Calculate iteration efficiency
+        const iterationEfficiency = this.iterationCount > 0 ? totalTools / this.iterationCount : 0;
+        // Calculate token usage if model provided
+        let tokenUsage;
+        if (model) {
+            try {
+                const counter = new TokenCounter(model);
+                const total = counter.countConversation(messages);
+                counter.dispose();
+                tokenUsage = {
+                    total,
+                    systemPrompt: 0,
+                    userContent: 0,
+                    toolResults: 0,
+                    conversation: total
+                };
+            } catch (error) {
+                this.logger.warn('Could not calculate token usage', {
+                    error
+                });
+            }
+        }
+        return {
+            startTime: this.startTime,
+            endTime,
+            totalDuration,
+            iterations: this.iterationCount,
+            toolCallsExecuted: this.toolMetrics.length,
+            toolMetrics: this.toolMetrics,
+            toolStats,
+            messageCount: messages.length,
+            tokenUsage,
+            investigationDepth,
+            toolDiversity: uniqueTools.size,
+            iterationEfficiency
+        };
+    }
+    /**
+     * Calculate aggregated tool statistics
+     */ calculateToolStats() {
+        const stats = new Map();
+        // Group by tool name
+        const byTool = new Map();
+        for (const metric of this.toolMetrics){
+            if (!byTool.has(metric.name)) {
+                byTool.set(metric.name, []);
+            }
+            byTool.get(metric.name).push(metric);
+        }
+        // Calculate stats for each tool
+        for (const [name, metrics] of byTool){
+            const total = metrics.length;
+            const success = metrics.filter((m)=>m.success).length;
+            const failures = total - success;
+            const totalDuration = metrics.reduce((sum, m)=>sum + m.duration, 0);
+            const avgDuration = totalDuration / total;
+            const successRate = total > 0 ? success / total : 0;
+            stats.set(name, {
+                name,
+                total,
+                success,
+                failures,
+                totalDuration,
+                avgDuration,
+                successRate
+            });
+        }
+        return stats;
+    }
+    constructor(logger){
+        _define_property$1(this, "startTime", void 0);
+        _define_property$1(this, "toolMetrics", void 0);
+        _define_property$1(this, "iterationCount", void 0);
+        _define_property$1(this, "logger", void 0);
+        this.startTime = new Date();
+        this.toolMetrics = [];
+        this.iterationCount = 0;
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'MetricsCollector');
+    }
+}
+// ===== REFLECTION REPORT GENERATOR =====
+/**
+ * ReflectionReportGenerator generates analysis reports from execution metrics.
+ *
+ * @example
+ * ```typescript
+ * const generator = new ReflectionReportGenerator();
+ * const report = generator.generate(metrics, result);
+ *
+ * console.log('Success rate:', report.toolEffectiveness.overallSuccessRate);
+ * console.log('Recommendations:', report.recommendations.length);
+ * ```
+ */ class ReflectionReportGenerator {
+    /**
+     * Generate reflection report
+     */ generate(metrics, result) {
+        var _result_finalMessage;
+        this.logger.debug('Generating reflection report');
+        const report = {
+            id: `reflection-${Date.now()}`,
+            generated: new Date(),
+            summary: this.generateSummary(metrics),
+            toolEffectiveness: this.analyzeToolEffectiveness(metrics),
+            performanceInsights: this.analyzePerformance(metrics),
+            timeline: this.buildTimeline(metrics),
+            tokenUsage: metrics.tokenUsage,
+            qualityAssessment: this.assessQuality(metrics),
+            recommendations: this.generateRecommendations(metrics, result),
+            conversationHistory: result.conversation.getMessages(),
+            output: ((_result_finalMessage = result.finalMessage) === null || _result_finalMessage === void 0 ? void 0 : _result_finalMessage.content) || undefined
+        };
+        this.logger.info('Generated reflection report', {
+            recommendations: report.recommendations.length,
+            toolsAnalyzed: metrics.toolStats.size
+        });
+        return report;
+    }
+    /**
+     * Generate execution summary
+     */ generateSummary(metrics) {
+        const successfulTools = metrics.toolMetrics.filter((m)=>m.success).length;
+        const successRate = metrics.toolMetrics.length > 0 ? successfulTools / metrics.toolMetrics.length : 0;
+        return {
+            startTime: metrics.startTime,
+            endTime: metrics.endTime || new Date(),
+            totalDuration: metrics.totalDuration,
+            iterations: metrics.iterations,
+            toolCallsExecuted: metrics.toolCallsExecuted,
+            uniqueToolsUsed: metrics.toolDiversity,
+            successRate
+        };
+    }
+    /**
+     * Analyze tool effectiveness
+     */ analyzeToolEffectiveness(metrics) {
+        const successfulTools = metrics.toolMetrics.filter((m)=>m.success).length;
+        const overallSuccessRate = metrics.toolMetrics.length > 0 ? successfulTools / metrics.toolMetrics.length : 1;
+        // Find failed tools
+        const failedTools = Array.from(metrics.toolStats.values()).filter((stats)=>stats.failures > 0).map((stats)=>({
+                name: stats.name,
+                failures: stats.failures,
+                rate: stats.successRate
+            })).sort((a, b)=>b.failures - a.failures);
+        // Find slow tools (>1s average)
+        const slowTools = Array.from(metrics.toolStats.values()).filter((stats)=>stats.avgDuration > 1000).map((stats)=>({
+                name: stats.name,
+                avgDuration: stats.avgDuration
+            })).sort((a, b)=>b.avgDuration - a.avgDuration);
+        // Most used tools
+        const mostUsedTools = Array.from(metrics.toolStats.values()).map((stats)=>({
+                name: stats.name,
+                count: stats.total
+            })).sort((a, b)=>b.count - a.count).slice(0, 5);
+        return {
+            overallSuccessRate,
+            toolStats: metrics.toolStats,
+            failedTools,
+            slowTools,
+            mostUsedTools
+        };
+    }
+    /**
+     * Analyze performance
+     */ analyzePerformance(metrics) {
+        const avgIterationDuration = metrics.iterations > 0 ? metrics.totalDuration / metrics.iterations : 0;
+        // Find slowest and fastest tools
+        const toolsBySpeed = Array.from(metrics.toolStats.values()).sort((a, b)=>b.avgDuration - a.avgDuration);
+        const slowestTool = toolsBySpeed[0] ? {
+            name: toolsBySpeed[0].name,
+            duration: toolsBySpeed[0].avgDuration
+        } : undefined;
+        const fastestTool = toolsBySpeed[toolsBySpeed.length - 1] ? {
+            name: toolsBySpeed[toolsBySpeed.length - 1].name,
+            duration: toolsBySpeed[toolsBySpeed.length - 1].avgDuration
+        } : undefined;
+        // Identify bottlenecks
+        const bottlenecks = [];
+        if (slowestTool && slowestTool.duration > 1000) {
+            bottlenecks.push(`${slowestTool.name} averaging ${slowestTool.duration}ms`);
+        }
+        if (avgIterationDuration > 10000) {
+            bottlenecks.push(`Slow iterations averaging ${avgIterationDuration.toFixed(0)}ms`);
+        }
+        return {
+            totalDuration: metrics.totalDuration,
+            avgIterationDuration,
+            slowestTool,
+            fastestTool,
+            bottlenecks
+        };
+    }
+    /**
+     * Build execution timeline
+     */ buildTimeline(metrics) {
+        const events = [];
+        for (const metric of metrics.toolMetrics){
+            events.push({
+                timestamp: metric.timestamp,
+                iteration: metric.iteration,
+                type: 'tool-call',
+                description: `${metric.name}(${metric.success ? 'success' : 'failure'})`,
+                duration: metric.duration,
+                success: metric.success
+            });
+        }
+        return events.sort((a, b)=>new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    }
+    /**
+     * Assess investigation quality
+     */ assessQuality(metrics) {
+        const toolDiversity = metrics.toolDiversity;
+        const iterationEfficiency = metrics.iterationEfficiency;
+        // Calculate coverage (tools / iterations - aim for 1-2)
+        const coverage = metrics.iterations > 0 ? Math.min(1, metrics.toolCallsExecuted / (metrics.iterations * 2)) : 0;
+        // Overall quality score (0-1)
+        const depthScore = metrics.investigationDepth === 'deep' ? 1 : metrics.investigationDepth === 'moderate' ? 0.7 : 0.3;
+        const diversityScore = Math.min(1, toolDiversity / 5); // 5+ tools = max score
+        const efficiencyScore = Math.min(1, iterationEfficiency / 2); // 2 tools/iteration = max
+        const overall = (depthScore + diversityScore + efficiencyScore) / 3;
+        return {
+            investigationDepth: metrics.investigationDepth,
+            toolDiversity,
+            iterationEfficiency,
+            coverage,
+            overall
+        };
+    }
+    /**
+     * Generate recommendations
+     */ generateRecommendations(metrics, _result) {
+        const recommendations = [];
+        // Check for tool failures
+        const failedTools = Array.from(metrics.toolStats.values()).filter((stats)=>stats.failures > 0);
+        if (failedTools.length > 0) {
+            recommendations.push({
+                type: 'tool-failure',
+                severity: 'high',
+                message: `${failedTools.length} tool(s) had failures. Review tool implementations.`,
+                suggestion: 'Check error logs and validate tool parameters',
+                relatedTools: failedTools.map((t)=>t.name)
+            });
+        }
+        // Check for shallow investigation
+        if (metrics.investigationDepth === 'shallow' && metrics.toolCallsExecuted < 2) {
+            recommendations.push({
+                type: 'investigation-depth',
+                severity: 'medium',
+                message: 'Investigation was shallow. Consider adjusting strategy to encourage more tool usage.',
+                suggestion: 'Use investigateThenRespond strategy with requireMinimumTools'
+            });
+        }
+        // Check for slow tools
+        const slowTools = Array.from(metrics.toolStats.values()).filter((stats)=>stats.avgDuration > 1000);
+        if (slowTools.length > 0) {
+            recommendations.push({
+                type: 'performance',
+                severity: 'medium',
+                message: `${slowTools.length} tool(s) taking >1s. Consider optimization.`,
+                suggestion: 'Add caching, reduce scope, or optimize implementations',
+                relatedTools: slowTools.map((t)=>t.name)
+            });
+        }
+        // Check token usage
+        if (metrics.tokenUsage) {
+            if (metrics.tokenUsage.percentage && metrics.tokenUsage.percentage > 80) {
+                recommendations.push({
+                    type: 'token-budget',
+                    severity: 'high',
+                    message: `Token usage at ${metrics.tokenUsage.percentage.toFixed(1)}%. Increase budget or enable compression.`,
+                    suggestion: 'Increase max tokens or use priority-based compression'
+                });
+            }
+        }
+        return recommendations;
+    }
+    /**
+     * Format report as markdown
+     */ formatMarkdown(report) {
+        let markdown = `# Agentic Execution - Self-Reflection Report\n\n`;
+        markdown += `**Generated:** ${report.generated.toISOString()}\n`;
+        markdown += `**Duration:** ${(report.summary.totalDuration / 1000).toFixed(1)}s\n\n`;
+        markdown += `## Execution Summary\n\n`;
+        markdown += `- **Iterations**: ${report.summary.iterations}\n`;
+        markdown += `- **Tool Calls**: ${report.summary.toolCallsExecuted}\n`;
+        markdown += `- **Unique Tools**: ${report.summary.uniqueToolsUsed}\n`;
+        markdown += `- **Investigation Depth**: ${report.qualityAssessment.investigationDepth}\n`;
+        markdown += `- **Success Rate**: ${(report.summary.successRate * 100).toFixed(1)}%\n\n`;
+        markdown += `## Tool Effectiveness Analysis\n\n`;
+        markdown += `| Tool | Calls | Success | Failures | Success Rate | Avg Duration |\n`;
+        markdown += `|------|-------|---------|----------|--------------|---------------|\n`;
+        for (const [name, stats] of report.toolEffectiveness.toolStats){
+            markdown += `| ${name} | ${stats.total} | ${stats.success} | ${stats.failures} | `;
+            markdown += `${(stats.successRate * 100).toFixed(1)}% | ${stats.avgDuration.toFixed(0)}ms |\n`;
+        }
+        if (report.toolEffectiveness.failedTools.length > 0) {
+            markdown += `\n### Tools with Failures\n\n`;
+            for (const tool of report.toolEffectiveness.failedTools){
+                markdown += `- **${tool.name}**: ${tool.failures} failures (${(tool.rate * 100).toFixed(1)}% success)\n`;
+            }
+        }
+        if (report.toolEffectiveness.slowTools.length > 0) {
+            markdown += `\n### Slow Tools (>1s average)\n\n`;
+            for (const tool of report.toolEffectiveness.slowTools){
+                markdown += `- **${tool.name}**: ${(tool.avgDuration / 1000).toFixed(2)}s average\n`;
+            }
+        }
+        markdown += `\n## Quality Assessment\n\n`;
+        markdown += `- **Overall Score**: ${(report.qualityAssessment.overall * 100).toFixed(0)}%\n`;
+        markdown += `- **Investigation Depth**: ${report.qualityAssessment.investigationDepth}\n`;
+        markdown += `- **Tool Diversity**: ${report.qualityAssessment.toolDiversity} unique tools\n`;
+        markdown += `- **Efficiency**: ${report.qualityAssessment.iterationEfficiency.toFixed(2)} tools per iteration\n\n`;
+        if (report.recommendations.length > 0) {
+            markdown += `## Recommendations\n\n`;
+            const byPriority = {
+                high: report.recommendations.filter((r)=>r.severity === 'high'),
+                medium: report.recommendations.filter((r)=>r.severity === 'medium'),
+                low: report.recommendations.filter((r)=>r.severity === 'low')
+            };
+            if (byPriority.high.length > 0) {
+                markdown += `### 🔴 High Priority\n\n`;
+                byPriority.high.forEach((rec, i)=>{
+                    markdown += `${i + 1}. **${rec.message}**\n`;
+                    if (rec.suggestion) {
+                        markdown += `   - Suggestion: ${rec.suggestion}\n`;
+                    }
+                    markdown += `\n`;
+                });
+            }
+            if (byPriority.medium.length > 0) {
+                markdown += `### 🟡 Medium Priority\n\n`;
+                byPriority.medium.forEach((rec, i)=>{
+                    markdown += `${i + 1}. **${rec.message}**\n`;
+                    if (rec.suggestion) {
+                        markdown += `   - Suggestion: ${rec.suggestion}\n`;
+                    }
+                    markdown += `\n`;
+                });
+            }
+        }
+        if (report.output) {
+            markdown += `## Final Output\n\n`;
+            markdown += `\`\`\`\n${report.output}\n\`\`\`\n\n`;
+        }
+        markdown += `---\n\n`;
+        markdown += `*Report generated by RiotPrompt Agentic Reflection System*\n`;
+        return markdown;
+    }
+    constructor(logger){
+        _define_property$1(this, "logger", void 0);
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'ReflectionReportGenerator');
+    }
+}
+
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+// ===== STRATEGY EXECUTOR =====
+/**
+ * StrategyExecutor executes iteration strategies.
+ *
+ * Features:
+ * - Execute multi-phase strategies
+ * - Manage tool calls and results
+ * - Track state and metrics
+ * - Handle timeouts and errors
+ * - Provide lifecycle hooks
+ *
+ * @example
+ * ```typescript
+ * const executor = new StrategyExecutor(llmClient);
+ *
+ * const result = await executor.execute(
+ *   conversation,
+ *   toolRegistry,
+ *   strategy
+ * );
+ *
+ * console.log('Completed in', result.totalIterations, 'iterations');
+ * console.log('Used', result.toolCallsExecuted, 'tools');
+ * ```
+ */ class StrategyExecutor {
+    /**
+     * Enable reflection generation
+     */ withReflection(config) {
+        this.reflectionConfig = config;
+        return this;
+    }
+    /**
+     * Execute a strategy
+     */ async execute(conversation, tools, strategy) {
+        var _this_reflectionConfig;
+        const startTime = Date.now();
+        // Initialize metrics collector if reflection enabled
+        if ((_this_reflectionConfig = this.reflectionConfig) === null || _this_reflectionConfig === void 0 ? void 0 : _this_reflectionConfig.enabled) {
+            this.metricsCollector = new MetricsCollector(this.logger);
+        }
+        const state = {
+            phase: 0,
+            iteration: 0,
+            toolCallsExecuted: 0,
+            startTime,
+            insights: [],
+            findings: [],
+            errors: []
+        };
+        this.logger.info('Starting strategy execution', {
+            strategy: strategy.name
+        });
+        const context = {
+            conversation,
+            tools,
+            llm: this.llm,
+            state
+        };
+        try {
+            var _strategy_onStart, _this_reflectionConfig1, _strategy_onComplete;
+            // Initialize
+            await ((_strategy_onStart = strategy.onStart) === null || _strategy_onStart === void 0 ? void 0 : _strategy_onStart.call(strategy, context));
+            // Execute phases or single loop
+            const phases = strategy.phases || [
+                {
+                    name: 'default',
+                    maxIterations: strategy.maxIterations,
+                    toolUsage: 'encouraged'
+                }
+            ];
+            const phaseResults = [];
+            for (const phase of phases){
+                var _phase_skipIf, _strategy_onPhaseComplete;
+                // Check if should skip phase
+                if ((_phase_skipIf = phase.skipIf) === null || _phase_skipIf === void 0 ? void 0 : _phase_skipIf.call(phase, state)) {
+                    this.logger.debug('Skipping phase', {
+                        phase: phase.name
+                    });
+                    continue;
+                }
+                state.phase = phase.name;
+                state.iteration = 0;
+                this.logger.debug('Starting phase', {
+                    phase: phase.name
+                });
+                const phaseResult = await this.executePhase(conversation, tools, phase, state, strategy);
+                phaseResults.push(phaseResult);
+                // Track iteration for metrics
+                if (this.metricsCollector) {
+                    this.metricsCollector.incrementIteration();
+                }
+                await ((_strategy_onPhaseComplete = strategy.onPhaseComplete) === null || _strategy_onPhaseComplete === void 0 ? void 0 : _strategy_onPhaseComplete.call(strategy, phaseResult, state));
+                // Check if should continue
+                if (strategy.shouldContinue && !strategy.shouldContinue(state)) {
+                    this.logger.debug('Strategy decided to stop');
+                    break;
+                }
+            }
+            const duration = Date.now() - startTime;
+            const result = {
+                finalMessage: conversation.getLastMessage(),
+                phases: phaseResults,
+                totalIterations: state.iteration,
+                toolCallsExecuted: state.toolCallsExecuted,
+                duration,
+                success: true,
+                conversation
+            };
+            // Generate reflection if enabled
+            if (this.metricsCollector && ((_this_reflectionConfig1 = this.reflectionConfig) === null || _this_reflectionConfig1 === void 0 ? void 0 : _this_reflectionConfig1.enabled)) {
+                const metrics = this.metricsCollector.getMetrics(conversation.getMessages(), conversation.getMetadata().model);
+                const generator = new ReflectionReportGenerator(this.logger);
+                result.reflection = generator.generate(metrics, result);
+                // Save reflection if output path specified
+                if (this.reflectionConfig.outputPath && result.reflection) {
+                    await this.saveReflection(result.reflection, this.reflectionConfig);
+                }
+            }
+            await ((_strategy_onComplete = strategy.onComplete) === null || _strategy_onComplete === void 0 ? void 0 : _strategy_onComplete.call(strategy, result));
+            this.logger.info('Strategy execution complete', {
+                iterations: result.totalIterations,
+                toolCalls: result.toolCallsExecuted,
+                duration
+            });
+            return result;
+        } catch (error) {
+            this.logger.error('Strategy execution failed', {
+                error
+            });
+            return {
+                finalMessage: conversation.getLastMessage(),
+                phases: [],
+                totalIterations: state.iteration,
+                toolCallsExecuted: state.toolCallsExecuted,
+                duration: Date.now() - startTime,
+                success: false,
+                conversation
+            };
+        }
+    }
+    /**
+     * Save reflection report
+     */ async saveReflection(reflection, config) {
+        if (!config.outputPath) {
+            return;
+        }
+        try {
+            const fs = await import('fs/promises');
+            const path = await import('path');
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const filename = `reflection-${timestamp}.${config.format === 'json' ? 'json' : 'md'}`;
+            const fullPath = path.join(config.outputPath, filename);
+            // Ensure directory exists
+            await fs.mkdir(config.outputPath, {
+                recursive: true
+            });
+            // Save based on format
+            if (config.format === 'json') {
+                await fs.writeFile(fullPath, JSON.stringify(reflection, null, 2), 'utf-8');
+            } else {
+                const generator = new ReflectionReportGenerator(this.logger);
+                const markdown = generator.formatMarkdown(reflection);
+                await fs.writeFile(fullPath, markdown, 'utf-8');
+            }
+            this.logger.info('Reflection saved', {
+                path: fullPath
+            });
+        } catch (error) {
+            this.logger.error('Failed to save reflection', {
+                error
+            });
+        }
+    }
+    /**
+     * Execute a single phase
+     */ async executePhase(conversation, tools, phase, state, strategy) {
+        const phaseStartTools = state.toolCallsExecuted;
+        // Add phase instructions if provided
+        if (phase.instructions) {
+            conversation.asUser(phase.instructions);
+        }
+        // Iteration loop for this phase
+        for(let i = 0; i < phase.maxIterations; i++){
+            var _strategy_onIteration;
+            state.iteration++;
+            this.logger.debug('Iteration', {
+                phase: phase.name,
+                iteration: i + 1
+            });
+            // Check iteration hook
+            const action = await ((_strategy_onIteration = strategy.onIteration) === null || _strategy_onIteration === void 0 ? void 0 : _strategy_onIteration.call(strategy, i, state));
+            if (action === 'stop') {
+                break;
+            }
+            if (action === 'next-phase') {
+                break;
+            }
+            // Get LLM response
+            const toolsToProvide = phase.toolUsage !== 'forbidden' ? tools.toOpenAIFormat() : undefined;
+            const response = await this.llm.complete(conversation.toMessages(), toolsToProvide);
+            // Handle tool calls
+            if (response.tool_calls && response.tool_calls.length > 0) {
+                if (phase.toolUsage === 'forbidden') {
+                    this.logger.warn('Tool calls requested but forbidden in this phase');
+                    conversation.asAssistant(response.content);
+                    continue;
+                }
+                conversation.asAssistant(response.content, response.tool_calls);
+                // Execute tools
+                for (const toolCall of response.tool_calls){
+                    var _strategy_onToolCall;
+                    // Check if tool is allowed in this phase
+                    if (phase.allowedTools && !phase.allowedTools.includes(toolCall.function.name)) {
+                        this.logger.debug('Tool not allowed in phase', {
+                            tool: toolCall.function.name
+                        });
+                        continue;
+                    }
+                    // Check tool call hook
+                    const toolAction = await ((_strategy_onToolCall = strategy.onToolCall) === null || _strategy_onToolCall === void 0 ? void 0 : _strategy_onToolCall.call(strategy, toolCall, state));
+                    if (toolAction === 'skip') {
+                        continue;
+                    }
+                    // Execute tool
+                    const toolStart = Date.now();
+                    try {
+                        var _strategy_onToolResult;
+                        const result = await tools.execute(toolCall.function.name, JSON.parse(toolCall.function.arguments));
+                        const toolDuration = Date.now() - toolStart;
+                        const toolResult = {
+                            callId: toolCall.id,
+                            toolName: toolCall.function.name,
+                            result,
+                            duration: toolDuration
+                        };
+                        conversation.asTool(toolCall.id, result, {
+                            duration: toolDuration,
+                            success: true
+                        });
+                        state.toolCallsExecuted++;
+                        // Record metrics
+                        if (this.metricsCollector) {
+                            this.metricsCollector.recordToolCall(toolCall.function.name, state.iteration, toolDuration, true);
+                        }
+                        await ((_strategy_onToolResult = strategy.onToolResult) === null || _strategy_onToolResult === void 0 ? void 0 : _strategy_onToolResult.call(strategy, toolResult, state));
+                    } catch (error) {
+                        var _strategy_onToolResult1;
+                        this.logger.error('Tool execution failed', {
+                            tool: toolCall.function.name,
+                            error
+                        });
+                        const toolDuration = Date.now() - toolStart;
+                        const toolResult = {
+                            callId: toolCall.id,
+                            toolName: toolCall.function.name,
+                            result: null,
+                            error: error,
+                            duration: toolDuration
+                        };
+                        conversation.asTool(toolCall.id, {
+                            error: error.message
+                        }, {
+                            success: false,
+                            errorName: error.name
+                        });
+                        state.errors.push(error);
+                        // Record metrics
+                        if (this.metricsCollector) {
+                            this.metricsCollector.recordToolCall(toolCall.function.name, state.iteration, toolDuration, false, error.message);
+                        }
+                        await ((_strategy_onToolResult1 = strategy.onToolResult) === null || _strategy_onToolResult1 === void 0 ? void 0 : _strategy_onToolResult1.call(strategy, toolResult, state));
+                    }
+                }
+            } else {
+                // No tool calls - add response and potentially end phase
+                conversation.asAssistant(response.content);
+                // Check if this phase requires tool calls
+                if (phase.toolUsage === 'required' && state.toolCallsExecuted === phaseStartTools) {
+                    this.logger.warn('No tools used but required in phase');
+                // Continue to try again
+                } else if (phase.earlyExit !== false) {
+                    break;
+                }
+            }
+            // Check phase completion conditions
+            const toolCallsInPhase = state.toolCallsExecuted - phaseStartTools;
+            if (phase.minToolCalls && toolCallsInPhase < phase.minToolCalls) {
+                continue; // Need more tool calls
+            }
+            if (phase.maxToolCalls && toolCallsInPhase >= phase.maxToolCalls) {
+                break; // Hit max tool calls for phase
+            }
+            if (phase.continueIf && !phase.continueIf(state)) {
+                break; // Condition not met
+            }
+        }
+        return {
+            name: phase.name,
+            iterations: state.iteration,
+            toolCalls: state.toolCallsExecuted - phaseStartTools,
+            success: true,
+            insights: state.insights
+        };
+    }
+    constructor(llm, logger){
+        _define_property(this, "llm", void 0);
+        _define_property(this, "logger", void 0);
+        _define_property(this, "metricsCollector", void 0);
+        _define_property(this, "reflectionConfig", void 0);
+        this.llm = llm;
+        this.logger = wrapLogger(logger || DEFAULT_LOGGER, 'StrategyExecutor');
+    }
+}
+// ===== PRE-BUILT STRATEGIES =====
+/**
+ * Factory for creating iteration strategies
+ */ class IterationStrategyFactory {
+    /**
+     * Investigate then respond strategy
+     * Phase 1: Use tools to gather information
+     * Phase 2: Synthesize into final answer
+     */ static investigateThenRespond(config = {}) {
+        const { maxInvestigationSteps = 5, requireMinimumTools = 1, finalSynthesis = true } = config;
+        return {
+            name: 'investigate-then-respond',
+            description: 'Investigate using tools, then synthesize findings',
+            maxIterations: maxInvestigationSteps + (finalSynthesis ? 1 : 0),
+            phases: [
+                {
+                    name: 'investigate',
+                    maxIterations: maxInvestigationSteps,
+                    toolUsage: 'encouraged',
+                    minToolCalls: requireMinimumTools,
+                    earlyExit: false
+                },
+                ...finalSynthesis ? [
+                    {
+                        name: 'respond',
+                        maxIterations: 1,
+                        toolUsage: 'forbidden',
+                        instructions: 'Based on your investigation, provide a comprehensive answer.',
+                        requireFinalAnswer: true
+                    }
+                ] : []
+            ]
+        };
+    }
+    /**
+     * Multi-pass refinement strategy
+     * Generate, critique, refine repeatedly
+     */ static multiPassRefinement(config = {}) {
+        const { passes = 3, critiqueBetweenPasses = true } = config;
+        const phases = [];
+        for(let i = 0; i < passes; i++){
+            phases.push({
+                name: `pass-${i + 1}`,
+                maxIterations: 1,
+                toolUsage: 'optional',
+                instructions: i === 0 ? 'Generate your best response' : 'Refine your previous response based on the critique'
+            });
+            if (critiqueBetweenPasses && i < passes - 1) {
+                phases.push({
+                    name: `critique-${i + 1}`,
+                    maxIterations: 1,
+                    toolUsage: 'forbidden',
+                    instructions: 'Critique the previous response. What can be improved?'
+                });
+            }
+        }
+        return {
+            name: 'multi-pass-refinement',
+            description: 'Iteratively refine response through multiple passes',
+            maxIterations: passes * 2,
+            phases
+        };
+    }
+    /**
+     * Breadth-first investigation
+     * Explore broadly before going deep
+     */ static breadthFirst(config = {}) {
+        const { levelsDeep = 3, toolsPerLevel = 4 } = config;
+        const phases = [];
+        for(let level = 0; level < levelsDeep; level++){
+            phases.push({
+                name: `level-${level + 1}`,
+                maxIterations: toolsPerLevel,
+                toolUsage: 'encouraged',
+                minToolCalls: 1,
+                maxToolCalls: toolsPerLevel,
+                instructions: level === 0 ? 'Get a broad overview' : `Dive deeper into areas discovered in level ${level}`
+            });
+        }
+        return {
+            name: 'breadth-first',
+            description: 'Explore broadly at each level before going deeper',
+            maxIterations: levelsDeep * toolsPerLevel,
+            phases
+        };
+    }
+    /**
+     * Depth-first investigation
+     * Deep dive immediately
+     */ static depthFirst(config = {}) {
+        const { maxDepth = 5, backtrackOnFailure = true } = config;
+        return {
+            name: 'depth-first',
+            description: 'Deep dive investigation path',
+            maxIterations: maxDepth,
+            phases: [
+                {
+                    name: 'deep-dive',
+                    maxIterations: maxDepth,
+                    toolUsage: 'encouraged',
+                    adaptiveDepth: true
+                }
+            ],
+            shouldContinue: (state)=>{
+                // Continue if making progress
+                if (backtrackOnFailure && state.errors.length > 2) {
+                    return false;
+                }
+                return true;
+            }
+        };
+    }
+    /**
+     * Adaptive strategy
+     * Changes behavior based on progress
+     */ static adaptive(_config = {}) {
+        return {
+            name: 'adaptive',
+            description: 'Adapts strategy based on progress',
+            maxIterations: 20,
+            onIteration: async (iteration, state)=>{
+                // Change behavior based on iteration count
+                if (iteration < 5) {
+                    // Early: broad exploration
+                    return 'continue';
+                } else if (iteration < 15) {
+                    // Mid: focused investigation
+                    return 'continue';
+                } else {
+                    // Late: wrap up
+                    return state.toolCallsExecuted > 0 ? 'continue' : 'stop';
+                }
+            }
+        };
+    }
+    /**
+     * Simple iteration (basic tool-use loop)
+     */ static simple(config = {}) {
+        const { maxIterations = 10, allowTools = true } = config;
+        return {
+            name: 'simple',
+            description: 'Simple iteration loop',
+            maxIterations,
+            phases: [
+                {
+                    name: 'main',
+                    maxIterations,
+                    toolUsage: allowTools ? 'encouraged' : 'forbidden',
+                    earlyExit: true
+                }
+            ]
+        };
+    }
+}
+
+// ===== CONFIGURATION SCHEMAS =====
+const ContentItemSchema = zod.z.union([
+    zod.z.string(),
+    zod.z.object({
+        content: zod.z.string(),
+        title: zod.z.string().optional(),
+        weight: zod.z.number().optional()
+    }),
+    zod.z.object({
+        path: zod.z.string(),
+        title: zod.z.string().optional(),
+        weight: zod.z.number().optional()
+    }),
+    zod.z.object({
+        directories: zod.z.array(zod.z.string()),
+        title: zod.z.string().optional(),
+        weight: zod.z.number().optional()
+    })
+]);
+const RecipeConfigSchema = zod.z.object({
+    // Core settings
+    basePath: zod.z.string(),
+    logger: zod.z.any().optional().default(DEFAULT_LOGGER),
+    overridePaths: zod.z.array(zod.z.string()).optional().default([
+        "./"
+    ]),
+    overrides: zod.z.boolean().optional().default(false),
+    parameters: ParametersSchema.optional().default({}),
+    // Content sections
+    persona: ContentItemSchema.optional(),
+    instructions: zod.z.array(ContentItemSchema).optional().default([]),
+    content: zod.z.array(ContentItemSchema).optional().default([]),
+    context: zod.z.array(ContentItemSchema).optional().default([]),
+    // Templates and inheritance
+    extends: zod.z.string().optional(),
+    template: zod.z.string().optional(),
+    // Tool integration
+    tools: zod.z.any().optional(),
+    toolGuidance: zod.z.union([
+        zod.z.enum([
+            'auto',
+            'minimal',
+            'detailed'
+        ]),
+        zod.z.object({
+            strategy: zod.z.enum([
+                'adaptive',
+                'prescriptive',
+                'minimal'
+            ]),
+            includeExamples: zod.z.boolean().optional(),
+            explainWhenToUse: zod.z.boolean().optional(),
+            includeCategories: zod.z.boolean().optional(),
+            customInstructions: zod.z.string().optional()
+        })
+    ]).optional(),
+    toolCategories: zod.z.array(zod.z.string()).optional()
+});
+// User-customizable template registry
+let TEMPLATES = {};
+/**
+ * Register custom templates with the recipes system
+ *
+ * @example
+ * ```typescript
+ * // Register your own templates
+ * registerTemplates({
+ *   myWorkflow: {
+ *     persona: { path: "personas/my-persona.md" },
+ *     instructions: [{ path: "instructions/my-instructions.md" }]
+ *   },
+ *   anotherTemplate: {
+ *     persona: { content: "You are a helpful assistant" },
+ *     instructions: [{ content: "Follow these steps..." }]
+ *   }
+ * });
+ * ```
+ */ const registerTemplates = (templates)=>{
+    TEMPLATES = {
+        ...TEMPLATES,
+        ...templates
+    };
+};
+/**
+ * Get currently registered templates
+ */ const getTemplates = ()=>({
+        ...TEMPLATES
+    });
+/**
+ * Clear all registered templates
+ */ const clearTemplates = ()=>{
+    TEMPLATES = {};
+};
+// ===== TOOL GUIDANCE GENERATION =====
+/**
+ * Generate tool guidance instructions based on strategy
+ */ const generateToolGuidance = (tools, guidance)=>{
+    if (tools.length === 0) {
+        return '';
+    }
+    // Normalize guidance config
+    let config;
+    if (typeof guidance === 'string') {
+        switch(guidance){
+            case 'auto':
+            case 'detailed':
+                config = {
+                    strategy: 'adaptive',
+                    includeExamples: true,
+                    explainWhenToUse: true
+                };
+                break;
+            case 'minimal':
+                config = {
+                    strategy: 'minimal',
+                    includeExamples: false,
+                    explainWhenToUse: false
+                };
+                break;
+            default:
+                config = {
+                    strategy: 'adaptive'
+                };
+        }
+    } else {
+        config = guidance;
+    }
+    let output = '## Available Tools\n\n';
+    if (config.customInstructions) {
+        output += config.customInstructions + '\n\n';
+    }
+    // Group by category if enabled
+    if (config.includeCategories) {
+        const categorized = new Map();
+        tools.forEach((tool)=>{
+            const category = tool.category || 'General';
+            if (!categorized.has(category)) {
+                categorized.set(category, []);
+            }
+            categorized.get(category).push(tool);
+        });
+        categorized.forEach((categoryTools, category)=>{
+            output += `### ${category}\n\n`;
+            categoryTools.forEach((tool)=>{
+                output += formatToolGuidance(tool, config);
+            });
+        });
+    } else {
+        tools.forEach((tool)=>{
+            output += formatToolGuidance(tool, config);
+        });
+    }
+    return output;
+};
+const formatToolGuidance = (tool, config)=>{
+    let output = `**${tool.name}**`;
+    if (tool.cost) {
+        output += ` _(${tool.cost})_`;
+    }
+    output += `\n${tool.description}\n\n`;
+    if (config.strategy !== 'minimal') {
+        // Parameters
+        const required = tool.parameters.required || [];
+        const paramList = Object.entries(tool.parameters.properties).map(([name, param])=>{
+            const isRequired = required.includes(name);
+            return `- \`${name}\`${isRequired ? ' (required)' : ''}: ${param.description}`;
+        }).join('\n');
+        if (paramList) {
+            output += 'Parameters:\n' + paramList + '\n\n';
+        }
+        // When to use (adaptive and prescriptive)
+        if (config.explainWhenToUse && (config.strategy === 'adaptive' || config.strategy === 'prescriptive')) {
+            output += `**When to use:** ${tool.description}\n\n`;
+        }
+        // Examples
+        if (config.includeExamples && tool.examples && tool.examples.length > 0) {
+            output += '**Examples:**\n';
+            tool.examples.forEach((example)=>{
+                output += `- ${example.scenario}: \`${tool.name}(${JSON.stringify(example.params)})\`\n`;
+            });
+            output += '\n';
+        }
+    }
+    output += '---\n\n';
+    return output;
+};
+// ===== CORE RECIPE ENGINE =====
+const cook = async (config)=>{
+    // Parse and validate configuration with defaults
+    const validatedConfig = RecipeConfigSchema.parse({
+        overridePaths: [
+            "./"
+        ],
+        overrides: false,
+        parameters: {},
+        instructions: [],
+        content: [],
+        context: [],
+        ...config
+    });
+    // Handle template inheritance
+    let finalConfig = {
+        ...validatedConfig
+    };
+    if (validatedConfig.template) {
+        const template = TEMPLATES[validatedConfig.template];
+        if (template) {
+            finalConfig = {
+                ...validatedConfig,
+                persona: validatedConfig.persona || template.persona,
+                instructions: [
+                    ...template.instructions || [],
+                    ...validatedConfig.instructions || []
+                ],
+                content: [
+                    ...template.content || [],
+                    ...validatedConfig.content || []
+                ],
+                context: [
+                    ...template.context || [],
+                    ...validatedConfig.context || []
+                ]
+            };
+        }
+    }
+    // Setup internal services
+    const logger = wrapLogger(finalConfig.logger, 'Recipe');
+    const parser$1 = create$4({
+        logger
+    });
+    const override$1 = create$1({
+        logger,
+        configDirs: finalConfig.overridePaths || [
+            "./"
+        ],
+        overrides: finalConfig.overrides || false
+    });
+    const loader$1 = create$2({
+        logger
+    });
+    // Create sections
+    const personaSection = create$8({
+        title: "Persona"
+    });
+    const instructionSection = create$8({
+        title: "Instruction"
+    });
+    const contentSection = create$8({
+        title: "Content"
+    });
+    const contextSection = create$8({
+        title: "Context"
+    });
+    // Process persona
+    if (finalConfig.persona) {
+        await processContentItem(finalConfig.persona, personaSection, 'persona', {
+            basePath: finalConfig.basePath,
+            parser: parser$1,
+            override: override$1,
+            loader: loader$1,
+            parameters: finalConfig.parameters});
+    }
+    // Process instructions
+    for (const item of finalConfig.instructions || []){
+        await processContentItem(item, instructionSection, 'instruction', {
+            basePath: finalConfig.basePath,
+            parser: parser$1,
+            override: override$1,
+            loader: loader$1,
+            parameters: finalConfig.parameters});
+    }
+    // Generate tool guidance if tools are provided
+    if (finalConfig.tools) {
+        const tools = Array.isArray(finalConfig.tools) ? finalConfig.tools : finalConfig.tools.getAll();
+        // Filter by categories if specified
+        const filteredTools = finalConfig.toolCategories ? tools.filter((tool)=>finalConfig.toolCategories.includes(tool.category || '')) : tools;
+        if (filteredTools.length > 0 && finalConfig.toolGuidance) {
+            const guidance = generateToolGuidance(filteredTools, finalConfig.toolGuidance);
+            const toolSection = await parser$1.parse(guidance, {
+                parameters: finalConfig.parameters
+            });
+            instructionSection.add(toolSection);
+        }
+    }
+    // Process content
+    for (const item of finalConfig.content || []){
+        await processContentItem(item, contentSection, 'content', {
+            basePath: finalConfig.basePath,
+            parser: parser$1,
+            override: override$1,
+            loader: loader$1,
+            parameters: finalConfig.parameters});
+    }
+    // Process context
+    for (const item of finalConfig.context || []){
+        await processContentItem(item, contextSection, 'context', {
+            basePath: finalConfig.basePath,
+            parser: parser$1,
+            override: override$1,
+            loader: loader$1,
+            parameters: finalConfig.parameters});
+    }
+    // Build and return prompt
+    return create$6({
+        persona: personaSection,
+        instructions: instructionSection,
+        contents: contentSection,
+        contexts: contextSection
+    });
+};
+const processContentItem = async (item, section, type, ctx)=>{
+    const sectionOptions = {
+        parameters: ctx.parameters
+    };
+    if (typeof item === 'string') {
+        // Simple string content
+        const parsedSection = await ctx.parser.parse(item, sectionOptions);
+        section.add(parsedSection);
+    } else if ('content' in item) {
+        // Inline content with options
+        const parsedSection = await ctx.parser.parse(item.content, {
+            ...sectionOptions,
+            title: item.title,
+            weight: item.weight
+        });
+        section.add(parsedSection);
+    } else if ('path' in item) {
+        // File path
+        const fullPath = path.join(ctx.basePath, item.path);
+        const parsedSection = await ctx.parser.parseFile(fullPath, {
+            ...sectionOptions,
+            title: item.title,
+            weight: item.weight
+        });
+        const overrideSection = await ctx.override.customize(item.path, parsedSection, sectionOptions);
+        section.add(overrideSection);
+    } else if ('directories' in item) {
+        // Directory loading
+        const sections = await ctx.loader.load(item.directories, {
+            ...sectionOptions,
+            title: item.title,
+            weight: item.weight
+        });
+        section.add(sections);
+    }
+};
+// ===== FLUENT RECIPE BUILDER =====
+const recipe = (basePath)=>{
+    const config = {
+        basePath
+    };
+    const builder = {
+        template: (name)=>{
+            config.template = name;
+            return builder;
+        },
         with: (partialConfig)=>{
             Object.assign(config, partialConfig);
             return builder;
@@ -1649,7 +4911,61 @@ const recipe = (basePath)=>{
             config.overridePaths = paths;
             return builder;
         },
-        cook: ()=>cook(config)
+        tools: (tools)=>{
+            config.tools = tools;
+            return builder;
+        },
+        toolRegistry: (registry)=>{
+            config.tools = registry;
+            return builder;
+        },
+        toolGuidance: (guidance)=>{
+            config.toolGuidance = guidance;
+            return builder;
+        },
+        toolCategories: (categories)=>{
+            config.toolCategories = categories;
+            return builder;
+        },
+        cook: ()=>cook(config),
+        buildConversation: async (model, tokenBudget)=>{
+            const prompt = await cook(config);
+            const conversation = ConversationBuilder.create({
+                model
+            }, config.logger);
+            conversation.fromPrompt(prompt, model);
+            // Apply token budget if provided
+            if (tokenBudget) {
+                conversation.withTokenBudget(tokenBudget);
+            }
+            return conversation;
+        },
+        getToolRegistry: ()=>{
+            if (config.tools instanceof ToolRegistry) {
+                return config.tools;
+            } else if (Array.isArray(config.tools)) {
+                const registry = ToolRegistry.create({}, config.logger);
+                registry.registerAll(config.tools);
+                return registry;
+            }
+            return undefined;
+        },
+        executeWith: async (llm, strategy, tokenBudget)=>{
+            const prompt = await cook(config);
+            const conversation = ConversationBuilder.create({
+                model: 'gpt-4o'
+            }, config.logger);
+            conversation.fromPrompt(prompt, 'gpt-4o');
+            if (tokenBudget) {
+                conversation.withTokenBudget(tokenBudget);
+            }
+            const registry = builder.getToolRegistry();
+            if (!registry) {
+                throw new Error('Tools must be configured to use executeWith');
+            }
+            const executor = new StrategyExecutor(llm, config.logger);
+            return executor.execute(conversation, registry, strategy);
+        }
     };
     return builder;
 };
@@ -1658,6 +4974,7 @@ const recipes = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
     __proto__: null,
     clearTemplates,
     cook,
+    generateToolGuidance,
     getTemplates,
     recipe,
     registerTemplates
@@ -1665,11 +4982,24 @@ const recipes = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
 
 exports.Builder = builder;
 exports.Chat = chat;
+exports.ContextManager = ContextManager;
+exports.ConversationBuilder = ConversationBuilder;
+exports.ConversationLogger = ConversationLogger;
+exports.ConversationReplayer = ConversationReplayer;
 exports.Formatter = formatter;
+exports.IterationStrategyFactory = IterationStrategyFactory;
 exports.Loader = loader;
+exports.MessageBuilder = MessageBuilder;
+exports.MessageTemplates = MessageTemplates;
+exports.MetricsCollector = MetricsCollector;
 exports.Override = override;
 exports.Parser = parser;
 exports.Recipes = recipes;
+exports.ReflectionReportGenerator = ReflectionReportGenerator;
+exports.StrategyExecutor = StrategyExecutor;
+exports.TokenBudgetManager = TokenBudgetManager;
+exports.TokenCounter = TokenCounter;
+exports.ToolRegistry = ToolRegistry;
 exports.clearTemplates = clearTemplates;
 exports.cook = cook;
 exports.createContent = create$b;
@@ -1680,6 +5010,7 @@ exports.createPrompt = create$6;
 exports.createSection = create$8;
 exports.createTrait = create$7;
 exports.createWeighted = create$c;
+exports.generateToolGuidance = generateToolGuidance;
 exports.getTemplates = getTemplates;
 exports.recipe = recipe;
 exports.registerTemplates = registerTemplates;