@wundam/orchex 1.0.0-rc.1

package/dist/intelligence/context-optimizer.d.ts

@@ -0,0 +1,111 @@
+export interface TokenBudget {
+    totalTokens: number;
+    projectContext: number;
+    streamContext: number;
+    dependencyContext: number;
+    instructions: number;
+}
+export interface ContextOptimization {
+    includedFiles: string[];
+    excludedFiles: string[];
+    tokenBudget: TokenBudget;
+    cachingHints: CachingHint[];
+    estimatedSavings: number;
+    warnings?: string[];
+    metrics?: OptimizationMetrics;
+}
+export interface CachingHint {
+    content: string;
+    type: 'system_prompt' | 'project_context' | 'stream_context';
+    reusable: boolean;
+    estimatedTokens: number;
+}
+export interface OptimizationMetrics {
+    totalFiles: number;
+    includedFiles: number;
+    excludedFiles: number;
+    originalTokens: number;
+    optimizedTokens: number;
+    compressionRatio: number;
+}
+/**
+ * Default token budgets by model.
+ * Based on Anthropic's context window sizes.
+ */
+export declare const MODEL_TOKEN_LIMITS: Record<string, number>;
+/**
+ * Analyze import graph and return files actually needed for a stream.
+ * Prunes files that are not transitively imported.
+ *
+ * Uses breadth-first search to traverse the import graph starting from owned files.
+ * Detects circular dependencies and includes them in warnings.
+ *
+ * Algorithm:
+ * - BFS from owned files, following imports
+ * - Track the import chain (path from root) for each discovered file
+ * - Detect cycles when we find an import to an already-visited file
+ */
+export declare function pruneUnusedFiles(ownedFiles: string[], readFiles: string[], fileContents: Record<string, string>): {
+    needed: string[];
+    pruned: string[];
+    warnings?: string[];
+};
+/**
+ * Allocate token budget across context layers with intelligent prioritization.
+ *
+ * Priority: instructions > stream context > dependency context > project context
+ *
+ * Strategy:
+ * - Instructions: Fixed 15% or 1000 tokens (whichever is smaller) for task description
+ * - Stream context: Up to 50% of remaining, based on actual file sizes
+ * - Dependency context: Up to 30% of remaining, ~300 tokens per artifact
+ * - Project context: Remaining budget for file tree and metadata
+ *
+ * When file contents are provided, uses actual token estimates for more accurate allocation.
+ */
+export declare function allocateTokenBudget(totalTokens: number, streamFiles: string[], dependencyArtifacts: number, fileContents?: Record<string, string>): TokenBudget;
+/**
+ * Generate caching hints for Anthropic's prompt caching.
+ *
+ * Prompt caching can reduce costs by up to 90% for repeated context.
+ * See: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+ *
+ * Caching strategy:
+ * - System prompts: Highly reusable across all streams
+ * - Project context: Reusable within an orchestration run
+ * - Stream context: Reusable across retries of the same stream
+ *
+ * Only generates hints for content exceeding minimum thresholds to avoid
+ * cache overhead on small contexts.
+ */
+export declare function generateCachingHints(projectContext: string, streamContext: string, instructions: string): CachingHint[];
+/**
+ * Estimate token count for a string using content-aware heuristics.
+ *
+ * Different content types have different token densities:
+ * - Code: ~3.5 chars/token (dense, lots of symbols)
+ * - Comments: ~4.5 chars/token (prose, more natural language)
+ * - Whitespace: ~6.0 chars/token (sparse)
+ * - JSON: ~3.8 chars/token (structured data)
+ * - Markdown: ~4.2 chars/token (formatted prose)
+ *
+ * This provides better accuracy than simple char/4 estimation.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Full context optimization for a stream.
+ *
+ * This is the main entry point for context optimization. It:
+ * 1. Prunes unused files based on import graph analysis
+ * 2. Allocates token budget across context layers
+ * 3. Generates prompt caching hints for cost optimization
+ * 4. Calculates optimization metrics and savings estimates
+ *
+ * @param ownedFiles - Files this stream owns (will always be included)
+ * @param readFiles - Files this stream needs to read (will always be included)
+ * @param fileContents - Map of file paths to their contents
+ * @param dependencyArtifacts - Number of dependency artifacts to include
+ * @param model - Claude model name for token limit lookup
+ * @returns Complete optimization analysis with included/excluded files, budgets, and hints
+ */
+export declare function optimizeContext(ownedFiles: string[], readFiles: string[], fileContents: Record<string, string>, dependencyArtifacts: number, model?: string): ContextOptimization;

package/dist/intelligence/context-optimizer.js

@@ -0,0 +1,282 @@
+import { extractImports, resolveImportPath } from './heuristics.js';
+/**
+ * Default token budgets by model.
+ * Based on Anthropic's context window sizes.
+ */
+export const MODEL_TOKEN_LIMITS = {
+    'claude-sonnet-4-20250514': 8192,
+    'claude-3-5-sonnet-20241022': 8192,
+    'claude-3-opus-20240229': 4096,
+    default: 8192,
+};
+/**
+ * Token estimation constants based on empirical analysis.
+ * Different content types have different token densities.
+ */
+const TOKEN_DENSITY = {
+    CODE: 3.5, // chars per token for code
+    COMMENTS: 4.5, // chars per token for comments/prose
+    WHITESPACE: 6.0, // chars per token for whitespace
+    JSON: 3.8, // chars per token for JSON
+    MARKDOWN: 4.2, // chars per token for markdown
+};
+/**
+ * Analyze import graph and return files actually needed for a stream.
+ * Prunes files that are not transitively imported.
+ *
+ * Uses breadth-first search to traverse the import graph starting from owned files.
+ * Detects circular dependencies and includes them in warnings.
+ *
+ * Algorithm:
+ * - BFS from owned files, following imports
+ * - Track the import chain (path from root) for each discovered file
+ * - Detect cycles when we find an import to an already-visited file
+ */
+export function pruneUnusedFiles(ownedFiles, readFiles, fileContents) {
+    const needed = new Set([...ownedFiles]);
+    const visited = new Set();
+    const queue = [...ownedFiles];
+    const warnings = [];
+    const importChain = new Map(); // Track import path for cycle reporting
+    // Initialize chains for owned files (they're the roots)
+    for (const file of ownedFiles) {
+        importChain.set(file, []);
+    }
+    // BFS through import graph
+    while (queue.length > 0) {
+        const file = queue.shift();
+        if (visited.has(file))
+            continue; // Already processed
+        visited.add(file);
+        const content = fileContents[file];
+        if (!content)
+            continue;
+        const imports = extractImports(content);
+        for (const imp of imports) {
+            const resolved = resolveImportPath(file, imp);
+            if (resolved && fileContents[resolved]) {
+                if (visited.has(resolved)) {
+                    // CYCLE DETECTED: importing a file we've already fully processed
+                    const currentChain = importChain.get(file) || [];
+                    warnings.push(`Circular dependency detected: ${[...currentChain, file, resolved].join(' → ')}`);
+                }
+                else if (!needed.has(resolved)) {
+                    // New file discovered - add to queue
+                    needed.add(resolved);
+                    queue.push(resolved);
+                    // Track import chain for cycle reporting
+                    const currentChain = importChain.get(file) || [];
+                    importChain.set(resolved, [...currentChain, file]);
+                }
+            }
+        }
+    }
+    // Add explicitly requested read files
+    for (const f of readFiles) {
+        needed.add(f);
+    }
+    const pruned = Object.keys(fileContents).filter(f => !needed.has(f));
+    return {
+        needed: [...needed],
+        pruned,
+        warnings: warnings.length > 0 ? warnings : undefined
+    };
+}
+/**
+ * Allocate token budget across context layers with intelligent prioritization.
+ *
+ * Priority: instructions > stream context > dependency context > project context
+ *
+ * Strategy:
+ * - Instructions: Fixed 15% or 1000 tokens (whichever is smaller) for task description
+ * - Stream context: Up to 50% of remaining, based on actual file sizes
+ * - Dependency context: Up to 30% of remaining, ~300 tokens per artifact
+ * - Project context: Remaining budget for file tree and metadata
+ *
+ * When file contents are provided, uses actual token estimates for more accurate allocation.
+ */
+export function allocateTokenBudget(totalTokens, streamFiles, dependencyArtifacts, fileContents) {
+    // Reserve fixed amounts for essential parts
+    const instructions = Math.min(1000, totalTokens * 0.15); // 15% or 1000 max
+    const remaining = totalTokens - instructions;
+    // If we have file contents, use actual sizes; otherwise use estimates
+    let streamContext;
+    if (fileContents) {
+        const actualTokens = streamFiles.reduce((sum, file) => {
+            const content = fileContents[file] || '';
+            return sum + estimateTokens(content);
+        }, 0);
+        streamContext = Math.min(remaining * 0.5, actualTokens);
+    }
+    else {
+        streamContext = Math.min(remaining * 0.5, streamFiles.length * 500); // ~500 tokens per file estimate
+    }
+    const afterStream = remaining - streamContext;
+    // Dependency context: ~300 tokens per artifact
+    const dependencyContext = Math.min(afterStream * 0.3, dependencyArtifacts * 300);
+    const afterDeps = afterStream - dependencyContext;
+    // Project context gets the rest
+    const projectContext = afterDeps;
+    return {
+        totalTokens,
+        projectContext: Math.floor(projectContext),
+        streamContext: Math.floor(streamContext),
+        dependencyContext: Math.floor(dependencyContext),
+        instructions: Math.floor(instructions),
+    };
+}
+/**
+ * Generate caching hints for Anthropic's prompt caching.
+ *
+ * Prompt caching can reduce costs by up to 90% for repeated context.
+ * See: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+ *
+ * Caching strategy:
+ * - System prompts: Highly reusable across all streams
+ * - Project context: Reusable within an orchestration run
+ * - Stream context: Reusable across retries of the same stream
+ *
+ * Only generates hints for content exceeding minimum thresholds to avoid
+ * cache overhead on small contexts.
+ */
+export function generateCachingHints(projectContext, streamContext, instructions) {
+    const hints = [];
+    // System prompt / instructions are highly reusable
+    if (instructions.length > 100) {
+        hints.push({
+            content: instructions,
+            type: 'system_prompt',
+            reusable: true,
+            estimatedTokens: estimateTokens(instructions),
+        });
+    }
+    // Project context (file tree, deps) is reusable within an orchestration
+    if (projectContext.length > 500) {
+        hints.push({
+            content: projectContext,
+            type: 'project_context',
+            reusable: true,
+            estimatedTokens: estimateTokens(projectContext),
+        });
+    }
+    // Stream context is reusable across retries of the same stream
+    if (streamContext.length > 500) {
+        hints.push({
+            content: streamContext,
+            type: 'stream_context',
+            reusable: true,
+            estimatedTokens: estimateTokens(streamContext),
+        });
+    }
+    return hints;
+}
+/**
+ * Estimate token count for a string using content-aware heuristics.
+ *
+ * Different content types have different token densities:
+ * - Code: ~3.5 chars/token (dense, lots of symbols)
+ * - Comments: ~4.5 chars/token (prose, more natural language)
+ * - Whitespace: ~6.0 chars/token (sparse)
+ * - JSON: ~3.8 chars/token (structured data)
+ * - Markdown: ~4.2 chars/token (formatted prose)
+ *
+ * This provides better accuracy than simple char/4 estimation.
+ */
+export function estimateTokens(text) {
+    if (!text || text.length === 0)
+        return 0;
+    // Detect file type from content patterns
+    const isJson = text.trim().startsWith('{') || text.trim().startsWith('[');
+    const isMarkdown = /^#+\s|^-\s|^\*\s|^\d+\.\s/m.test(text);
+    // For JSON and Markdown, use specialized densities
+    if (isJson) {
+        return Math.ceil(text.length / TOKEN_DENSITY.JSON);
+    }
+    if (isMarkdown) {
+        return Math.ceil(text.length / TOKEN_DENSITY.MARKDOWN);
+    }
+    // For code, analyze line-by-line
+    const lines = text.split('\n');
+    let totalChars = 0;
+    let codeChars = 0;
+    let commentChars = 0;
+    let whitespaceChars = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        totalChars += line.length;
+        // Whitespace-only lines
+        if (trimmed.length === 0) {
+            whitespaceChars += line.length;
+            continue;
+        }
+        // Detect code vs comments (rough heuristic)
+        if (trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*') || trimmed.startsWith('#')) {
+            commentChars += line.length;
+        }
+        else {
+            codeChars += line.length;
+            // Account for indentation as whitespace
+            const indent = line.length - trimmed.length;
+            whitespaceChars += indent;
+            codeChars -= indent;
+        }
+    }
+    // Calculate tokens by content type
+    const codeTokens = Math.ceil(codeChars / TOKEN_DENSITY.CODE);
+    const commentTokens = Math.ceil(commentChars / TOKEN_DENSITY.COMMENTS);
+    const whitespaceTokens = Math.ceil(whitespaceChars / TOKEN_DENSITY.WHITESPACE);
+    const otherTokens = Math.ceil((totalChars - codeChars - commentChars - whitespaceChars) / TOKEN_DENSITY.COMMENTS);
+    return codeTokens + commentTokens + whitespaceTokens + otherTokens;
+}
+/**
+ * Full context optimization for a stream.
+ *
+ * This is the main entry point for context optimization. It:
+ * 1. Prunes unused files based on import graph analysis
+ * 2. Allocates token budget across context layers
+ * 3. Generates prompt caching hints for cost optimization
+ * 4. Calculates optimization metrics and savings estimates
+ *
+ * @param ownedFiles - Files this stream owns (will always be included)
+ * @param readFiles - Files this stream needs to read (will always be included)
+ * @param fileContents - Map of file paths to their contents
+ * @param dependencyArtifacts - Number of dependency artifacts to include
+ * @param model - Claude model name for token limit lookup
+ * @returns Complete optimization analysis with included/excluded files, budgets, and hints
+ */
+export function optimizeContext(ownedFiles, readFiles, fileContents, dependencyArtifacts, model = 'default') {
+    const totalTokens = MODEL_TOKEN_LIMITS[model] ?? MODEL_TOKEN_LIMITS.default;
+    // Prune unused files
+    const { needed, pruned, warnings } = pruneUnusedFiles(ownedFiles, readFiles, fileContents);
+    // Build context strings
+    const streamContext = needed.map(f => fileContents[f] || '').join('\n');
+    const projectContext = `Project files: ${Object.keys(fileContents).length}\nIncluded: ${needed.length}`;
+    const instructions = `You are implementing stream changes. Output an orchex-artifact block.`;
+    // Allocate budget using actual file contents
+    const tokenBudget = allocateTokenBudget(totalTokens, needed, dependencyArtifacts, fileContents);
+    // Generate caching hints
+    const cachingHints = generateCachingHints(projectContext, streamContext, instructions);
+    // Calculate optimization metrics
+    const originalTokens = estimateTokens(Object.values(fileContents).join('\n'));
+    const optimizedTokens = estimateTokens(streamContext);
+    const estimatedSavings = originalTokens > 0
+        ? Math.round((1 - optimizedTokens / originalTokens) * 100)
+        : 0;
+    const metrics = {
+        totalFiles: Object.keys(fileContents).length,
+        includedFiles: needed.length,
+        excludedFiles: pruned.length,
+        originalTokens,
+        optimizedTokens,
+        compressionRatio: originalTokens > 0 ? optimizedTokens / originalTokens : 0,
+    };
+    return {
+        includedFiles: needed,
+        excludedFiles: pruned,
+        tokenBudget,
+        cachingHints,
+        estimatedSavings,
+        warnings,
+        metrics,
+    };
+}

package/dist/intelligence/cost-tracker.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Token cost tracking and estimation for Orchex Learn.
+ * Provides cost estimation and aggregation for multi-provider token usage.
+ */
+import type { TelemetryEvent } from '../telemetry/telemetry-types.js';
+/**
+ * Token costs per 1000 tokens (in USD).
+ * Prices as of February 2026 - should be updated periodically.
+ *
+ * Reference (per 1M tokens):
+ * - DeepSeek V3.2:   $0.28 / $0.42   (~95% cheaper than Claude)
+ * - Gemini 2.5 Pro:  $1.25 / $10.00  (~60% cheaper than Claude)
+ * - Claude Sonnet:   $3.00 / $15.00  (baseline)
+ * - OpenAI GPT-4o:   $5.00 / $15.00  (~40% more than Claude)
+ * - Claude Opus:     $15.00 / $75.00 (5x Claude Sonnet)
+ */
+export declare const TOKEN_COSTS: Record<string, {
+    input: number;
+    output: number;
+}>;
+/**
+ * Cache discount rate for Anthropic prompt caching.
+ * Cached tokens cost 90% less than regular input tokens.
+ */
+export declare const CACHE_DISCOUNT_RATE = 0.9;
+/**
+ * Cost estimate for a single execution.
+ */
+export interface CostEstimate {
+    /** Number of input tokens */
+    inputTokens: number;
+    /** Number of output tokens */
+    outputTokens: number;
+    /** Cost for input tokens (USD) */
+    inputCost: number;
+    /** Cost for output tokens (USD) */
+    outputCost: number;
+    /** Total cost before cache savings (USD) */
+    totalCost: number;
+    /** Tokens read from cache (if applicable) */
+    cacheHitTokens?: number;
+    /** Estimated savings from cache (USD) */
+    cacheDiscount?: number;
+    /** Final cost after cache discount (USD) */
+    finalCost: number;
+    /** Model used for this estimate */
+    model: string;
+}
+/**
+ * Aggregated cost summary across multiple executions.
+ */
+export interface CostSummary {
+    /** Total cost across all executions (USD) */
+    totalCost: number;
+    /** Total input tokens */
+    totalInputTokens: number;
+    /** Total output tokens */
+    totalOutputTokens: number;
+    /** Total cache hit tokens */
+    totalCacheHitTokens: number;
+    /** Total savings from cache (USD) */
+    totalCacheSavings: number;
+    /** Final cost after cache discounts (USD) */
+    finalCost: number;
+    /** Cost breakdown by provider */
+    byProvider: Record<string, number>;
+    /** Cost breakdown by model */
+    byModel: Record<string, number>;
+    /** Number of executions */
+    executionCount: number;
+    /** Average cost per execution (USD) */
+    avgCostPerExecution: number;
+}
+/**
+ * Get token costs for a model, falling back to default if unknown.
+ */
+export declare function getModelCosts(model: string): {
+    input: number;
+    output: number;
+};
+/**
+ * Estimate cost for a single execution.
+ *
+ * @param inputTokens - Number of input tokens
+ * @param outputTokens - Number of output tokens
+ * @param model - Model identifier
+ * @param cacheHitTokens - Optional tokens read from cache
+ * @returns Cost estimate with breakdown
+ */
+export declare function estimateCost(inputTokens: number, outputTokens: number, model: string, cacheHitTokens?: number): CostEstimate;
+/**
+ * Aggregate costs from multiple telemetry events.
+ *
+ * @param events - Array of telemetry events with token data
+ * @returns Aggregated cost summary
+ */
+export declare function aggregateCosts(events: TelemetryEvent[]): CostSummary;
+/**
+ * Format a cost value for display.
+ *
+ * @param cost - Cost in USD
+ * @returns Formatted string like "$0.0123" or "<$0.01"
+ */
+export declare function formatCost(cost: number): string;
+/**
+ * Estimate cost for a planned execution based on token estimates.
+ * Useful for budget warnings before execution.
+ *
+ * @param estimatedInputTokens - Estimated input tokens
+ * @param model - Model to use
+ * @param estimatedOutputRatio - Expected output/input ratio (default 0.3)
+ * @returns Cost estimate
+ */
+export declare function estimatePlannedCost(estimatedInputTokens: number, model: string, estimatedOutputRatio?: number): CostEstimate;

package/dist/intelligence/cost-tracker.js

@@ -0,0 +1,183 @@
+/**
+ * Token cost tracking and estimation for Orchex Learn.
+ * Provides cost estimation and aggregation for multi-provider token usage.
+ */
+/**
+ * Token costs per 1000 tokens (in USD).
+ * Prices as of February 2026 - should be updated periodically.
+ *
+ * Reference (per 1M tokens):
+ * - DeepSeek V3.2:   $0.28 / $0.42   (~95% cheaper than Claude)
+ * - Gemini 2.5 Pro:  $1.25 / $10.00  (~60% cheaper than Claude)
+ * - Claude Sonnet:   $3.00 / $15.00  (baseline)
+ * - OpenAI GPT-4o:   $5.00 / $15.00  (~40% more than Claude)
+ * - Claude Opus:     $15.00 / $75.00 (5x Claude Sonnet)
+ */
+export const TOKEN_COSTS = {
+    // Anthropic models (Feb 2026)
+    'claude-opus-4-5-20251101': { input: 0.015, output: 0.075 },
+    'claude-sonnet-4-5-20250929': { input: 0.003, output: 0.015 },
+    'claude-sonnet-4-20250514': { input: 0.003, output: 0.015 },
+    'claude-3-5-sonnet-20241022': { input: 0.003, output: 0.015 },
+    'claude-3-opus-20240229': { input: 0.015, output: 0.075 },
+    'claude-3-haiku-20240307': { input: 0.00025, output: 0.00125 },
+    // OpenAI models (Feb 2026)
+    'gpt-4.5-turbo': { input: 0.005, output: 0.015 },
+    'gpt-4-turbo': { input: 0.01, output: 0.03 },
+    'gpt-4-turbo-preview': { input: 0.01, output: 0.03 },
+    'gpt-4o': { input: 0.005, output: 0.015 },
+    'gpt-4o-mini': { input: 0.00015, output: 0.0006 },
+    'o1-preview': { input: 0.015, output: 0.06 },
+    'o1-mini': { input: 0.003, output: 0.012 },
+    'o3-mini': { input: 0.0011, output: 0.0044 },
+    'gpt-3.5-turbo': { input: 0.0005, output: 0.0015 },
+    // Google models (Feb 2026)
+    'gemini-2.5-pro': { input: 0.00125, output: 0.01 },
+    'gemini-2.0-flash': { input: 0.0001, output: 0.0004 },
+    'gemini-1.5-pro': { input: 0.00125, output: 0.005 },
+    'gemini-1.5-flash': { input: 0.000075, output: 0.0003 },
+    'gemini-pro': { input: 0.000125, output: 0.000375 },
+    // DeepSeek models (Feb 2026) — ~95% cheaper than Claude!
+    'deepseek-chat': { input: 0.00028, output: 0.00042 },
+    'deepseek-coder': { input: 0.00028, output: 0.00042 },
+    'deepseek-reasoner': { input: 0.00055, output: 0.00219 },
+    // Ollama/Local (free but track for comparison)
+    'llama3.3:70b': { input: 0, output: 0 },
+    'llama3.2:latest': { input: 0, output: 0 },
+    'mistral:latest': { input: 0, output: 0 },
+    // Default fallback (conservative estimate)
+    default: { input: 0.003, output: 0.015 },
+};
+/**
+ * Cache discount rate for Anthropic prompt caching.
+ * Cached tokens cost 90% less than regular input tokens.
+ */
+export const CACHE_DISCOUNT_RATE = 0.9;
+/**
+ * Get token costs for a model, falling back to default if unknown.
+ */
+export function getModelCosts(model) {
+    // Try exact match first
+    if (TOKEN_COSTS[model]) {
+        return TOKEN_COSTS[model];
+    }
+    // Try to match by prefix (handles versioned model names)
+    const modelLower = model.toLowerCase();
+    for (const [key, costs] of Object.entries(TOKEN_COSTS)) {
+        if (key !== 'default' && modelLower.includes(key.split('-').slice(0, 2).join('-'))) {
+            return costs;
+        }
+    }
+    return TOKEN_COSTS.default;
+}
+/**
+ * Estimate cost for a single execution.
+ *
+ * @param inputTokens - Number of input tokens
+ * @param outputTokens - Number of output tokens
+ * @param model - Model identifier
+ * @param cacheHitTokens - Optional tokens read from cache
+ * @returns Cost estimate with breakdown
+ */
+export function estimateCost(inputTokens, outputTokens, model, cacheHitTokens) {
+    const costs = getModelCosts(model);
+    // Calculate base costs (per 1000 tokens)
+    const inputCost = (inputTokens / 1000) * costs.input;
+    const outputCost = (outputTokens / 1000) * costs.output;
+    const totalCost = inputCost + outputCost;
+    // Calculate cache discount
+    let cacheDiscount;
+    if (cacheHitTokens && cacheHitTokens > 0) {
+        // Cache hits save CACHE_DISCOUNT_RATE of the input cost for those tokens
+        cacheDiscount = (cacheHitTokens / 1000) * costs.input * CACHE_DISCOUNT_RATE;
+    }
+    const finalCost = totalCost - (cacheDiscount ?? 0);
+    return {
+        inputTokens,
+        outputTokens,
+        inputCost,
+        outputCost,
+        totalCost,
+        cacheHitTokens,
+        cacheDiscount,
+        finalCost,
+        model,
+    };
+}
+/**
+ * Aggregate costs from multiple telemetry events.
+ *
+ * @param events - Array of telemetry events with token data
+ * @returns Aggregated cost summary
+ */
+export function aggregateCosts(events) {
+    const byProvider = {};
+    const byModel = {};
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalCacheHitTokens = 0;
+    let totalCost = 0;
+    let totalCacheSavings = 0;
+    let executionCount = 0;
+    for (const event of events) {
+        // Skip events without token data
+        if (!event.tokensInput && !event.tokensOutput) {
+            continue;
+        }
+        const inputTokens = event.tokensInput ?? 0;
+        const outputTokens = event.tokensOutput ?? 0;
+        const cacheHitTokens = event.cacheReadTokens ?? 0;
+        const model = event.model ?? 'default';
+        const provider = event.provider ?? 'unknown';
+        const estimate = estimateCost(inputTokens, outputTokens, model, cacheHitTokens);
+        totalInputTokens += inputTokens;
+        totalOutputTokens += outputTokens;
+        totalCacheHitTokens += cacheHitTokens;
+        totalCost += estimate.totalCost;
+        totalCacheSavings += estimate.cacheDiscount ?? 0;
+        executionCount++;
+        // Aggregate by provider
+        byProvider[provider] = (byProvider[provider] ?? 0) + estimate.finalCost;
+        // Aggregate by model
+        byModel[model] = (byModel[model] ?? 0) + estimate.finalCost;
+    }
+    const finalCost = totalCost - totalCacheSavings;
+    return {
+        totalCost,
+        totalInputTokens,
+        totalOutputTokens,
+        totalCacheHitTokens,
+        totalCacheSavings,
+        finalCost,
+        byProvider,
+        byModel,
+        executionCount,
+        avgCostPerExecution: executionCount > 0 ? finalCost / executionCount : 0,
+    };
+}
+/**
+ * Format a cost value for display.
+ *
+ * @param cost - Cost in USD
+ * @returns Formatted string like "$0.0123" or "<$0.01"
+ */
+export function formatCost(cost) {
+    if (cost === 0)
+        return '$0.00';
+    if (cost < 0.01)
+        return '<$0.01';
+    return `$${cost.toFixed(4)}`;
+}
+/**
+ * Estimate cost for a planned execution based on token estimates.
+ * Useful for budget warnings before execution.
+ *
+ * @param estimatedInputTokens - Estimated input tokens
+ * @param model - Model to use
+ * @param estimatedOutputRatio - Expected output/input ratio (default 0.3)
+ * @returns Cost estimate
+ */
+export function estimatePlannedCost(estimatedInputTokens, model, estimatedOutputRatio = 0.3) {
+    const estimatedOutputTokens = Math.ceil(estimatedInputTokens * estimatedOutputRatio);
+    return estimateCost(estimatedInputTokens, estimatedOutputTokens, model);
+}