@blockrun/clawrouter 0.12.282 → 0.12.284

package/dist/index.js

@@ -34678,6 +34678,11 @@ function getSharedSpendControl() {
   host.__clawrouterSharedSpendControl ??= new SpendControl();
   return host.__clawrouterSharedSpendControl;
 }
+function parseQuotedAmountMicros(selected) {
+  const raw = selected.amount ?? selected.maxAmountRequired;
+  if (typeof raw !== "string" || !CANONICAL_AMOUNT.test(raw)) return void 0;
+  return BigInt(raw);
+}
 function parseQuotedAmountUsd(selected) {
   const raw = selected.amount ?? selected.maxAmountRequired;
   if (typeof raw !== "string" || !CANONICAL_AMOUNT.test(raw)) {
@@ -35443,6 +35448,16 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
       return est === void 0 ? void 0 : Number(est);
     };
     const needMicros = estimateMicros();
+    const notifyDeclinedPayment = () => {
+      if (!options?.onPaymentDeclined) return;
+      try {
+        options.onPaymentDeclined();
+      } catch (error) {
+        console.error(
+          `[ClawRouter] onPaymentDeclined callback failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    };
     const cached = !options?.skipPreAuth ? cache2.get(cacheKey2) : void 0;
     const preAuthCovers = cached !== void 0 && Date.now() - cached.cachedAt < ttlMs && cached.coverMicros !== void 0 && needMicros !== void 0 && needMicros <= cached.coverMicros;
     if (preAuthCovers) {
@@ -35461,6 +35476,7 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
           return response2;
         }
         paymentInFlight = false;
+        notifyDeclinedPayment();
         cache2.delete(cacheKey2);
       } catch (err) {
         cache2.delete(cacheKey2);
@@ -35505,6 +35521,7 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
       clonedRequest.headers.set(key3, value);
     }
     const paidResponse = await baseFetch(clonedRequest);
+    if (paidResponse.status === 402) notifyDeclinedPayment();
     notifyAcceptedPayment(paidResponse, payload);
     return paidResponse;
   };
@@ -64542,6 +64559,132 @@ var init_api_key = __esm({
   }
 });
 
+// src/session-spend.ts
+function parseMicros(raw) {
+  if (raw === void 0 || !/^\d+$/.test(raw)) return void 0;
+  return BigInt(raw);
+}
+function usdToMicros(usd) {
+  return BigInt(Math.round(usd * 1e6));
+}
+function microsToUsd(micros) {
+  return Number(micros) / 1e6;
+}
+var SessionSpend, CostCapError;
+var init_session_spend = __esm({
+  "src/session-spend.ts"() {
+    "use strict";
+    init_spend_control();
+    SessionSpend = class _SessionSpend {
+      constructor(store, sessionId, capMicros, holdMicros) {
+        this.store = store;
+        this.sessionId = sessionId;
+        this.capMicros = capMicros;
+        this.heldMicros = holdMicros;
+        if (holdMicros > 0n) store.adjustSessionHold(sessionId, holdMicros);
+      }
+      store;
+      sessionId;
+      capMicros;
+      /** Budget this request still holds against the session (strict mode only). */
+      heldMicros;
+      /** Sum of payments signed by this request that still count. */
+      signedMicros = 0n;
+      /** The most recent signature not yet settled or voided — the one a decline undoes. */
+      lastSignedMicros = 0n;
+      released = false;
+      /**
+       * Strict mode: admit the request only if the session's spend, plus what its
+       * other in-flight requests hold, plus this request's estimate fits the cap —
+       * and hold the estimate in the same step.
+       */
+      static admit(store, sessionId, capMicros, estimateMicros) {
+        const spentMicros = store.getSessionCostMicros(sessionId);
+        const heldMicros = store.getSessionHoldMicros(sessionId);
+        if (spentMicros + heldMicros + estimateMicros > capMicros) {
+          return { admitted: false, spentMicros, heldMicros, estimateMicros };
+        }
+        return {
+          admitted: true,
+          spend: new _SessionSpend(store, sessionId, capMicros, estimateMicros)
+        };
+      }
+      /** Graceful mode: track signed spend, enforce nothing. */
+      static track(store, sessionId) {
+        return new _SessionSpend(store, sessionId, void 0, 0n);
+      }
+      get isStrict() {
+        return this.capMicros !== void 0;
+      }
+      /**
+       * Before a payment is created: may this request sign `quoteMicros`?
+       * Spend already recorded (including this request's own earlier signatures)
+       * plus what OTHER in-flight requests hold, plus the quote, must fit the cap.
+       * Always true in graceful mode.
+       */
+      coverPayment(quoteMicros) {
+        if (this.capMicros === void 0) return true;
+        const spent = this.store.getSessionCostMicros(this.sessionId);
+        const heldByOthers = this.store.getSessionHoldMicros(this.sessionId) - this.heldMicros;
+        if (spent + heldByOthers + quoteMicros > this.capMicros) return false;
+        if (quoteMicros > this.heldMicros) {
+          this.store.adjustSessionHold(this.sessionId, quoteMicros - this.heldMicros);
+          this.heldMicros = quoteMicros;
+        }
+        return true;
+      }
+      /** A payment was signed: it is spend now, and replaces part of the hold. */
+      recordSigned(amountMicros) {
+        if (amountMicros <= 0n) return;
+        this.signedMicros += amountMicros;
+        this.lastSignedMicros = amountMicros;
+        this.store.addSessionCost(this.sessionId, amountMicros);
+        this.shrinkHold(amountMicros);
+      }
+      /**
+       * The gateway answered the payment just signed with a 402: nothing settled.
+       * Payments within one request are signed and sent one at a time, so the
+       * decline always belongs to the latest signature. Undone at most once.
+       */
+      voidLastSigned() {
+        const undo = this.lastSignedMicros;
+        this.lastSignedMicros = 0n;
+        if (undo <= 0n) return;
+        this.signedMicros -= undo;
+        this.store.addSessionCost(this.sessionId, -undo);
+      }
+      /**
+       * An attempt succeeded. When nothing was signed for this request (the API
+       * key rail), the local estimate is the only record of the spend. When a
+       * payment was signed, it is already recorded at its real amount.
+       */
+      recordSuccess(estimateMicros) {
+        if (this.signedMicros > 0n || estimateMicros <= 0n) return;
+        this.store.addSessionCost(this.sessionId, estimateMicros);
+        this.shrinkHold(estimateMicros);
+      }
+      /** The request is over: return whatever it still holds. Idempotent. */
+      release() {
+        if (this.released) return;
+        this.released = true;
+        this.shrinkHold(this.heldMicros);
+      }
+      shrinkHold(byMicros) {
+        const drop = byMicros < this.heldMicros ? byMicros : this.heldMicros;
+        if (drop <= 0n) return;
+        this.heldMicros -= drop;
+        this.store.adjustSessionHold(this.sessionId, -drop);
+      }
+    };
+    CostCapError = class extends SpendPolicyError {
+      constructor(reason) {
+        super(reason);
+        this.name = "CostCapError";
+      }
+    };
+  }
+});
+
 // src/compression/types.ts
 var DEFAULT_COMPRESSION_CONFIG;
 var init_types2 = __esm({
@@ -65389,6 +65532,9 @@ var init_session = __esm({
     };
     SessionStore = class {
       sessions = /* @__PURE__ */ new Map();
+      // Kept apart from `sessions`: a hold belongs to requests still running, so it
+      // must not vanish when the idle-session sweep drops an entry mid-request.
+      sessionHolds = /* @__PURE__ */ new Map();
       config;
       cleanupInterval = null;
       constructor(config = {}) {
@@ -65564,14 +65710,34 @@ var init_session = __esm({
           this.sessions.set(sessionId, entry);
         }
         entry.sessionCostMicros += additionalMicros;
+        if (entry.sessionCostMicros < 0n) entry.sessionCostMicros = 0n;
       }
       /**
        * Get the total accumulated cost for a session in USD.
        */
       getSessionCostUsd(sessionId) {
-        const entry = this.sessions.get(sessionId);
-        if (!entry) return 0;
-        return Number(entry.sessionCostMicros) / 1e6;
+        return Number(this.getSessionCostMicros(sessionId)) / 1e6;
+      }
+      /**
+       * Get the total accumulated cost for a session in USDC micros.
+       */
+      getSessionCostMicros(sessionId) {
+        return this.sessions.get(sessionId)?.sessionCostMicros ?? 0n;
+      }
+      /**
+       * Budget held by a session's in-flight requests (USDC micros) — admitted
+       * against the strict cap but not yet spent. See session-spend.ts.
+       */
+      getSessionHoldMicros(sessionId) {
+        return this.sessionHolds.get(sessionId) ?? 0n;
+      }
+      /**
+       * Grow (positive) or release (negative) a session's in-flight hold.
+       */
+      adjustSessionHold(sessionId, deltaMicros) {
+        const next = (this.sessionHolds.get(sessionId) ?? 0n) + deltaMicros;
+        if (next > 0n) this.sessionHolds.set(sessionId, next);
+        else this.sessionHolds.delete(sessionId);
       }
       /**
        * Stop the cleanup interval.
@@ -96274,6 +96440,19 @@ async function startProxy(options) {
   }
   const account = walletKey ? privateKeyToAccount(walletKey) : void 0;
   const x402 = authMode === "wallet" ? new x402Client() : void 0;
+  x402?.onBeforePaymentCreation(async (context) => {
+    const spend = paymentStore.getStore()?.sessionSpend;
+    if (!spend?.isStrict) return;
+    const quote = parseQuotedAmountMicros(context.selectedRequirements);
+    if (quote === void 0) {
+      throw new CostCapError("ClawRouter cost cap: unreadable payment amount in the 402 quote");
+    }
+    if (!spend.coverPayment(quote)) {
+      throw new CostCapError(
+        `ClawRouter cost cap exceeded: signing $${microsToUsd(quote).toFixed(6)} would push this session past its maxCostPerRun limit`
+      );
+    }
+  });
   if (x402 && account) {
     const evmPublicClient = createPublicClient({ chain: base, transport: http() });
     const evmSigner = toClientEvmSigner(account, evmPublicClient);
@@ -96316,6 +96495,11 @@ async function startProxy(options) {
     if (store) store.amountUsd = amountUsd;
     console.log(`[ClawRouter] Payment signed on ${chain3} (${network}) \u2014 $${amountUsd.toFixed(6)}`);
   });
+  x402?.onAfterPaymentCreation(async (context) => {
+    const spend = paymentStore.getStore()?.sessionSpend;
+    const amount = parseQuotedAmountMicros(context.selectedRequirements);
+    if (spend && amount !== void 0) spend.recordSigned(amount);
+  });
   const payFetch = authMode === "api-key" ? withSpendPolicy(
     createApiKeyFetch(apiKey, fetch, apiBase),
     options.spendControl ?? getSharedSpendControl(),
@@ -96334,7 +96518,10 @@ async function startProxy(options) {
     // Only the wallet rail settles per call. The API-key rail is billed
     // server-side against account credit, so there is no per-request
     // settlement for an observer to report.
-    onPayment: options.onPayment
+    onPayment: options.onPayment,
+    // A 402 answer to a signed payment means the gateway declined it and
+    // nothing settled — take it back off the session's budget.
+    onPaymentDeclined: () => paymentStore.getStore()?.sessionSpend?.voidLastSigned()
   });
   let balanceMonitor;
   if (options._balanceMonitorOverride) {
@@ -97618,6 +97805,17 @@ async function tryModelRequest(upstreamUrl, method, headers, body, modelId, maxT
     return { success: true, response };
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
+    if (err instanceof CostCapError) {
+      return {
+        success: false,
+        errorBody: JSON.stringify({
+          error: { message: errorMsg, type: "cost_cap_exceeded", code: "cost_cap_exceeded" }
+        }),
+        errorStatus: 429,
+        isProviderError: false,
+        errorCategory: "payment_error"
+      };
+    }
     if (err instanceof SpendPolicyError) {
       return {
         success: false,
@@ -98697,14 +98895,23 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
       }
     }
   }
+  let sessionSpend;
   if (options.maxCostPerRunUsd && effectiveSessionId && !isFreeModel && (options.maxCostPerRunMode ?? "graceful") === "strict") {
-    const runCostUsd = sessionStore.getSessionCostUsd(effectiveSessionId);
     const thisReqEstStr = estimatedCostMicros !== void 0 ? estimatedCostMicros.toString() : modelId ? estimateAmount(modelId, body.length, maxTokens) : void 0;
-    const thisReqEstUsd = thisReqEstStr ? Number(thisReqEstStr) / 1e6 : 0;
-    const projectedCostUsd = runCostUsd + thisReqEstUsd;
-    if (projectedCostUsd > options.maxCostPerRunUsd) {
+    const admission = SessionSpend.admit(
+      sessionStore,
+      effectiveSessionId,
+      usdToMicros(options.maxCostPerRunUsd),
+      parseMicros(thisReqEstStr) ?? 0n
+    );
+    if (!admission.admitted) {
+      const spentUsd = microsToUsd(admission.spentMicros);
+      const heldUsd = microsToUsd(admission.heldMicros);
+      const estUsd = microsToUsd(admission.estimateMicros);
+      const projectedCostUsd = spentUsd + heldUsd + estUsd;
+      const breakdown = `spent $${spentUsd.toFixed(4)}${heldUsd > 0 ? ` + in flight $${heldUsd.toFixed(4)}` : ""} + est $${estUsd.toFixed(4)}`;
       console.log(
-        `[ClawRouter] Cost cap exceeded for session ${effectiveSessionId.slice(0, 8)}...: projected $${projectedCostUsd.toFixed(4)} (spent $${runCostUsd.toFixed(4)} + est $${thisReqEstUsd.toFixed(4)}) > $${options.maxCostPerRunUsd} limit`
+        `[ClawRouter] Cost cap exceeded for session ${effectiveSessionId.slice(0, 8)}...: projected $${projectedCostUsd.toFixed(4)} (${breakdown}) > $${options.maxCostPerRunUsd} limit`
       );
       res.writeHead(429, {
         "Content-Type": "application/json",
@@ -98713,7 +98920,7 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
       res.end(
         JSON.stringify({
           error: {
-            message: `ClawRouter cost cap exceeded: projected spend $${projectedCostUsd.toFixed(4)} (spent $${runCostUsd.toFixed(4)} + est $${thisReqEstUsd.toFixed(4)}) would exceed limit $${options.maxCostPerRunUsd}`,
+            message: `ClawRouter cost cap exceeded: projected spend $${projectedCostUsd.toFixed(4)} (${breakdown}) would exceed limit $${options.maxCostPerRunUsd}`,
             type: "cost_cap_exceeded",
             code: "cost_cap_exceeded"
           }
@@ -98722,7 +98929,12 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
       deduplicator.removeInflight(dedupKey);
       return;
     }
+    sessionSpend = admission.spend;
+  } else if (options.maxCostPerRunUsd && effectiveSessionId) {
+    sessionSpend = SessionSpend.track(sessionStore, effectiveSessionId);
   }
+  const requestStore = paymentStore.getStore();
+  if (requestStore) requestStore.sessionSpend = sessionSpend;
   if (options.maxCostPerRunUsd && effectiveSessionId && !isFreeModel && (options.maxCostPerRunMode ?? "graceful") === "graceful") {
     const runCostUsd = sessionStore.getSessionCostUsd(effectiveSessionId);
     const remainingUsd = options.maxCostPerRunUsd - runCostUsd;
@@ -99118,11 +99330,9 @@ data: [DONE]
         actualModelUsed = tryModel;
         recordOutcome(tryModel, requestKind, true);
         console.log(`[ClawRouter] Success with model: ${tryModel}`);
-        if (options.maxCostPerRunUsd && effectiveSessionId && !FREE_MODELS.has(tryModel)) {
-          const costEst = estimateAmount(tryModel, body.length, maxTokens);
-          if (costEst) {
-            sessionStore.addSessionCost(effectiveSessionId, BigInt(costEst));
-          }
+        if (sessionSpend && !FREE_MODELS.has(tryModel)) {
+          const costEst = parseMicros(estimateAmount(tryModel, body.length, maxTokens));
+          if (costEst !== void 0) sessionSpend.recordSuccess(costEst);
         }
         break;
       }
@@ -99196,11 +99406,9 @@ data: [DONE]
             upstream = retryResult.response;
             actualModelUsed = tryModel;
             console.log(`[ClawRouter] Explicit-pin retry succeeded for: ${tryModel}`);
-            if (options.maxCostPerRunUsd && effectiveSessionId && !FREE_MODELS.has(tryModel)) {
-              const costEst = estimateAmount(tryModel, body.length, maxTokens);
-              if (costEst) {
-                sessionStore.addSessionCost(effectiveSessionId, BigInt(costEst));
-              }
+            if (sessionSpend && !FREE_MODELS.has(tryModel)) {
+              const costEst = parseMicros(estimateAmount(tryModel, body.length, maxTokens));
+              if (costEst !== void 0) sessionSpend.recordSuccess(costEst);
             }
             break;
           }
@@ -99267,11 +99475,9 @@ data: [DONE]
                 upstream = retryResult.response;
                 actualModelUsed = tryModel;
                 console.log(`[ClawRouter] Rate-limit retry succeeded for: ${tryModel}`);
-                if (options.maxCostPerRunUsd && effectiveSessionId && !FREE_MODELS.has(tryModel)) {
-                  const costEst = estimateAmount(tryModel, body.length, maxTokens);
-                  if (costEst) {
-                    sessionStore.addSessionCost(effectiveSessionId, BigInt(costEst));
-                  }
+                if (sessionSpend && !FREE_MODELS.has(tryModel)) {
+                  const costEst = parseMicros(estimateAmount(tryModel, body.length, maxTokens));
+                  if (costEst !== void 0) sessionSpend.recordSuccess(costEst);
                 }
                 break;
               }
@@ -99365,6 +99571,7 @@ data: [DONE]
       );
       const rawErrBody = lastError?.body || structuredMessage;
       const errStatus = lastError?.status || 502;
+      const costCapRefusal = errStatus === 429 && rawErrBody.includes('"cost_cap_exceeded"');
       const transformedErr = transformPaymentError(rawErrBody);
       requestHadError = true;
       if (headersSentEarly) {
@@ -99401,7 +99608,8 @@ data: [DONE]
           "Content-Type": "application/json",
           "x-context-used-kb": String(originalContextSizeKB),
           "x-context-limit-kb": String(CONTEXT_LIMIT_KB),
-          ...lastError?.requestId ? { "x-blockrun-request-id": lastError.requestId } : {}
+          ...lastError?.requestId ? { "x-blockrun-request-id": lastError.requestId } : {},
+          ...costCapRefusal ? { "X-ClawRouter-Cost-Cap-Exceeded": "1" } : {}
         });
         res.end(transformedErr);
         deduplicator.complete(dedupKey, {
@@ -99835,6 +100043,8 @@ data: [DONE]
       throw new Error(`Request timed out after ${timeoutMs}ms`, { cause: err });
     }
     throw err;
+  } finally {
+    sessionSpend?.release();
   }
   const logModel = routingDecision?.model ?? modelId;
   if (logModel) {
@@ -99921,6 +100131,7 @@ var init_proxy = __esm({
     init_auth();
     init_api_key();
     init_spend_control();
+    init_session_spend();
     init_compression();
     init_errors5();
     init_version4();
@@ -122622,7 +122833,7 @@ var init_client5 = __esm({
 function resolveSpendControl(deps) {
   return deps?.spendControl ?? getSharedSpendControl();
 }
-function usdToMicros(usd) {
+function usdToMicros2(usd) {
   return String(Math.ceil(usd * 1e6));
 }
 async function signUnderSpendPolicy(deps, quote, action, sign4) {
@@ -122888,7 +123099,7 @@ Re-call with confirm:true to sign and submit.`,
         payTo: negRisk ? NEG_RISK_CTF_EXCHANGE_V2 : CTF_EXCHANGE_V2,
         network: `eip155:${POLYGON_CHAIN_ID}`,
         asset: PUSD_COLLATERAL,
-        amount: usdToMicros(notional)
+        amount: usdToMicros2(notional)
       };
       let r2;
       try {

package/docs/9-free-ai-models-zero-cost-blockrun.md

@@ -1,7 +1,7 @@
 # 9 Free AI Models, Zero Cost: How BlockRun Gives Developers Top-Tier LLMs for Nothing
 
 > **The count in this title is a snapshot, and so is every model name below.**
-> It was 9 when this was written; the published free tier is <!-- br:models.free -->6<!-- /br:models.free --> today, and _none_ of the
+> It was 9 when this was written; the published free tier is <!-- br:models.free -->7<!-- /br:models.free --> today, and _none_ of the
 > nine originals is still in it. Free hosting is volatile — NVIDIA retired four
 > of the five visible free models in a single sweep on 2026-08-30 — so the tier
 > gets rebuilt rather than topped up. The URL keeps its original slug so existing
@@ -23,7 +23,7 @@ BlockRun's answer: just take them.
 
 ---
 
-## The Lineup: <!-- br:models.free -->6<!-- /br:models.free --> Models, $0.00
+## The Lineup: <!-- br:models.free -->7<!-- /br:models.free --> Models, $0.00
 
 Through [ClawRouter](https://github.com/BlockRunAI/ClawRouter) — BlockRun's local AI routing proxy — you get zero-cost access to the following (checked against the live catalog 2026-09-29):
 
@@ -236,13 +236,13 @@ Look at the cost trajectory over the past three years:
 - **2023:** GPT-4 dominates alone at $30/$60 per M tokens
 - **2024:** Open-source models surge, prices halve repeatedly
 - **2025:** DeepSeek, Qwen push top-tier inference below $1/M
-- **2026:** BlockRun offers <!-- br:models.free -->6<!-- /br:models.free --> free models through a single API
+- **2026:** BlockRun offers <!-- br:models.free -->7<!-- /br:models.free --> free models through a single API
 
 **A free tier that gets rebuilt rather than retired isn't just a product feature — it's a signal.** Baseline AI capability is becoming infrastructure. Like internet bandwidth before it, the cost of "good enough" AI inference is converging toward zero.
 
 BlockRun and ClawRouter exist to be the **routing layer** in this transition: not locked to any single provider, not bound to any single model, always giving developers the lowest-cost path to the right capability.
 
-Today it's <!-- br:models.free -->6<!-- /br:models.free --> free models, and they are not the same seven as last month. Tomorrow it could be 50. Prices will only drop. Capabilities will only improve. The names will keep churning.
+Today it's <!-- br:models.free -->7<!-- /br:models.free --> free models, and they are not the same seven as last month. Tomorrow it could be 50. Prices will only drop. Capabilities will only improve. The names will keep churning.
 
 **The one constant: your code doesn't need to change.**
 
@@ -257,7 +257,7 @@ clawrouter start
 
 Point your `base_url` to `http://localhost:8402/v1`. That's the whole setup.
 
-<!-- br:models.free -->6<!-- /br:models.free --> free models. Up to 1M context. Unlimited calls. Zero cost.
+<!-- br:models.free -->7<!-- /br:models.free --> free models. Up to 1M context. Unlimited calls. Zero cost.
 
 Go build something.
 

package/docs/anthropic-cost-savings.md

@@ -50,7 +50,7 @@ This is where you're paying for real value:
 
 ## The Solution: ClawRouter
 
-[ClawRouter](https://github.com/BlockRunAI/ClawRouter) is an open-source local proxy that sits between your app and <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> AI models. It saves you money in three ways: **smart routing**, **token optimization**, and **response caching**.
+[ClawRouter](https://github.com/BlockRunAI/ClawRouter) is an open-source local proxy that sits between your app and <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> AI models. It saves you money in three ways: **smart routing**, **token optimization**, and **response caching**.
 
 ```
 ┌─────────────┐     ┌──────────────────────────────┐     ┌──────────────────┐

package/docs/anthropic-third-party-harness-changes.md

@@ -31,7 +31,7 @@ This is exactly the problem [ClawRouter](https://github.com/BlockRunAI/ClawRoute
 
 ## ClawRouter: Smart Routing for Agents
 
-ClawRouter is an open-source local proxy that sits between your agent and <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> LLM models across 9 providers. It analyzes every request across 15 dimensions and routes it to the cheapest model that can handle it — in under 1ms, entirely locally.
+ClawRouter is an open-source local proxy that sits between your agent and <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> LLM models across 9 providers. It analyzes every request across 15 dimensions and routes it to the cheapest model that can handle it — in under 1ms, entirely locally.
 
 ```
 Your Agent → ClawRouter (localhost:8402) → Best model for the job
@@ -74,12 +74,12 @@ Then point your agent at `http://localhost:8402/v1/` with any OpenAI-compatible
 
 - **No API keys to manage** — wallet-based cryptographic auth
 - **No subscriptions** — pay per request in USDC (Base or Solana)
-- **No vendor lock-in** — <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models, switch anytime
+- **No vendor lock-in** — <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, switch anytime
 - **You control your wallet** — non-custodial, funds never held by a third party
 - **Budget caps** — set a max spend per session, ClawRouter gracefully downgrades when budget runs low
 - **Token compression** — 7-layer pipeline reduces token costs by 7–40% before they hit any provider
 - **Response caching** — identical requests within 10 minutes cost $0
-- **<!-- br:models.free -->6<!-- /br:models.free --> free models** — for tasks that don't need a paid model at all
+- **<!-- br:models.free -->7<!-- /br:models.free --> free models** — for tasks that don't need a paid model at all
 
 ### Routing Profiles
 

package/docs/clawrouter-vs-openrouter-llm-routing-comparison.md

@@ -222,7 +222,7 @@ OpenRouter doesn't always pass through provider-specific features correctly. Ima
 
 **Direct provider routing.** ClawRouter routes through BlockRun's API directly to providers — not through a second aggregator. One hop, not two. Provider-specific features work because there's no middleman translating them.
 
-![Guaranteed Feature Parity & Direct Connectivity — Three-panel diagram: Vision (image_url auto-detected → vision-capable models only), Tool Calling (toolCalling flag → agentic models only), Catalog (curated <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models with automatic legacy-to-modern redirects). Direct provider routing means no dropped payloads.](./assets/clawrouter-feature-parity-direct-connectivity.png)
+![Guaranteed Feature Parity & Direct Connectivity — Three-panel diagram: Vision (image_url auto-detected → vision-capable models only), Tool Calling (toolCalling flag → agentic models only), Catalog (curated <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models with automatic legacy-to-modern redirects). Direct provider routing means no dropped payloads.](./assets/clawrouter-feature-parity-direct-connectivity.png)
 
 ---
 
@@ -240,7 +240,7 @@ When new models launch, OpenRouter's catalog lags. Users configure a model that
 
 ### How ClawRouter Solves This
 
-ClawRouter maintains a curated catalog of <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models across 9 providers (including <!-- br:models.free -->6<!-- /br:models.free --> free models), updated with each release. Delisted models have automatic redirect aliases:
+ClawRouter maintains a curated catalog of <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models across 9 providers (including <!-- br:models.free -->7<!-- /br:models.free --> free models), updated with each release. Delisted models have automatic redirect aliases:
 
 ```typescript
 // Delisted models redirect automatically
@@ -268,7 +268,7 @@ No silent drops. No stale catalog. Models are benchmarked for speed, quality, an
 | **Rate limits**     | Per-key, shared                  | Per-wallet, independent                                                                                  |
 | **Vision support**  | Images sometimes dropped         | Auto-detected, vision-only fallback                                                                      |
 | **Tool calling**    | Silent failures with some models | Flag-based filtering, guaranteed support                                                                 |
-| **Model catalog**   | Laggy, silent drops              | Curated <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models, redirect aliases         |
+| **Model catalog**   | Laggy, silent drops              | Curated <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, redirect aliases         |
 | **Budget control**  | Monthly invoice                  | Per-session cap (`maxCostPerRun`)                                                                        |
 | **Setup**           | Create account, paste key        | Agent generates wallet, auto-configured                                                                  |
 | **Average cost**    | $25/M tokens (Opus direct)       | auto-routed = **<!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% savings** |

package/docs/configuration.md

@@ -489,9 +489,15 @@ plugins:
       # graceful (default): when budget runs low, ClawRouter automatically downgrades
       #   to cheaper models (premium → auto → eco → free). Tasks keep running.
       #   Only returns an error if no model can serve the request at all.
+      #   Spend is the amount each signed payment authorized, counted when it is
+      #   signed — a payment whose response is lost still counts.
       #
       # strict: immediately returns 429 (X-ClawRouter-Cost-Cap-Exceeded: 1) once
       #   the session spend reaches the cap. Use when you need a hard budget ceiling.
+      #   Requests in flight hold their estimated cost, so concurrent calls cannot
+      #   all pass on the same spent total; every signed payment counts at once,
+      #   even one whose response is lost; and each payment (including retries and
+      #   fallbacks) is checked against the cap before it is signed.
       maxCostPerRunMode: graceful # or: strict
 
       # Note: image generation endpoints (/v1/images/generations) bypass maxCostPerRun.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blockrun/clawrouter",
-  "version": "0.12.282",
-  "description": "Smart LLM router — save 84% on inference costs. 82 models (6 free). Pay by credit card (API key) or USDC (x402 wallet).",
+  "version": "0.12.284",
+  "description": "Smart LLM router — save 84% on inference costs. 88 models (7 free). Pay by credit card (API key) or USDC (x402 wallet).",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/clawrouter/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawrouter
-description: Hosted-gateway LLM router — save 84% on inference costs. A local proxy that forwards each request to the blockrun.ai gateway, which routes to the cheapest capable model across 82 models from OpenAI, Anthropic, Google, DeepSeek, xAI, Z.AI, and more. 6 free open-weight models included. Also exposes realtime market data (global stocks, crypto, FX, commodities), Twitter/X intelligence, prediction-market data across Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow + UMA oracle resolution + wallet identity & clustering, phone-number intelligence (carrier + SIM-swap fraud detection) plus AI-powered outbound voice calls (Twilio + Bland.ai), AND the Surf unified crypto data API (84 endpoints — CEX/DEX, on-chain SQL over 80+ ClickHouse tables, 100M+ labeled wallets, prediction markets, social/CT mindshare, news, VC fund intel) as built-in agent tools. Not a local-inference tool — prompts are sent to the blockrun.ai gateway.
+description: Hosted-gateway LLM router — save 84% on inference costs. A local proxy that forwards each request to the blockrun.ai gateway, which routes to the cheapest capable model across 88 models from OpenAI, Anthropic, Google, DeepSeek, xAI, Z.AI, and more. 7 free open-weight models included. Also exposes realtime market data (global stocks, crypto, FX, commodities), Twitter/X intelligence, prediction-market data across Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow + UMA oracle resolution + wallet identity & clustering, phone-number intelligence (carrier + SIM-swap fraud detection) plus AI-powered outbound voice calls (Twilio + Bland.ai), AND the Surf unified crypto data API (84 endpoints — CEX/DEX, on-chain SQL over 80+ ClickHouse tables, 100M+ labeled wallets, prediction markets, social/CT mindshare, news, VC fund intel) as built-in agent tools. Not a local-inference tool — prompts are sent to the blockrun.ai gateway.
 triggers:
   - "clawrouter"
   - "claw router"
@@ -53,7 +53,7 @@ metadata:
 
 # ClawRouter
 
-Hosted-gateway LLM router that saves <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% on inference costs by forwarding each request to the blockrun.ai gateway, which picks the cheapest model capable of handling it across <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models from 9 providers (<!-- br:models.free -->6<!-- /br:models.free --> free open-weight models). All billing flows through one BlockRun credential — either a USDC wallet paying x402 per call, or a BlockRun API key drawing on card-funded account credit. Either way you do not hold provider API keys.
+Hosted-gateway LLM router that saves <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% on inference costs by forwarding each request to the blockrun.ai gateway, which picks the cheapest model capable of handling it across <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models from 9 providers (<!-- br:models.free -->7<!-- /br:models.free --> free open-weight models). All billing flows through one BlockRun credential — either a USDC wallet paying x402 per call, or a BlockRun API key drawing on card-funded account credit. Either way you do not hold provider API keys.
 
 **This is not a local-inference tool.** ClawRouter is a thin local proxy. Your prompts are sent over HTTPS to the blockrun.ai gateway for model execution. If your workload requires inference that never leaves your machine, use a local runtime like Ollama — ClawRouter is not the right tool for that use case.
 
@@ -147,7 +147,7 @@ it against a baseline nobody wrote down. See
 
 ## Available Models
 
-<!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models including: gpt-6-astra [GPT-6 flagship, 1M ctx], gpt-6-sol, gpt-6-luna [fast, $0.10/$0.50], gpt-5.6-terra [balanced, stable default], gpt-5.6-sol [flagship], gpt-5.6-luna [cost-efficient], gpt-5.6-sol/terra/luna-pro [pro reasoning tiers], gpt-5.5, gpt-5.5-pro [max compute], chat-latest [ChatGPT Instant], gpt-5.4, gpt-5.1, gpt-4o, o3, claude-fable-5.1, claude-fable-5, claude-opus-5.5 [newest Opus, $4/$20], claude-opus-5 [1M ctx], claude-opus-4.8, claude-opus-4.7, claude-opus-4.5, claude-sonnet-5.5, claude-sonnet-5, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-2.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.7, grok-4.6, grok-4.5, grok-4.3, grok-build-0.1, glm-5.3 [Z.AI flagship, 1M ctx], glm-5.3-flash [natively multimodal, 1M ctx — $0.15/$0.50], glm-5.2, minimax-m3, kimi-k3 [1M ctx flagship], kimi-k2.7, qwen3.7-max [Qwen flagship, 1M ctx], qwen3.7-plus, qwen3.7-flash, mimo [Xiaomi MiMo-V2.5 Pro, 1M ctx], and <!-- br:models.free -->6<!-- /br:models.free --> free open-weight models (nemotron-3.5-lightning [1M ctx, thinking mode — the free default], nemotron-3-ultra-550b [550B/55B MoE, 1M ctx — the largest free model], nemotron-3-nano-omni-30b-a3b-reasoning [256K ctx], llama-3.2-11b-vision [Meta Llama], north-mini-code [Cohere, coding, sub-second], laguna-xs-2.1 [Poolside, coding, ~161 tok/s]). The free tier is text-only — image turns route to a paid vision model, because the two free models the catalogs advertise as vision-capable fail a solid-colour probe on both chains and do so with an HTTP 200.
+<!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models including: gpt-6-astra [GPT-6 flagship, 1M ctx], gpt-6-sol, gpt-6-luna [fast, $0.10/$0.50], gpt-5.6-terra [balanced, stable default], gpt-5.6-sol [flagship], gpt-5.6-luna [cost-efficient], gpt-5.6-sol/terra/luna-pro [pro reasoning tiers], gpt-5.5, gpt-5.5-pro [max compute], chat-latest [ChatGPT Instant], gpt-5.4, gpt-5.1, gpt-4o, o3, claude-fable-5.1, claude-fable-5, claude-opus-5.5 [newest Opus, $4/$20], claude-opus-5 [1M ctx], claude-opus-4.8, claude-opus-4.7, claude-opus-4.5, claude-sonnet-5.5, claude-sonnet-5, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-2.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.7, grok-4.6, grok-4.5, grok-4.3, grok-build-0.1, glm-5.3 [Z.AI flagship, 1M ctx], glm-5.3-flash [natively multimodal, 1M ctx — $0.15/$0.50], glm-5.2, minimax-m3, kimi-k3 [1M ctx flagship], kimi-k2.7, qwen3.7-max [Qwen flagship, 1M ctx], qwen3.7-plus, qwen3.7-flash, mimo [Xiaomi MiMo-V2.5 Pro, 1M ctx], and <!-- br:models.free -->7<!-- /br:models.free --> free open-weight models (nemotron-3.5-lightning [1M ctx, thinking mode — the free default], nemotron-3-ultra-550b [550B/55B MoE, 1M ctx — the largest free model], nemotron-3-nano-omni-30b-a3b-reasoning [256K ctx], llama-3.2-11b-vision [Meta Llama], north-mini-code [Cohere, coding, sub-second], laguna-xs-2.1 [Poolside, coding, ~161 tok/s]). The free tier is text-only — image turns route to a paid vision model, because the two free models the catalogs advertise as vision-capable fail a solid-colour probe on both chains and do so with an HTTP 200.
 
 ## Built-in Agent Tools