budget-agent 0.4.3

package/dist/router.js

@@ -0,0 +1,29 @@
+// ─── Default thresholds ─────────────────────────────────────────────────────
+const DEFAULT_THRESHOLDS = [0.6, 0.85];
+/**
+ * Resolves which model to use from the fallback chain based on current
+ * budget consumption. Returns the model and its index in the chain.
+ */
+export function resolveModel(fallbackChain, thresholds, usage, maxCostUSD) {
+    if (!maxCostUSD || maxCostUSD <= 0) {
+        return { model: fallbackChain[0], index: 0 };
+    }
+    const pct = usage.totalCostUSD / maxCostUSD;
+    const t = thresholds ?? DEFAULT_THRESHOLDS;
+    // Find the appropriate tier
+    let tier = 0;
+    for (let i = 0; i < t.length; i++) {
+        if (pct >= t[i]) {
+            tier = i + 1;
+        }
+    }
+    // Clamp to chain length
+    const idx = Math.min(tier, fallbackChain.length - 1);
+    return { model: fallbackChain[idx], index: idx };
+}
+/**
+ * Checks if a downgrade occurred and returns logging info.
+ */
+export function shouldLogDowngrade(prevIndex, currentIndex) {
+    return currentIndex > prevIndex;
+}

package/dist/tracker.d.ts

@@ -0,0 +1,15 @@
+import type { BudgetUsage, StepUsage } from './types.js';
+export declare class UsageTracker {
+    private startTime;
+    private stepHistory;
+    private totalInputTokens;
+    private totalOutputTokens;
+    private totalCostUSD;
+    constructor();
+    static fromSnapshot(usage: BudgetUsage): UsageTracker;
+    record(step: StepUsage): void;
+    snapshot(): BudgetUsage;
+    stepCount(): number;
+    reset(): void;
+    rollback(): StepUsage | null;
+}

package/dist/tracker.js

@@ -0,0 +1,53 @@
+export class UsageTracker {
+    startTime;
+    stepHistory = [];
+    totalInputTokens = 0;
+    totalOutputTokens = 0;
+    totalCostUSD = 0;
+    constructor() {
+        this.startTime = Date.now();
+    }
+    static fromSnapshot(usage) {
+        const t = new UsageTracker();
+        t.stepHistory = usage.stepHistory;
+        t.totalInputTokens = usage.totalInputTokens;
+        t.totalOutputTokens = usage.totalOutputTokens;
+        t.totalCostUSD = usage.totalCostUSD;
+        t.startTime = Date.now() - usage.elapsedMs;
+        return t;
+    }
+    record(step) {
+        this.stepHistory.push(step);
+        this.totalInputTokens += step.inputTokens;
+        this.totalOutputTokens += step.outputTokens;
+        this.totalCostUSD += step.costUSD;
+    }
+    snapshot() {
+        return {
+            steps: this.stepHistory.length,
+            totalInputTokens: this.totalInputTokens,
+            totalOutputTokens: this.totalOutputTokens,
+            totalCostUSD: this.totalCostUSD,
+            elapsedMs: Date.now() - this.startTime,
+            stepHistory: [...this.stepHistory],
+        };
+    }
+    stepCount() {
+        return this.stepHistory.length;
+    }
+    reset() {
+        this.stepHistory = [];
+        this.totalInputTokens = 0;
+        this.totalOutputTokens = 0;
+        this.totalCostUSD = 0;
+    }
+    rollback() {
+        const last = this.stepHistory.pop();
+        if (!last)
+            return null;
+        this.totalInputTokens -= last.inputTokens;
+        this.totalOutputTokens -= last.outputTokens;
+        this.totalCostUSD -= last.costUSD;
+        return last;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,149 @@
+export interface BudgetLimits {
+    maxCostUSD?: number;
+    maxInputTokens?: number;
+    maxOutputTokens?: number;
+    maxTotalTokens?: number;
+    maxSteps?: number;
+    maxWallTimeMs?: number;
+    preflightCheck?: boolean;
+    preflightOutputTokenEstimate?: number;
+}
+export type ExceededStrategy = 'abort' | ((usage: BudgetUsage) => void);
+export interface ExecutorResult {
+    model: string;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    choices: Array<{
+        message: {
+            role: string;
+            content: string;
+        };
+        finish_reason: string;
+    }>;
+}
+/**
+ * Custom API executor. Replaces the built-in OpenRouter fetch.
+ * Receives the StepRequest (after adaptive routing, auto-compress, etc.) and
+ * returns a normalized response. Use this to integrate any LLM provider.
+ */
+export type AgentExecutor = (request: StepRequest) => Promise<ExecutorResult>;
+export interface BudgetOptions {
+    apiKey: string;
+    limits: BudgetLimits;
+    onExceeded?: ExceededStrategy;
+    pricingCacheTTLMs?: number;
+    siteUrl?: string;
+    appTitle?: string;
+    autoCompress?: {
+        thresholdTokens: number;
+        keepLastN?: number;
+    };
+    circuitBreaker?: {
+        repetitionWindow?: number;
+        repetitionThreshold?: number;
+        stagnationWindow?: number;
+        stagnationMinLength?: number;
+    };
+    adaptiveRouting?: {
+        fallbackChain: string[];
+        thresholds?: number[];
+    };
+    checkpoint?: {
+        path?: string;
+        enabled?: boolean;
+    };
+    onEvent?: (event: import('./events.js').AgentBudgetEvent) => void;
+    warningThreshold?: number;
+    telemetry?: {
+        enabled: boolean;
+        tracer?: unknown;
+    };
+    executor?: AgentExecutor;
+    baseUrl?: string;
+    defaultHeaders?: Record<string, string>;
+}
+export interface ModelPricing {
+    promptPerToken: number;
+    completionPerToken: number;
+}
+export interface StepUsage {
+    stepIndex: number;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUSD: number;
+    durationMs: number;
+    outputContent?: string;
+}
+export interface BudgetUsage {
+    steps: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCostUSD: number;
+    elapsedMs: number;
+    stepHistory: StepUsage[];
+}
+export type ExceededReason = 'cost' | 'inputTokens' | 'outputTokens' | 'totalTokens' | 'steps' | 'wallTime' | 'preflightCostEstimate' | 'circuitBreaker' | 'fallbackChainExhausted';
+export interface BudgetExceededError {
+    reason: ExceededReason;
+    limit: number;
+    actual: number;
+    usage: BudgetUsage;
+    remainingBudget?: number;
+    triggerMode?: 'repetition' | 'stagnation';
+    windowSize?: number;
+    similarity?: number;
+    estimatedCost?: number;
+}
+export interface OpenRouterMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_call_id?: string;
+    name?: string;
+}
+export interface StepRequest {
+    model: string;
+    messages: OpenRouterMessage[];
+    tools?: unknown[];
+    temperature?: number;
+    max_tokens?: number;
+    stream?: boolean;
+    [key: string]: unknown;
+}
+export interface StreamChunk {
+    type: 'token' | 'done' | 'error';
+    token?: string;
+    response?: OpenRouterResponse;
+    error?: string;
+}
+export type TokenCallback = (token: string) => void;
+export interface OpenRouterResponse {
+    id: string;
+    model: string;
+    choices: Array<{
+        message: OpenRouterMessage;
+        finish_reason: string;
+        native_finish_reason?: string | null;
+        error?: {
+            code: number;
+            message: string;
+            metadata?: Record<string, unknown>;
+        };
+    }>;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+export interface CheckpointData {
+    checkpointVersion: string;
+    messages: OpenRouterMessage[];
+    usage: BudgetUsage;
+    model: string;
+    resumeFromStep: number;
+    createdAt: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// ─── Limits ──────────────────────────────────────────────────────────────────
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "budget-agent",
+  "version": "0.4.3",
+  "description": "Provider-agnostic budget enforcement SDK for LLM agents. Track token/cost/step usage, enforce limits, auto-compress, circuit-breaker, checkpoints, adaptive routing, and more.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "agent",
+    "budget",
+    "token",
+    "cost",
+    "llm",
+    "circuit-breaker",
+    "checkpoint",
+    "rate-limit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/duggal1/agent-budget.git"
+  }
+}