observability-toolkit 1.8.5 → 2.1.0

package/dist/lib/cost/cost-estimation.test.js

@@ -0,0 +1,701 @@
+/**
+ * Tests for Cost Estimation Layer
+ */
+import { describe, it, beforeEach } from 'vitest';
+import * as assert from 'node:assert';
+import { calculateCost, getModelPricing, listModelsWithPricing, isPricingStale, checkBudget, createBudgetTracker, estimateBatchCost, estimateCostBeforeRequest, estimateTokens, CostEstimationError, InvalidModelError, tokenUsageSchema, budgetConfigSchema, DEFAULT_CACHE_DISCOUNT, } from './cost-estimation.js';
+import { HOURS_PER_DAY, TIME_MS, MINUTES_PER_HOUR, SECONDS, } from '../core/units.js';
+import { COUNT_FIFTY, COUNT_FIVE, COUNT_FIVE_THOUSAND, COUNT_HUNDRED, COUNT_SEVEN, COUNT_SIX, COUNT_THOUSAND, COUNT_THREE, COUNT_TWO, COUNT_TWO_THOUSAND, } from '../../test-helpers/test-constants.js';
+const TEST_OUTPUT_TOKENS = COUNT_THOUSAND / COUNT_TWO;
+const TEST_CACHE_CREATION_TOKENS = COUNT_TWO_THOUSAND;
+const TEST_CACHE_READ_TOKENS = COUNT_FIVE_THOUSAND;
+const TEST_METADATA_OUTPUT_TOKENS = COUNT_FIFTY;
+const EXPECTED_SONNET_INPUT_COST = 0.003;
+const EXPECTED_SONNET_OUTPUT_COST = 0.0075;
+const EXPECTED_SONNET_TOTAL_COST = 0.0105;
+const EXPECTED_OPUS_INPUT_COST = 0.005;
+const EXPECTED_OPUS_OUTPUT_COST = 0.0125;
+const EXPECTED_OPUS_TOTAL_COST = 0.0175;
+const EXPECTED_SONNET_CACHE_READ_INPUT_COST = 0.0045;
+const EXPECTED_SONNET_CACHE_CREATE_INPUT_COST = 0.009;
+const EXPECTED_HALF_DISCOUNT_INPUT_COST = 0.015;
+const EXPECTED_GPT4O_INPUT_COST = 0.0025;
+const HALF_DISCOUNT = 0.5;
+const INVALID_NEGATIVE_DISCOUNT = -0.1;
+const INVALID_OVER_MAX_DISCOUNT = 1.5;
+const BUDGET_LIMIT_STANDARD = 10.0;
+const BUDGET_SPEND_HALF = 5.0;
+const BUDGET_SPEND_WARNING = 8.0;
+const BUDGET_SPEND_CRITICAL = 9.6;
+const BUDGET_SPEND_EXCEEDED = 11.0;
+const BUDGET_SPEND_DEFAULT_WARNING = 8.5;
+const BUDGET_SPEND_DEFAULT_OK = 7.0;
+const NEGATIVE_BUDGET_LIMIT = -10.0;
+const BUDGET_PERCENT_HALF = 50;
+const BUDGET_PERCENT_WARNING = 80;
+const BUDGET_PERCENT_CRITICAL = 96;
+const TRACKED_DAILY_SPEND = 4.0;
+const SESSION_SPEND_FIRST = 2.0;
+const SESSION_SPEND_SECOND = 2.5;
+const SESSION_SPEND_TOTAL = 4.5;
+const SUMMARY_TOTAL_COST = 3.0;
+const LARGE_METADATA_LENGTH = 2000;
+const MAX_ATTRIBUTIONS = COUNT_FIVE;
+const ATTRIBUTION_INSERTIONS = COUNT_SEVEN;
+const EXPECTED_BATCH_TOTAL_COST = 0.0315;
+const EXPECTED_PRE_REQUEST_INPUT_COST = 0.015;
+const EXPECTED_PRE_REQUEST_OUTPUT_COST = 0.03;
+const EXPECTED_PRE_REQUEST_TOTAL_COST = 0.045;
+const NEGATIVE_TOKEN_COUNT = -100;
+const EXPECTED_DEFAULT_TOKEN_COUNT = COUNT_THREE;
+const CHARS_PER_TOKEN_CUSTOM = COUNT_TWO;
+const EXPECTED_CUSTOM_TOKEN_COUNT = COUNT_SIX;
+describe('cost-estimation', () => {
+    // ==========================================================================
+    // calculateCost
+    // ==========================================================================
+    describe('calculateCost', () => {
+        it('calculates cost for known model', () => {
+            const usage = { inputTokens: COUNT_THOUSAND, outputTokens: TEST_OUTPUT_TOKENS };
+            const result = calculateCost(usage, 'claude-sonnet-4-20250514');
+            // Sonnet: $3/1M input, $15/1M output
+            assert.strictEqual(result.inputCost, EXPECTED_SONNET_INPUT_COST);
+            assert.strictEqual(result.outputCost, EXPECTED_SONNET_OUTPUT_COST);
+            assert.strictEqual(result.totalCost, EXPECTED_SONNET_TOTAL_COST);
+            assert.strictEqual(result.model, 'claude-sonnet-4-20250514');
+            assert.strictEqual(result.usedFallbackPricing, undefined);
+        });
+        it('calculates cost for opus model', () => {
+            const usage = { inputTokens: COUNT_THOUSAND, outputTokens: TEST_OUTPUT_TOKENS };
+            const result = calculateCost(usage, 'claude-opus-4-5-20251101');
+            // Opus 4.5: $5/1M input, $25/1M output
+            assert.strictEqual(result.inputCost, EXPECTED_OPUS_INPUT_COST);
+            assert.strictEqual(result.outputCost, EXPECTED_OPUS_OUTPUT_COST);
+            assert.strictEqual(result.totalCost, EXPECTED_OPUS_TOTAL_COST);
+        });
+        it('falls back to sonnet pricing for unknown models and flags it', () => {
+            const usage = { inputTokens: COUNT_THOUSAND, outputTokens: TEST_OUTPUT_TOKENS };
+            const result = calculateCost(usage, 'unknown-model-v1');
+            // Should use sonnet pricing as fallback
+            assert.strictEqual(result.inputCost, EXPECTED_SONNET_INPUT_COST);
+            assert.strictEqual(result.outputCost, EXPECTED_SONNET_OUTPUT_COST);
+            assert.strictEqual(result.model, 'unknown-model-v1');
+            assert.strictEqual(result.usedFallbackPricing, true);
+        });
+        it('handles cache read tokens with discount', () => {
+            const usage = {
+                inputTokens: COUNT_THOUSAND,
+                outputTokens: TEST_OUTPUT_TOKENS,
+                cacheReadTokens: TEST_CACHE_READ_TOKENS,
+            };
+            const result = calculateCost(usage, 'claude-sonnet-4-20250514');
+            // Regular input: 1000 * $3/1M = $0.003
+            // Cache read: 5000 * $3/1M * (1 - 0.9) = $0.0015
+            // Output: 500 * $15/1M = $0.0075
+            assert.strictEqual(result.inputCost, EXPECTED_SONNET_CACHE_READ_INPUT_COST);
+            assert.strictEqual(result.outputCost, EXPECTED_SONNET_OUTPUT_COST);
+            assert.strictEqual(result.cacheDiscount, DEFAULT_CACHE_DISCOUNT);
+        });
+        it('handles cache creation tokens', () => {
+            const usage = {
+                inputTokens: COUNT_THOUSAND,
+                outputTokens: TEST_OUTPUT_TOKENS,
+                cacheCreationTokens: TEST_CACHE_CREATION_TOKENS,
+            };
+            const result = calculateCost(usage, 'claude-sonnet-4-20250514');
+            // Regular input: 1000 * $3/1M = $0.003
+            // Cache creation: 2000 * $3/1M = $0.006 (no discount)
+            // Output: 500 * $15/1M = $0.0075
+            assert.strictEqual(result.inputCost, EXPECTED_SONNET_CACHE_CREATE_INPUT_COST);
+            assert.strictEqual(result.outputCost, EXPECTED_SONNET_OUTPUT_COST);
+        });
+        it('handles custom cache discount', () => {
+            const usage = {
+                inputTokens: 0,
+                outputTokens: 0,
+                cacheReadTokens: COUNT_HUNDRED * COUNT_HUNDRED,
+            };
+            const result = calculateCost(usage, 'claude-sonnet-4-20250514', HALF_DISCOUNT);
+            // Cache read with 50% discount: 10000 * $3/1M * 0.5 = $0.015
+            assert.strictEqual(result.inputCost, EXPECTED_HALF_DISCOUNT_INPUT_COST);
+            assert.strictEqual(result.cacheDiscount, HALF_DISCOUNT);
+        });
+        it('handles zero tokens', () => {
+            const usage = { inputTokens: 0, outputTokens: 0 };
+            const result = calculateCost(usage, 'claude-sonnet-4-20250514');
+            assert.strictEqual(result.inputCost, 0);
+            assert.strictEqual(result.outputCost, 0);
+            assert.strictEqual(result.totalCost, 0);
+        });
+        it('calculates cost for GPT models', () => {
+            const usage = { inputTokens: COUNT_THOUSAND, outputTokens: TEST_OUTPUT_TOKENS };
+            const result = calculateCost(usage, 'gpt-4o');
+            // GPT-4o: $2.50/1M input, $10/1M output
+            assert.strictEqual(result.inputCost, EXPECTED_GPT4O_INPUT_COST);
+            assert.strictEqual(result.outputCost, EXPECTED_OPUS_INPUT_COST);
+        });
+        // Error handling tests
+        it('throws on negative input tokens', () => {
+            assert.throws(() => calculateCost({ inputTokens: -1, outputTokens: 0 }, 'claude-sonnet-4-20250514'), CostEstimationError);
+        });
+        it('throws on negative output tokens', () => {
+            assert.throws(() => calculateCost({ inputTokens: 0, outputTokens: -1 }, 'claude-sonnet-4-20250514'), CostEstimationError);
+        });
+        it('throws on non-integer tokens', () => {
+            assert.throws(() => calculateCost({ inputTokens: 1.5, outputTokens: 0 }, 'claude-sonnet-4-20250514'), CostEstimationError);
+        });
+        it('throws on NaN tokens', () => {
+            assert.throws(() => calculateCost({ inputTokens: NaN, outputTokens: 0 }, 'claude-sonnet-4-20250514'), CostEstimationError);
+        });
+        it('throws on negative cache discount', () => {
+            assert.throws(() => calculateCost({ inputTokens: COUNT_HUNDRED, outputTokens: 0 }, 'claude-sonnet-4-20250514', INVALID_NEGATIVE_DISCOUNT), CostEstimationError);
+        });
+        it('throws on cache discount > 1', () => {
+            assert.throws(() => calculateCost({ inputTokens: COUNT_HUNDRED, outputTokens: 0 }, 'claude-sonnet-4-20250514', INVALID_OVER_MAX_DISCOUNT), CostEstimationError);
+        });
+        it('throws on NaN cache discount', () => {
+            assert.throws(() => calculateCost({ inputTokens: COUNT_HUNDRED, outputTokens: 0 }, 'claude-sonnet-4-20250514', NaN), CostEstimationError);
+        });
+    });
+    // ==========================================================================
+    // getModelPricing
+    // ==========================================================================
+    describe('getModelPricing', () => {
+        it('returns pricing for known model', () => {
+            const pricing = getModelPricing('claude-sonnet-4-20250514');
+            assert.deepStrictEqual(pricing, { input: 3.0, output: 15.0 });
+        });
+        it('returns null for unknown model', () => {
+            const pricing = getModelPricing('nonexistent-model');
+            assert.strictEqual(pricing, null);
+        });
+        it('return shape has no provider field (BF-2 regression)', () => {
+            // BF-2: getModelPricing previously returned { input, output, provider }.
+            // The provider field was removed; this guard prevents re-introduction.
+            const pricing = getModelPricing('claude-sonnet-4-20250514');
+            assert.ok(pricing !== null, 'expected non-null pricing for known model');
+            assert.ok(!('provider' in pricing), 'return shape must not include a provider field');
+        });
+    });
+    // ==========================================================================
+    // listModelsWithPricing
+    // ==========================================================================
+    describe('listModelsWithPricing', () => {
+        it('returns array of models with pricing', () => {
+            const models = listModelsWithPricing();
+            assert.ok(Array.isArray(models));
+            assert.ok(models.length > 0);
+            assert.ok('model' in models[0]);
+            assert.ok('input' in models[0]);
+            assert.ok('output' in models[0]);
+        });
+        it('includes major providers', () => {
+            const models = listModelsWithPricing();
+            const modelNames = models.map(m => m.model);
+            assert.ok(modelNames.includes('claude-sonnet-4-20250514'));
+            assert.ok(modelNames.includes('gpt-4o'));
+            assert.ok(modelNames.includes('gemini-1.5-pro'));
+        });
+    });
+    // ==========================================================================
+    // isPricingStale
+    // ==========================================================================
+    describe('isPricingStale', () => {
+        it('returns staleness status', () => {
+            const result = isPricingStale();
+            assert.ok('isStale' in result);
+            assert.ok('daysSinceUpdate' in result);
+            assert.ok('lastUpdated' in result);
+            assert.strictEqual(typeof result.isStale, 'boolean');
+            assert.strictEqual(typeof result.daysSinceUpdate, 'number');
+        });
+    });
+    // ==========================================================================
+    // checkBudget
+    // ==========================================================================
+    describe('checkBudget', () => {
+        it('returns ok when under threshold', () => {
+            const result = checkBudget(BUDGET_SPEND_HALF, BUDGET_LIMIT_STANDARD);
+            assert.strictEqual(result.level, 'ok');
+            assert.strictEqual(result.percentUsed, BUDGET_PERCENT_HALF);
+            assert.strictEqual(result.remainingBudget, BUDGET_SPEND_HALF);
+        });
+        it('returns warning at alert threshold', () => {
+            const result = checkBudget(BUDGET_SPEND_WARNING, BUDGET_LIMIT_STANDARD, { alertThreshold: 0.8, criticalThreshold: 0.95 });
+            assert.strictEqual(result.level, 'warning');
+            assert.strictEqual(result.percentUsed, BUDGET_PERCENT_WARNING);
+        });
+        it('returns critical at critical threshold', () => {
+            const result = checkBudget(BUDGET_SPEND_CRITICAL, BUDGET_LIMIT_STANDARD, { alertThreshold: 0.8, criticalThreshold: 0.95 });
+            assert.strictEqual(result.level, 'critical');
+            assert.strictEqual(result.percentUsed, BUDGET_PERCENT_CRITICAL);
+        });
+        it('returns exceeded when over limit', () => {
+            const result = checkBudget(BUDGET_SPEND_EXCEEDED, BUDGET_LIMIT_STANDARD);
+            assert.strictEqual(result.level, 'exceeded');
+            assert.strictEqual(result.remainingBudget, 0);
+        });
+        it('handles zero limit gracefully', () => {
+            const result = checkBudget(0, 0);
+            assert.strictEqual(result.percentUsed, 0);
+        });
+        it('uses default thresholds', () => {
+            // 85% should trigger warning (default 80%)
+            const warning = checkBudget(BUDGET_SPEND_DEFAULT_WARNING, BUDGET_LIMIT_STANDARD);
+            assert.strictEqual(warning.level, 'warning');
+            // 70% should be ok
+            const ok = checkBudget(BUDGET_SPEND_DEFAULT_OK, BUDGET_LIMIT_STANDARD);
+            assert.strictEqual(ok.level, 'ok');
+        });
+        // Error handling tests
+        it('throws on negative spend', () => {
+            assert.throws(() => checkBudget(-1, BUDGET_LIMIT_STANDARD), CostEstimationError);
+        });
+        it('throws on negative limit', () => {
+            assert.throws(() => checkBudget(BUDGET_SPEND_HALF, NEGATIVE_BUDGET_LIMIT), CostEstimationError);
+        });
+        it('throws on NaN spend', () => {
+            assert.throws(() => checkBudget(NaN, BUDGET_LIMIT_STANDARD), CostEstimationError);
+        });
+        it('throws on Infinity limit', () => {
+            assert.throws(() => checkBudget(BUDGET_SPEND_HALF, Infinity), CostEstimationError);
+        });
+        it('throws when alertThreshold >= criticalThreshold', () => {
+            assert.throws(() => checkBudget(BUDGET_SPEND_HALF, BUDGET_LIMIT_STANDARD, { alertThreshold: 0.9, criticalThreshold: 0.8 }), CostEstimationError);
+        });
+        it('throws when thresholds are equal', () => {
+            assert.throws(() => checkBudget(BUDGET_SPEND_HALF, BUDGET_LIMIT_STANDARD, { alertThreshold: 0.8, criticalThreshold: 0.8 }), CostEstimationError);
+        });
+    });
+    // ==========================================================================
+    // createBudgetTracker
+    // ==========================================================================
+    describe('createBudgetTracker', () => {
+        let tracker;
+        beforeEach(() => {
+            tracker = createBudgetTracker({
+                dailyLimit: BUDGET_LIMIT_STANDARD,
+                sessionLimit: BUDGET_SPEND_HALF,
+                userDailyLimit: SUMMARY_TOTAL_COST,
+                alertThreshold: 0.8,
+                criticalThreshold: 0.95,
+            });
+        });
+        it('tracks spend and checks daily budget', () => {
+            tracker.recordSpend(TRACKED_DAILY_SPEND, 'session-1', 'user-1', 'claude-sonnet-4-20250514');
+            const daily = tracker.checkDaily();
+            assert.ok(daily !== null);
+            assert.strictEqual(daily.currentSpend, TRACKED_DAILY_SPEND);
+            assert.strictEqual(daily.level, 'ok');
+        });
+        it('tracks session budget', () => {
+            tracker.recordSpend(SESSION_SPEND_FIRST, 'session-1', 'user-1');
+            tracker.recordSpend(SESSION_SPEND_SECOND, 'session-1', 'user-1');
+            const session = tracker.checkSession('session-1');
+            assert.ok(session !== null);
+            assert.strictEqual(session.currentSpend, SESSION_SPEND_TOTAL);
+            assert.strictEqual(session.level, 'warning'); // 90% of $5 limit
+        });
+        it('tracks user daily budget', () => {
+            tracker.recordSpend(SESSION_SPEND_SECOND, 'session-1', 'user-1');
+            const userDaily = tracker.checkUserDaily('user-1');
+            assert.ok(userDaily !== null);
+            assert.strictEqual(userDaily.currentSpend, SESSION_SPEND_SECOND);
+            assert.strictEqual(userDaily.level, 'warning'); // 83% of $3 limit
+        });
+        it('returns null when limit not configured', () => {
+            const noLimits = createBudgetTracker({});
+            assert.strictEqual(noLimits.checkDaily(), null);
+            assert.strictEqual(noLimits.checkSession('any'), null);
+            assert.strictEqual(noLimits.checkUserDaily('any'), null);
+        });
+        it('generates cost summary', () => {
+            tracker.recordSpend(1, 'session-1', 'user-1', 'claude-sonnet-4-20250514', COUNT_THOUSAND, TEST_OUTPUT_TOKENS);
+            tracker.recordSpend(SESSION_SPEND_FIRST, 'session-2', 'user-2', 'gpt-4o', COUNT_TWO_THOUSAND, COUNT_THOUSAND);
+            const summary = tracker.getSummary();
+            assert.strictEqual(summary.totalCost, SUMMARY_TOTAL_COST);
+            assert.strictEqual(summary.totalRequests, COUNT_TWO);
+            assert.strictEqual(summary.byModel['claude-sonnet-4-20250514'].cost, 1.0);
+            assert.strictEqual(summary.byModel['gpt-4o'].cost, SESSION_SPEND_FIRST);
+            assert.ok(summary.bySession);
+            assert.strictEqual(summary.bySession['session-1'].cost, 1.0);
+            assert.ok(summary.byUser);
+            assert.strictEqual(summary.byUser['user-1'].cost, 1.0);
+        });
+        it('filters summary by date range', () => {
+            const now = new Date();
+            const yesterday = new Date(now.getTime() - HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS.MINUTE * TIME_MS.SECOND);
+            tracker.recordSpend(1.0, 'session-1', 'user-1');
+            // Summary with future range should be empty
+            const futureStart = new Date(now.getTime() + MINUTES_PER_HOUR * SECONDS.MINUTE * TIME_MS.SECOND).toISOString();
+            const futureEnd = new Date(now.getTime() + COUNT_TWO * MINUTES_PER_HOUR * SECONDS.MINUTE * TIME_MS.SECOND).toISOString();
+            const future = tracker.getSummary(futureStart, futureEnd);
+            assert.strictEqual(future.totalRequests, 0);
+            // Summary including now should have data
+            const full = tracker.getSummary(yesterday.toISOString(), now.toISOString());
+            assert.strictEqual(full.totalRequests, 1);
+        });
+        it('resets tracked data', () => {
+            tracker.recordSpend(BUDGET_SPEND_HALF, 'session-1', 'user-1');
+            tracker.reset();
+            const daily = tracker.checkDaily();
+            assert.ok(daily !== null);
+            assert.strictEqual(daily.currentSpend, 0);
+            assert.strictEqual(tracker.getAttributions().length, 0);
+        });
+        it('includes metadata in attributions', () => {
+            tracker.recordSpend(1, 'session-1', 'user-1', 'model', COUNT_HUNDRED, TEST_METADATA_OUTPUT_TOKENS, { feature: 'test' });
+            const attrs = tracker.getAttributions();
+            assert.deepStrictEqual(attrs[0].metadata, { feature: 'test' });
+        });
+        // Memory protection tests
+        it('enforces max attributions with FIFO eviction', () => {
+            const limitedTracker = createBudgetTracker({
+                dailyLimit: 100.0,
+                maxAttributions: MAX_ATTRIBUTIONS,
+            });
+            // Add 7 attributions
+            for (let i = 0; i < ATTRIBUTION_INSERTIONS; i++) {
+                limitedTracker.recordSpend(1.0, `session-${i}`, 'user-1');
+            }
+            // Should only have 5 (latest)
+            const attrs = limitedTracker.getAttributions();
+            assert.strictEqual(attrs.length, MAX_ATTRIBUTIONS);
+            // First attribution should be session-2 (0, 1 were evicted)
+            assert.strictEqual(attrs[0].sessionId, 'session-2');
+        });
+        it('provides memory stats', () => {
+            tracker.recordSpend(1.0, 'session-1', 'user-1');
+            tracker.recordSpend(SESSION_SPEND_FIRST, 'session-2', 'user-2');
+            const stats = tracker.getStats();
+            assert.strictEqual(stats.attributions, COUNT_TWO);
+            assert.strictEqual(stats.dailyEntries, 1); // Same day
+            assert.strictEqual(stats.sessionEntries, COUNT_TWO);
+            assert.strictEqual(stats.userDailyEntries, COUNT_TWO);
+        });
+        it('throws on negative cost', () => {
+            assert.throws(() => tracker.recordSpend(-1.0, 'session-1', 'user-1'), CostEstimationError);
+        });
+        it('throws on NaN cost', () => {
+            assert.throws(() => tracker.recordSpend(NaN, 'session-1', 'user-1'), CostEstimationError);
+        });
+        it('throws on oversized metadata', () => {
+            const largeMetadata = { data: 'x'.repeat(LARGE_METADATA_LENGTH) };
+            assert.throws(() => tracker.recordSpend(1.0, 'session-1', 'user-1', 'model', 0, 0, largeMetadata), CostEstimationError);
+        });
+        it('throws on non-serializable metadata', () => {
+            const circular = {};
+            circular.self = circular;
+            assert.throws(() => tracker.recordSpend(1.0, 'session-1', 'user-1', 'model', 0, 0, circular), CostEstimationError);
+        });
+        it('allows manual cleanup', () => {
+            tracker.recordSpend(1.0, 'session-1', 'user-1');
+            tracker.cleanup();
+            // Should not throw
+            assert.ok(true);
+        });
+    });
+    // ==========================================================================
+    // estimateBatchCost
+    // ==========================================================================
+    describe('estimateBatchCost', () => {
+        it('calculates total cost for batch', () => {
+            const requests = [
+                { usage: { inputTokens: COUNT_THOUSAND, outputTokens: TEST_OUTPUT_TOKENS }, model: 'claude-sonnet-4-20250514' },
+                { usage: { inputTokens: COUNT_TWO_THOUSAND, outputTokens: COUNT_THOUSAND }, model: 'claude-sonnet-4-20250514' },
+            ];
+            const result = estimateBatchCost(requests);
+            // First: $0.003 + $0.0075 = $0.0105
+            // Second: $0.006 + $0.015 = $0.021
+            // Total: $0.0315
+            assert.strictEqual(result.totalCost, EXPECTED_BATCH_TOTAL_COST);
+            assert.strictEqual(result.perRequest.length, COUNT_TWO);
+        });
+        it('handles empty batch', () => {
+            const result = estimateBatchCost([]);
+            assert.strictEqual(result.totalCost, 0);
+            assert.strictEqual(result.perRequest.length, 0);
+        });
+        it('handles mixed models', () => {
+            const requests = [
+                { usage: { inputTokens: COUNT_THOUSAND, outputTokens: TEST_OUTPUT_TOKENS }, model: 'claude-sonnet-4-20250514' },
+                { usage: { inputTokens: COUNT_THOUSAND, outputTokens: TEST_OUTPUT_TOKENS }, model: 'gpt-4o' },
+            ];
+            const result = estimateBatchCost(requests);
+            assert.strictEqual(result.perRequest[0].model, 'claude-sonnet-4-20250514');
+            assert.strictEqual(result.perRequest[1].model, 'gpt-4o');
+        });
+        it('throws on invalid usage in batch', () => {
+            assert.throws(() => estimateBatchCost([
+                { usage: { inputTokens: -1, outputTokens: 0 }, model: 'test' }
+            ]), CostEstimationError);
+        });
+    });
+    // ==========================================================================
+    // estimateCostBeforeRequest
+    // ==========================================================================
+    describe('estimateCostBeforeRequest', () => {
+        it('estimates cost for planned request', () => {
+            const result = estimateCostBeforeRequest(COUNT_FIVE_THOUSAND, COUNT_TWO_THOUSAND, 'claude-sonnet-4-20250514');
+            // Input: 5000 * $3/1M = $0.015
+            // Output: 2000 * $15/1M = $0.03
+            assert.strictEqual(result.inputCost, EXPECTED_PRE_REQUEST_INPUT_COST);
+            assert.strictEqual(result.outputCost, EXPECTED_PRE_REQUEST_OUTPUT_COST);
+            assert.strictEqual(result.totalCost, EXPECTED_PRE_REQUEST_TOTAL_COST);
+        });
+        it('throws on negative tokens', () => {
+            assert.throws(() => estimateCostBeforeRequest(NEGATIVE_TOKEN_COUNT, 0, 'test'), CostEstimationError);
+        });
+    });
+    // ==========================================================================
+    // estimateTokens
+    // ==========================================================================
+    describe('estimateTokens', () => {
+        it('estimates tokens from text length', () => {
+            const text = 'Hello world'; // 11 chars
+            const tokens = estimateTokens(text);
+            // 11 / 4 = 2.75, ceil = 3
+            assert.strictEqual(tokens, EXPECTED_DEFAULT_TOKEN_COUNT);
+        });
+        it('uses custom chars per token', () => {
+            const text = 'Hello world'; // 11 chars
+            const tokens = estimateTokens(text, CHARS_PER_TOKEN_CUSTOM);
+            // 11 / 2 = 5.5, ceil = 6
+            assert.strictEqual(tokens, EXPECTED_CUSTOM_TOKEN_COUNT);
+        });
+        it('handles empty string', () => {
+            assert.strictEqual(estimateTokens(''), 0);
+        });
+        it('throws on zero charsPerToken', () => {
+            assert.throws(() => estimateTokens('hello', 0), CostEstimationError);
+        });
+        it('throws on negative charsPerToken', () => {
+            assert.throws(() => estimateTokens('hello', -1), CostEstimationError);
+        });
+        it('throws on NaN charsPerToken', () => {
+            assert.throws(() => estimateTokens('hello', NaN), CostEstimationError);
+        });
+        it('throws on Infinity charsPerToken', () => {
+            assert.throws(() => estimateTokens('hello', Infinity), CostEstimationError);
+        });
+    });
+    // ==========================================================================
+    // Error class tests
+    // ==========================================================================
+    describe('CostEstimationError', () => {
+        it('has correct name', () => {
+            const error = new CostEstimationError('test');
+            assert.strictEqual(error.name, 'CostEstimationError');
+        });
+        it('has correct message', () => {
+            const error = new CostEstimationError('test message');
+            assert.strictEqual(error.message, 'test message');
+        });
+        it('is instanceof Error', () => {
+            const error = new CostEstimationError('test');
+            assert.ok(error instanceof Error);
+        });
+    });
+    // ==========================================================================
+    // InvalidModelError tests
+    // ==========================================================================
+    describe('InvalidModelError', () => {
+        it('has correct name', () => {
+            const error = new InvalidModelError('bad-model-v1');
+            assert.strictEqual(error.name, 'InvalidModelError');
+        });
+        it('is instanceof CostEstimationError', () => {
+            const error = new InvalidModelError('bad-model-v1');
+            assert.ok(error instanceof CostEstimationError);
+        });
+        it('is instanceof Error', () => {
+            const error = new InvalidModelError('bad-model-v1');
+            assert.ok(error instanceof Error);
+        });
+        it('includes model name in message', () => {
+            const error = new InvalidModelError('my-unknown-model');
+            assert.ok(error.message.includes('my-unknown-model'));
+            assert.ok(error.message.includes('Unknown model'));
+        });
+    });
+    // ==========================================================================
+    // Zod Schema tests
+    // ==========================================================================
+    describe('tokenUsageSchema', () => {
+        it('accepts valid token usage', () => {
+            const result = tokenUsageSchema.safeParse({
+                inputTokens: COUNT_THOUSAND,
+                outputTokens: TEST_OUTPUT_TOKENS,
+            });
+            assert.ok(result.success);
+        });
+        it('accepts cache tokens', () => {
+            const result = tokenUsageSchema.safeParse({
+                inputTokens: COUNT_HUNDRED,
+                outputTokens: COUNT_HUNDRED,
+                cacheReadTokens: COUNT_FIVE_THOUSAND,
+                cacheCreationTokens: COUNT_TWO_THOUSAND,
+            });
+            assert.ok(result.success);
+            if (result.success) {
+                assert.strictEqual(result.data.cacheReadTokens, COUNT_FIVE_THOUSAND);
+                assert.strictEqual(result.data.cacheCreationTokens, COUNT_TWO_THOUSAND);
+            }
+        });
+        it('validates max token bounds', () => {
+            const tooLarge = Number.MAX_SAFE_INTEGER + 1;
+            const result = tokenUsageSchema.safeParse({
+                inputTokens: tooLarge,
+                outputTokens: 0,
+            });
+            assert.ok(!result.success);
+        });
+        it('rejects negative tokens', () => {
+            const result = tokenUsageSchema.safeParse({
+                inputTokens: -1,
+                outputTokens: 0,
+            });
+            assert.ok(!result.success);
+        });
+        it('rejects non-integer tokens', () => {
+            const result = tokenUsageSchema.safeParse({
+                inputTokens: 1.5,
+                outputTokens: 0,
+            });
+            assert.ok(!result.success);
+        });
+    });
+    describe('budgetConfigSchema', () => {
+        it('accepts valid config', () => {
+            const result = budgetConfigSchema.safeParse({
+                dailyLimit: COUNT_HUNDRED,
+                sessionLimit: COUNT_FIFTY,
+                alertThreshold: 0.8,
+                criticalThreshold: 0.95,
+            });
+            assert.ok(result.success);
+        });
+        it('enforces alert < critical threshold', () => {
+            const result = budgetConfigSchema.safeParse({
+                alertThreshold: 0.95,
+                criticalThreshold: 0.8,
+            });
+            assert.ok(!result.success);
+        });
+        it('applies default thresholds', () => {
+            const result = budgetConfigSchema.safeParse({
+                dailyLimit: COUNT_HUNDRED,
+            });
+            assert.ok(result.success);
+            if (result.success) {
+                assert.strictEqual(result.data.alertThreshold, 0.8);
+                assert.strictEqual(result.data.criticalThreshold, 0.95);
+            }
+        });
+        it('rejects non-positive limits', () => {
+            const result = budgetConfigSchema.safeParse({
+                dailyLimit: 0,
+            });
+            assert.ok(!result.success);
+        });
+    });
+    // ==========================================================================
+    // createBudgetTracker advanced tests
+    // ==========================================================================
+    describe('createBudgetTracker (advanced)', () => {
+        it('returns undefined bySession/byUser in summary with no attributions', () => {
+            const tracker = createBudgetTracker({});
+            const summary = tracker.getSummary();
+            assert.strictEqual(summary.totalCost, 0);
+            assert.strictEqual(summary.bySession, undefined);
+            assert.strictEqual(summary.byUser, undefined);
+        });
+        it('returns empty bySession/byUser when no session/user data recorded', () => {
+            const tracker = createBudgetTracker({});
+            tracker.recordSpend(1.0); // no sessionId or userId
+            const summary = tracker.getSummary();
+            assert.strictEqual(summary.bySession, undefined);
+            assert.strictEqual(summary.byUser, undefined);
+        });
+        it('cleanup removes entries older than retention days', () => {
+            const tracker = createBudgetTracker({
+                retentionDays: COUNT_TWO,
+            });
+            // Record spend today
+            tracker.recordSpend(1.0, 'session-1', 'user-1');
+            // Access internal state via getStats to confirm initial setup
+            let stats = tracker.getStats();
+            assert.strictEqual(stats.dailyEntries, 1);
+            tracker.cleanup();
+            // Old entries should be cleaned up
+            // New entries should remain
+            stats = tracker.getStats();
+            assert.ok(stats.dailyEntries <= 1); // Cleaned old entries
+        });
+        it('reset zeroes all tracked stats', () => {
+            const tracker = createBudgetTracker({
+                dailyLimit: BUDGET_LIMIT_STANDARD,
+            });
+            tracker.recordSpend(BUDGET_SPEND_HALF, 'session-1', 'user-1');
+            tracker.recordSpend(SESSION_SPEND_FIRST, 'session-2', 'user-2');
+            let stats = tracker.getStats();
+            assert.strictEqual(stats.attributions, COUNT_TWO);
+            assert.ok(stats.dailyEntries > 0);
+            assert.ok(stats.sessionEntries > 0);
+            tracker.reset();
+            stats = tracker.getStats();
+            assert.strictEqual(stats.attributions, 0);
+            assert.strictEqual(stats.dailyEntries, 0);
+            assert.strictEqual(stats.sessionEntries, 0);
+            assert.strictEqual(stats.userDailyEntries, 0);
+        });
+        it('getStats reflects accurate counts after operations', () => {
+            const tracker = createBudgetTracker({});
+            tracker.recordSpend(1.0, 'sess-1', 'user-1');
+            tracker.recordSpend(2.0, 'sess-1', 'user-2');
+            tracker.recordSpend(3.0, 'sess-2', 'user-1');
+            const stats = tracker.getStats();
+            assert.strictEqual(stats.attributions, COUNT_THREE);
+            assert.strictEqual(stats.sessionEntries, COUNT_TWO); // sess-1, sess-2
+            assert.strictEqual(stats.userDailyEntries, COUNT_TWO); // user-1, user-2 (today)
+        });
+        it('recordSpend without sessionId/userId still tracks properly', () => {
+            const tracker = createBudgetTracker({});
+            tracker.recordSpend(1.0);
+            tracker.recordSpend(2.0, 'sess-1');
+            tracker.recordSpend(3.0, undefined, 'user-1');
+            const summary = tracker.getSummary();
+            assert.strictEqual(summary.totalCost, 6.0);
+            assert.strictEqual(summary.totalRequests, COUNT_THREE);
+            // bySession should only have sess-1
+            if (summary.bySession) {
+                assert.strictEqual(Object.keys(summary.bySession).length, 1);
+                assert.ok('sess-1' in summary.bySession);
+            }
+        });
+    });
+    // ==========================================================================
+    // estimateTokens additional tests
+    // ==========================================================================
+    describe('estimateTokens (additional)', () => {
+        it('handles short strings', () => {
+            const result = estimateTokens('hi'); // 2 chars
+            assert.strictEqual(result, 1); // 2 / 4 = 0.5, ceil = 1
+        });
+        it('uses fallback charsPerToken when default not optimal', () => {
+            const text = 'a'; // 1 char
+            const resultDefault = estimateTokens(text); // 1 / 4 = 0.25, ceil = 1
+            const resultCustom = estimateTokens(text, 1); // 1 / 1 = 1
+            assert.strictEqual(resultDefault, 1);
+            assert.strictEqual(resultCustom, 1);
+        });
+        it('scales linearly with text length', () => {
+            const base = 'x'.repeat(COUNT_HUNDRED);
+            const result1 = estimateTokens(base);
+            const result2 = estimateTokens(base + base); // Double size
+            assert.ok(result2 > result1);
+            assert.strictEqual(result2, COUNT_TWO * result1); // Linear scaling
+        });
+    });
+});
+//# sourceMappingURL=cost-estimation.test.js.map