budget-agent 0.4.3

package/dist/compressor.js

@@ -0,0 +1,126 @@
+const OPENROUTER_CHAT = 'https://openrouter.ai/api/v1/chat/completions';
+const COMPRESSION_MODEL = 'cohere/north-mini-code:free';
+const CHARS_PER_TOKEN = 4;
+// ─── Token estimation ─────────────────────────────────────────────────────────
+/**
+ * Character-based token approximation. 4 chars ≈ 1 token.
+ * Good enough for threshold decisions — not for billing.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/**
+ * Estimates total token count for a message array.
+ */
+export function estimateMessagesTokens(messages) {
+    let total = 0;
+    for (const msg of messages) {
+        if (typeof msg.content === 'string') {
+            total += estimateTokens(msg.content);
+        }
+    }
+    return total;
+}
+// ─── Compression ──────────────────────────────────────────────────────────────
+/**
+ * Compresses a message array by summarizing the middle section via an LLM call.
+ *
+ * Strategy:
+ * 1. Preserve the system message (if present) — never touched.
+ * 2. Preserve the last `keepLastN` messages — never touched.
+ * 3. Everything in between is replaced with a single synthetic assistant
+ *    message containing an LLM-generated summary.
+ *
+ * The summary is clearly marked so downstream code can detect it.
+ */
+export async function compressMessages(messages, apiKey, keepLastN = 4) {
+    // Nothing to compress if we have fewer messages than the keep window
+    if (messages.length <= keepLastN + 1) {
+        return messages;
+    }
+    // Split: system message (if any) + middle messages + last N messages
+    let systemMessage = null;
+    let startIndex = 0;
+    if (messages[0]?.role === 'system') {
+        systemMessage = messages[0];
+        startIndex = 1;
+    }
+    const endIndex = messages.length - keepLastN;
+    const middleMessages = messages.slice(startIndex, endIndex);
+    const lastNMessages = messages.slice(endIndex);
+    if (middleMessages.length === 0) {
+        return messages;
+    }
+    // Build the conversation text for summarization
+    const conversationText = middleMessages
+        .map((msg) => `[${msg.role}]: ${msg.content ?? ''}`)
+        .join('\n\n');
+    // Call LLM to generate summary
+    const summaryContent = await generateSummary(conversationText, apiKey, middleMessages.length);
+    // Build compressed message array
+    const compressed = [];
+    if (systemMessage) {
+        compressed.push(systemMessage);
+    }
+    compressed.push({
+        role: 'assistant',
+        content: summaryContent,
+    });
+    compressed.push(...lastNMessages);
+    return compressed;
+}
+// ─── Summary generation ───────────────────────────────────────────────────────
+async function generateSummary(conversationText, apiKey, collapsedCount) {
+    const prompt = 'You are a conversation summarizer for an AI agent loop. ' +
+        'Summarize the following conversation between a user and an assistant. ' +
+        'Focus on:\n' +
+        '- What was discussed\n' +
+        '- What decisions were made\n' +
+        '- What tool calls were made\n' +
+        '- What the current goal state is\n\n' +
+        'Keep the summary concise but comprehensive. Output ONLY the summary text, no preamble.\n\n' +
+        `Conversation:\n${conversationText}`;
+    const res = await fetch(OPENROUTER_CHAT, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            model: COMPRESSION_MODEL,
+            messages: [{ role: 'user', content: prompt }],
+            max_tokens: 256,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        // If the LLM call fails (rate limit, etc.), use a heuristic fallback
+        console.warn(`[agent-budget] Compression summary LLM call failed (${res.status}), using heuristic fallback`);
+        const heuristic = makeHeuristicSummary(conversationText, collapsedCount);
+        return `[COMPRESSED SUMMARY — ${collapsedCount} messages collapsed]\n${heuristic}`;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const json = (await res.json());
+    const summary = json.choices?.[0]?.message?.content ?? '';
+    return `[COMPRESSED SUMMARY — ${collapsedCount} messages collapsed]\n${summary}`;
+}
+/**
+ * Heuristic fallback when the LLM summary call fails.
+ * Extracts key topics from the conversation text to produce a basic summary.
+ */
+function makeHeuristicSummary(conversationText, collapsedCount) {
+    const lines = conversationText.split('\n').filter(Boolean);
+    const userLines = lines.filter(l => l.startsWith('[user]:'));
+    const assistantLines = lines.filter(l => l.startsWith('[assistant]:'));
+    // Extract key topics by finding noun phrases from user messages
+    const keyPhrases = [];
+    for (const line of userLines.slice(0, 5)) {
+        const words = line.replace(/\[user\]:\s*/i, '').split(' ');
+        const topic = words.slice(0, 8).join(' ');
+        keyPhrases.push(topic);
+    }
+    const summary = `The conversation covered ${collapsedCount} exchanges between user and assistant. ` +
+        `Key topics discussed include: ${keyPhrases.join('; ')}. ` +
+        `The assistant provided ${assistantLines.length} responses with explanations, code examples, and guidance.`;
+    return summary;
+}

package/dist/estimator.d.ts

@@ -0,0 +1,12 @@
+import type { StepRequest, ModelPricing } from './types.js';
+export interface CostEstimate {
+    estimatedInputTokens: number;
+    estimatedOutputTokens: number;
+    estimatedCostUSD: number;
+    confidence: 'approximate';
+}
+/**
+ * Estimates the cost of a step BEFORE making the API call.
+ * Uses character-based approximation (4 chars ≈ 1 token).
+ */
+export declare function estimateStepCost(request: StepRequest, pricing: ModelPricing, defaultOutputTokens?: number): CostEstimate;

package/dist/estimator.js

@@ -0,0 +1,38 @@
+import { calculateCost } from './pricing.js';
+// ─── Character-based token estimation ─────────────────────────────────────────
+const CHARS_PER_TOKEN = 4;
+function estimateMessageTokens(messages) {
+    let chars = 0;
+    for (const msg of messages) {
+        if (msg.content)
+            chars += msg.content.length;
+        if (msg.tool_call_id)
+            chars += msg.tool_call_id.length;
+        if (msg.name)
+            chars += msg.name.length;
+    }
+    return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+function estimateToolTokens(tools) {
+    if (!tools || tools.length === 0)
+        return 0;
+    return Math.ceil(JSON.stringify(tools).length / CHARS_PER_TOKEN);
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Estimates the cost of a step BEFORE making the API call.
+ * Uses character-based approximation (4 chars ≈ 1 token).
+ */
+export function estimateStepCost(request, pricing, defaultOutputTokens = 512) {
+    const messageTokens = estimateMessageTokens(request.messages);
+    const toolTokens = estimateToolTokens(request.tools);
+    const estimatedInputTokens = messageTokens + toolTokens;
+    const estimatedOutputTokens = request.max_tokens ?? defaultOutputTokens;
+    const estimatedCostUSD = calculateCost(pricing, estimatedInputTokens, estimatedOutputTokens);
+    return {
+        estimatedInputTokens,
+        estimatedOutputTokens,
+        estimatedCostUSD,
+        confidence: 'approximate',
+    };
+}

package/dist/events.d.ts

@@ -0,0 +1,99 @@
+import type { BudgetExceededError, ExceededReason } from './types.js';
+export type AgentBudgetEvent = {
+    type: 'step:start';
+    stepIndex: number;
+    model: string;
+    estimatedCostUSD?: number;
+} | {
+    type: 'step:token';
+    stepIndex: number;
+    token: string;
+} | {
+    type: 'step:end';
+    stepIndex: number;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUSD: number;
+    durationMs: number;
+} | {
+    type: 'budget:warning';
+    reason: ExceededReason;
+    pctConsumed: number;
+    remaining: number;
+} | {
+    type: 'budget:exceeded';
+    exceeded: BudgetExceededError;
+} | {
+    type: 'model:downgraded';
+    from: string;
+    to: string;
+    pctConsumed: number;
+} | {
+    type: 'circuit:tripped';
+    triggerMode: 'repetition' | 'stagnation';
+    stepIndex: number;
+} | {
+    type: 'compress:triggered';
+    messagesBefore: number;
+    messagesAfter: number;
+    tokensFreed: number;
+} | {
+    type: 'pricing:fetched';
+    modelCount: number;
+    cachedUntil: number;
+};
+export interface AgentBudgetEventMap {
+    'step:start': AgentBudgetEvent & {
+        type: 'step:start';
+    };
+    'step:token': AgentBudgetEvent & {
+        type: 'step:token';
+    };
+    'step:end': AgentBudgetEvent & {
+        type: 'step:end';
+    };
+    'budget:warning': AgentBudgetEvent & {
+        type: 'budget:warning';
+    };
+    'budget:exceeded': AgentBudgetEvent & {
+        type: 'budget:exceeded';
+    };
+    'model:downgraded': AgentBudgetEvent & {
+        type: 'model:downgraded';
+    };
+    'circuit:tripped': AgentBudgetEvent & {
+        type: 'circuit:tripped';
+    };
+    'compress:triggered': AgentBudgetEvent & {
+        type: 'compress:triggered';
+    };
+    'pricing:fetched': AgentBudgetEvent & {
+        type: 'pricing:fetched';
+    };
+}
+export declare class AgentEventEmitter {
+    private readonly onEvent?;
+    private readonly emitter;
+    constructor(onEvent?: ((event: AgentBudgetEvent) => void) | undefined);
+    emit(event: AgentBudgetEvent): void;
+    on<K extends keyof AgentBudgetEventMap>(type: K, handler: (event: AgentBudgetEventMap[K]) => void): this;
+    off<K extends keyof AgentBudgetEventMap>(type: K, handler: (event: AgentBudgetEventMap[K]) => void): this;
+    removeAllListeners(): void;
+}
+export declare class WarningChecker {
+    private firedMetrics;
+    reset(): void;
+    check(usage: {
+        totalCostUSD: number;
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        steps: number;
+    }, limits: {
+        maxCostUSD?: number;
+        maxInputTokens?: number;
+        maxOutputTokens?: number;
+        maxTotalTokens?: number;
+        maxSteps?: number;
+    }, warnPct: number, emit: (event: AgentBudgetEvent) => void): void;
+}

package/dist/events.js

@@ -0,0 +1,56 @@
+import { EventEmitter } from 'node:events';
+// ─── Typed emitter ───────────────────────────────────────────────────────────
+export class AgentEventEmitter {
+    onEvent;
+    emitter = new EventEmitter();
+    constructor(onEvent) {
+        this.onEvent = onEvent;
+        this.emitter.setMaxListeners(50);
+    }
+    emit(event) {
+        this.emitter.emit(event.type, event);
+        this.onEvent?.(event);
+    }
+    on(type, handler) {
+        this.emitter.on(type, handler);
+        return this;
+    }
+    off(type, handler) {
+        this.emitter.off(type, handler);
+        return this;
+    }
+    removeAllListeners() {
+        this.emitter.removeAllListeners();
+    }
+}
+// ─── Warning threshold checker ───────────────────────────────────────────────
+export class WarningChecker {
+    firedMetrics = new Set();
+    reset() {
+        this.firedMetrics.clear();
+    }
+    check(usage, limits, warnPct, emit) {
+        const totalTokens = usage.totalInputTokens + usage.totalOutputTokens;
+        const metrics = [
+            { key: 'cost', reason: 'cost', limit: limits.maxCostUSD, actual: usage.totalCostUSD },
+            { key: 'steps', reason: 'steps', limit: limits.maxSteps, actual: usage.steps },
+            { key: 'totalTokens', reason: 'totalTokens', limit: limits.maxTotalTokens, actual: totalTokens },
+            { key: 'inputTokens', reason: 'inputTokens', limit: limits.maxInputTokens, actual: usage.totalInputTokens },
+            { key: 'outputTokens', reason: 'outputTokens', limit: limits.maxOutputTokens, actual: usage.totalOutputTokens },
+        ];
+        for (const { key, reason, limit, actual } of metrics) {
+            if (limit === undefined)
+                continue;
+            const pctConsumed = actual / limit;
+            if (pctConsumed >= warnPct && !this.firedMetrics.has(key)) {
+                this.firedMetrics.add(key);
+                emit({
+                    type: 'budget:warning',
+                    reason,
+                    pctConsumed,
+                    remaining: limit - actual,
+                });
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import type { BudgetOptions, BudgetUsage, StepRequest, OpenRouterResponse, OpenRouterMessage, CheckpointData } from './types.js';
+export declare class AgentBudget {
+    private readonly apiKey;
+    private readonly limits;
+    private readonly onExceeded;
+    private readonly cacheTTL;
+    private readonly siteUrl?;
+    private readonly appTitle?;
+    private readonly autoCompress?;
+    private readonly adaptiveRouting?;
+    private currentModelIndex;
+    private tracker;
+    private readonly circuitBreaker;
+    private readonly checkpointManager;
+    private readonly emitter;
+    private readonly warningChecker;
+    private readonly warningThreshold;
+    private readonly telemetry;
+    private tracer;
+    private readonly executor?;
+    private readonly baseUrl;
+    private readonly defaultHeaders;
+    constructor(options: BudgetOptions);
+    /**
+     * Execute one agent step through OpenRouter.
+     * Checks budget limits before AND after the API call.
+     * Throws BudgetError if any limit is exceeded.
+     */
+    step(request: StepRequest): Promise<OpenRouterResponse>;
+    /**
+     * Current accumulated usage. Safe to call at any time.
+     */
+    getUsage(): BudgetUsage;
+    /**
+     * Prints a single summary table to console. Returns the same usage snapshot.
+     */
+    summary(): BudgetUsage;
+    /**
+     * Subscribe to a specific event type.
+     */
+    on<K extends keyof import('./events.js').AgentBudgetEventMap>(type: K, handler: (event: import('./events.js').AgentBudgetEventMap[K]) => void): this;
+    /**
+     * Unsubscribe from a specific event type.
+     */
+    off<K extends keyof import('./events.js').AgentBudgetEventMap>(type: K, handler: (event: import('./events.js').AgentBudgetEventMap[K]) => void): this;
+    /**
+     * Resets all usage counters. Does NOT reset pricing cache.
+     */
+    reset(): void;
+    /**
+     * Force-refresh pricing on next step. Useful for long-running agents.
+     */
+    refreshPricing(): void;
+    /**
+     * Returns the model that the adaptive router would use right now,
+     * or undefined if adaptive routing is not configured.
+     */
+    getCurrentModel(): string | undefined;
+    /**
+     * Manually record a step into the tracker.
+     * Useful for replaying checkpoints or simulating usage in tests.
+     */
+    recordStep(usage: {
+        inputTokens: number;
+        outputTokens: number;
+        costUSD: number;
+    }): void;
+    /**
+     * 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.
+     */
+    compressMessages(messages: OpenRouterMessage[], keepLastN?: number): Promise<OpenRouterMessage[]>;
+    /**
+     * Delete the checkpoint file. Call after the agent loop completes successfully.
+     */
+    clearCheckpoint(): Promise<void>;
+    /**
+     * Load an existing checkpoint. Returns null if none exists.
+     */
+    loadCheckpoint(): Promise<CheckpointData | 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 resume(options: BudgetOptions, checkpointPath?: string): Promise<AgentBudget>;
+    private _initTracer;
+    private _startSpan;
+    private _readStream;
+    private _defaultFetch;
+    private _checkOrThrow;
+}
+export declare function createAgentBudget(options: BudgetOptions): AgentBudget;
+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 type { RoutingDecision } from './router.js';
+export type { CostEstimate } from './estimator.js';
+export type { CircuitBreakerConfig, CircuitBreakerTrip } from './circuit-breaker.js';
+export { CheckpointManager } from './checkpoint.js';
+export { compressMessages, estimateMessagesTokens } from './compressor.js';
+export { AgentEventEmitter } from './events.js';
+export type { AgentBudgetEvent, AgentBudgetEventMap } from './events.js';
+export type { CheckpointData } from './types.js';
+export type { BudgetOptions, BudgetLimits, BudgetUsage, StepUsage, StepRequest, OpenRouterResponse, OpenRouterMessage, BudgetExceededError, ExceededReason, ExceededStrategy, ModelPricing, StreamChunk, TokenCallback, AgentExecutor, ExecutorResult, } from './types.js';