@blockrun/clawrouter 0.12.268 → 0.12.270

package/dist/cli.js

@@ -32310,6 +32310,11 @@ function canonicalLimits(limits) {
     Object.fromEntries(Object.entries(limits).sort(([a], [b]) => a < b ? -1 : 1))
   );
 }
+function getSharedSpendControl() {
+  const host = sharedControlHost();
+  host.__clawrouterSharedSpendControl ??= new SpendControl();
+  return host.__clawrouterSharedSpendControl;
+}
 function parseQuotedAmountUsd(selected) {
   const raw = selected.amount ?? selected.maxAmountRequired;
   if (typeof raw !== "string" || !CANONICAL_AMOUNT.test(raw)) {
@@ -32385,7 +32390,7 @@ function formatDuration(seconds) {
     return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`;
   }
 }
-var WALLET_DIR, HOUR_MS, DAY_MS, CAIP2_BASE, CAIP2_SOLANA_MAINNET, PAYABLE_NETWORKS, POLICY_LISTS, ADDRESS_LISTS, EVM_ADDRESS, MalformedSpendPolicyError, SpendPolicyConflictError, FileSpendControlStorage, InMemorySpendControlStorage, RESERVATION_TTL_MS, SpendControl, SpendPolicyError, CANONICAL_AMOUNT;
+var WALLET_DIR, HOUR_MS, DAY_MS, CAIP2_BASE, CAIP2_SOLANA_MAINNET, PAYABLE_NETWORKS, POLICY_LISTS, ADDRESS_LISTS, EVM_ADDRESS, UnreadableSpendPolicyError, MalformedSpendPolicyError, SpendPolicyConflictError, FileSpendControlStorage, InMemorySpendControlStorage, RESERVATION_TTL_MS, SpendControl, sharedControlHost, SpendPolicyError, CANONICAL_AMOUNT;
 var init_spend_control = __esm({
   "src/spend-control.ts"() {
     "use strict";
@@ -32404,6 +32409,12 @@ var init_spend_control = __esm({
     ];
     ADDRESS_LISTS = ["allowedPayees", "blockedPayees", "allowedAssets"];
     EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+    UnreadableSpendPolicyError = class extends Error {
+      constructor(cause) {
+        super(`[ClawRouter] Failed to load spending data: ${cause}`);
+        this.name = "UnreadableSpendPolicyError";
+      }
+    };
     MalformedSpendPolicyError = class extends Error {
       constructor(key2) {
         super(
@@ -32464,9 +32475,7 @@ var init_spend_control = __esm({
           if (err instanceof MalformedSpendPolicyError) {
             throw err;
           }
-          console.error(
-            `[ClawRouter] Failed to load spending data, starting fresh (any configured spend policy is NOT in effect until this file is repaired): ${err}`
-          );
+          throw new UnreadableSpendPolicyError(err);
         }
         return null;
       }
@@ -32607,6 +32616,33 @@ var init_spend_control = __esm({
       getPolicyFileError() {
         return this.policyFileBroken;
       }
+      /**
+       * Re-read limits from storage, keeping this instance's history and open
+       * reservations. Used on an in-process proxy restart so a hand-edit to
+       * spending.json made while the process was running still applies, without
+       * resetting the rolling windows. Fails closed exactly like the constructor:
+       * a malformed file refuses every payment until repaired, and a repaired
+       * file clears that refusal.
+       */
+      reloadLimits() {
+        let data;
+        try {
+          data = this.storage.load();
+        } catch (err) {
+          if (err instanceof UnreadableSpendPolicyError) {
+            console.error(`${err.message} \u2014 keeping the limits already in effect`);
+            return;
+          }
+          if (!(err instanceof MalformedSpendPolicyError)) throw err;
+          this.policyFileBroken = err.message;
+          console.error(`[ClawRouter] ${err.message}`);
+          return;
+        }
+        this.policyFileBroken = void 0;
+        this.limits = data ? cloneLimits(data.limits) : {};
+        this.diskLimits = cloneLimits(this.limits);
+        this.limitsDirty = false;
+      }
       check(estimatedCost2, counterparty) {
         if (this.policyFileBroken !== void 0) {
           return {
@@ -32851,6 +32887,16 @@ var init_spend_control = __esm({
         const records = [...this.history].reverse();
         return limit ? records.slice(0, limit) : records;
       }
+      /**
+       * Reset the session window. `sessionSpent`/`sessionCalls` are instance state
+       * that is never persisted, so this used to happen implicitly: every
+       * startProxy() built a fresh SpendControl. The process-wide ledger outlives
+       * an in-process proxy restart, which would silently redefine `session` as
+       * "since the gateway booted" — docs/configuration.md and the /policy help
+       * both promise "session resets on restart". The restart path in index.ts
+       * calls this to keep that promise. History and the rolling hourly/daily
+       * windows are deliberately untouched.
+       */
       resetSession() {
         this.sessionSpent = 0;
         this.sessionCalls = 0;
@@ -32872,10 +32918,13 @@ var init_spend_control = __esm({
             this.storage.saveLimits(cloneLimits(this.limits), cloneLimits(this.diskLimits));
           } catch (err) {
             if (err instanceof SpendPolicyConflictError) {
-              const current = this.storage.load();
-              this.limits = cloneLimits(current?.limits ?? {});
-              this.diskLimits = cloneLimits(this.limits);
-              this.limitsDirty = false;
+              try {
+                const current = this.storage.load();
+                this.limits = cloneLimits(current?.limits ?? {});
+                this.diskLimits = cloneLimits(this.limits);
+                this.limitsDirty = false;
+              } catch {
+              }
             }
             throw err;
           }
@@ -32893,6 +32942,12 @@ var init_spend_control = __esm({
         try {
           data = this.storage.load();
         } catch (err) {
+          if (err instanceof UnreadableSpendPolicyError) {
+            console.error(
+              `${err.message} \u2014 starting fresh (any configured spend policy is NOT in effect until this file is repaired)`
+            );
+            return;
+          }
           if (!(err instanceof MalformedSpendPolicyError)) throw err;
           this.policyFileBroken = err.message;
           console.error(`[ClawRouter] ${err.message}`);
@@ -32909,6 +32964,7 @@ var init_spend_control = __esm({
         }
       }
     };
+    sharedControlHost = () => process;
     SpendPolicyError = class extends Error {
       blockedBy;
       blockedByPolicy;
@@ -32946,6 +33002,21 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
       }
     }
     const cacheKey2 = `${urlPath}:${requestModel}`;
+    const notifyAcceptedPayment = (response2, payload2) => {
+      const settled = response2.headers.has("payment-response") || response2.headers.has("x-payment-response");
+      if (!settled || !options?.onPayment) return;
+      try {
+        options.onPayment({
+          model: requestModel,
+          amount: payload2.accepted.amount,
+          network: payload2.accepted.network
+        });
+      } catch (error) {
+        console.error(
+          `[ClawRouter] onPayment callback failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    };
     const estimateMicros = () => {
       if (!options?.estimateAmount || !requestModel) return void 0;
       const est = options.estimateAmount(requestModel, bodyLength, maxTokens);
@@ -32966,6 +33037,7 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
         paymentInFlight = true;
         const response2 = await baseFetch(preAuthRequest);
         if (response2.status !== 402) {
+          notifyAcceptedPayment(response2, payload2);
           return response2;
         }
         paymentInFlight = false;
@@ -33012,7 +33084,9 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
     for (const [key2, value] of Object.entries(paymentHeaders)) {
       clonedRequest.headers.set(key2, value);
     }
-    return baseFetch(clonedRequest);
+    const paidResponse = await baseFetch(clonedRequest);
+    notifyAcceptedPayment(paidResponse, payload);
+    return paidResponse;
   };
 }
 var DEFAULT_TTL_MS;
@@ -38467,8 +38541,8 @@ var init_models = __esm({
         id: "openai/gpt-5.6-sol",
         name: "GPT-5.6 Sol",
         version: "5.6",
-        inputPrice: 5,
-        outputPrice: 30,
+        inputPrice: 4,
+        outputPrice: 20,
         contextWindow: 105e4,
         maxOutput: 128e3,
         reasoning: true,
@@ -38509,8 +38583,8 @@ var init_models = __esm({
         id: "openai/gpt-5.6-sol-pro",
         name: "GPT-5.6 Sol Pro",
         version: "5.6",
-        inputPrice: 5,
-        outputPrice: 30,
+        inputPrice: 4,
+        outputPrice: 20,
         contextWindow: 105e4,
         maxOutput: 128e3,
         reasoning: true,
@@ -38948,8 +39022,8 @@ var init_models = __esm({
         id: "google/gemini-3.6-flash",
         name: "Gemini 3.6 Flash",
         version: "3.6",
-        inputPrice: 1.5,
-        outputPrice: 7.5,
+        inputPrice: 0.75,
+        outputPrice: 3.75,
         contextWindow: 1048576,
         maxOutput: 65536,
         reasoning: true,
@@ -39345,8 +39419,8 @@ var init_models = __esm({
         id: "xai/grok-4.5",
         name: "Grok 4.5",
         version: "4.5",
-        inputPrice: 2.5,
-        outputPrice: 9,
+        inputPrice: 2,
+        outputPrice: 6,
         contextWindow: 5e5,
         maxOutput: 16384,
         reasoning: true,
@@ -39360,8 +39434,8 @@ var init_models = __esm({
         id: "xai/grok-4.3",
         name: "Grok 4.3",
         version: "4.3",
-        inputPrice: 1.5,
-        outputPrice: 4,
+        inputPrice: 1.25,
+        outputPrice: 2.5,
         contextWindow: 1e6,
         maxOutput: 16384,
         reasoning: true,
@@ -39373,8 +39447,8 @@ var init_models = __esm({
         id: "xai/grok-build-0.1",
         name: "Grok Build 0.1",
         version: "0.1",
-        inputPrice: 1.5,
-        outputPrice: 3,
+        inputPrice: 1,
+        outputPrice: 2,
         contextWindow: 256e3,
         maxOutput: 16384,
         agentic: true,
@@ -59980,13 +60054,18 @@ async function loadPaymentChain() {
   const core = await readOptional(CORE_CHAIN_FILE);
   if (core === "solana") return "solana";
   if (core === "base") return "base";
-  try {
-    const content = (await readTextFile(CHAIN_FILE)).trim();
-    if (content === "solana") return "solana";
-    return "base";
-  } catch {
-    return "base";
-  }
+  const legacy = await readOptional(CHAIN_FILE);
+  if (legacy === "solana") return "solana";
+  if (legacy === "base") return "base";
+  return await hasExistingWallet() ? "base" : "solana";
+}
+async function hasExistingWallet() {
+  if (process["env"].BLOCKRUN_WALLET_KEY?.trim()) return true;
+  const [core, legacy] = await Promise.all([
+    readOptional(CORE_WALLET_FILE),
+    readOptional(WALLET_FILE)
+  ]);
+  return Boolean(core || legacy);
 }
 async function resolvePaymentChain() {
   if (process["env"].CLAWROUTER_PAYMENT_CHAIN === "solana") return "solana";
@@ -60120,7 +60199,7 @@ var init_api_key = __esm({
     HINTS = {
       401: `Check BLOCKRUN_API_KEY, or mint a new key at ${PORTAL_KEYS_URL}.`,
       402: `Top up your BlockRun credit at ${PORTAL_CREDITS_URL}.`,
-      404: `api.blockrun.ai does not serve this endpoint yet \u2014 it currently carries chat and text completions. For media and partner APIs, run ClawRouter in wallet mode (unset BLOCKRUN_API_KEY and run "clawrouter logout").`
+      404: `api.blockrun.ai does not serve this endpoint. Chat, Anthropic-shaped messages, images, speech, video and the partner APIs (Surf, Exa, prediction markets, phone lookup) all work on an API key. The wallet-only exceptions are the routes that bind a lease or a position to a payer address \u2014 buying/renewing/releasing phone numbers, and Polymarket trading \u2014 which need a wallet to own the thing being bought. For those, unset BLOCKRUN_API_KEY and run "clawrouter logout".`
     };
   }
 });
@@ -91588,7 +91667,7 @@ async function startProxy(options) {
   if (x402 && account) {
     const evmPublicClient = createPublicClient({ chain: base, transport: http() });
     const evmSigner = toClientEvmSigner(account, evmPublicClient);
-    const spendControl = options.spendControl ?? new SpendControl();
+    const spendControl = options.spendControl ?? getSharedSpendControl();
     registerSpendPolicyHook(x402, spendControl);
     registerExactEvmScheme(x402, { signer: evmSigner });
   }
@@ -91620,7 +91699,11 @@ async function startProxy(options) {
     // Per-request cost estimate so pre-auth is only reused when the cached
     // payment still covers the (possibly larger) request — BlockRun prices per
     // token, so one model can cost different amounts across requests.
-    estimateAmount
+    estimateAmount,
+    // 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
   });
   let balanceMonitor;
   if (options._balanceMonitorOverride) {
@@ -92500,7 +92583,8 @@ async function startProxy(options) {
         }
         return;
       }
-      if (req.url?.match(
+      const isVerbatimGatewayPath = req.url === "/v1/messages" || (req.url?.startsWith("/v1/messages?") ?? false) || req.url === "/v1/audio/speech" || (req.url?.startsWith("/v1/audio/speech?") ?? false);
+      if (isVerbatimGatewayPath || req.url?.match(
         /^\/v1\/(?:partner|pm|exa|modal|stocks|usstock|crypto|fx|commodity|phone|voice|surf)\//
       )) {
         try {
@@ -92532,6 +92616,19 @@ async function startProxy(options) {
         res.end(JSON.stringify({ error: "Not found" }));
         return;
       }
+      if (!req.url.includes("/chat/completions")) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: {
+              message: `ClawRouter does not proxy ${req.url}. It serves /v1/chat/completions, /v1/messages, /v1/models, /v1/images/generations, /v1/images/image2image, /v1/videos/generations, /v1/audio/generations, /v1/audio/speech, and the partner prefixes /v1/{partner,pm,exa,modal,stocks,usstock,crypto,fx,commodity,phone,voice,surf}/. If BlockRun serves this endpoint, call it directly against the gateway.`,
+              type: "invalid_request_error",
+              code: "unsupported_endpoint"
+            }
+          })
+        );
+        return;
+      }
       try {
         await proxyRequest(
           req,
@@ -117892,9 +117989,7 @@ var init_client5 = __esm({
 
 // src/polymarket/spend-policy.ts
 function resolveSpendControl(deps) {
-  if (deps?.spendControl) return deps.spendControl;
-  defaultControl ??= new SpendControl();
-  return defaultControl;
+  return deps?.spendControl ?? getSharedSpendControl();
 }
 function usdToMicros(usd) {
   return String(Math.ceil(usd * 1e6));
@@ -117911,7 +118006,6 @@ async function signUnderSpendPolicy(deps, quote, action, sign4) {
     throw err;
   }
 }
-var defaultControl;
 var init_spend_policy = __esm({
   "src/polymarket/spend-policy.ts"() {
     "use strict";
@@ -227276,7 +227370,7 @@ var init_fund = __esm({
 });
 
 // src/polymarket/tool.ts
-function buildPolymarketTool() {
+function buildPolymarketTool(deps) {
   return {
     name: "blockrun_polymarket",
     description: DESCRIPTION,
@@ -227361,26 +227455,32 @@ function buildPolymarketTool() {
           result = await runSetup({ confirm });
           break;
         case "fund":
-          result = await fundVault({
-            amount_usd: params.amount_usd,
-            confirm
-          });
+          result = await fundVault(
+            {
+              amount_usd: params.amount_usd,
+              confirm
+            },
+            deps
+          );
           break;
         case "buy":
         case "sell":
-          result = await executeTrade({
-            action,
-            token_id: params.token_id,
-            condition_id: params.condition_id,
-            outcome: params.outcome,
-            price: params.price,
-            size: params.size,
-            amount_usd: params.amount_usd,
-            order_type: params.order_type,
-            expires_at: params.expires_at,
-            post_only: params.post_only,
-            confirm
-          });
+          result = await executeTrade(
+            {
+              action,
+              token_id: params.token_id,
+              condition_id: params.condition_id,
+              outcome: params.outcome,
+              price: params.price,
+              size: params.size,
+              amount_usd: params.amount_usd,
+              order_type: params.order_type,
+              expires_at: params.expires_at,
+              post_only: params.post_only,
+              confirm
+            },
+            deps
+          );
           break;
         case "orders":
           result = await listOpenOrders({
@@ -227397,17 +227497,23 @@ function buildPolymarketTool() {
           result = await listPositions();
           break;
         case "redeem":
-          result = await redeemPosition({
-            condition_id: params.condition_id,
-            confirm
-          });
+          result = await redeemPosition(
+            {
+              condition_id: params.condition_id,
+              confirm
+            },
+            deps
+          );
           break;
         case "withdraw":
-          result = await withdrawFunds({
-            amount_usd: params.amount_usd,
-            to_address: params.to_address,
-            confirm
-          });
+          result = await withdrawFunds(
+            {
+              amount_usd: params.amount_usd,
+              to_address: params.to_address,
+              confirm
+            },
+            deps
+          );
           break;
         default:
           throw new Error(`Unknown blockrun_polymarket action: ${action}`);
@@ -227823,6 +227929,7 @@ __export(index_exports, {
   SolanaBalanceMonitor: () => SolanaBalanceMonitor,
   SpendControl: () => SpendControl,
   SpendPolicyError: () => SpendPolicyError,
+  UnreadableSpendPolicyError: () => UnreadableSpendPolicyError,
   VISIBLE_OPENCLAW_MODELS: () => VISIBLE_OPENCLAW_MODELS,
   blockrunProvider: () => blockrunProvider,
   buildImageGenerationProvider: () => buildImageGenerationProvider,
@@ -228403,12 +228510,18 @@ async function startProxyInBackground(api, startupGeneration) {
       `Cost cap: $${maxCostPerRunUsd.toFixed(2)} per session (mode: ${maxCostPerRunMode})`
     );
   }
+  const sharedControl = getSharedSpendControl();
+  sharedControl.reloadLimits();
+  sharedControl.resetSession();
   const proxy = await startProxy({
     ...apiKey ? { apiKey } : { wallet },
     routingConfig,
     maxCostPerRunUsd,
     maxCostPerRunMode,
-    spendControl: liveSpendControl = new SpendControl(),
+    // The process-wide ledger: the polymarket tool and the /policy command
+    // registered below use the same instance, so hourly/daily/session windows
+    // cover every surface and a /policy write reaches the live signer.
+    spendControl: sharedControl,
     onReady: (port) => {
       api.logger.info(`BlockRun ${apiKey ? "API-key" : "x402"} proxy listening on port ${port}`);
     },
@@ -229151,7 +229264,7 @@ function createWalletCommand(api) {
     }
   };
 }
-var activeProxyHandle, liveSpendControl, pendingConfiguredStartupApi, IMAGE_DIR2, AUDIO_DIR2, VIDEO_DIR2, plugin, index_default2;
+var activeProxyHandle, pendingConfiguredStartupApi, IMAGE_DIR2, AUDIO_DIR2, VIDEO_DIR2, plugin, index_default2;
 var init_index = __esm({
   "src/index.ts"() {
     "use strict";
@@ -229170,10 +229283,10 @@ var init_index = __esm({
     init_stats();
     init_partners();
     init_tool();
+    init_spend_control();
     init_stats2();
     init_exclude();
     init_policy();
-    init_spend_control();
     init_mcp_config();
     init_openclaw_plugin_config();
     init_openclaw_plugin_config();
@@ -229195,7 +229308,6 @@ var init_index = __esm({
     init_response_cache();
     init_partners();
     activeProxyHandle = null;
-    liveSpendControl = null;
     pendingConfiguredStartupApi = null;
     IMAGE_DIR2 = join17(homedir14(), ".openclaw", "blockrun", "images");
     AUDIO_DIR2 = join17(homedir14(), ".openclaw", "blockrun", "audio");
@@ -229511,7 +229623,7 @@ ${errText}`
         api.registerCommand(createExcludeCommand());
         api.registerCommand(
           createPolicyCommand({
-            liveControl: () => activeProxyHandle ? liveSpendControl ?? void 0 : void 0
+            liveControl: () => process.__clawrouterProxyStarted ? getSharedSpendControl() : void 0
           })
         );
         if (shouldLogRegistration) {
@@ -229540,7 +229652,15 @@ ${errText}`
         });
         if (!isGatewayMode()) {
           if (shouldLogRegistration) {
-            resolveOrGenerateWalletKey().then(({ address: address2, source }) => {
+            void (async () => {
+              const keyResolution = await resolveApiKey().catch(() => void 0);
+              if (keyResolution) {
+                api.logger.info(
+                  `Using BlockRun API key ${maskApiKey(keyResolution.key)} (from ${keyResolution.source}) \u2014 billing account credit, no wallet`
+                );
+                return;
+              }
+              const { address: address2, source } = await resolveOrGenerateWalletKey();
               if (source === "generated") {
                 api.logger.warn(`\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550`);
                 api.logger.warn(`  NEW WALLET GENERATED \u2014 BACK UP YOUR KEY NOW!`);
@@ -229557,7 +229677,7 @@ ${errText}`
               } else {
                 api.logger.info(`Using wallet from BLOCKRUN_WALLET_KEY: ${address2}`);
               }
-            }).catch((err) => {
+            })().catch((err) => {
               api.logger.warn(
                 `Failed to initialize wallet: ${err instanceof Error ? err.message : String(err)}`
               );
@@ -230089,7 +230209,7 @@ function createDoctorX402Client(opts) {
   const publicClient = createPublicClient({ chain: base, transport: http() });
   const evmSigner = toClientEvmSigner(account, publicClient);
   const x402 = new x402Client();
-  registerSpendPolicyHook(x402, opts.spendControl ?? new SpendControl());
+  registerSpendPolicyHook(x402, opts.spendControl ?? getSharedSpendControl());
   registerExactEvmScheme(x402, { signer: evmSigner });
   return x402;
 }

package/dist/index.d.ts

@@ -665,6 +665,14 @@ declare const PAYABLE_NETWORKS: readonly string[];
  * pay, which is the one direction this file must never fail in. Callers
  * classify on `instanceof`, not on the message text.
  */
+/**
+ * spending.json exists but could not be read or parsed. Distinct from "no file
+ * yet" (load() returns null) so a reload can tell a failed read from an empty
+ * store and refuse to widen what the agent may pay.
+ */
+declare class UnreadableSpendPolicyError extends Error {
+    constructor(cause: unknown);
+}
 declare class MalformedSpendPolicyError extends Error {
     constructor(key: string);
 }
@@ -816,6 +824,15 @@ declare class SpendControl {
      * reporting a change as applied.
      */
     getPolicyFileError(): string | undefined;
+    /**
+     * Re-read limits from storage, keeping this instance's history and open
+     * reservations. Used on an in-process proxy restart so a hand-edit to
+     * spending.json made while the process was running still applies, without
+     * resetting the rolling windows. Fails closed exactly like the constructor:
+     * a malformed file refuses every payment until repaired, and a repaired
+     * file clears that refusal.
+     */
+    reloadLimits(): void;
     check(estimatedCost: number, counterparty?: CounterpartyInfo): CheckResult;
     record(amount: number, metadata?: {
         model?: string;
@@ -850,6 +867,16 @@ declare class SpendControl {
     getRemaining(window: "hourly" | "daily" | "session"): number | null;
     getStatus(): SpendingStatus;
     getHistory(limit?: number): SpendRecord[];
+    /**
+     * Reset the session window. `sessionSpent`/`sessionCalls` are instance state
+     * that is never persisted, so this used to happen implicitly: every
+     * startProxy() built a fresh SpendControl. The process-wide ledger outlives
+     * an in-process proxy restart, which would silently redefine `session` as
+     * "since the gateway booted" — docs/configuration.md and the /policy help
+     * both promise "session resets on restart". The restart path in index.ts
+     * calls this to keep that promise. History and the rolling hourly/daily
+     * windows are deliberately untouched.
+     */
     resetSession(): void;
     private cleanup;
     private save;
@@ -1221,13 +1248,29 @@ declare function setupSolana(): Promise<{
 declare function savePaymentChain(chain: "base" | "solana"): Promise<void>;
 /**
  * Load the persisted payment chain selection from disk.
- * Returns "base" if no file exists or the file is invalid.
- * New installs persist "solana" at wallet generation, so an absent file
- * means a pre-existing install whose funds live on Base.
+ *
+ * Solana is the preferred rail, and since v0.12.246 wallet generation persists
+ * `solana` outright — so a fresh install answers "solana" from its own chain
+ * file, not from a default. This function only decides the case where no chain
+ * file exists at all, and there the answer turns on whether a wallet already
+ * does:
+ *
+ *   no chain file, no wallet   → "solana"  (nothing to strand; prefer Solana)
+ *   no chain file, wallet on disk → "base" (a pre-v0.12.246 install)
+ *
+ * That second line is the one that must not move. An install predating the
+ * Solana default has USDC sitting in its Base wallet and no Solana balance;
+ * flipping it would point every request at a gateway its money is not on and
+ * fail them all with an empty balance. The same reasoning covers a wallet
+ * supplied through BLOCKRUN_WALLET_KEY, and a generated wallet whose Solana
+ * derivation failed (no chain file is written in that case, on purpose — see
+ * resolveOrGenerateWalletKey — and the wallet it did write keeps us on Base,
+ * which is the only chain that proxy can actually sign for).
  */
 declare function loadPaymentChain(): Promise<"base" | "solana">;
 /**
- * Resolve payment chain: env var first → persisted file second → default "base".
+ * Resolve payment chain: env var first → persisted file second → the
+ * fresh-install preference (Solana) last. See loadPaymentChain.
  */
 declare function resolvePaymentChain(): Promise<"base" | "solana">;
 
@@ -1814,4 +1857,4 @@ declare function buildImageGenerationProvider(): ImageGenerationProviderPlugin;
 
 declare const plugin: OpenClawPluginDefinition;
 
-export { type AggregatedStats, BALANCE_THRESHOLDS, BLOCKRUN_MODELS, BLOCKRUN_PLUGIN_ID, type BalanceInfo, BalanceMonitor, CAIP2_BASE, CAIP2_SOLANA_MAINNET, type CachedLLMResponse, type CachedResponse, type CheckResult, type CounterpartyInfo, DEFAULT_RETRY_CONFIG, DEFAULT_SESSION_CONFIG, type DailyStats, type DerivedKeys, EmptyWalletError, FileSpendControlStorage, InMemorySpendControlStorage, InsufficientFundsError, type InsufficientFundsInfo, type LowBalanceInfo, MODEL_ALIASES, MalformedSpendPolicyError, OPENCLAW_MODELS, PARTNER_SERVICES, PAYABLE_NETWORKS, type PartnerServiceDefinition, type PartnerToolDefinition, type PaymentChain, type PolicyList, type ProxyHandle, type ProxyOptions, RequestDeduplicator, ResponseCache, type ResponseCacheConfig, type RetryConfig, RpcError, type SessionConfig, type SessionEntry, SessionStore, type SolanaBalanceInfo, SolanaBalanceMonitor, SpendControl, type SpendControlOptions, type SpendControlStorage, type SpendLimits, SpendPolicyError, type SpendRecord, type SpendWindow, type SpendingStatus, type SufficiencyResult, type UsageEntry, VISIBLE_OPENCLAW_MODELS, type WalletConfig, type WalletResolution, blockrunProvider, buildImageGenerationProvider, buildPartnerTools, buildProviderModels, clearStats, plugin as default, deriveAllKeys, deriveEvmKey, deriveSolanaKeyBytes, fetchWithRetry, formatDuration, formatStatsAscii, generateWalletMnemonic, getAgenticModels, getModelContextWindow, getPartnerService, getProxyPort, getSessionId, getStats, hashRequestContent, injectAuthProfile, injectModelsConfig, isAgenticModel, isBalanceError, isBlockrunWebSearchDisabled, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, isValidMnemonic, loadPaymentChain, logUsage, parseCallArgs, registerSpendPolicyHook, resolveModelAlias, resolvePaymentChain, savePaymentChain, setupSolana, startProxy, syncAgentModelCache };
+export { type AggregatedStats, BALANCE_THRESHOLDS, BLOCKRUN_MODELS, BLOCKRUN_PLUGIN_ID, type BalanceInfo, BalanceMonitor, CAIP2_BASE, CAIP2_SOLANA_MAINNET, type CachedLLMResponse, type CachedResponse, type CheckResult, type CounterpartyInfo, DEFAULT_RETRY_CONFIG, DEFAULT_SESSION_CONFIG, type DailyStats, type DerivedKeys, EmptyWalletError, FileSpendControlStorage, InMemorySpendControlStorage, InsufficientFundsError, type InsufficientFundsInfo, type LowBalanceInfo, MODEL_ALIASES, MalformedSpendPolicyError, OPENCLAW_MODELS, PARTNER_SERVICES, PAYABLE_NETWORKS, type PartnerServiceDefinition, type PartnerToolDefinition, type PaymentChain, type PolicyList, type ProxyHandle, type ProxyOptions, RequestDeduplicator, ResponseCache, type ResponseCacheConfig, type RetryConfig, RpcError, type SessionConfig, type SessionEntry, SessionStore, type SolanaBalanceInfo, SolanaBalanceMonitor, SpendControl, type SpendControlOptions, type SpendControlStorage, type SpendLimits, SpendPolicyError, type SpendRecord, type SpendWindow, type SpendingStatus, type SufficiencyResult, UnreadableSpendPolicyError, type UsageEntry, VISIBLE_OPENCLAW_MODELS, type WalletConfig, type WalletResolution, blockrunProvider, buildImageGenerationProvider, buildPartnerTools, buildProviderModels, clearStats, plugin as default, deriveAllKeys, deriveEvmKey, deriveSolanaKeyBytes, fetchWithRetry, formatDuration, formatStatsAscii, generateWalletMnemonic, getAgenticModels, getModelContextWindow, getPartnerService, getProxyPort, getSessionId, getStats, hashRequestContent, injectAuthProfile, injectModelsConfig, isAgenticModel, isBalanceError, isBlockrunWebSearchDisabled, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, isValidMnemonic, loadPaymentChain, logUsage, parseCallArgs, registerSpendPolicyHook, resolveModelAlias, resolvePaymentChain, savePaymentChain, setupSolana, startProxy, syncAgentModelCache };