@llm-dev-ops/agentics-cli 1.4.29 → 1.4.34

package/dist/bundled-agents/auto-optimizer-agents/dist/agents/token-optimization-agent/index.js

@@ -1,1096 +0,0 @@
-"use strict";
-/**
- * Token Optimization Agent
- *
- * A RECOMMENDATION agent that analyzes token usage patterns and generates
- * strategies to reduce token consumption without degrading output quality.
- *
- * Classification: ANALYSIS / RECOMMENDATION
- * Decision Type: token_optimization_recommendation | token_optimization_analysis
- *
- * This agent:
- * - Analyzes prompt and response token patterns
- * - Identifies token usage inefficiencies
- * - Recommends bounded prompt or configuration adjustments
- * - Provides quality impact assessments for each recommendation
- *
- * This agent MUST NOT:
- * - Execute optimizations directly
- * - Modify runtime behavior autonomously
- * - Intercept execution traffic
- * - Trigger retries
- * - Emit alerts (that is Sentinel)
- * - Enforce policies (that is Shield)
- * - Perform orchestration (that is LLM-Orchestrator)
- *
- * @module agents/token-optimization-agent
- * @version 1.0.0
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TokenOptimizationAgent = exports.DECISION_TYPE_ANALYZE = exports.DECISION_TYPE_RECOMMEND = exports.AGENT_VERSION = exports.AGENT_ID = void 0;
-exports.createTokenOptimizationAgent = createTokenOptimizationAgent;
-const ruvector_client_1 = require("../../services/ruvector-client");
-const types_1 = require("./types");
-// ============================================================================
-// Constants
-// ============================================================================
-exports.AGENT_ID = 'token-optimization-agent';
-exports.AGENT_VERSION = '1.0.0';
-exports.DECISION_TYPE_RECOMMEND = 'token_optimization_recommendation';
-exports.DECISION_TYPE_ANALYZE = 'token_optimization_analysis';
-// Pattern detection thresholds
-const PATTERN_THRESHOLDS = {
-    redundant_context_min_frequency: 0.1, // 10% of requests have redundant context
-    verbose_instructions_ratio: 0.3, // 30% more tokens than necessary
-    duplicate_examples_threshold: 0.2, // 20% duplicated
-    response_padding_threshold: 0.15, // 15% padding in responses
-    waste_significance_threshold: 100, // Min 100 tokens to be significant
-};
-// Quality preservation defaults
-const QUALITY_DEFAULTS = {
-    min_quality_threshold: 0.85, // 85% quality preservation
-    max_quality_drop_pct: 5, // Max 5% quality drop
-    high_risk_quality_threshold: 0.9, // High-value tasks need 90%
-};
-const DEFAULT_CONFIG = {
-    ruVectorClient: undefined,
-    enableTelemetry: true,
-    telemetryEndpoint: process.env.TELEMETRY_ENDPOINT || '',
-    maxOpportunities: 15,
-    minConfidenceThreshold: 0.6,
-    minSavingsThreshold: 1.0, // $1 minimum savings to report
-};
-// ============================================================================
-// Token Optimization Agent Class
-// ============================================================================
-/**
- * Token Optimization Agent - Analyzes and recommends token usage optimizations.
- *
- * This is a stateless, deterministic agent designed to run as a
- * Google Cloud Edge Function.
- */
-class TokenOptimizationAgent {
-    config;
-    ruVectorClient;
-    constructor(config = {}) {
-        this.config = {
-            ...DEFAULT_CONFIG,
-            ...config,
-        };
-        // Initialize RuVector client
-        this.ruVectorClient = this.config.ruVectorClient || (0, ruvector_client_1.createRuVectorClient)();
-    }
-    // --------------------------------------------------------------------------
-    // Public API - CLI Invocable Endpoints
-    // --------------------------------------------------------------------------
-    /**
-     * ANALYZE - Perform token usage analysis without generating recommendations.
-     * Use this for understanding current token patterns and identifying inefficiencies.
-     *
-     * CLI: npx @llm-auto-optimizer/cli token-optimization analyze [options]
-     */
-    async analyze(input) {
-        return this.execute(input, 'analyze');
-    }
-    /**
-     * RECOMMEND - Generate ranked token optimization recommendations.
-     * Primary entry point for the agent.
-     *
-     * CLI: npx @llm-auto-optimizer/cli token-optimization recommend [options]
-     */
-    async recommend(input) {
-        return this.execute(input, 'recommend');
-    }
-    /**
-     * SIMULATE - Simulate proposed token optimizations without persisting.
-     * Use for what-if analysis of specific optimization strategies.
-     *
-     * CLI: npx @llm-auto-optimizer/cli token-optimization simulate [options]
-     */
-    async simulate(input) {
-        return this.execute(input, 'simulate');
-    }
-    // --------------------------------------------------------------------------
-    // Core Execution Logic
-    // --------------------------------------------------------------------------
-    async execute(input, mode) {
-        const startTime = Date.now();
-        // Step 1: Validate input
-        this.validateInput(input);
-        // Step 2: Compute inputs hash for reproducibility
-        const inputsHash = this.hashInputs(input);
-        // Step 3: Detect token usage patterns
-        const patterns = this.detectPatterns(input.token_telemetry, input.analysis_depth);
-        // Step 4: Calculate efficiency metrics
-        const efficiencyMetrics = this.calculateEfficiencyMetrics(input.token_telemetry);
-        // Step 5: Identify optimization opportunities
-        const opportunities = mode === 'analyze'
-            ? []
-            : this.identifyOpportunities(input.token_telemetry, patterns, input.constraints, input.quality_threshold, input.focus_areas);
-        // Step 6: Evaluate constraints
-        const evaluatedConstraints = this.evaluateConstraints(input.constraints, opportunities);
-        // Step 7: Build output
-        const output = this.buildOutput(input, patterns, opportunities, evaluatedConstraints, efficiencyMetrics, startTime);
-        // Step 8: Build and persist DecisionEvent
-        const decisionType = mode === 'analyze' ? exports.DECISION_TYPE_ANALYZE : exports.DECISION_TYPE_RECOMMEND;
-        const decisionEvent = this.buildDecisionEvent(input, output, inputsHash, evaluatedConstraints, decisionType);
-        // Persist to ruvector-service (non-blocking — don't crash on persistence failure)
-        try {
-            await this.ruVectorClient.persistDecisionEvent(decisionEvent);
-        }
-        catch (persistErr) {
-            console.warn('[TokenOptimizationAgent] RuVector persistence failed (non-blocking):', persistErr instanceof Error ? persistErr.message : persistErr);
-        }
-        // Step 9: Emit telemetry (if enabled)
-        if (this.config.enableTelemetry) {
-            await this.emitTelemetry(decisionEvent, output, Date.now() - startTime);
-        }
-        return output;
-    }
-    // --------------------------------------------------------------------------
-    // Input Validation
-    // --------------------------------------------------------------------------
-    validateInput(input) {
-        if (!input || typeof input !== 'object') {
-            throw new Error('Invalid input: must be an object');
-        }
-        // Required fields
-        const requiredFields = [
-            'execution_ref',
-            'time_window',
-            'target_services',
-            'constraints',
-            'token_telemetry',
-            'analysis_depth',
-            'quality_threshold',
-        ];
-        for (const field of requiredFields) {
-            if (!(field in input)) {
-                throw new Error(`Invalid input: missing required field '${field}'`);
-            }
-        }
-        // Validate time window
-        const start = new Date(input.time_window.start);
-        const end = new Date(input.time_window.end);
-        if (isNaN(start.getTime()) || isNaN(end.getTime())) {
-            throw new Error('Invalid input: time_window dates must be valid ISO 8601');
-        }
-        if (end <= start) {
-            throw new Error('Invalid input: time_window end must be after start');
-        }
-        // Validate quality threshold
-        if (input.quality_threshold < 0 || input.quality_threshold > 1) {
-            throw new Error('Invalid input: quality_threshold must be between 0 and 1');
-        }
-        // Validate telemetry has data
-        if (!input.token_telemetry.aggregate) {
-            throw new Error('Invalid input: token_telemetry.aggregate is required');
-        }
-    }
-    hashInputs(input) {
-        const crypto = require('crypto');
-        const canonicalized = JSON.stringify(input, Object.keys(input).sort());
-        return crypto.createHash('sha256').update(canonicalized).digest('hex');
-    }
-    // --------------------------------------------------------------------------
-    // Pattern Detection
-    // --------------------------------------------------------------------------
-    detectPatterns(telemetry, depth) {
-        const patterns = [];
-        // Pattern 1: Redundant context detection
-        const redundantContextPattern = this.detectRedundantContext(telemetry);
-        if (redundantContextPattern)
-            patterns.push(redundantContextPattern);
-        // Pattern 2: Verbose instructions detection
-        const verbosePattern = this.detectVerboseInstructions(telemetry);
-        if (verbosePattern)
-            patterns.push(verbosePattern);
-        // Pattern 3: Response padding detection
-        const paddingPattern = this.detectResponsePadding(telemetry);
-        if (paddingPattern)
-            patterns.push(paddingPattern);
-        // Deep analysis patterns
-        if (depth === 'deep' || depth === 'standard') {
-            // Pattern 4: Duplicate examples
-            const duplicatePattern = this.detectDuplicateExamples(telemetry);
-            if (duplicatePattern)
-                patterns.push(duplicatePattern);
-            // Pattern 5: Inefficient structure
-            const structurePattern = this.detectInefficientStructure(telemetry);
-            if (structurePattern)
-                patterns.push(structurePattern);
-        }
-        // Deep-only patterns
-        if (depth === 'deep') {
-            // Pattern 6: Over-specification
-            const overSpecPattern = this.detectOverSpecification(telemetry);
-            if (overSpecPattern)
-                patterns.push(overSpecPattern);
-            // Pattern 7: Suboptimal encoding
-            const encodingPattern = this.detectSuboptimalEncoding(telemetry);
-            if (encodingPattern)
-                patterns.push(encodingPattern);
-        }
-        return patterns;
-    }
-    detectRedundantContext(telemetry) {
-        // Analyze input token distribution for repeated patterns
-        const aggregate = telemetry.aggregate;
-        const avgInput = aggregate.avg_input_per_request;
-        // Heuristic: If avg input is significantly higher than typical, suspect redundancy
-        const typicalAvgInput = 500; // baseline tokens
-        const redundancyRatio = (avgInput - typicalAvgInput) / avgInput;
-        if (redundancyRatio > PATTERN_THRESHOLDS.redundant_context_min_frequency) {
-            const wastedTokens = Math.floor(redundancyRatio * aggregate.total_input_tokens);
-            const costPerToken = this.getAverageCostPerToken(telemetry, 'input');
-            return {
-                pattern_id: `pattern-redundant-${Date.now()}`,
-                category: 'redundant_context',
-                description: 'Repeated context or system prompts detected across requests. Consider using context caching or prompt references.',
-                frequency: redundancyRatio,
-                token_waste: {
-                    avg_input_tokens: Math.floor(avgInput * redundancyRatio),
-                    avg_output_tokens: 0,
-                    total_tokens: wastedTokens,
-                    cost_usd: wastedTokens * costPerToken / 1000,
-                    waste_pct: redundancyRatio * 100,
-                },
-                affected_count: aggregate.total_requests,
-            };
-        }
-        return null;
-    }
-    detectVerboseInstructions(telemetry) {
-        // Analyze input/output ratio - verbose instructions often have high input/low output ratio
-        const aggregate = telemetry.aggregate;
-        const ioRatio = aggregate.avg_input_per_request / Math.max(aggregate.avg_output_per_request, 1);
-        // High I/O ratio (>3:1) may indicate verbose instructions
-        if (ioRatio > 3.0) {
-            const verbosityFactor = (ioRatio - 2.0) / ioRatio; // Above 2:1 is considered verbose
-            const wastedTokens = Math.floor(aggregate.total_input_tokens * verbosityFactor * 0.3);
-            const costPerToken = this.getAverageCostPerToken(telemetry, 'input');
-            return {
-                pattern_id: `pattern-verbose-${Date.now()}`,
-                category: 'verbose_instructions',
-                description: 'System prompts or instructions appear verbose relative to output. Consider condensing prompts while preserving intent.',
-                frequency: verbosityFactor,
-                token_waste: {
-                    avg_input_tokens: Math.floor(aggregate.avg_input_per_request * verbosityFactor * 0.3),
-                    avg_output_tokens: 0,
-                    total_tokens: wastedTokens,
-                    cost_usd: wastedTokens * costPerToken / 1000,
-                    waste_pct: (wastedTokens / aggregate.total_input_tokens) * 100,
-                },
-                affected_count: aggregate.total_requests,
-            };
-        }
-        return null;
-    }
-    detectResponsePadding(telemetry) {
-        // Analyze output token patterns for padding
-        const aggregate = telemetry.aggregate;
-        // Check for services with high output variability (may indicate padding)
-        let paddingServices = 0;
-        let totalPaddingWaste = 0;
-        for (const [_, metrics] of Object.entries(telemetry.by_service || {})) {
-            // Services with high token count but low efficiency may have padding
-            if (metrics.efficiency_score < 0.7 && metrics.avg_tokens_per_request > 1000) {
-                paddingServices++;
-                totalPaddingWaste += metrics.total_tokens * (1 - metrics.efficiency_score) * 0.5;
-            }
-        }
-        if (paddingServices > 0 && totalPaddingWaste > PATTERN_THRESHOLDS.waste_significance_threshold) {
-            const costPerToken = this.getAverageCostPerToken(telemetry, 'output');
-            return {
-                pattern_id: `pattern-padding-${Date.now()}`,
-                category: 'response_padding',
-                description: 'Model responses contain unnecessary padding, preambles, or verbose formatting. Consider using structured output or response trimming.',
-                frequency: paddingServices / Object.keys(telemetry.by_service || {}).length,
-                token_waste: {
-                    avg_input_tokens: 0,
-                    avg_output_tokens: Math.floor(totalPaddingWaste / aggregate.total_requests),
-                    total_tokens: Math.floor(totalPaddingWaste),
-                    cost_usd: totalPaddingWaste * costPerToken / 1000,
-                    waste_pct: (totalPaddingWaste / aggregate.total_output_tokens) * 100,
-                },
-                affected_count: paddingServices,
-            };
-        }
-        return null;
-    }
-    detectDuplicateExamples(telemetry) {
-        // Heuristic: High input tokens with many requests may indicate repeated examples
-        const aggregate = telemetry.aggregate;
-        if (aggregate.avg_input_per_request > 1500 && aggregate.total_requests > 100) {
-            const duplicateFactor = 0.15; // Assume 15% duplication
-            const wastedTokens = Math.floor(aggregate.total_input_tokens * duplicateFactor);
-            const costPerToken = this.getAverageCostPerToken(telemetry, 'input');
-            return {
-                pattern_id: `pattern-duplicate-${Date.now()}`,
-                category: 'duplicate_examples',
-                description: 'Few-shot examples may be repeated unnecessarily. Consider example caching or dynamic example selection.',
-                frequency: duplicateFactor,
-                token_waste: {
-                    avg_input_tokens: Math.floor(aggregate.avg_input_per_request * duplicateFactor),
-                    avg_output_tokens: 0,
-                    total_tokens: wastedTokens,
-                    cost_usd: wastedTokens * costPerToken / 1000,
-                    waste_pct: duplicateFactor * 100,
-                },
-                affected_count: aggregate.total_requests,
-            };
-        }
-        return null;
-    }
-    detectInefficientStructure(telemetry) {
-        // Analyze model-level metrics for structural inefficiencies
-        const inefficientModels = [];
-        let totalWaste = 0;
-        for (const [modelId, metrics] of Object.entries(telemetry.by_model || {})) {
-            const ref = types_1.TOKEN_MODEL_REFERENCE[modelId];
-            if (ref) {
-                // Compare actual I/O ratio with expected
-                const actualIoRatio = metrics.avg_input_tokens / Math.max(metrics.avg_output_tokens, 1);
-                if (actualIoRatio > 4.0) { // Unusually high
-                    inefficientModels.push(modelId);
-                    totalWaste += metrics.total_input_tokens * 0.2; // Assume 20% structure inefficiency
-                }
-            }
-        }
-        if (inefficientModels.length > 0 && totalWaste > PATTERN_THRESHOLDS.waste_significance_threshold) {
-            const costPerToken = this.getAverageCostPerToken(telemetry, 'input');
-            return {
-                pattern_id: `pattern-structure-${Date.now()}`,
-                category: 'inefficient_structure',
-                description: `Prompt structure appears inefficient for models: ${inefficientModels.join(', ')}. Consider restructuring prompts for better token efficiency.`,
-                frequency: inefficientModels.length / Object.keys(telemetry.by_model || {}).length,
-                token_waste: {
-                    avg_input_tokens: Math.floor(totalWaste / telemetry.aggregate.total_requests),
-                    avg_output_tokens: 0,
-                    total_tokens: Math.floor(totalWaste),
-                    cost_usd: totalWaste * costPerToken / 1000,
-                    waste_pct: (totalWaste / telemetry.aggregate.total_input_tokens) * 100,
-                },
-                affected_count: inefficientModels.length,
-            };
-        }
-        return null;
-    }
-    detectOverSpecification(telemetry) {
-        // Deep analysis: Check for over-specification in high-token requests
-        const aggregate = telemetry.aggregate;
-        // High average input with low quality variance suggests over-specification
-        if (aggregate.avg_input_per_request > 2000) {
-            const overSpecFactor = 0.1; // Conservative estimate
-            const wastedTokens = Math.floor(aggregate.total_input_tokens * overSpecFactor);
-            const costPerToken = this.getAverageCostPerToken(telemetry, 'input');
-            return {
-                pattern_id: `pattern-overspec-${Date.now()}`,
-                category: 'over_specification',
-                description: 'Prompts may contain more detail than necessary for the task. Consider simplifying requirements or using tiered prompting.',
-                frequency: overSpecFactor,
-                token_waste: {
-                    avg_input_tokens: Math.floor(aggregate.avg_input_per_request * overSpecFactor),
-                    avg_output_tokens: 0,
-                    total_tokens: wastedTokens,
-                    cost_usd: wastedTokens * costPerToken / 1000,
-                    waste_pct: overSpecFactor * 100,
-                },
-                affected_count: aggregate.total_requests,
-            };
-        }
-        return null;
-    }
-    detectSuboptimalEncoding(telemetry) {
-        // Deep analysis: Check for encoding inefficiencies
-        // This would require actual token-level analysis in production
-        // Placeholder heuristic based on tokens-per-character ratio
-        const aggregate = telemetry.aggregate;
-        // If we have character data (not available in current telemetry),
-        // we could detect encoding issues. For now, return null.
-        return null;
-    }
-    // --------------------------------------------------------------------------
-    // Efficiency Metrics Calculation
-    // --------------------------------------------------------------------------
-    calculateEfficiencyMetrics(telemetry) {
-        const aggregate = telemetry.aggregate;
-        // Input efficiency: Compare to baseline (500 tokens avg)
-        const baselineInput = 500;
-        const inputEfficiency = Math.min(1.0, baselineInput / aggregate.avg_input_per_request);
-        // Output efficiency: Based on existing efficiency score
-        const outputEfficiency = aggregate.efficiency_score || 0.7;
-        // Context utilization: Based on I/O ratio (ideal is 1:1 to 2:1)
-        const ioRatio = aggregate.avg_input_per_request / Math.max(aggregate.avg_output_per_request, 1);
-        const contextUtilization = ioRatio <= 2.0 ? 1.0 : Math.max(0.3, 1.0 - (ioRatio - 2.0) * 0.1);
-        // Compression potential: Based on detected waste
-        const totalWastePct = Math.min(0.5, 1 - aggregate.efficiency_score);
-        const compressionPotential = totalWastePct;
-        // Overall efficiency
-        const overall = (inputEfficiency * 0.3 + outputEfficiency * 0.3 + contextUtilization * 0.4);
-        return {
-            overall: Math.round(overall * 100) / 100,
-            input_efficiency: Math.round(inputEfficiency * 100) / 100,
-            output_efficiency: Math.round(outputEfficiency * 100) / 100,
-            context_utilization: Math.round(contextUtilization * 100) / 100,
-            compression_potential: Math.round(compressionPotential * 100) / 100,
-        };
-    }
-    // --------------------------------------------------------------------------
-    // Opportunity Identification
-    // --------------------------------------------------------------------------
-    identifyOpportunities(telemetry, patterns, constraints, qualityThreshold, focusAreas) {
-        const opportunities = [];
-        // Generate opportunities from detected patterns
-        for (const pattern of patterns) {
-            // Skip if pattern is not in focus areas (when specified)
-            if (focusAreas && focusAreas.length > 0 && !focusAreas.includes(pattern.category)) {
-                continue;
-            }
-            // Skip low-impact patterns
-            if (pattern.token_waste.cost_usd < this.config.minSavingsThreshold) {
-                continue;
-            }
-            const opportunity = this.patternToOpportunity(pattern, telemetry, qualityThreshold);
-            if (opportunity && !this.violatesHardConstraints(opportunity, constraints)) {
-                opportunities.push(opportunity);
-            }
-        }
-        // Generate model-specific opportunities
-        const modelOpportunities = this.identifyModelOpportunities(telemetry, qualityThreshold);
-        for (const opp of modelOpportunities) {
-            if (!this.violatesHardConstraints(opp, constraints)) {
-                opportunities.push(opp);
-            }
-        }
-        // Sort by priority and limit
-        return opportunities
-            .sort((a, b) => b.priority - a.priority)
-            .slice(0, this.config.maxOpportunities);
-    }
-    patternToOpportunity(pattern, telemetry, qualityThreshold) {
-        const opportunityId = `opp-${pattern.pattern_id}`;
-        let type;
-        let actions = [];
-        let qualityImpact;
-        switch (pattern.category) {
-            case 'redundant_context':
-                type = 'context_caching';
-                qualityImpact = {
-                    expected_change: 0,
-                    confidence: 0.95,
-                    risk_level: 'none',
-                    affected_metrics: [],
-                };
-                actions = [{
-                        action_id: `action-${opportunityId}-1`,
-                        type: 'add',
-                        target: 'model_config',
-                        description: 'Enable context caching for repeated system prompts',
-                        proposed: { context_cache: { enabled: true, ttl_seconds: 3600 } },
-                        token_impact: { input_delta: -pattern.token_waste.avg_input_tokens, output_delta: 0 },
-                    }];
-                break;
-            case 'verbose_instructions':
-                type = 'prompt_compression';
-                qualityImpact = {
-                    expected_change: -0.02,
-                    confidence: 0.8,
-                    risk_level: 'low',
-                    affected_metrics: ['instruction_following'],
-                    mitigations: ['A/B test compressed prompts', 'Monitor quality metrics'],
-                };
-                actions = [{
-                        action_id: `action-${opportunityId}-1`,
-                        type: 'modify',
-                        target: 'prompt_template',
-                        description: 'Compress verbose instructions while preserving intent',
-                        current: 'Verbose system prompt (see analysis)',
-                        proposed: 'Condensed system prompt with key directives only',
-                        token_impact: { input_delta: -pattern.token_waste.avg_input_tokens, output_delta: 0 },
-                    }];
-                break;
-            case 'response_padding':
-                type = 'response_trimming';
-                qualityImpact = {
-                    expected_change: 0.01, // May improve by removing fluff
-                    confidence: 0.85,
-                    risk_level: 'low',
-                    affected_metrics: ['response_completeness'],
-                };
-                actions = [{
-                        action_id: `action-${opportunityId}-1`,
-                        type: 'add',
-                        target: 'response_format',
-                        description: 'Add response format constraints to reduce padding',
-                        proposed: {
-                            response_format: 'concise',
-                            max_preamble_tokens: 20,
-                            skip_acknowledgments: true,
-                        },
-                        token_impact: { input_delta: 0, output_delta: -pattern.token_waste.avg_output_tokens },
-                    }];
-                break;
-            case 'duplicate_examples':
-                type = 'example_reduction';
-                qualityImpact = {
-                    expected_change: -0.03,
-                    confidence: 0.75,
-                    risk_level: 'low',
-                    affected_metrics: ['few_shot_accuracy'],
-                    mitigations: ['Implement dynamic example selection', 'Cache top-performing examples'],
-                };
-                actions = [{
-                        action_id: `action-${opportunityId}-1`,
-                        type: 'modify',
-                        target: 'examples',
-                        description: 'Reduce duplicate examples using dynamic selection',
-                        current: 'Static example set with duplicates',
-                        proposed: 'Dynamic example selection based on task similarity',
-                        token_impact: { input_delta: -pattern.token_waste.avg_input_tokens, output_delta: 0 },
-                    }];
-                break;
-            case 'inefficient_structure':
-                type = 'template_optimization';
-                qualityImpact = {
-                    expected_change: 0,
-                    confidence: 0.9,
-                    risk_level: 'none',
-                    affected_metrics: [],
-                };
-                actions = [{
-                        action_id: `action-${opportunityId}-1`,
-                        type: 'modify',
-                        target: 'prompt_template',
-                        description: 'Restructure prompts for better token efficiency',
-                        current: 'Current template structure',
-                        proposed: 'Optimized template with reduced overhead',
-                        token_impact: { input_delta: -pattern.token_waste.avg_input_tokens, output_delta: 0 },
-                    }];
-                break;
-            case 'over_specification':
-                type = 'instruction_tuning';
-                qualityImpact = {
-                    expected_change: -0.02,
-                    confidence: 0.7,
-                    risk_level: 'medium',
-                    affected_metrics: ['task_accuracy', 'edge_case_handling'],
-                    mitigations: ['Gradual reduction with quality monitoring', 'Preserve critical specifications'],
-                };
-                actions = [{
-                        action_id: `action-${opportunityId}-1`,
-                        type: 'modify',
-                        target: 'system_instruction',
-                        description: 'Simplify over-specified instructions',
-                        current: 'Detailed specification',
-                        proposed: 'Simplified specification with key requirements',
-                        token_impact: { input_delta: -pattern.token_waste.avg_input_tokens, output_delta: 0 },
-                    }];
-                break;
-            default:
-                return null;
-        }
-        // Check quality threshold
-        if (qualityThreshold > 0 && Math.abs(qualityImpact.expected_change) > (1 - qualityThreshold)) {
-            qualityImpact.risk_level = 'high';
-        }
-        const savings = {
-            input_tokens: pattern.token_waste.avg_input_tokens * pattern.affected_count,
-            output_tokens: pattern.token_waste.avg_output_tokens * pattern.affected_count,
-            total_tokens: pattern.token_waste.total_tokens,
-            cost_usd: pattern.token_waste.cost_usd,
-            savings_pct: pattern.token_waste.waste_pct,
-        };
-        // Calculate priority based on savings, confidence, and quality impact
-        const savingsScore = Math.min(1.0, savings.cost_usd / 100); // $100 = 1.0
-        const qualityScore = 1.0 - Math.abs(qualityImpact.expected_change);
-        const confidenceScore = qualityImpact.confidence;
-        const priority = (savingsScore * 0.4 + qualityScore * 0.3 + confidenceScore * 0.3);
-        return {
-            opportunity_id: opportunityId,
-            type,
-            priority: Math.round(priority * 100) / 100,
-            savings_per_request: {
-                input_tokens: pattern.token_waste.avg_input_tokens,
-                output_tokens: pattern.token_waste.avg_output_tokens,
-                total_tokens: pattern.token_waste.avg_input_tokens + pattern.token_waste.avg_output_tokens,
-                cost_usd: pattern.token_waste.cost_usd / pattern.affected_count,
-                savings_pct: pattern.token_waste.waste_pct,
-            },
-            total_savings: savings,
-            quality_impact: qualityImpact,
-            complexity: this.determineComplexity(type, actions),
-            actions,
-            evidence: [{
-                    type: 'statistical',
-                    source: 'token-telemetry-analysis',
-                    description: `Pattern detected with ${(pattern.frequency * 100).toFixed(1)}% frequency affecting ${pattern.affected_count} requests`,
-                    confidence: this.config.minConfidenceThreshold,
-                    data: {
-                        pattern_category: pattern.category,
-                        affected_count: pattern.affected_count,
-                        waste_pct: pattern.token_waste.waste_pct,
-                    },
-                }],
-        };
-    }
-    identifyModelOpportunities(telemetry, qualityThreshold) {
-        const opportunities = [];
-        for (const [modelId, metrics] of Object.entries(telemetry.by_model || {})) {
-            const ref = types_1.TOKEN_MODEL_REFERENCE[modelId];
-            if (!ref)
-                continue;
-            // Check if a cheaper model could handle the workload
-            const cheaperModels = this.findCheaperModelsForTokens(modelId, metrics);
-            for (const cheaper of cheaperModels) {
-                if (cheaper.qualityDrop <= (1 - qualityThreshold)) {
-                    const savings = this.calculateModelSwitchSavings(modelId, cheaper.modelId, metrics);
-                    opportunities.push({
-                        opportunity_id: `opp-model-${modelId}-to-${cheaper.modelId}`,
-                        type: 'model_downgrade',
-                        priority: Math.min(0.9, savings.savings_pct / 100 + 0.3),
-                        savings_per_request: {
-                            input_tokens: 0, // Same tokens, different cost
-                            output_tokens: 0,
-                            total_tokens: 0,
-                            cost_usd: savings.cost_usd / metrics.request_count,
-                            savings_pct: savings.savings_pct,
-                        },
-                        total_savings: savings,
-                        quality_impact: {
-                            expected_change: -cheaper.qualityDrop,
-                            confidence: 0.85,
-                            risk_level: cheaper.qualityDrop > 0.05 ? 'medium' : 'low',
-                            affected_metrics: ['overall_quality'],
-                            mitigations: ['Canary deployment', 'Quality monitoring'],
-                        },
-                        complexity: 'low',
-                        actions: [{
-                                action_id: `action-model-switch-${modelId}`,
-                                type: 'replace',
-                                target: 'model_config',
-                                description: `Switch from ${modelId} to ${cheaper.modelId} for cost optimization`,
-                                current: modelId,
-                                proposed: cheaper.modelId,
-                                token_impact: { input_delta: 0, output_delta: 0 },
-                            }],
-                        evidence: [{
-                                type: 'benchmark',
-                                source: 'model-pricing-reference',
-                                description: `${cheaper.modelId} costs ${(100 - savings.savings_pct).toFixed(0)}% less than ${modelId}`,
-                                confidence: 0.95,
-                                data: {
-                                    current_model: modelId,
-                                    proposed_model: cheaper.modelId,
-                                    cost_reduction_pct: savings.savings_pct,
-                                    quality_benchmark_delta: cheaper.qualityDrop,
-                                },
-                            }],
-                    });
-                }
-            }
-        }
-        return opportunities;
-    }
-    findCheaperModelsForTokens(currentModel, metrics) {
-        const currentRef = types_1.TOKEN_MODEL_REFERENCE[currentModel];
-        if (!currentRef)
-            return [];
-        const results = [];
-        for (const [modelId, ref] of Object.entries(types_1.TOKEN_MODEL_REFERENCE)) {
-            if (modelId === currentModel)
-                continue;
-            // Calculate cost comparison
-            const currentCostPer1k = (currentRef.input_cost_per_1k + currentRef.output_cost_per_1k) / 2;
-            const newCostPer1k = (ref.input_cost_per_1k + ref.output_cost_per_1k) / 2;
-            if (newCostPer1k < currentCostPer1k) {
-                const qualityDrop = Math.max(0, currentRef.quality_benchmark - ref.quality_benchmark);
-                results.push({ modelId, qualityDrop });
-            }
-        }
-        return results.sort((a, b) => a.qualityDrop - b.qualityDrop);
-    }
-    calculateModelSwitchSavings(fromModel, toModel, metrics) {
-        const fromRef = types_1.TOKEN_MODEL_REFERENCE[fromModel];
-        const toRef = types_1.TOKEN_MODEL_REFERENCE[toModel];
-        if (!fromRef || !toRef) {
-            return {
-                input_tokens: 0,
-                output_tokens: 0,
-                total_tokens: 0,
-                cost_usd: 0,
-                savings_pct: 0,
-            };
-        }
-        const currentCost = metrics.total_cost_usd;
-        const newInputCost = (metrics.total_input_tokens / 1000) * toRef.input_cost_per_1k;
-        const newOutputCost = (metrics.total_output_tokens / 1000) * toRef.output_cost_per_1k;
-        const newTotalCost = newInputCost + newOutputCost;
-        const savings = currentCost - newTotalCost;
-        return {
-            input_tokens: 0,
-            output_tokens: 0,
-            total_tokens: 0,
-            cost_usd: Math.max(0, savings),
-            savings_pct: Math.max(0, (savings / currentCost) * 100),
-        };
-    }
-    determineComplexity(type, actions) {
-        // Trivial: No code changes needed
-        if (type === 'context_caching' || type === 'model_downgrade') {
-            return actions.length <= 1 ? 'trivial' : 'low';
-        }
-        // Low: Simple configuration changes
-        if (type === 'response_trimming' || type === 'structured_output') {
-            return 'low';
-        }
-        // Medium: Template modifications
-        if (type === 'prompt_compression' || type === 'template_optimization' || type === 'example_reduction') {
-            return 'medium';
-        }
-        // High: Requires significant prompt engineering
-        if (type === 'instruction_tuning' || type === 'encoding_optimization') {
-            return 'high';
-        }
-        return 'medium';
-    }
-    // --------------------------------------------------------------------------
-    // Constraint Evaluation
-    // --------------------------------------------------------------------------
-    violatesHardConstraints(opportunity, constraints) {
-        for (const constraint of constraints) {
-            if (!constraint.hard)
-                continue;
-            switch (constraint.type) {
-                case 'min_quality_score':
-                    if (1 + opportunity.quality_impact.expected_change < Number(constraint.value)) {
-                        return true;
-                    }
-                    break;
-                case 'max_latency_increase_pct':
-                    // Model downgrades may affect latency
-                    if (opportunity.type === 'model_downgrade') {
-                        // Assume some latency impact for model changes
-                        return false; // Would need actual latency data
-                    }
-                    break;
-                case 'min_savings_threshold_pct':
-                    if (opportunity.total_savings.savings_pct < Number(constraint.value)) {
-                        return true;
-                    }
-                    break;
-                case 'allowed_optimization_types':
-                    const allowedTypes = String(constraint.value).split(',');
-                    if (!allowedTypes.includes(opportunity.type)) {
-                        return true;
-                    }
-                    break;
-            }
-        }
-        return false;
-    }
-    evaluateConstraints(constraints, opportunities) {
-        return constraints.map(constraint => {
-            const violated = opportunities.some(opp => this.opportunityViolatesConstraint(opp, constraint));
-            return {
-                constraint,
-                satisfied: !violated,
-                impact_description: !violated
-                    ? 'All opportunities comply with this constraint'
-                    : 'Some opportunities were filtered due to this constraint',
-            };
-        });
-    }
-    opportunityViolatesConstraint(opportunity, constraint) {
-        switch (constraint.type) {
-            case 'min_quality_score':
-                return 1 + opportunity.quality_impact.expected_change < Number(constraint.value);
-            case 'min_savings_threshold_pct':
-                return opportunity.total_savings.savings_pct < Number(constraint.value);
-            case 'allowed_optimization_types':
-                const allowedTypes = String(constraint.value).split(',');
-                return !allowedTypes.includes(opportunity.type);
-            default:
-                return false;
-        }
-    }
-    // --------------------------------------------------------------------------
-    // Output Building
-    // --------------------------------------------------------------------------
-    buildOutput(input, patterns, opportunities, evaluatedConstraints, efficiency, startTime) {
-        const timestamp = new Date().toISOString();
-        const outputId = `out-${exports.AGENT_ID}-${Date.now()}`;
-        // Calculate total potential savings
-        const totalSavings = opportunities.reduce((acc, opp) => ({
-            input_tokens: acc.input_tokens + opp.total_savings.input_tokens,
-            output_tokens: acc.output_tokens + opp.total_savings.output_tokens,
-            total_tokens: acc.total_tokens + opp.total_savings.total_tokens,
-            cost_usd: acc.cost_usd + opp.total_savings.cost_usd,
-            savings_pct: 0, // Calculated below
-        }), { input_tokens: 0, output_tokens: 0, total_tokens: 0, cost_usd: 0, savings_pct: 0 });
-        // Calculate savings percentage
-        if (input.token_telemetry.aggregate.total_cost_usd > 0) {
-            totalSavings.savings_pct =
-                (totalSavings.cost_usd / input.token_telemetry.aggregate.total_cost_usd) * 100;
-        }
-        // Generate key findings
-        const keyFindings = [];
-        if (patterns.length > 0) {
-            keyFindings.push(`Identified ${patterns.length} token usage patterns with optimization potential`);
-        }
-        if (totalSavings.cost_usd > 10) {
-            keyFindings.push(`Potential monthly savings of $${(totalSavings.cost_usd * 30).toFixed(2)}`);
-        }
-        if (efficiency.compression_potential > 0.2) {
-            keyFindings.push(`${(efficiency.compression_potential * 100).toFixed(0)}% compression potential identified`);
-        }
-        // Determine risk level
-        const highRiskOpps = opportunities.filter(o => o.quality_impact.risk_level === 'high');
-        const riskLevel = highRiskOpps.length > opportunities.length / 2 ? 'high' :
-            highRiskOpps.length > 0 ? 'medium' : 'low';
-        const analysis = {
-            current_state: {
-                total_tokens_analyzed: input.token_telemetry.aggregate.total_input_tokens +
-                    input.token_telemetry.aggregate.total_output_tokens,
-                total_cost_analyzed_usd: input.token_telemetry.aggregate.total_cost_usd,
-                overall_efficiency: efficiency.overall,
-                input_efficiency: efficiency.input_efficiency,
-                output_efficiency: efficiency.output_efficiency,
-            },
-            patterns_identified: patterns.length,
-            opportunities_identified: opportunities.length,
-            total_potential_savings: totalSavings,
-            risk_level: riskLevel,
-            key_findings: keyFindings,
-        };
-        const metadata = {
-            processing_duration_ms: Date.now() - startTime,
-            data_points_analyzed: Object.keys(input.token_telemetry.by_model || {}).length +
-                Object.keys(input.token_telemetry.by_service || {}).length +
-                (input.token_telemetry.aggregate.daily_trend?.length || 0),
-            strategies_used: [
-                'pattern_detection',
-                'efficiency_analysis',
-                'model_comparison',
-                'cost_optimization',
-            ],
-            warnings: [],
-            coverage: {
-                services_analyzed: Object.keys(input.token_telemetry.by_service || {}).length,
-                models_analyzed: Object.keys(input.token_telemetry.by_model || {}).length,
-                requests_sampled: input.token_telemetry.aggregate.total_requests,
-                time_range_hours: this.calculateTimeRangeHours(input.time_window),
-            },
-        };
-        return {
-            output_id: outputId,
-            execution_ref: input.execution_ref,
-            agent_version: exports.AGENT_VERSION,
-            timestamp,
-            analysis,
-            patterns,
-            opportunities,
-            constraints_evaluated: evaluatedConstraints,
-            metadata,
-        };
-    }
-    // --------------------------------------------------------------------------
-    // DecisionEvent Building
-    // --------------------------------------------------------------------------
-    buildDecisionEvent(input, output, inputsHash, evaluatedConstraints, decisionType) {
-        // Convert token opportunities to standard recommendations for DecisionOutputs
-        const recommendations = output.opportunities.map((opp, idx) => ({
-            recommendation_id: opp.opportunity_id,
-            rank: idx + 1,
-            category: this.mapOpportunityTypeToCategory(opp.type),
-            title: `Token Optimization: ${opp.type.replace(/_/g, ' ')}`,
-            description: opp.actions[0]?.description || '',
-            proposed_changes: opp.actions.map(action => ({
-                type: action.type,
-                parameter: action.target,
-                current_value: action.current,
-                proposed_value: action.proposed,
-                affected_services: input.target_services,
-            })),
-            expected_impact: {
-                cost_change_pct: -opp.total_savings.savings_pct,
-                latency_change_pct: 0,
-                quality_change_pct: opp.quality_impact.expected_change * 100,
-                monthly_savings_usd: opp.total_savings.cost_usd * 30,
-                confidence: opp.quality_impact.confidence,
-            },
-            complexity: opp.complexity === 'trivial' ? 'low' : opp.complexity,
-            risk: opp.quality_impact.risk_level === 'none' ? 'low' : opp.quality_impact.risk_level,
-            confidence: opp.priority,
-            evidence: opp.evidence.map(e => ({
-                type: e.type,
-                source: e.source,
-                data_points: e.data,
-                strength: e.confidence,
-            })),
-            rollout_strategy: {
-                type: opp.quality_impact.risk_level === 'high' ? 'canary' : 'gradual',
-                canary_percentage: 10,
-                rollback_criteria: {
-                    max_error_rate_increase_pct: 5,
-                    max_latency_increase_pct: 10,
-                    min_quality_threshold: 0.85,
-                    monitoring_duration_minutes: 60,
-                },
-            },
-        }));
-        const outputs = {
-            recommendations,
-            analysis: output.opportunities.length === 0 ? {
-                analysis_type: 'cost',
-                depth: input.analysis_depth === 'deep' ? 'deep' : input.analysis_depth === 'standard' ? 'medium' : 'shallow',
-                findings: output.patterns.map(p => ({
-                    finding_id: p.pattern_id,
-                    category: p.category,
-                    severity: p.token_waste.cost_usd > 50 ? 'warning' : 'info',
-                    description: p.description,
-                    metrics: {
-                        waste_tokens: p.token_waste.total_tokens,
-                        waste_cost_usd: p.token_waste.cost_usd,
-                        waste_pct: p.token_waste.waste_pct,
-                    },
-                })),
-                trends: {
-                    cost_trend: 'stable',
-                    latency_trend: 'stable',
-                    quality_trend: 'stable',
-                    confidence: 0.8,
-                },
-            } : undefined,
-        };
-        const constraintsApplied = evaluatedConstraints.map((ec, idx) => ({
-            constraint_id: `constraint-${idx}`,
-            type: this.mapTokenConstraintType(ec.constraint.type),
-            value: ec.constraint.value,
-            hard: ec.constraint.hard,
-            satisfied: ec.satisfied,
-        }));
-        // Calculate overall confidence
-        const overallConfidence = output.opportunities.length > 0
-            ? output.opportunities.reduce((sum, o) => sum + o.priority, 0) / output.opportunities.length
-            : 0.5;
-        return {
-            agent_id: exports.AGENT_ID,
-            agent_version: exports.AGENT_VERSION,
-            decision_type: decisionType,
-            inputs_hash: inputsHash,
-            outputs,
-            confidence: Math.round(overallConfidence * 100) / 100,
-            constraints_applied: constraintsApplied,
-            execution_ref: input.execution_ref,
-            timestamp: output.timestamp,
-        };
-    }
-    mapOpportunityTypeToCategory(type) {
-        switch (type) {
-            case 'prompt_compression':
-            case 'template_optimization':
-            case 'instruction_tuning':
-                return 'prompt_optimization';
-            case 'context_caching':
-                return 'caching_strategy';
-            case 'model_downgrade':
-                return 'model_substitution';
-            case 'response_trimming':
-                return 'response_optimization';
-            case 'batching':
-                return 'request_batching';
-            case 'example_reduction':
-            case 'encoding_optimization':
-                return 'token_reduction';
-            case 'structured_output':
-                return 'context_optimization';
-            default:
-                return 'cost_optimization';
-        }
-    }
-    mapTokenConstraintType(type) {
-        switch (type) {
-            case 'min_quality_score':
-                return 'min_quality_threshold';
-            case 'max_latency_increase_pct':
-                return 'max_latency_increase_ms';
-            default:
-                return 'compliance_policy';
-        }
-    }
-    // --------------------------------------------------------------------------
-    // Telemetry Emission
-    // --------------------------------------------------------------------------
-    async emitTelemetry(decisionEvent, output, durationMs) {
-        if (!this.config.telemetryEndpoint)
-            return;
-        const telemetry = {
-            agent_id: exports.AGENT_ID,
-            agent_version: exports.AGENT_VERSION,
-            execution_ref: decisionEvent.execution_ref,
-            metrics: {
-                processing_duration_ms: durationMs,
-                patterns_detected: output.patterns.length,
-                opportunities_generated: output.opportunities.length,
-                total_potential_savings_usd: output.analysis.total_potential_savings.cost_usd,
-                overall_efficiency: output.analysis.current_state.overall_efficiency,
-                overall_confidence: decisionEvent.confidence,
-                constraints_evaluated: decisionEvent.constraints_applied.length,
-                constraints_satisfied: decisionEvent.constraints_applied.filter(c => c.satisfied).length,
-            },
-            timestamp: new Date().toISOString(),
-        };
-        try {
-            await fetch(this.config.telemetryEndpoint, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'X-Agent-Id': exports.AGENT_ID,
-                },
-                body: JSON.stringify(telemetry),
-            });
-        }
-        catch (error) {
-            // Telemetry failure should not fail the agent
-            console.error('[TokenOptimizationAgent] Telemetry emission failed:', error);
-        }
-    }
-    // --------------------------------------------------------------------------
-    // Utility Methods
-    // --------------------------------------------------------------------------
-    getAverageCostPerToken(telemetry, direction) {
-        let totalCost = 0;
-        let totalTokens = 0;
-        for (const [modelId, metrics] of Object.entries(telemetry.by_model || {})) {
-            const ref = types_1.TOKEN_MODEL_REFERENCE[modelId];
-            if (ref) {
-                if (direction === 'input') {
-                    totalCost += metrics.total_input_tokens * ref.input_cost_per_1k / 1000;
-                    totalTokens += metrics.total_input_tokens;
-                }
-                else {
-                    totalCost += metrics.total_output_tokens * ref.output_cost_per_1k / 1000;
-                    totalTokens += metrics.total_output_tokens;
-                }
-            }
-        }
-        return totalTokens > 0 ? totalCost / totalTokens * 1000 : 0.001;
-    }
-    calculateTimeRangeHours(timeWindow) {
-        const start = new Date(timeWindow.start);
-        const end = new Date(timeWindow.end);
-        return (end.getTime() - start.getTime()) / (1000 * 60 * 60);
-    }
-}
-exports.TokenOptimizationAgent = TokenOptimizationAgent;
-// ============================================================================
-// Factory Function
-// ============================================================================
-/**
- * Create a Token Optimization Agent instance.
- */
-function createTokenOptimizationAgent(config) {
-    return new TokenOptimizationAgent(config);
-}
-//# sourceMappingURL=index.js.map