@ashlr/hub 2.2.0

package/dist/core/mcp-registry.js

@@ -0,0 +1,180 @@
+/**
+ * core/mcp-registry.ts — MCP server discovery registry.
+ *
+ * Scans known config file locations on this machine, extracts mcpServers
+ * entries, deduplicates by name (first occurrence wins), and returns a
+ * typed McpRegistry.  Never throws — unreadable or malformed files are
+ * silently skipped.  Never prints or returns real env values; use
+ * redactEnv() before displaying any spec.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * The known config file paths discovery scans, in scan order.  Absolute paths:
+ *   ~/.claude.json, ~/.claude/settings.json, ~/.mcp.json,
+ *   ~/.ashlrcode/settings.json, and ashlr-workbench agent settings.
+ */
+export function knownConfigPaths() {
+    const home = homedir();
+    return [
+        join(home, '.claude.json'),
+        join(home, '.claude', 'settings.json'),
+        join(home, '.mcp.json'),
+        join(home, '.ashlrcode', 'settings.json'),
+        // ashlr-workbench agent settings (two candidate locations)
+        join(home, '.ashlr-workbench', 'settings.json'),
+        join(home, '.aw', 'settings.json'),
+    ];
+}
+/**
+ * Discover MCP servers already configured on this machine.
+ *
+ * Reads the known config paths (see knownConfigPaths), parses each
+ * `mcpServers` object ({ <name>: { command, args, env? } }), and returns
+ * deduped specs (dedupe by `name`; first occurrence wins, stable order).
+ * Recognises the ashlr-plugin server (name "ashlr") and phantom
+ * (name "phantom-secrets") when present.
+ *
+ * Never throws: unreadable/malformed configs are skipped silently.
+ * When producing ANY printed/displayed form, redact every env value to '<set>'
+ * via redactEnv().
+ */
+export function discoverMcpServers(paths) {
+    const seen = new Set();
+    const servers = [];
+    // Paths may be injected (tests / callers that want a hermetic scan); default
+    // to the machine's known config locations.
+    const configPaths = paths ?? knownConfigPaths();
+    for (const configPath of configPaths) {
+        if (!existsSync(configPath))
+            continue;
+        let parsed;
+        try {
+            const raw = readFileSync(configPath, 'utf8');
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // Unreadable or malformed — skip silently per contract.
+            continue;
+        }
+        // Extract specs from all mcpServers objects in this file.
+        const specsFromFile = extractSpecsFromConfig(parsed, configPath);
+        for (const spec of specsFromFile) {
+            if (!seen.has(spec.name)) {
+                seen.add(spec.name);
+                servers.push(spec);
+            }
+        }
+    }
+    return { servers };
+}
+/**
+ * Return a copy of the spec with all env values replaced by the literal
+ * string '<set>'.  Use this before printing or serialising for display.
+ * Non-env fields are returned unchanged.
+ */
+export function redactEnv(spec) {
+    if (!spec.env || Object.keys(spec.env).length === 0) {
+        return spec;
+    }
+    const redacted = {};
+    for (const key of Object.keys(spec.env)) {
+        redacted[key] = '<set>';
+    }
+    return { ...spec, env: redacted };
+}
+/**
+ * Extract McpServerSpec[] from a parsed config object.
+ *
+ * Handles two shapes Claude Code uses:
+ *   1. Top-level `mcpServers` object.
+ *   2. `projects[*].mcpServers` per-project objects.
+ *
+ * Also handles a flat top-level object that IS itself a server map
+ * (some minimal configs omit the `mcpServers` wrapper).
+ */
+function extractSpecsFromConfig(parsed, source) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return [];
+    }
+    const obj = parsed;
+    const specs = [];
+    // Shape 1: top-level mcpServers
+    if (obj['mcpServers'] !== undefined) {
+        const fromTop = specsFromMcpServersMap(obj['mcpServers'], source);
+        specs.push(...fromTop);
+    }
+    // Shape 2: projects[*].mcpServers
+    const projects = obj['projects'];
+    if (projects !== null && typeof projects === 'object' && !Array.isArray(projects)) {
+        const projectsMap = projects;
+        for (const projectKey of Object.keys(projectsMap)) {
+            const project = projectsMap[projectKey];
+            if (project !== null && typeof project === 'object' && !Array.isArray(project)) {
+                const proj = project;
+                if (proj['mcpServers'] !== undefined) {
+                    const fromProject = specsFromMcpServersMap(proj['mcpServers'], source);
+                    specs.push(...fromProject);
+                }
+            }
+        }
+    }
+    return specs;
+}
+/**
+ * Convert a raw `mcpServers` value (expected: Record<string, RawServerEntry>)
+ * into McpServerSpec[].  Skips any entry that lacks a usable `command` string.
+ */
+function specsFromMcpServersMap(raw, source) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return [];
+    }
+    const map = raw;
+    const specs = [];
+    for (const name of Object.keys(map)) {
+        const entry = map[name];
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            continue;
+        }
+        const e = entry;
+        // command is required and must be a string.
+        if (typeof e.command !== 'string' || e.command.trim() === '') {
+            continue;
+        }
+        // args: must be string[], default [].
+        let args = [];
+        if (Array.isArray(e.args)) {
+            args = e.args.filter((a) => typeof a === 'string');
+        }
+        // env: must be Record<string, string>, default undefined.
+        let env;
+        if (e.env !== null && typeof e.env === 'object' && !Array.isArray(e.env)) {
+            const rawEnv = e.env;
+            const safeEnv = {};
+            for (const k of Object.keys(rawEnv)) {
+                if (typeof rawEnv[k] === 'string') {
+                    safeEnv[k] = rawEnv[k];
+                }
+            }
+            if (Object.keys(safeEnv).length > 0) {
+                env = safeEnv;
+            }
+        }
+        const spec = {
+            name,
+            command: e.command.trim(),
+            args,
+            source,
+        };
+        if (env !== undefined) {
+            spec.env = env;
+        }
+        specs.push(spec);
+    }
+    return specs;
+}
+//# sourceMappingURL=mcp-registry.js.map

package/dist/core/mcp-registry.js.map

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

package/dist/core/observability/budget-alert.d.ts

@@ -0,0 +1,18 @@
+/**
+ * budget-alert.ts — evaluate a budget cap against spent totals.
+ *
+ * Pure function, no I/O, never throws.
+ * Privacy: reads only numeric caps from cfg.telemetry — no message content.
+ */
+import type { AshlrConfig, BudgetAlert } from "../types.js";
+/**
+ * Evaluate the budget cap for a window against spent totals.
+ *
+ * Caps are read from cfg.telemetry.budgetUsd / budgetTokens (either may be unset).
+ * level: 'over' when any cap is exceeded; 'warn' when >= 80% of any cap; else 'ok'.
+ * message is a concise human-readable status. Never throws.
+ */
+export declare function evalBudget(totals: {
+    spentUsd: number;
+    spentTokens: number;
+}, cfg: AshlrConfig, window: string): BudgetAlert;

package/dist/core/observability/budget-alert.js

@@ -0,0 +1,90 @@
+/**
+ * budget-alert.ts — evaluate a budget cap against spent totals.
+ *
+ * Pure function, no I/O, never throws.
+ * Privacy: reads only numeric caps from cfg.telemetry — no message content.
+ */
+/**
+ * Evaluate the budget cap for a window against spent totals.
+ *
+ * Caps are read from cfg.telemetry.budgetUsd / budgetTokens (either may be unset).
+ * level: 'over' when any cap is exceeded; 'warn' when >= 80% of any cap; else 'ok'.
+ * message is a concise human-readable status. Never throws.
+ */
+export function evalBudget(totals, cfg, window) {
+    try {
+        const capUsd = cfg.telemetry?.budgetUsd ?? null;
+        const capTokens = cfg.telemetry?.budgetTokens ?? null;
+        const { spentUsd, spentTokens } = totals;
+        // No caps configured — always ok
+        if (capUsd === null && capTokens === null) {
+            return {
+                level: "ok",
+                window,
+                spentUsd,
+                capUsd: null,
+                spentTokens,
+                capTokens: null,
+                message: "No budget cap configured.",
+            };
+        }
+        // Determine level: 'over' if any cap exceeded, 'warn' if >= 80%, else 'ok'
+        const usdOver = capUsd !== null && spentUsd >= capUsd;
+        const tokensOver = capTokens !== null && spentTokens >= capTokens;
+        const usdWarn = capUsd !== null && !usdOver && spentUsd >= capUsd * 0.8;
+        const tokensWarn = capTokens !== null && !tokensOver && spentTokens >= capTokens * 0.8;
+        let level;
+        if (usdOver || tokensOver) {
+            level = "over";
+        }
+        else if (usdWarn || tokensWarn) {
+            level = "warn";
+        }
+        else {
+            level = "ok";
+        }
+        // Build message focusing on whichever cap is most relevant (tightest %)
+        const parts = [];
+        if (capUsd !== null) {
+            const pct = capUsd > 0 ? Math.round((spentUsd / capUsd) * 100) : 0;
+            parts.push(`$${spentUsd.toFixed(2)} of $${capUsd.toFixed(2)} (${pct}%) this ${window}`);
+        }
+        if (capTokens !== null) {
+            const pct = capTokens > 0 ? Math.round((spentTokens / capTokens) * 100) : 0;
+            const spentK = formatTokens(spentTokens);
+            const capK = formatTokens(capTokens);
+            parts.push(`${spentK} of ${capK} tokens (${pct}%) this ${window}`);
+        }
+        const prefix = level === "over" ? "Over budget: " : level === "warn" ? "Warning: " : "";
+        return {
+            level,
+            window,
+            spentUsd,
+            capUsd,
+            spentTokens,
+            capTokens,
+            message: prefix + parts.join("; "),
+        };
+    }
+    catch {
+        // Never throws — return safe fallback
+        return {
+            level: "ok",
+            window,
+            spentUsd: totals.spentUsd,
+            capUsd: null,
+            spentTokens: totals.spentTokens,
+            capTokens: null,
+            message: "Budget evaluation unavailable.",
+        };
+    }
+}
+/** Format a token count as a compact string (e.g. 1500000 -> '1.5M', 42000 -> '42K'). */
+function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${Math.round(n / 1_000)}K`;
+    return String(n);
+}
+//# sourceMappingURL=budget-alert.js.map

package/dist/core/observability/budget-alert.js.map

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

package/dist/core/observability/estimate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * M32: pre-flight cost estimation — predict tokens / cost / duration for a
+ * `run` or `swarm` BEFORE committing, from persisted history.
+ *
+ * Method: percentile statistics (p25 / median / p75) over completed history
+ * (~/.ashlr/runs/, ~/.ashlr/swarms/), lightly weighted toward goals that share
+ * keywords with the new goal. The upper bound is clamped to the requested
+ * budget. Cloud cost uses the same reference pricing as forecast.ts; local
+ * runs cost $0 (the would-be-cloud figure is reported for context).
+ *
+ * Contract: PURE READ-ONLY (never writes, never scans repos, never calls a
+ * model); NEVER throws — empty/corrupt history yields a zeroed estimate with
+ * confidence 'low'.
+ */
+import type { AshlrConfig, RunEstimate } from '../types.js';
+/** Estimate a `run` from run history. Never throws. */
+export declare function estimateRun(goal: string, opts: {
+    maxTokens?: number;
+    allowCloud?: boolean;
+}, _cfg: AshlrConfig): Promise<RunEstimate>;
+/** Estimate a `swarm` from swarm history. Never throws. */
+export declare function estimateSwarm(goal: string, opts: {
+    maxTokens?: number;
+    allowCloud?: boolean;
+}, _cfg: AshlrConfig): Promise<RunEstimate>;
+/** Render an estimate as a compact human block (shared by run/swarm CLIs). */
+export declare function renderEstimate(e: RunEstimate): string;

package/dist/core/observability/estimate.js

@@ -0,0 +1,188 @@
+/**
+ * M32: pre-flight cost estimation — predict tokens / cost / duration for a
+ * `run` or `swarm` BEFORE committing, from persisted history.
+ *
+ * Method: percentile statistics (p25 / median / p75) over completed history
+ * (~/.ashlr/runs/, ~/.ashlr/swarms/), lightly weighted toward goals that share
+ * keywords with the new goal. The upper bound is clamped to the requested
+ * budget. Cloud cost uses the same reference pricing as forecast.ts; local
+ * runs cost $0 (the would-be-cloud figure is reported for context).
+ *
+ * Contract: PURE READ-ONLY (never writes, never scans repos, never calls a
+ * model); NEVER throws — empty/corrupt history yields a zeroed estimate with
+ * confidence 'low'.
+ */
+/** Reference cloud pricing ($/M tokens) — mirrors forecast.ts. */
+const CLOUD_REF_PRICE_IN = 3.0;
+const CLOUD_REF_PRICE_OUT = 15.0;
+/** Minimum samples for medium/high confidence. */
+const MEDIUM_SAMPLES = 3;
+const HIGH_SAMPLES = 10;
+function keywordSet(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w.length > 3));
+}
+/** Jaccard-ish goal similarity in [0,1]. */
+function similarity(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let shared = 0;
+    for (const w of a)
+        if (b.has(w))
+            shared++;
+    return shared / Math.max(a.size, b.size);
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.floor((p / 100) * sorted.length)));
+    return sorted[idx] ?? 0;
+}
+function cloudCost(tokensIn, tokensOut) {
+    return ((Math.max(0, tokensIn) / 1_000_000) * CLOUD_REF_PRICE_IN +
+        (Math.max(0, tokensOut) / 1_000_000) * CLOUD_REF_PRICE_OUT);
+}
+function buildEstimate(kind, goal, samples, opts) {
+    const zeroed = {
+        kind,
+        goal,
+        sampleSize: 0,
+        confidence: 'low',
+        tokens: { p25: 0, median: 0, p75: 0 },
+        steps: { p25: 0, median: 0, p75: 0 },
+        estCostUsd: { p25: 0, median: 0, p75: 0 },
+        wouldBeCloudUsd: 0,
+        durationMs: { p25: 0, median: 0, p75: 0 },
+        budgetClamped: false,
+        generatedAt: new Date().toISOString(),
+    };
+    if (samples.length === 0)
+        return zeroed;
+    // Similarity weighting: when ≥3 samples share keywords with the goal, use
+    // ONLY those (a focused prior beats a diffuse one); otherwise use everything.
+    const goalWords = keywordSet(goal);
+    const similar = samples.filter((s) => similarity(goalWords, keywordSet(s.goal)) > 0.15);
+    const used = similar.length >= MEDIUM_SAMPLES ? similar : samples;
+    const tokens = used.map((s) => s.tokens).sort((a, b) => a - b);
+    const steps = used.map((s) => s.steps).sort((a, b) => a - b);
+    const costs = used.map((s) => s.estCostUsd).sort((a, b) => a - b);
+    const durations = used.map((s) => s.durationMs).filter((d) => d > 0).sort((a, b) => a - b);
+    let p25t = percentile(tokens, 25);
+    let p50t = percentile(tokens, 50);
+    let p75t = percentile(tokens, 75);
+    // Clamp to the requested budget (a run can never exceed its hard cap).
+    let budgetClamped = false;
+    const cap = opts.maxTokens;
+    if (cap !== undefined && cap > 0) {
+        if (p75t > cap) {
+            p75t = cap;
+            budgetClamped = true;
+        }
+        if (p50t > cap) {
+            p50t = cap;
+            budgetClamped = true;
+        }
+        if (p25t > cap) {
+            p25t = cap;
+            budgetClamped = true;
+        }
+    }
+    // Median in/out split from history (for the would-be-cloud figure).
+    const ratioSum = used.reduce((acc, s) => {
+        acc.in += s.tokensIn;
+        acc.out += s.tokensOut;
+        return acc;
+    }, { in: 0, out: 0 });
+    const total = ratioSum.in + ratioSum.out;
+    const inShare = total > 0 ? ratioSum.in / total : 0.7;
+    const confidence = used.length >= HIGH_SAMPLES ? 'high' : used.length >= MEDIUM_SAMPLES ? 'medium' : 'low';
+    return {
+        kind,
+        goal,
+        sampleSize: used.length,
+        confidence,
+        tokens: { p25: p25t, median: p50t, p75: p75t },
+        steps: { p25: percentile(steps, 25), median: percentile(steps, 50), p75: percentile(steps, 75) },
+        estCostUsd: {
+            p25: percentile(costs, 25),
+            median: percentile(costs, 50),
+            p75: percentile(costs, 75),
+        },
+        wouldBeCloudUsd: cloudCost(p50t * inShare, p50t * (1 - inShare)),
+        durationMs: {
+            p25: percentile(durations, 25),
+            median: percentile(durations, 50),
+            p75: percentile(durations, 75),
+        },
+        budgetClamped,
+        generatedAt: new Date().toISOString(),
+    };
+}
+/** Estimate a `run` from run history. Never throws. */
+export async function estimateRun(goal, opts, _cfg) {
+    let samples = [];
+    try {
+        const { listRuns } = await import('../run/orchestrator.js');
+        samples = listRuns()
+            .filter((r) => r.status === 'done' || r.status === 'failed')
+            .map((r) => ({
+            goal: r.goal,
+            tokens: r.usage.tokensIn + r.usage.tokensOut,
+            tokensIn: r.usage.tokensIn,
+            tokensOut: r.usage.tokensOut,
+            steps: r.usage.steps,
+            estCostUsd: r.usage.estCostUsd,
+            durationMs: Date.parse(r.updatedAt) - Date.parse(r.createdAt) || 0,
+        }));
+    }
+    catch {
+        samples = [];
+    }
+    return buildEstimate('run', goal, samples, opts);
+}
+/** Estimate a `swarm` from swarm history. Never throws. */
+export async function estimateSwarm(goal, opts, _cfg) {
+    let samples = [];
+    try {
+        const { listSwarms } = await import('../swarm/store.js');
+        samples = listSwarms()
+            .filter((s) => s.status === 'done' || s.status === 'failed' || s.status === 'aborted')
+            .map((s) => ({
+            goal: s.goal,
+            tokens: s.usage.tokensIn + s.usage.tokensOut,
+            tokensIn: s.usage.tokensIn,
+            tokensOut: s.usage.tokensOut,
+            steps: s.usage.steps,
+            estCostUsd: s.usage.estCostUsd,
+            durationMs: Date.parse(s.updatedAt) - Date.parse(s.createdAt) || 0,
+        }));
+    }
+    catch {
+        samples = [];
+    }
+    return buildEstimate('swarm', goal, samples, opts);
+}
+/** Render an estimate as a compact human block (shared by run/swarm CLIs). */
+export function renderEstimate(e) {
+    const fmtTok = (n) => n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(Math.round(n));
+    const fmtDur = (ms) => {
+        if (ms <= 0)
+            return '—';
+        const s = Math.round(ms / 1000);
+        return s >= 60 ? `${Math.floor(s / 60)}m${s % 60}s` : `${s}s`;
+    };
+    const lines = [
+        `estimate (${e.kind}) — confidence: ${e.confidence} (${e.sampleSize} similar ${e.kind}${e.sampleSize === 1 ? '' : 's'})`,
+        `  tokens    p25 ${fmtTok(e.tokens.p25)} · median ${fmtTok(e.tokens.median)} · p75 ${fmtTok(e.tokens.p75)}${e.budgetClamped ? ' (clamped to budget)' : ''}`,
+        `  steps     p25 ${Math.round(e.steps.p25)} · median ${Math.round(e.steps.median)} · p75 ${Math.round(e.steps.p75)}`,
+        `  cost      median $${e.estCostUsd.median.toFixed(4)} (local $0; would-be-cloud ≈ $${e.wouldBeCloudUsd.toFixed(4)})`,
+        `  duration  p25 ${fmtDur(e.durationMs.p25)} · median ${fmtDur(e.durationMs.median)} · p75 ${fmtDur(e.durationMs.p75)}`,
+    ];
+    if (e.sampleSize === 0) {
+        lines.push('  (no history yet — run a few goals first for meaningful estimates)');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=estimate.js.map

package/dist/core/observability/estimate.js.map

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

package/dist/core/observability/forecast.d.ts

@@ -0,0 +1,19 @@
+/**
+ * forecast.ts — cost attribution + forward forecast for a recent usage window.
+ *
+ * M15: buildForecast reuses buildRollup for actual spend and wouldBeCloudCost
+ * (from router.ts) to compute local savings. All numbers are ESTIMATES, clearly
+ * labeled. Never throws — falls back to zeroed CostForecast on any error.
+ */
+import type { AshlrConfig, CostForecast } from '../types.js';
+/**
+ * Build a CostForecast for the given window.
+ *
+ * - `spentUsd`: actual cost from the rollup (local providers contribute $0).
+ * - `localSavingsUsd`: estimated cloud cost for tokens served by LOCAL models —
+ *   what you WOULD have paid if those same tokens ran on cloud.
+ * - `projectedMonthlyUsd`: the window's daily average spend × 30 days.
+ *
+ * All figures are ESTIMATES. Never throws — returns a zeroed forecast on error.
+ */
+export declare function buildForecast(window: '7d' | '30d', cfg: AshlrConfig): CostForecast;

package/dist/core/observability/forecast.js

@@ -0,0 +1,101 @@
+/**
+ * forecast.ts — cost attribution + forward forecast for a recent usage window.
+ *
+ * M15: buildForecast reuses buildRollup for actual spend and wouldBeCloudCost
+ * (from router.ts) to compute local savings. All numbers are ESTIMATES, clearly
+ * labeled. Never throws — falls back to zeroed CostForecast on any error.
+ */
+import { buildRollup, windowToMs, isLocalProviderModel } from './rollup.js';
+// ---------------------------------------------------------------------------
+// Local provider detection
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when the model id belongs to a local (zero-cost) provider.
+ *
+ * Reuses rollup.ts `isLocalProviderModel` (built on the SAME `modelToProviderKey`
+ * derivation rollup uses to compute cost) so the local/cloud split is identical
+ * across rollup, savings, and forecast — instead of a fragile raw substring test
+ * that only matched the run-source label format by coincidence.
+ */
+const isLocalModel = isLocalProviderModel;
+// ---------------------------------------------------------------------------
+// Cloud cost reference: representative cloud pricing used for savings estimate.
+// Uses claude/anthropic as the reference cloud tier (conservative mid estimate).
+// These are ESTIMATES only, never billed — reuse the same constants from budget.ts
+// rather than re-importing to avoid circular deps (budget.ts is a pure util).
+// ---------------------------------------------------------------------------
+/** $/M input tokens — conservative mid-tier cloud reference (anthropic claude). */
+const CLOUD_REF_PRICE_IN = 3.0;
+/** $/M output tokens — conservative mid-tier cloud reference (anthropic claude). */
+const CLOUD_REF_PRICE_OUT = 15.0;
+/**
+ * Estimate what `tokensIn`/`tokensOut` would have cost on a representative
+ * cloud model (conservative anthropic mid-tier).
+ *
+ * This is the same calculation as `wouldBeCloudCost` in router.ts — duplicated
+ * here to avoid a circular dependency (forecast -> router -> budget -> forecast).
+ * The function intentionally stays private; external callers use router.ts.
+ *
+ * Returns 0 when token counts are non-positive. Always >= 0. Clearly an estimate.
+ */
+function cloudRefCost(tokensIn, tokensOut) {
+    if (tokensIn <= 0 && tokensOut <= 0)
+        return 0;
+    const safeIn = Math.max(0, tokensIn);
+    const safeOut = Math.max(0, tokensOut);
+    return (safeIn / 1_000_000) * CLOUD_REF_PRICE_IN +
+        (safeOut / 1_000_000) * CLOUD_REF_PRICE_OUT;
+}
+// ---------------------------------------------------------------------------
+// buildForecast
+// ---------------------------------------------------------------------------
+/**
+ * Build a CostForecast for the given window.
+ *
+ * - `spentUsd`: actual cost from the rollup (local providers contribute $0).
+ * - `localSavingsUsd`: estimated cloud cost for tokens served by LOCAL models —
+ *   what you WOULD have paid if those same tokens ran on cloud.
+ * - `projectedMonthlyUsd`: the window's daily average spend × 30 days.
+ *
+ * All figures are ESTIMATES. Never throws — returns a zeroed forecast on error.
+ */
+export function buildForecast(window, cfg) {
+    try {
+        const rollup = buildRollup(window, cfg);
+        // Actual spend is already computed in the rollup totals.
+        const spentUsd = Math.max(0, rollup.totals.estCostUsd);
+        // ── Local savings ───────────────────────────────────────────────────────
+        // Sum up the cloud-equivalent cost for every local model's token usage.
+        // rollup.byModel lists per-model aggregates; we identify local models and
+        // compute what cloud would have charged for the same token volume.
+        let localSavingsUsd = 0;
+        for (const mu of rollup.byModel) {
+            if (isLocalModel(mu.model)) {
+                localSavingsUsd += cloudRefCost(mu.tokensIn, mu.tokensOut);
+            }
+        }
+        localSavingsUsd = Math.max(0, localSavingsUsd);
+        // ── Monthly projection ──────────────────────────────────────────────────
+        // Scale the window's spend to a 30-day equivalent.
+        // windowToMs is already exported from rollup.ts.
+        const windowDays = windowToMs(window) / 86_400_000; // exact days in window
+        const dailyRate = windowDays > 0 ? spentUsd / windowDays : 0;
+        const projectedMonthlyUsd = Math.max(0, dailyRate * 30);
+        return {
+            window,
+            spentUsd,
+            localSavingsUsd,
+            projectedMonthlyUsd,
+        };
+    }
+    catch {
+        // Never throw — return a safe zeroed forecast on any error.
+        return {
+            window,
+            spentUsd: 0,
+            localSavingsUsd: 0,
+            projectedMonthlyUsd: 0,
+        };
+    }
+}
+//# sourceMappingURL=forecast.js.map