@blockrun/clawrouter 0.12.267 → 0.12.269

package/dist/index.d.ts

@@ -543,6 +543,38 @@ declare class BalanceMonitor {
     /** Build BalanceInfo from raw balance */
     private buildInfo;
 }
+/**
+ * The balance monitor for API-key mode.
+ *
+ * There is no wallet to read. Credit lives in the customer's BlockRun account
+ * and the gateway is its own authority on it: a call that outruns the balance
+ * comes back as HTTP 402 `insufficient_quota`, with a message pointing at the
+ * top-up page. api.blockrun.ai publishes no key-authenticated balance endpoint,
+ * so ClawRouter cannot poll one, and inventing a number here would be worse
+ * than having none — the free-model fallback downgrades a request the moment
+ * the monitor reports empty, and a guessed zero would silently move a paying
+ * customer onto the free tier.
+ *
+ * So this reports "always sufficient" and lets the server refuse. That is not
+ * a bypass of the spend gate: the gate it satisfies is the local *wallet*
+ * check, which exists because an x402 payment that fails after the stream
+ * opens is unrecoverable. An API-key call is refused before a single token is
+ * generated, which is the stronger guarantee, and it is enforced server-side
+ * where the actual balance is.
+ */
+declare class ApiKeyBalanceMonitor {
+    /** Large enough that every `balance >= estimatedCost` comparison passes. */
+    private static readonly UNMETERED;
+    checkBalance(): Promise<BalanceInfo>;
+    checkSufficient(): Promise<SufficiencyResult>;
+    /** No local cache to adjust — the server keeps the books. */
+    deductEstimated(): void;
+    invalidate(): void;
+    refresh(): Promise<BalanceInfo>;
+    formatUSDC(amountMicros: bigint): string;
+    /** No wallet in this mode; callers render the account instead. */
+    getWalletAddress(): string;
+}
 
 /**
  * Solana USDC Balance Monitor
@@ -633,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);
 }
@@ -784,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;
@@ -818,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;
@@ -999,8 +1058,8 @@ declare function hashRequestContent(lastUserContent: string, toolCallNames?: str
  *   - Usage logging: log every request as JSON line to ~/.openclaw/blockrun/logs/
  */
 
-/** Union type for chain-agnostic balance monitoring */
-type AnyBalanceMonitor = BalanceMonitor | SolanaBalanceMonitor;
+/** Union type for chain- and auth-agnostic balance monitoring */
+type AnyBalanceMonitor = BalanceMonitor | SolanaBalanceMonitor | ApiKeyBalanceMonitor;
 
 /**
  * Get the proxy port from pre-loaded configuration.
@@ -1029,8 +1088,26 @@ type WalletConfig = string | {
     solanaPrivateKeyBytes?: Uint8Array;
 };
 type PaymentChain = "base" | "solana";
+/**
+ * How this proxy pays BlockRun.
+ * - "wallet"  — x402 micropayments signed per call from a local USDC wallet.
+ * - "api-key" — a `brk_…` bearer token drawing on account credit topped up by
+ *               card at https://user.blockrun.ai. No wallet, no chain, no gas.
+ */
+type AuthMode = "wallet" | "api-key";
 type ProxyOptions = {
-    wallet: WalletConfig;
+    /**
+     * Wallet material for x402 mode. Optional only when `apiKey` is set — one of
+     * the two must be present or the proxy has no way to pay for anything.
+     */
+    wallet?: WalletConfig;
+    /**
+     * BlockRun API key (`brk_…`). When present it wins over `wallet`: the proxy
+     * talks to api.blockrun.ai with a bearer token and signs no payments at all.
+     * Also readable from BLOCKRUN_API_KEY / ~/.blockrun/.api-key via
+     * resolveApiKey(); callers resolve it and pass it in.
+     */
+    apiKey?: string;
     apiBase?: string;
     /**
      * Payment chain: "base" or "solana". New installs persist "solana" at wallet
@@ -1132,19 +1209,16 @@ type ProxyOptions = {
 type ProxyHandle = {
     port: number;
     baseUrl: string;
+    /** The x402 signer's address, or "" in API-key mode (there is no wallet). */
     walletAddress: string;
     solanaAddress?: string;
+    /** Which credential this proxy is paying with. */
+    authMode: AuthMode;
+    /** Masked API key, for status display. Only set in API-key mode. */
+    apiKeyLabel?: string;
     balanceMonitor: AnyBalanceMonitor;
     close: () => Promise<void>;
 };
-/**
- * Start the local x402 proxy server.
- *
- * If a proxy is already running on the target port, reuses it instead of failing.
- * Port can be configured via BLOCKRUN_PROXY_PORT environment variable.
- *
- * Returns a handle with the assigned port, base URL, and a close function.
- */
 declare function startProxy(options: ProxyOptions): Promise<ProxyHandle>;
 
 /**
@@ -1767,4 +1841,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 };