@blockrun/clawrouter 0.12.55 → 0.12.60

package/dist/index.d.ts

@@ -522,6 +522,7 @@ type SessionEntry = {
     recentHashes: string[];
     strikes: number;
     escalated: boolean;
+    sessionCostMicros: bigint;
 };
 type SessionConfig = {
     /** Enable session persistence (default: false) */
@@ -590,6 +591,17 @@ declare class SessionStore {
         model: string;
         tier: string;
     } | null;
+    /**
+     * Add cost to a session's running total for maxCostPerRun tracking.
+     * Cost is in USDC 6-decimal units (micros).
+     * Creates a cost-tracking-only entry if none exists (e.g., explicit model requests
+     * that never go through the routing path).
+     */
+    addSessionCost(sessionId: string, additionalMicros: bigint): void;
+    /**
+     * Get the total accumulated cost for a session in USD.
+     */
+    getSessionCostUsd(sessionId: string): number;
     /**
      * Stop the cleanup interval.
      */
@@ -693,6 +705,18 @@ type ProxyOptions = {
      * Default: enabled with 10 minute TTL, 200 max entries.
      */
     cacheConfig?: ResponseCacheConfig;
+    /**
+     * Maximum total spend (in USD) per session run.
+     * Default: undefined (no limit). Example: 0.5 = $0.50 per session.
+     */
+    maxCostPerRunUsd?: number;
+    /**
+     * How to enforce the per-run cost cap.
+     * - 'graceful' (default): when budget runs low, downgrade to cheaper models; use free model
+     *   as last resort. Only hard-stops when no model can serve the request.
+     * - 'strict': immediately return 429 once the session spend reaches the cap.
+     */
+    maxCostPerRunMode?: "graceful" | "strict";
     onReady?: (port: number) => void;
     onError?: (error: Error) => void;
     onPayment?: (info: {