observability-toolkit 1.8.5 → 2.1.0

package/dist/tools/detect-trace-anomalies.js

@@ -0,0 +1,66 @@
+/**
+ * MCP tool: detect per-span anomalies in local telemetry (INV-2).
+ *
+ * Reads TraceSpan records from the local JSONL backend, runs the anomaly
+ * detection engine, and returns anomaly results grouped by severity.
+ */
+import { z } from 'zod';
+import { sharedLocalBackend } from '../backends/shared.js';
+import { sessionSchema, traceIdSchema, dateRangeSchema, paginationSchema, } from '../lib/core/shared-schemas.js';
+import { validateCommonInputs, wrapValidationErrors } from '../lib/core/input-validator.js';
+import { enforceMemoryLimit } from '../lib/core/file-utils.js';
+import { MAX_RESULTS_IN_MEMORY } from '../lib/core/constants.js';
+import { detectSpanAnomalies, buildAnomalySummary, } from '../lib/observability/trace-anomaly-detector.js';
+const ANOMALY_DETAIL_LIMIT = 100;
+export const detectTraceAnomaliesSchema = z.object({
+    ...sessionSchema,
+    ...traceIdSchema,
+    ...dateRangeSchema,
+    ...paginationSchema,
+    minSeverity: z.enum(['none', 'warn', 'error', 'critical']).default('warn').describe('Minimum severity to include in results. Defaults to "warn" (excludes clean spans).'),
+    includeClean: z.boolean().default(false).describe('When true, include spans with no anomalies (overrides minSeverity filtering).'),
+});
+const SEVERITY_ORDER = ['none', 'warn', 'error', 'critical'];
+function meetsMinSeverity(anomaly, min) {
+    return SEVERITY_ORDER.indexOf(anomaly.overallSeverity) >= SEVERITY_ORDER.indexOf(min);
+}
+export const detectTraceAnomalies = wrapValidationErrors(async (rawInput, options) => {
+    const input = detectTraceAnomaliesSchema.parse(rawInput);
+    const { limit: validatedLimit } = validateCommonInputs(input);
+    const local = options?.localBackend ?? sharedLocalBackend;
+    const attributeFilter = input.sessionId
+        ? { 'session.id': input.sessionId }
+        : undefined;
+    const rawSpans = await local.queryTraces({
+        traceId: input.traceId,
+        attributeFilter,
+        startDate: input.startDate,
+        endDate: input.endDate,
+        limit: validatedLimit,
+    });
+    const { results: spans, truncated, originalCount } = enforceMemoryLimit(rawSpans, MAX_RESULTS_IN_MEMORY);
+    const allAnomalies = detectSpanAnomalies(spans);
+    const summary = buildAnomalySummary(allAnomalies, input.sessionId);
+    const filtered = input.includeClean
+        ? allAnomalies
+        : allAnomalies.filter(a => meetsMinSeverity(a, input.minSeverity));
+    // Cap detailed results to avoid overwhelming output
+    const anomalies = filtered.slice(0, ANOMALY_DETAIL_LIMIT);
+    return {
+        summary,
+        anomalies,
+        ...(filtered.length > ANOMALY_DETAIL_LIMIT && {
+            anomaliesOmitted: filtered.length - ANOMALY_DETAIL_LIMIT,
+        }),
+        ...(truncated && { truncated: true, originalCount }),
+    };
+});
+export const detectTraceAnomaliesTool = {
+    name: 'obs_detect_trace_anomalies',
+    description: 'Detect anomalous spans in local JSONL telemetry. ' +
+        'Fires signals for: high duration, error status, excessive token usage, unknown span names, instrumentation loops. ' +
+        'Filter by sessionId, traceId, or date range. Use minSeverity to focus on high-severity issues.',
+    inputSchema: detectTraceAnomaliesSchema,
+    handler: detectTraceAnomalies,
+};
+//# sourceMappingURL=detect-trace-anomalies.js.map

package/dist/tools/detect-trace-anomalies.js.map

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

package/dist/tools/estimate-cost.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Cost estimation and multi-provider comparison tool
+ */
+import { z } from 'zod';
+export declare const estimateCostSchema: z.ZodObject<{
+    inputTokens: z.ZodInt;
+    outputTokens: z.ZodInt;
+    cacheReadTokens: z.ZodOptional<z.ZodInt>;
+    cacheCreationTokens: z.ZodOptional<z.ZodInt>;
+    providers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sortBy: z.ZodDefault<z.ZodEnum<{
+        model: "model";
+        provider: "provider";
+        cost: "cost";
+    }>>;
+}, z.core.$strip>;
+export type EstimateCostInput = z.input<typeof estimateCostSchema>;
+export declare function estimateCost(rawInput: EstimateCostInput): Promise<{
+    error: string;
+} | {
+    warning?: string | undefined;
+    input: {
+        cacheCreationTokens?: number | undefined;
+        cacheReadTokens?: number | undefined;
+        inputTokens: number;
+        outputTokens: number;
+    };
+    comparison: {
+        note?: string | undefined;
+        model: string;
+        provider: string;
+        totalCost: string;
+        inputCost: string;
+        outputCost: string;
+    }[];
+    byProvider: {
+        [k: string]: {
+            model: string;
+            totalCost: string;
+            inputCost: string;
+            outputCost: string;
+        }[];
+    };
+    summary: {
+        cheapest: {
+            model: string;
+            provider: string;
+            totalCost: string;
+        };
+        mostExpensive: {
+            model: string;
+            provider: string;
+            totalCost: string;
+        };
+        costRatio: string | null;
+        modelsCompared: number;
+    };
+    error?: undefined;
+}>;
+export declare const estimateCostTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        inputTokens: z.ZodInt;
+        outputTokens: z.ZodInt;
+        cacheReadTokens: z.ZodOptional<z.ZodInt>;
+        cacheCreationTokens: z.ZodOptional<z.ZodInt>;
+        providers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sortBy: z.ZodDefault<z.ZodEnum<{
+            model: "model";
+            provider: "provider";
+            cost: "cost";
+        }>>;
+    }, z.core.$strip>;
+    handler: typeof estimateCost;
+};
+//# sourceMappingURL=estimate-cost.d.ts.map

package/dist/tools/estimate-cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate-cost.d.ts","sourceRoot":"","sources":["../../src/tools/estimate-cost.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,eAAO,MAAM,kBAAkB;;;;;;;;;;;iBAO7B,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAgDnE,wBAAsB,YAAY,CAAC,QAAQ,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuD7D;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;CAK5B,CAAC"}

package/dist/tools/estimate-cost.js

@@ -0,0 +1,104 @@
+/**
+ * Cost estimation and multi-provider comparison tool
+ */
+import { z } from 'zod';
+import { calculateCost, listModelsWithPricing, isPricingStale, } from '../lib/cost/cost-estimation.js';
+import { listEffectiveModels } from '../lib/cost/pricing-cache.js';
+import { COST_DECIMAL_PLACES } from '../lib/core/units.js';
+// recordCostMetric is available from '../lib/observability/metrics.js' for per-request cost recording.
+// Not used here — this tool compares hypothetical costs across all models.
+export const estimateCostSchema = z.object({
+    inputTokens: z.int().min(0).describe('Input token count'),
+    outputTokens: z.int().min(0).describe('Output token count'),
+    cacheReadTokens: z.int().min(0).optional().describe('Cached read tokens (discounted input)'),
+    cacheCreationTokens: z.int().min(0).optional().describe('Cache creation tokens (full input rate)'),
+    providers: z.array(z.string()).optional().describe('Filter to specific providers (e.g. ["anthropic", "openai"])'),
+    sortBy: z.enum(['cost', 'model', 'provider']).default('cost').describe('Sort order (default: cost ascending)'),
+});
+function _buildModelRows(allModels, providers, usage) {
+    const providerMap = new Map(listEffectiveModels().map(m => [m.model, m.provider]));
+    return allModels
+        .map(({ model }) => {
+        const provider = providerMap.get(model) ?? 'other';
+        if (providers && !providers.includes(provider))
+            return null;
+        const cost = calculateCost(usage, model);
+        return { model, provider, inputCost: cost.inputCost, outputCost: cost.outputCost, totalCost: cost.totalCost, usedFallbackPricing: cost.usedFallbackPricing ?? false };
+    })
+        .filter((r) => r !== null);
+}
+function _sortModelRows(rows, sortBy) {
+    if (sortBy === 'cost') {
+        rows.sort((a, b) => a.totalCost - b.totalCost);
+    }
+    else if (sortBy === 'model') {
+        rows.sort((a, b) => a.model.localeCompare(b.model));
+    }
+    else {
+        rows.sort((a, b) => a.provider.localeCompare(b.provider) || a.totalCost - b.totalCost);
+    }
+}
+function _formatModelRow(r) {
+    return {
+        model: r.model,
+        provider: r.provider,
+        totalCost: `$${r.totalCost.toFixed(COST_DECIMAL_PLACES)}`,
+        inputCost: `$${r.inputCost.toFixed(COST_DECIMAL_PLACES)}`,
+        outputCost: `$${r.outputCost.toFixed(COST_DECIMAL_PLACES)}`,
+        ...(r.usedFallbackPricing && { note: 'fallback pricing' }),
+    };
+}
+export async function estimateCost(rawInput) {
+    const input = estimateCostSchema.parse(rawInput);
+    // Build and validate token usage using the inferred schema type
+    const usage = {
+        inputTokens: input.inputTokens,
+        outputTokens: input.outputTokens,
+        ...(input.cacheReadTokens !== undefined && { cacheReadTokens: input.cacheReadTokens }),
+        ...(input.cacheCreationTokens !== undefined && { cacheCreationTokens: input.cacheCreationTokens }),
+    };
+    const rows = _buildModelRows(listModelsWithPricing(), input.providers, usage);
+    if (rows.length === 0) {
+        return { error: `No models found for providers: ${input.providers?.join(', ')}. Available: anthropic, openai, google, mistral, cohere, groq, together, perplexity` };
+    }
+    // Cheapest/mostExpensive always by cost, independent of display sort order
+    const costSorted = [...rows].sort((a, b) => a.totalCost - b.totalCost);
+    const cheapest = costSorted[0];
+    const mostExpensive = costSorted[costSorted.length - 1];
+    _sortModelRows(rows, input.sortBy);
+    const byProvider = {};
+    for (const row of rows) {
+        (byProvider[row.provider] ??= []).push(row);
+    }
+    const staleness = isPricingStale();
+    const fmt = (n) => `$${n.toFixed(COST_DECIMAL_PLACES)}`;
+    return {
+        input: {
+            inputTokens: input.inputTokens,
+            outputTokens: input.outputTokens,
+            ...(input.cacheReadTokens !== undefined && { cacheReadTokens: input.cacheReadTokens }),
+            ...(input.cacheCreationTokens !== undefined && { cacheCreationTokens: input.cacheCreationTokens }),
+        },
+        comparison: rows.map(_formatModelRow),
+        byProvider: Object.fromEntries(Object.entries(byProvider).map(([provider, providerRows]) => [
+            provider,
+            providerRows.map(r => ({ model: r.model, totalCost: fmt(r.totalCost), inputCost: fmt(r.inputCost), outputCost: fmt(r.outputCost) })),
+        ])),
+        summary: {
+            cheapest: { model: cheapest.model, provider: cheapest.provider, totalCost: fmt(cheapest.totalCost) },
+            mostExpensive: { model: mostExpensive.model, provider: mostExpensive.provider, totalCost: fmt(mostExpensive.totalCost) },
+            costRatio: cheapest.totalCost > 0 ? `${(mostExpensive.totalCost / cheapest.totalCost).toFixed(1)}x spread` : null,
+            modelsCompared: rows.length,
+        },
+        ...(staleness.isStale && {
+            warning: `Pricing data is ${staleness.daysSinceUpdate} days old (last updated: ${staleness.lastUpdated}). Costs may be inaccurate.`,
+        }),
+    };
+}
+export const estimateCostTool = {
+    name: 'obs_estimate_cost',
+    description: 'Estimate and compare LLM request costs across all supported providers. Returns per-model cost breakdown sorted by cost, grouped by provider, with cheapest/most-expensive summary.',
+    inputSchema: estimateCostSchema,
+    handler: estimateCost,
+};
+//# sourceMappingURL=estimate-cost.js.map

package/dist/tools/estimate-cost.js.map

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

package/dist/tools/estimate-cost.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for estimate-cost tool
+ */
+export {};
+//# sourceMappingURL=estimate-cost.test.d.ts.map

package/dist/tools/estimate-cost.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate-cost.test.d.ts","sourceRoot":"","sources":["../../src/tools/estimate-cost.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/tools/estimate-cost.test.js

@@ -0,0 +1,343 @@
+/**
+ * Unit tests for estimate-cost tool
+ */
+import { describe, it } from 'vitest';
+import assert from 'node:assert';
+import { estimateCost, estimateCostSchema, estimateCostTool } from './estimate-cost.js';
+import { TOKENS_PER_MILLION } from '../lib/core/constants.js';
+// ---------- test constants ----------
+const INPUT_TOKENS_1K = 1000;
+const OUTPUT_TOKENS_500 = 500;
+const CACHE_READ_TOKENS = 200;
+const CACHE_CREATION_TOKENS = 100;
+const INPUT_TOKENS_5K = 5000;
+const OUTPUT_TOKENS_2K = 2000;
+const MIN_PROVIDER_COUNT = 5;
+// ============================================================================
+// Schema validation
+// ============================================================================
+void describe('estimateCostSchema', () => {
+    void it('should accept minimal valid input', () => {
+        const result = estimateCostSchema.safeParse({ inputTokens: 1000, outputTokens: 500 });
+        assert.strictEqual(result.success, true);
+        assert.strictEqual(result.data?.inputTokens, INPUT_TOKENS_1K);
+        assert.strictEqual(result.data?.outputTokens, OUTPUT_TOKENS_500);
+        assert.strictEqual(result.data?.sortBy, 'cost'); // default
+    });
+    void it('should accept all optional fields', () => {
+        const result = estimateCostSchema.safeParse({
+            inputTokens: 1000,
+            outputTokens: 500,
+            cacheReadTokens: 200,
+            cacheCreationTokens: 100,
+            providers: ['anthropic', 'openai'],
+            sortBy: 'provider',
+        });
+        assert.strictEqual(result.success, true);
+        assert.strictEqual(result.data?.cacheReadTokens, CACHE_READ_TOKENS);
+        assert.strictEqual(result.data?.cacheCreationTokens, CACHE_CREATION_TOKENS);
+        assert.deepStrictEqual(result.data?.providers, ['anthropic', 'openai']);
+        assert.strictEqual(result.data?.sortBy, 'provider');
+    });
+    void it('should accept zero tokens', () => {
+        const result = estimateCostSchema.safeParse({ inputTokens: 0, outputTokens: 0 });
+        assert.strictEqual(result.success, true);
+    });
+    void it('should reject negative tokens', () => {
+        const result = estimateCostSchema.safeParse({ inputTokens: -1, outputTokens: 0 });
+        assert.strictEqual(result.success, false);
+    });
+    void it('should reject non-integer tokens', () => {
+        const result = estimateCostSchema.safeParse({ inputTokens: 1.5, outputTokens: 0 });
+        assert.strictEqual(result.success, false);
+    });
+    void it('should reject missing required fields', () => {
+        assert.strictEqual(estimateCostSchema.safeParse({}).success, false);
+        assert.strictEqual(estimateCostSchema.safeParse({ inputTokens: 1000 }).success, false);
+        assert.strictEqual(estimateCostSchema.safeParse({ outputTokens: 500 }).success, false);
+    });
+    void it('should accept all sortBy values', () => {
+        for (const sortBy of ['cost', 'model', 'provider']) {
+            const result = estimateCostSchema.safeParse({ inputTokens: 1000, outputTokens: 500, sortBy });
+            assert.strictEqual(result.success, true);
+            assert.strictEqual(result.data?.sortBy, sortBy);
+        }
+    });
+    void it('should reject invalid sortBy values', () => {
+        const result = estimateCostSchema.safeParse({ inputTokens: 1000, outputTokens: 500, sortBy: 'invalid' });
+        assert.strictEqual(result.success, false);
+    });
+});
+// ============================================================================
+// Handler — basic output structure
+// ============================================================================
+void describe('estimateCost handler', () => {
+    void it('should return result with all expected fields', async () => {
+        const result = await estimateCost({ inputTokens: 1000, outputTokens: 500 });
+        assert.ok(!('error' in result));
+        assert.ok(result.input);
+        assert.ok(result.comparison);
+        assert.ok(result.byProvider);
+        assert.ok(result.summary);
+        assert.ok(result.summary.cheapest);
+        assert.ok(result.summary.mostExpensive);
+        assert.ok(typeof result.summary.modelsCompared === 'number');
+        assert.ok(result.summary.modelsCompared > 0);
+    });
+    void it('should echo input tokens in response', async () => {
+        const result = await estimateCost({ inputTokens: 5000, outputTokens: 2000 });
+        assert.ok(!('error' in result));
+        assert.strictEqual(result.input.inputTokens, INPUT_TOKENS_5K);
+        assert.strictEqual(result.input.outputTokens, OUTPUT_TOKENS_2K);
+    });
+    void it('should echo cache tokens when provided', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            cacheReadTokens: 200, cacheCreationTokens: 100,
+        });
+        assert.ok(!('error' in result));
+        assert.strictEqual(result.input.cacheReadTokens, CACHE_READ_TOKENS);
+        assert.strictEqual(result.input.cacheCreationTokens, CACHE_CREATION_TOKENS);
+    });
+    void it('should not include cache tokens in input when not provided', async () => {
+        const result = await estimateCost({ inputTokens: 1000, outputTokens: 500 });
+        assert.ok(!('error' in result));
+        assert.strictEqual('cacheReadTokens' in result.input, false);
+        assert.strictEqual('cacheCreationTokens' in result.input, false);
+    });
+});
+// ============================================================================
+// Provider detection
+// ============================================================================
+void describe('provider detection', () => {
+    void it('should group anthropic models correctly', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            providers: ['anthropic'],
+        });
+        assert.ok(!('error' in result));
+        assert.ok(result.byProvider.anthropic);
+        assert.ok(result.byProvider.anthropic.length > 0);
+        // All models should start with 'claude'
+        for (const model of result.byProvider.anthropic) {
+            assert.ok(model.model.startsWith('claude'), `Expected ${model.model} to start with 'claude'`);
+        }
+    });
+    void it('should group openai models correctly', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            providers: ['openai'],
+        });
+        assert.ok(!('error' in result));
+        assert.ok(result.byProvider.openai);
+        for (const model of result.byProvider.openai) {
+            assert.ok(model.model.startsWith('gpt-') || model.model.startsWith('o1') || model.model.startsWith('o3'), `Expected ${model.model} to be an OpenAI model`);
+        }
+    });
+    void it('should classify mixtral-8x7b-groq as groq, not mistral', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            providers: ['groq'],
+        });
+        assert.ok(!('error' in result));
+        assert.ok(result.byProvider.groq);
+        const groqModels = result.byProvider.groq.map(m => m.model);
+        assert.ok(groqModels.includes('mixtral-8x7b-groq'), `Expected 'mixtral-8x7b-groq' in groq, got: ${groqModels}`);
+    });
+    void it('should classify llama-3.3-70b as groq, not together', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            providers: ['groq'],
+        });
+        assert.ok(!('error' in result));
+        const groqModels = result.byProvider.groq.map(m => m.model);
+        assert.ok(groqModels.includes('llama-3.3-70b'), `Expected 'llama-3.3-70b' in groq, got: ${groqModels}`);
+    });
+    void it('should classify llama-3-70b and llama-3-8b as together', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            providers: ['together'],
+        });
+        assert.ok(!('error' in result));
+        const togetherModels = result.byProvider.together.map(m => m.model);
+        assert.ok(togetherModels.includes('llama-3-70b'), `Expected 'llama-3-70b' in together, got: ${togetherModels}`);
+    });
+    void it('should return error for unknown provider', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            providers: ['nonexistent-provider'],
+        });
+        assert.ok('error' in result);
+        assert.ok(typeof result.error === 'string' && result.error.includes('No models found'));
+    });
+});
+// ============================================================================
+// Provider filtering
+// ============================================================================
+void describe('provider filtering', () => {
+    void it('should return all providers when no filter set', async () => {
+        const result = await estimateCost({ inputTokens: 1000, outputTokens: 500 });
+        assert.ok(!('error' in result));
+        const providers = Object.keys(result.byProvider);
+        assert.ok(providers.length >= MIN_PROVIDER_COUNT, `Expected ${MIN_PROVIDER_COUNT}+ providers, got ${providers.length}`);
+    });
+    void it('should filter to single provider', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            providers: ['google'],
+        });
+        assert.ok(!('error' in result));
+        assert.deepStrictEqual(Object.keys(result.byProvider), ['google']);
+    });
+    void it('should filter to multiple providers', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            providers: ['anthropic', 'openai'],
+        });
+        assert.ok(!('error' in result));
+        const providers = Object.keys(result.byProvider).sort();
+        assert.deepStrictEqual(providers, ['anthropic', 'openai']);
+    });
+});
+// ============================================================================
+// Sort ordering
+// ============================================================================
+void describe('sort ordering', () => {
+    void it('should sort by cost ascending by default', async () => {
+        const result = await estimateCost({ inputTokens: 10000, outputTokens: 5000 });
+        assert.ok(!('error' in result));
+        const costs = result.comparison.map(r => parseFloat(r.totalCost.replace('$', '')));
+        for (let i = 1; i < costs.length; i++) {
+            assert.ok(costs[i] >= costs[i - 1], `Cost at index ${i} (${costs[i]}) should be >= ${costs[i - 1]}`);
+        }
+    });
+    void it('should sort by model name when sortBy=model', async () => {
+        const result = await estimateCost({
+            inputTokens: 1000, outputTokens: 500,
+            sortBy: 'model',
+        });
+        assert.ok(!('error' in result));
+        const models = result.comparison.map(r => r.model);
+        const sorted = [...models].sort();
+        assert.deepStrictEqual(models, sorted);
+    });
+    void it('should keep cheapest/mostExpensive correct regardless of sortBy', async () => {
+        const costResult = await estimateCost({
+            inputTokens: 10000, outputTokens: 5000,
+            sortBy: 'cost',
+        });
+        const modelResult = await estimateCost({
+            inputTokens: 10000, outputTokens: 5000,
+            sortBy: 'model',
+        });
+        const providerResult = await estimateCost({
+            inputTokens: 10000, outputTokens: 5000,
+            sortBy: 'provider',
+        });
+        assert.ok(!('error' in costResult) && !('error' in modelResult) && !('error' in providerResult));
+        // Summary cheapest/mostExpensive should be identical regardless of sort
+        assert.strictEqual(costResult.summary.cheapest.model, modelResult.summary.cheapest.model);
+        assert.strictEqual(costResult.summary.cheapest.model, providerResult.summary.cheapest.model);
+        assert.strictEqual(costResult.summary.mostExpensive.model, modelResult.summary.mostExpensive.model);
+        assert.strictEqual(costResult.summary.mostExpensive.model, providerResult.summary.mostExpensive.model);
+    });
+});
+// ============================================================================
+// Cost calculation correctness
+// ============================================================================
+void describe('cost calculation', () => {
+    void it('should return zero cost for zero tokens', async () => {
+        const result = await estimateCost({ inputTokens: 0, outputTokens: 0 });
+        assert.ok(!('error' in result));
+        for (const row of result.comparison) {
+            assert.strictEqual(row.totalCost, '$0.0000');
+        }
+    });
+    void it('should compute correct cost for known model', async () => {
+        // claude-sonnet-4-20250514: input $3.00/1M, output $15.00/1M
+        const result = await estimateCost({
+            inputTokens: TOKENS_PER_MILLION, outputTokens: TOKENS_PER_MILLION,
+            providers: ['anthropic'],
+        });
+        assert.ok(!('error' in result));
+        const sonnet = result.comparison.find(r => r.model === 'claude-sonnet-4-20250514');
+        assert.ok(sonnet, 'Expected to find claude-sonnet-4-20250514');
+        assert.strictEqual(sonnet.inputCost, '$3.0000');
+        assert.strictEqual(sonnet.outputCost, '$15.0000');
+        assert.strictEqual(sonnet.totalCost, '$18.0000');
+    });
+    void it('should apply cache read discount', async () => {
+        // With 1M cache read tokens at default 90% discount: 1M * $3.00/1M * 0.1 = $0.30
+        const result = await estimateCost({
+            inputTokens: 0, outputTokens: 0,
+            cacheReadTokens: TOKENS_PER_MILLION,
+            providers: ['anthropic'],
+        });
+        assert.ok(!('error' in result));
+        const sonnet = result.comparison.find(r => r.model === 'claude-sonnet-4-20250514');
+        assert.ok(sonnet);
+        // Input cost includes cache read: $3.00/1M * 1M * (1-0.9) = $0.30
+        assert.strictEqual(sonnet.inputCost, '$0.3000');
+        assert.strictEqual(sonnet.outputCost, '$0.0000');
+        assert.strictEqual(sonnet.totalCost, '$0.3000');
+    });
+    void it('should charge cache creation at full input rate', async () => {
+        // 1M cache creation tokens at full input rate: 1M * $3.00/1M = $3.00
+        const result = await estimateCost({
+            inputTokens: 0, outputTokens: 0,
+            cacheCreationTokens: TOKENS_PER_MILLION,
+            providers: ['anthropic'],
+        });
+        assert.ok(!('error' in result));
+        const sonnet = result.comparison.find(r => r.model === 'claude-sonnet-4-20250514');
+        assert.ok(sonnet);
+        assert.strictEqual(sonnet.inputCost, '$3.0000');
+        assert.strictEqual(sonnet.totalCost, '$3.0000');
+    });
+});
+// ============================================================================
+// Summary
+// ============================================================================
+void describe('summary', () => {
+    void it('should identify cheapest model correctly', async () => {
+        const result = await estimateCost({
+            inputTokens: 10000, outputTokens: 5000,
+        });
+        assert.ok(!('error' in result));
+        const cheapestCost = parseFloat(result.summary.cheapest.totalCost.replace('$', ''));
+        // Verify no model in comparison has a lower cost
+        for (const row of result.comparison) {
+            const cost = parseFloat(row.totalCost.replace('$', ''));
+            assert.ok(cost >= cheapestCost, `Model ${row.model} ($${cost}) is cheaper than summary.cheapest ${result.summary.cheapest.model} ($${cheapestCost})`);
+        }
+    });
+    void it('should compute costRatio as null for zero-cost input', async () => {
+        const result = await estimateCost({ inputTokens: 0, outputTokens: 0 });
+        assert.ok(!('error' in result));
+        assert.strictEqual(result.summary.costRatio, null);
+    });
+    void it('should compute costRatio > 1x for non-zero input', async () => {
+        const result = await estimateCost({ inputTokens: 10000, outputTokens: 5000 });
+        assert.ok(!('error' in result));
+        const costRatio = result.summary.costRatio;
+        assert.ok(costRatio !== null);
+        const ratio = parseFloat(costRatio.replace('x spread', ''));
+        assert.ok(ratio >= 1, `Expected costRatio >= 1, got ${ratio}`);
+    });
+});
+// ============================================================================
+// Tool definition
+// ============================================================================
+void describe('estimateCostTool', () => {
+    void it('should have correct tool name', () => {
+        assert.strictEqual(estimateCostTool.name, 'obs_estimate_cost');
+    });
+    void it('should have a description', () => {
+        assert.ok(estimateCostTool.description.length > 0);
+    });
+    void it('should have schema and handler', () => {
+        assert.ok(estimateCostTool.inputSchema);
+        assert.strictEqual(typeof estimateCostTool.handler, 'function');
+    });
+});
+//# sourceMappingURL=estimate-cost.test.js.map