budget-agent 0.4.3

package/dist/index.js

@@ -0,0 +1,557 @@
+import { CheckpointManager } from './checkpoint.js';
+import { UsageTracker } from './tracker.js';
+import { getModelPricing, calculateCost, invalidatePricingCache } from './pricing.js';
+import { checkLimits, BudgetError, RateLimitError, UpstreamError } from './budget.js';
+import { compressMessages as compressMessageHistory, estimateMessagesTokens, } from './compressor.js';
+import { estimateStepCost } from './estimator.js';
+import { CircuitBreaker } from './circuit-breaker.js';
+import { resolveModel, shouldLogDowngrade } from './router.js';
+import { AgentEventEmitter, WarningChecker } from './events.js';
+const DEFAULT_BASE_URL = 'https://openrouter.ai/api/v1';
+const DEFAULT_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+// ─── AgentBudget ─────────────────────────────────────────────────────────────
+export class AgentBudget {
+    apiKey;
+    limits;
+    onExceeded;
+    cacheTTL;
+    siteUrl;
+    appTitle;
+    autoCompress;
+    adaptiveRouting;
+    currentModelIndex = 0;
+    tracker;
+    circuitBreaker;
+    checkpointManager;
+    emitter;
+    warningChecker = new WarningChecker();
+    warningThreshold;
+    telemetry;
+    tracer = null;
+    executor;
+    baseUrl;
+    defaultHeaders;
+    constructor(options) {
+        const l = options.limits;
+        if (l.maxCostUSD !== undefined && l.maxCostUSD < 0)
+            throw new Error('[agent-budget] maxCostUSD must be >= 0');
+        if (l.maxSteps !== undefined && l.maxSteps < 0)
+            throw new Error('[agent-budget] maxSteps must be >= 0');
+        if (l.maxTotalTokens !== undefined && l.maxTotalTokens < 0)
+            throw new Error('[agent-budget] maxTotalTokens must be >= 0');
+        if (l.maxInputTokens !== undefined && l.maxInputTokens < 0)
+            throw new Error('[agent-budget] maxInputTokens must be >= 0');
+        if (l.maxOutputTokens !== undefined && l.maxOutputTokens < 0)
+            throw new Error('[agent-budget] maxOutputTokens must be >= 0');
+        if (l.maxWallTimeMs !== undefined && l.maxWallTimeMs < 0)
+            throw new Error('[agent-budget] maxWallTimeMs must be >= 0');
+        this.apiKey = options.apiKey;
+        this.limits = l;
+        this.onExceeded = options.onExceeded ?? 'abort';
+        this.cacheTTL = options.pricingCacheTTLMs ?? DEFAULT_CACHE_TTL;
+        this.siteUrl = options.siteUrl;
+        this.appTitle = options.appTitle;
+        this.autoCompress = options.autoCompress;
+        this.adaptiveRouting = options.adaptiveRouting;
+        this.tracker = new UsageTracker();
+        this.circuitBreaker = options.circuitBreaker
+            ? new CircuitBreaker(options.circuitBreaker)
+            : null;
+        this.checkpointManager = options.checkpoint?.enabled
+            ? new CheckpointManager({ path: options.checkpoint.path })
+            : null;
+        this.emitter = new AgentEventEmitter(options.onEvent);
+        this.warningThreshold = options.warningThreshold ?? 0.75;
+        this.telemetry = options.telemetry;
+        this.executor = options.executor;
+        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.defaultHeaders = options.defaultHeaders ?? {};
+    }
+    /**
+     * Execute one agent step through OpenRouter.
+     * Checks budget limits before AND after the API call.
+     * Throws BudgetError if any limit is exceeded.
+     */
+    async step(request) {
+        const stepIndex = this.tracker.stepCount();
+        const stepStart = Date.now();
+        this._initTracer();
+        const stepSpan = this._startSpan('agent-budget.step');
+        // ── Adaptive model routing: resolve model from fallback chain ────────────
+        // Runs BEFORE pre-flight checks so that fallbackChainExhausted fires
+        // instead of a generic cost error when on the last tier.
+        if (this.adaptiveRouting) {
+            const { fallbackChain, thresholds } = this.adaptiveRouting;
+            const usage = this.tracker.snapshot();
+            const decision = resolveModel(fallbackChain, thresholds, usage, this.limits.maxCostUSD);
+            const prevIndex = this.currentModelIndex;
+            this.currentModelIndex = decision.index;
+            // Override the request model with the router's decision
+            request.model = decision.model;
+            // Check if chain is exhausted and budget is critically over
+            if (decision.index >= fallbackChain.length - 1) {
+                const pct = this.limits.maxCostUSD ? usage.totalCostUSD / this.limits.maxCostUSD : 1;
+                if (pct >= 1) {
+                    const exceeded = {
+                        reason: 'fallbackChainExhausted',
+                        limit: this.limits.maxCostUSD ?? 0,
+                        actual: usage.totalCostUSD,
+                        usage,
+                    };
+                    this.emitter.emit({ type: 'budget:exceeded', exceeded });
+                    if (typeof this.onExceeded === 'function') {
+                        this.onExceeded(usage);
+                    }
+                    throw new BudgetError(exceeded);
+                }
+            }
+            // Log downgrade if moving to a cheaper tier
+            if (shouldLogDowngrade(prevIndex, decision.index)) {
+                const pct = this.limits.maxCostUSD
+                    ? usage.totalCostUSD / this.limits.maxCostUSD
+                    : 0;
+                console.log(`[agent-budget] Downgrading model: ${fallbackChain[prevIndex]} → ${decision.model} (budget ${(pct * 100).toFixed(1)}% consumed)`);
+                this.emitter.emit({
+                    type: 'model:downgraded',
+                    from: fallbackChain[prevIndex],
+                    to: decision.model,
+                    pctConsumed: pct,
+                });
+            }
+        }
+        // ── Pre-flight: check limits before burning tokens ────────────────────────
+        // Runs AFTER routing so fallbackChainExhausted takes priority over generic cost.
+        this._checkOrThrow(this.tracker.snapshot());
+        // ── Fetch live pricing for this model ─────────────────────────────────────
+        const pricingSpan = this._startSpan('agent-budget.pricing');
+        const pricing = await getModelPricing(request.model, this.apiKey, this.cacheTTL, (modelCount, cachedUntil) => {
+            this.emitter.emit({ type: 'pricing:fetched', modelCount, cachedUntil });
+        });
+        pricingSpan?.end();
+        // ── Pre-flight cost estimation ────────────────────────────────────────────
+        if (this.limits.preflightCheck !== false && this.limits.maxCostUSD !== undefined) {
+            const estimate = estimateStepCost(request, pricing, this.limits.preflightOutputTokenEstimate ?? 512);
+            const usage = this.tracker.snapshot();
+            const remainingBudget = this.limits.maxCostUSD - usage.totalCostUSD;
+            if (estimate.estimatedCostUSD > remainingBudget) {
+                const exceeded = {
+                    reason: 'preflightCostEstimate',
+                    limit: this.limits.maxCostUSD,
+                    actual: usage.totalCostUSD,
+                    usage,
+                    remainingBudget,
+                    estimatedCost: estimate.estimatedCostUSD,
+                };
+                this.emitter.emit({ type: 'budget:exceeded', exceeded });
+                if (typeof this.onExceeded === 'function') {
+                    this.onExceeded(usage);
+                }
+                throw new BudgetError(exceeded);
+            }
+        }
+        // ── Auto-compress messages if approaching token threshold ────────────────
+        if (this.autoCompress) {
+            const estimatedTokens = estimateMessagesTokens(request.messages);
+            if (estimatedTokens > this.autoCompress.thresholdTokens) {
+                const messagesBefore = request.messages.length;
+                request.messages = await compressMessageHistory(request.messages, this.apiKey, this.autoCompress.keepLastN ?? 4);
+                const messagesAfter = request.messages.length;
+                this.emitter.emit({
+                    type: 'compress:triggered',
+                    messagesBefore,
+                    messagesAfter,
+                    tokensFreed: estimatedTokens - estimateMessagesTokens(request.messages),
+                });
+            }
+        }
+        // ── Emit step:start before API call ─────────────────────────────────────
+        this.emitter.emit({
+            type: 'step:start',
+            stepIndex,
+            model: request.model,
+        });
+        // ── Execute the step (custom executor or built-in OpenRouter fetch) ──────
+        let response;
+        if (this.executor) {
+            const result = await this.executor({ ...request });
+            response = {
+                id: '',
+                model: result.model,
+                choices: result.choices.map(c => ({
+                    message: c.message,
+                    finish_reason: c.finish_reason,
+                })),
+                usage: result.usage,
+            };
+        }
+        else {
+            response = await this._defaultFetch(request, stepIndex, pricing);
+        }
+        const durationMs = Date.now() - stepStart;
+        // ── Record this step (before checks so circuit breaker can analyze it) ─────
+        const inputTokens = response.usage?.prompt_tokens ?? 0;
+        const outputTokens = response.usage?.completion_tokens ?? 0;
+        const costUSD = calculateCost(pricing, inputTokens, outputTokens);
+        const outputContent = response.choices?.[0]?.message?.content ?? '';
+        this.tracker.record({
+            stepIndex: this.tracker.stepCount(),
+            model: request.model,
+            inputTokens,
+            outputTokens,
+            costUSD,
+            durationMs,
+            outputContent,
+        });
+        // ── Emit step:end ───────────────────────────────────────────────────────
+        this.emitter.emit({
+            type: 'step:end',
+            stepIndex,
+            model: request.model,
+            inputTokens,
+            outputTokens,
+            costUSD,
+            durationMs,
+        });
+        // ── Circuit breaker: check for repetition or stagnation ──────────────────
+        if (this.circuitBreaker) {
+            const trip = this.circuitBreaker.check(this.tracker.snapshot());
+            if (trip) {
+                const usage = this.tracker.snapshot();
+                const exceeded = {
+                    reason: 'circuitBreaker',
+                    limit: 0,
+                    actual: 0,
+                    usage,
+                    triggerMode: trip.triggerMode,
+                    windowSize: trip.windowSize,
+                    similarity: trip.similarity,
+                };
+                this.emitter.emit({
+                    type: 'circuit:tripped',
+                    triggerMode: trip.triggerMode,
+                    stepIndex,
+                });
+                this.emitter.emit({ type: 'budget:exceeded', exceeded });
+                if (typeof this.onExceeded === 'function') {
+                    this.onExceeded(usage);
+                }
+                this.tracker.rollback();
+                throw new BudgetError(exceeded);
+            }
+        }
+        // ── Checkpoint: write after step succeeds ────────────────────────────────
+        if (this.checkpointManager) {
+            const responseMessage = response.choices?.[0]?.message;
+            const checkpointMessages = responseMessage
+                ? [...request.messages, responseMessage]
+                : request.messages;
+            await this.checkpointManager.save(checkpointMessages, this.tracker.snapshot(), request.model, this.tracker.stepCount());
+        }
+        // ── Post-step: check all limits including updated cost + token totals ──────
+        try {
+            this._checkOrThrow(this.tracker.snapshot());
+        }
+        catch (err) {
+            // Roll back the tracker so the consumer can retry without stale data.
+            // The actual API spend is included in the error for transparency.
+            this.tracker.rollback();
+            throw err;
+        }
+        stepSpan?.end();
+        return response;
+    }
+    /**
+     * Current accumulated usage. Safe to call at any time.
+     */
+    getUsage() {
+        return this.tracker.snapshot();
+    }
+    /**
+     * Prints a single summary table to console. Returns the same usage snapshot.
+     */
+    summary() {
+        const u = this.tracker.snapshot();
+        const models = [...new Set(u.stepHistory.map(s => s.model))];
+        const costPerStep = u.steps > 0 ? u.totalCostUSD / u.steps : 0;
+        const durSec = (u.elapsedMs / 1000).toFixed(1);
+        console.log('┌──────────────────────────────────────────────┐');
+        console.log('│  agent-budget summary                        │');
+        console.log('├──────────────────────────────────────────────┤');
+        console.log(`│  Steps:        ${String(u.steps).padStart(10)}                     │`);
+        console.log(`│  Cost:         $${u.totalCostUSD.toFixed(6).padStart(10)}                     │`);
+        console.log(`│  Cost/step:    $${costPerStep.toFixed(6).padStart(10)}                     │`);
+        console.log(`│  Input tokens: ${String(u.totalInputTokens).padStart(10)}                     │`);
+        console.log(`│  Output tokens:${String(u.totalOutputTokens).padStart(10)}                     │`);
+        console.log(`│  Duration:     ${durSec.padStart(7)}s                      │`);
+        console.log(`│  Model:        ${models.join(', ').slice(0, 30).padEnd(30)} │`);
+        console.log('└──────────────────────────────────────────────┘');
+        return u;
+    }
+    /**
+     * Subscribe to a specific event type.
+     */
+    on(type, handler) {
+        this.emitter.on(type, handler);
+        return this;
+    }
+    /**
+     * Unsubscribe from a specific event type.
+     */
+    off(type, handler) {
+        this.emitter.off(type, handler);
+        return this;
+    }
+    /**
+     * Resets all usage counters. Does NOT reset pricing cache.
+     */
+    reset() {
+        this.tracker.reset();
+        this.warningChecker.reset();
+    }
+    /**
+     * Force-refresh pricing on next step. Useful for long-running agents.
+     */
+    refreshPricing() {
+        invalidatePricingCache();
+    }
+    /**
+     * Returns the model that the adaptive router would use right now,
+     * or undefined if adaptive routing is not configured.
+     */
+    getCurrentModel() {
+        if (!this.adaptiveRouting)
+            return undefined;
+        return this.adaptiveRouting.fallbackChain[this.currentModelIndex];
+    }
+    /**
+     * Manually record a step into the tracker.
+     * Useful for replaying checkpoints or simulating usage in tests.
+     */
+    recordStep(usage) {
+        this.tracker.record({
+            stepIndex: this.tracker.stepCount(),
+            model: this.getCurrentModel() ?? 'unknown',
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            costUSD: usage.costUSD,
+            durationMs: 0,
+        });
+    }
+    /**
+     * Manually compress a message array. Useful outside of the step() flow.
+     * Preserves the system message (if any) and the last `keepLastN` messages.
+     * Everything in between is summarized via an LLM call.
+     */
+    async compressMessages(messages, keepLastN) {
+        return compressMessageHistory(messages, this.apiKey, keepLastN ?? this.autoCompress?.keepLastN ?? 4);
+    }
+    /**
+     * Delete the checkpoint file. Call after the agent loop completes successfully.
+     */
+    async clearCheckpoint() {
+        await this.checkpointManager?.clear();
+    }
+    /**
+     * Load an existing checkpoint. Returns null if none exists.
+     */
+    async loadCheckpoint() {
+        return this.checkpointManager?.load() ?? null;
+    }
+    /**
+     * Resume from a checkpoint. Constructs a new AgentBudget with tracker state
+     * pre-loaded so budget accounting continues from where it left off.
+     * Throws if no checkpoint file exists.
+     */
+    static async resume(options, checkpointPath) {
+        const path = options.checkpoint?.path ?? checkpointPath ?? './.agent-checkpoint.json';
+        const manager = new CheckpointManager({ path });
+        const data = await manager.load();
+        if (!data) {
+            throw new Error(`[agent-budget] No checkpoint found at ${path}`);
+        }
+        const agent = new AgentBudget(options);
+        agent.tracker = UsageTracker.fromSnapshot(data.usage);
+        return agent;
+    }
+    // ── Internal ────────────────────────────────────────────────────────────────
+    _initTracer() {
+        if (!this.telemetry?.enabled || this.tracer)
+            return;
+        try {
+            const otel = require('@opentelemetry/api');
+            this.tracer = otel.trace.getTracer('agent-budget');
+        }
+        catch {
+            this.tracer = null;
+        }
+    }
+    _startSpan(name) {
+        if (!this.tracer)
+            return null;
+        try {
+            const span = this.tracer.startSpan(name);
+            return {
+                end: () => { try {
+                    span.end();
+                }
+                catch { } }
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    async _readStream(res, model, stepIndex, stepStart, pricing) {
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let fullContent = '';
+        let responseId = '';
+        let responseModel = '';
+        let usage = null;
+        let streamError = null;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed.startsWith('data: '))
+                    continue;
+                const data = trimmed.slice(6);
+                if (data === '[DONE]')
+                    continue;
+                try {
+                    const parsed = JSON.parse(data);
+                    const choice = parsed.choices?.[0];
+                    // Check for streamed provider error (finish_reason: "error" + choice.error)
+                    if (choice?.error) {
+                        streamError = { code: choice.error.code, message: choice.error.message };
+                    }
+                    // Emit token for each content delta
+                    if (choice?.delta?.content) {
+                        const token = choice.delta.content;
+                        fullContent += token;
+                        this.emitter.emit({ type: 'step:token', stepIndex, token });
+                    }
+                    // Capture usage — it appears in the final chunk before [DONE].
+                    // With stream_options: { include_usage: true }, this chunk has
+                    // an empty choices array and a usage object.
+                    if (parsed.usage) {
+                        usage = parsed.usage;
+                    }
+                    if (parsed.id)
+                        responseId = parsed.id;
+                    if (parsed.model)
+                        responseModel = parsed.model;
+                }
+                catch { /* skip malformed SSE lines */ }
+            }
+        }
+        // If a streamed error was captured, throw it so the budget layer
+        // doesn't record a fake zero-cost step.
+        if (streamError) {
+            throw new UpstreamError(streamError.code, streamError.message);
+        }
+        return {
+            id: responseId,
+            model: responseModel || model,
+            choices: [{
+                    message: { role: 'assistant', content: fullContent },
+                    finish_reason: 'stop',
+                }],
+            usage: usage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+        };
+    }
+    async _defaultFetch(request, stepIndex, pricing) {
+        const headers = {
+            ...this.defaultHeaders,
+            Authorization: `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+        };
+        if (this.siteUrl)
+            headers['HTTP-Referer'] = this.siteUrl;
+        if (this.appTitle)
+            headers['X-OpenRouter-Title'] = this.appTitle;
+        // When streaming, include stream_options so usage data is returned
+        // in the final chunk. Respect any user-supplied value.
+        const body = { ...request };
+        if (body.stream === true && !('stream_options' in body)) {
+            body.stream_options = { include_usage: true };
+        }
+        const url = `${this.baseUrl.replace(/\/+$/, '')}/chat/completions`;
+        let res;
+        const MAX_RETRIES = 3;
+        for (let attempt = 0;; attempt++) {
+            res = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+            });
+            if (res.status === 429 && attempt < MAX_RETRIES) {
+                const retryAfter = parseInt(res.headers.get('retry-after') ?? '0', 10) || 0;
+                const backoff = retryAfter > 0
+                    ? retryAfter * 1000
+                    : Math.min(1000 * 2 ** attempt, 30000);
+                console.warn(`[agent-budget] Rate limited (429). Retrying in ${backoff}ms (attempt ${attempt + 1}/${MAX_RETRIES})`);
+                await new Promise(r => setTimeout(r, backoff));
+                continue;
+            }
+            break;
+        }
+        if (!res.ok) {
+            const bodyText = await res.text();
+            if (res.status === 402) {
+                throw new Error(`[agent-budget] Insufficient credits (402): ${bodyText}`);
+            }
+            if (res.status === 502) {
+                throw new Error(`[agent-budget] Provider unavailable (502): ${bodyText}`);
+            }
+            if (res.status === 429) {
+                const retryAfter = parseInt(res.headers.get('retry-after') ?? '0', 10) || 0;
+                throw new RateLimitError(429, retryAfter, `[agent-budget] Rate limit exceeded after ${MAX_RETRIES} retries: ${bodyText}`);
+            }
+            throw new Error(`[agent-budget] API error ${res.status}: ${bodyText}`);
+        }
+        const response = request.stream === true
+            ? await this._readStream(res, request.model, stepIndex, Date.now(), pricing)
+            : (await res.json());
+        // OpenRouter may return HTTP 200 with an error inside choices[0].
+        // This happens when the provider rejects the request (insufficient
+        // credits, guardrail, provider outage, etc.).
+        const choiceError = response.choices?.[0]?.error;
+        if (choiceError) {
+            throw new UpstreamError(choiceError.code, choiceError.message, choiceError.metadata);
+        }
+        return response;
+    }
+    _checkOrThrow(usage) {
+        const exceeded = checkLimits(usage, this.limits);
+        if (exceeded) {
+            this.emitter.emit({ type: 'budget:exceeded', exceeded });
+            if (typeof this.onExceeded === 'function') {
+                this.onExceeded(usage);
+            }
+            throw new BudgetError(exceeded);
+        }
+        this.warningChecker.check(usage, this.limits, this.warningThreshold, (event) => {
+            this.emitter.emit(event);
+        });
+    }
+}
+// ─── Convenience factory ─────────────────────────────────────────────────────
+export function createAgentBudget(options) {
+    return new AgentBudget(options);
+}
+// ─── Re-exports ───────────────────────────────────────────────────────────────
+export { BudgetError, RateLimitError, UpstreamError } from './budget.js';
+export { getModelPricing, calculateCost, invalidatePricingCache, setModelPricing } from './pricing.js';
+export { estimateStepCost } from './estimator.js';
+export { CircuitBreaker } from './circuit-breaker.js';
+export { resolveModel } from './router.js';
+export { CheckpointManager } from './checkpoint.js';
+export { compressMessages, estimateMessagesTokens } from './compressor.js';
+export { AgentEventEmitter } from './events.js';

package/dist/pricing.d.ts

@@ -0,0 +1,19 @@
+import type { ModelPricing } from './types.js';
+/**
+ * Returns pricing for a model. Fetches all model prices from OpenRouter once,
+ * then caches for `cacheTTLMs`. Unknown models return zero-cost (with a warning).
+ */
+export declare function getModelPricing(modelId: string, apiKey: string, cacheTTLMs: number, onFreshFetch?: (modelCount: number, cachedUntil: number) => void): Promise<ModelPricing>;
+/**
+ * Computes USD cost from pricing + token counts.
+ */
+export declare function calculateCost(pricing: ModelPricing, inputTokens: number, outputTokens: number): number;
+/**
+ * Force-invalidates the pricing cache. Call this if you need fresh prices mid-run.
+ */
+export declare function invalidatePricingCache(): void;
+/**
+ * Override pricing for a specific model. Used for testing with simulated costs.
+ * Does NOT persist across cache invalidations.
+ */
+export declare function setModelPricing(modelId: string, pricing: ModelPricing): void;

package/dist/pricing.js

@@ -0,0 +1,81 @@
+// ─── Module-level cache (shared across all AgentBudget instances) ─────────────
+let cache = null;
+// ─── Public ───────────────────────────────────────────────────────────────────
+/**
+ * Returns pricing for a model. Fetches all model prices from OpenRouter once,
+ * then caches for `cacheTTLMs`. Unknown models return zero-cost (with a warning).
+ */
+export async function getModelPricing(modelId, apiKey, cacheTTLMs, onFreshFetch) {
+    const now = Date.now();
+    if (!cache || now - cache.fetchedAt > cacheTTLMs) {
+        try {
+            cache = await fetchAllPricing(apiKey, now);
+            onFreshFetch?.(cache.data.size, cache.fetchedAt + cacheTTLMs);
+        }
+        catch (err) {
+            // If fetch fails, use existing cache (even if expired) rather than throwing.
+            // If no cache exists at all, return zero pricing silently.
+            if (cache) {
+                console.warn(`[agent-budget] Failed to refresh pricing cache, using stale data: ${err.message?.split('\n')[0]}`);
+            }
+            else {
+                console.warn(`[agent-budget] Failed to fetch pricing for "${modelId}". Cost tracking will be 0.`);
+                return { promptPerToken: 0, completionPerToken: 0 };
+            }
+        }
+    }
+    const pricing = cache.data.get(modelId);
+    if (!pricing) {
+        console.warn(`[agent-budget] No pricing data for model "${modelId}". ` +
+            `Cost tracking will be 0 for this model. ` +
+            `Check https://openrouter.ai/models for the exact model slug.`);
+        return { promptPerToken: 0, completionPerToken: 0 };
+    }
+    return pricing;
+}
+/**
+ * Computes USD cost from pricing + token counts.
+ */
+export function calculateCost(pricing, inputTokens, outputTokens) {
+    return pricing.promptPerToken * inputTokens + pricing.completionPerToken * outputTokens;
+}
+/**
+ * Force-invalidates the pricing cache. Call this if you need fresh prices mid-run.
+ */
+export function invalidatePricingCache() {
+    cache = null;
+}
+/**
+ * Override pricing for a specific model. Used for testing with simulated costs.
+ * Does NOT persist across cache invalidations.
+ */
+export function setModelPricing(modelId, pricing) {
+    if (!cache) {
+        cache = { data: new Map(), fetchedAt: Date.now() };
+    }
+    cache.data.set(modelId, pricing);
+}
+// ─── Private ──────────────────────────────────────────────────────────────────
+async function fetchAllPricing(apiKey, fetchedAt) {
+    const res = await fetch('https://openrouter.ai/api/v1/models', {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok) {
+        throw new Error(`[agent-budget] Failed to fetch OpenRouter model list: ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    const data = new Map();
+    for (const model of json.data) {
+        if (!model.pricing)
+            continue;
+        const prompt = parseFloat(model.pricing.prompt);
+        const completion = parseFloat(model.pricing.completion);
+        if (!isNaN(prompt) && !isNaN(completion)) {
+            data.set(model.id, {
+                promptPerToken: prompt,
+                completionPerToken: completion,
+            });
+        }
+    }
+    return { data, fetchedAt };
+}

package/dist/router.d.ts

@@ -0,0 +1,14 @@
+import type { BudgetUsage } from './types.js';
+export interface RoutingDecision {
+    model: string;
+    index: number;
+}
+/**
+ * Resolves which model to use from the fallback chain based on current
+ * budget consumption. Returns the model and its index in the chain.
+ */
+export declare function resolveModel(fallbackChain: string[], thresholds: number[] | undefined, usage: BudgetUsage, maxCostUSD: number | undefined): RoutingDecision;
+/**
+ * Checks if a downgrade occurred and returns logging info.
+ */
+export declare function shouldLogDowngrade(prevIndex: number, currentIndex: number): boolean;