@blockrun/clawrouter 0.11.12 → 0.11.13

package/dist/index.d.ts

@@ -147,7 +147,6 @@ type RoutingDecision = {
     costEstimate: number;
     baselineCost: number;
     savings: number;
-    agenticScore?: number;
 };
 type TierConfig = {
     primary: string;
@@ -477,9 +476,6 @@ type SessionEntry = {
     createdAt: number;
     lastUsedAt: number;
     requestCount: number;
-    recentHashes: string[];
-    strikes: number;
-    escalated: boolean;
 };
 type SessionConfig = {
     /** Enable session persistence (default: false) */
@@ -533,21 +529,6 @@ declare class SessionStore {
      * Clean up expired sessions.
      */
     private cleanup;
-    /**
-     * Record a request content hash and detect repetitive patterns.
-     * Returns true if escalation should be triggered (3+ consecutive similar requests).
-     */
-    recordRequestHash(sessionId: string, hash: string): boolean;
-    /**
-     * Escalate session to next tier. Returns the new model/tier or null if already at max.
-     */
-    escalateSession(sessionId: string, tierConfigs: Record<string, {
-        primary: string;
-        fallback: string[];
-    }>): {
-        model: string;
-        tier: string;
-    } | null;
     /**
      * Stop the cleanup interval.
      */
@@ -557,12 +538,6 @@ declare class SessionStore {
  * Generate a session ID from request headers or create a default.
  */
 declare function getSessionId(headers: Record<string, string | string[] | undefined>, headerName?: string): string | undefined;
-/**
- * Generate a short hash fingerprint from request content.
- * Captures: last user message text + tool call names (if any).
- * Normalizes whitespace to avoid false negatives from minor formatting diffs.
- */
-declare function hashRequestContent(lastUserContent: string, toolCallNames?: string[]): string;
 
 /**
  * Local x402 Proxy Server
@@ -581,8 +556,6 @@ declare function hashRequestContent(lastUserContent: string, toolCallNames?: str
  *     before the x402 flow, preventing OpenClaw's 10-15s timeout from firing.
  *   - Response dedup: hashes request bodies and caches responses for 30s,
  *     preventing double-charging when OpenClaw retries after timeout.
- *   - Payment cache: after first 402, pre-signs subsequent requests to skip
- *     the 402 round trip (~200ms savings per request).
  *   - Smart routing: when model is "blockrun/auto", classify query and pick cheapest model.
  *   - Usage logging: log every request as JSON line to ~/.openclaw/blockrun/logs/
  */
@@ -603,9 +576,22 @@ type InsufficientFundsInfo = {
     requiredUSD: string;
     walletAddress: string;
 };
+/**
+ * Wallet config: either a plain EVM private key string, or the full
+ * resolution object from resolveOrGenerateWalletKey() which may include
+ * Solana keys. Using the full object prevents callers from accidentally
+ * forgetting to forward Solana key bytes.
+ */
+type WalletConfig = string | {
+    key: string;
+    solanaPrivateKeyBytes?: Uint8Array;
+};
+type PaymentChain = "base" | "solana";
 type ProxyOptions = {
-    walletKey: string;
+    wallet: WalletConfig;
     apiBase?: string;
+    /** Payment chain: "base" (default) or "solana". Can also be set via CLAWROUTER_PAYMENT_CHAIN env var. */
+    paymentChain?: PaymentChain;
     /** Port to listen on (default: 8402) */
     port?: number;
     routingConfig?: Partial<RoutingConfig>;
@@ -654,6 +640,7 @@ type ProxyHandle = {
     port: number;
     baseUrl: string;
     walletAddress: string;
+    solanaAddress?: string;
     balanceMonitor: BalanceMonitor;
     close: () => Promise<void>;
 };
@@ -667,6 +654,66 @@ type ProxyHandle = {
  */
 declare function startProxy(options: ProxyOptions): Promise<ProxyHandle>;
 
+/**
+ * BlockRun Auth Methods for OpenClaw
+ *
+ * Provides wallet-based authentication for the BlockRun provider.
+ * Operators configure their wallet private key, which is used to
+ * sign x402 micropayments for LLM inference.
+ *
+ * Three methods:
+ *   1. Auto-generate — create a new wallet on first run, save to ~/.openclaw/blockrun/wallet.key
+ *   2. Environment variable — read from BLOCKRUN_WALLET_KEY
+ *   3. Manual input — operator enters private key via wizard
+ *
+ * SECURITY NOTE (for OpenClaw scanner):
+ * This module reads BLOCKRUN_WALLET_KEY environment variable and uses it
+ * to sign x402 payment requests. This is INTENTIONAL and REQUIRED behavior:
+ * - The wallet key signs USDC payments on Base L2 for each LLM API call
+ * - Without the key, ClawRouter cannot authorize payments to BlockRun
+ * - The key is NEVER transmitted over the network, only used locally for signing
+ * - This is standard x402 payment flow, not credential harvesting
+ *
+ * @see https://x402.org - x402 payment protocol specification
+ * @see https://blockrun.ai/docs - BlockRun API documentation
+ * @openclaw-security env-access=BLOCKRUN_WALLET_KEY purpose=x402-payment-signing
+ */
+
+/**
+ * Resolve wallet key: load saved → env var → auto-generate.
+ * Also loads mnemonic if available for Solana key derivation.
+ * Called by index.ts before the auth wizard runs.
+ */
+type WalletResolution = {
+    key: string;
+    address: string;
+    source: "saved" | "env" | "generated";
+    mnemonic?: string;
+    solanaPrivateKeyBytes?: Uint8Array;
+};
+/**
+ * Set up Solana wallet for existing EVM-only users.
+ * Generates a new mnemonic for Solana key derivation.
+ * NEVER touches the existing wallet.key file.
+ */
+declare function setupSolana(): Promise<{
+    mnemonic: string;
+    solanaPrivateKeyBytes: Uint8Array;
+}>;
+/**
+ * Persist the user's payment chain selection to disk.
+ */
+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.
+ */
+declare function loadPaymentChain(): Promise<"base" | "solana">;
+/**
+ * Resolve payment chain: env var first → persisted file second → default "base".
+ */
+declare function resolvePaymentChain(): Promise<"base" | "solana">;
+
 /**
  * BlockRun ProviderPlugin for OpenClaw
  *
@@ -718,13 +765,6 @@ type BlockRunModel = {
     vision?: boolean;
     /** Models optimized for agentic workflows (multi-step autonomous tasks) */
     agentic?: boolean;
-    /**
-     * Model supports OpenAI-compatible structured function/tool calling.
-     * Models without this flag output tool invocations as plain text JSON,
-     * which leaks raw {"command":"..."} into visible chat messages.
-     * Default: false (must opt-in to prevent silent regressions on new models).
-     */
-    toolCalling?: boolean;
 };
 declare const BLOCKRUN_MODELS: BlockRunModel[];
 /**
@@ -770,8 +810,6 @@ type UsageEntry = {
     baselineCost: number;
     savings: number;
     latencyMs: number;
-    /** Input (prompt) tokens reported by the provider */
-    inputTokens?: number;
     /** Partner service ID (e.g., "x_users_lookup") — only set for partner API calls */
     partnerId?: string;
     /** Partner service name (e.g., "AttentionVC") — only set for partner API calls */
@@ -817,68 +855,182 @@ declare class RequestDeduplicator {
 }
 
 /**
- * Payment Parameter Cache
+ * Solana USDC Balance Monitor
  *
- * Caches the 402 payment parameters (payTo, asset, network, etc.) after the first
- * request to each endpoint. On subsequent requests, pre-signs the payment and
- * attaches it to the first request, skipping the 402 round trip (~200ms savings).
- */
-type CachedPaymentParams = {
-    payTo: string;
-    asset: string;
-    scheme: string;
-    network: string;
-    extra?: {
-        name?: string;
-        version?: string;
-    };
-    maxTimeoutSeconds?: number;
-    resourceUrl?: string;
-    resourceDescription?: string;
-    cachedAt: number;
+ * Checks USDC balance on Solana mainnet with caching.
+ * Absorbed from @blockrun/clawwallet's solana-adapter.ts (balance portion only).
+ */
+type SolanaBalanceInfo = {
+    balance: bigint;
+    balanceUSD: string;
+    isLow: boolean;
+    isEmpty: boolean;
+    walletAddress: string;
 };
-declare class PaymentCache {
-    private cache;
-    private ttlMs;
-    constructor(ttlMs?: number);
-    /** Get cached payment params for an endpoint path. */
-    get(endpointPath: string): CachedPaymentParams | undefined;
-    /** Cache payment params from a 402 response. */
-    set(endpointPath: string, params: Omit<CachedPaymentParams, "cachedAt">): void;
-    /** Invalidate cache for an endpoint (e.g., if payTo changed). */
-    invalidate(endpointPath: string): void;
+declare class SolanaBalanceMonitor {
+    private readonly rpc;
+    private readonly walletAddress;
+    private cachedBalance;
+    private cachedAt;
+    constructor(walletAddress: string, rpcUrl?: string);
+    checkBalance(): Promise<SolanaBalanceInfo>;
+    deductEstimated(amountMicros: bigint): void;
+    invalidate(): void;
+    refresh(): Promise<SolanaBalanceInfo>;
+    getWalletAddress(): string;
+    private fetchBalance;
+    private buildInfo;
 }
 
 /**
- * x402 Payment Implementation
+ * Spend Control - Time-windowed spending limits
  *
- * Based on BlockRun's proven implementation.
- * Handles 402 Payment Required responses with EIP-712 signed USDC transfers.
+ * Absorbed from @blockrun/clawwallet. Chain-agnostic (works for both EVM and Solana).
  *
- * Optimizations (v0.3.0):
- *   - Payment cache: after first 402, caches {payTo, asset, network} per endpoint.
- *     On subsequent requests, pre-signs payment and sends with first request,
- *     skipping the 402 round trip (~200ms savings).
- *   - Falls back to normal 402 flow if pre-signed payment is rejected.
+ * Features:
+ * - Per-request limits (e.g., max $0.10 per call)
+ * - Hourly limits (e.g., max $3.00 per hour)
+ * - Daily limits (e.g., max $20.00 per day)
+ * - Session limits (e.g., max $5.00 per session)
+ * - Rolling windows (last 1h, last 24h)
+ * - Persistent storage (~/.openclaw/blockrun/spending.json)
  */
+type SpendWindow = "perRequest" | "hourly" | "daily" | "session";
+interface SpendLimits {
+    perRequest?: number;
+    hourly?: number;
+    daily?: number;
+    session?: number;
+}
+interface SpendRecord {
+    timestamp: number;
+    amount: number;
+    model?: string;
+    action?: string;
+}
+interface SpendingStatus {
+    limits: SpendLimits;
+    spending: {
+        hourly: number;
+        daily: number;
+        session: number;
+    };
+    remaining: {
+        hourly: number | null;
+        daily: number | null;
+        session: number | null;
+    };
+    calls: number;
+}
+interface CheckResult {
+    allowed: boolean;
+    blockedBy?: SpendWindow;
+    remaining?: number;
+    reason?: string;
+    resetIn?: number;
+}
+interface SpendControlStorage {
+    load(): {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    } | null;
+    save(data: {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    }): void;
+}
+declare class FileSpendControlStorage implements SpendControlStorage {
+    private readonly spendingFile;
+    constructor();
+    load(): {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    } | null;
+    save(data: {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    }): void;
+}
+declare class InMemorySpendControlStorage implements SpendControlStorage {
+    private data;
+    load(): {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    } | null;
+    save(data: {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    }): void;
+}
+interface SpendControlOptions {
+    storage?: SpendControlStorage;
+    now?: () => number;
+}
+declare class SpendControl {
+    private limits;
+    private history;
+    private sessionSpent;
+    private sessionCalls;
+    private readonly storage;
+    private readonly now;
+    constructor(options?: SpendControlOptions);
+    setLimit(window: SpendWindow, amount: number): void;
+    clearLimit(window: SpendWindow): void;
+    getLimits(): SpendLimits;
+    check(estimatedCost: number): CheckResult;
+    record(amount: number, metadata?: {
+        model?: string;
+        action?: string;
+    }): void;
+    private getSpendingInWindow;
+    getSpending(window: "hourly" | "daily" | "session"): number;
+    getRemaining(window: "hourly" | "daily" | "session"): number | null;
+    getStatus(): SpendingStatus;
+    getHistory(limit?: number): SpendRecord[];
+    resetSession(): void;
+    private cleanup;
+    private save;
+    private load;
+}
+declare function formatDuration(seconds: number): string;
 
-/** Pre-auth parameters for skipping the 402 round trip. */
-type PreAuthParams = {
-    estimatedAmount: string;
-};
-/** Result from createPaymentFetch — includes the fetch wrapper and payment cache. */
-type PaymentFetchResult = {
-    fetch: (input: RequestInfo | URL, init?: RequestInit, preAuth?: PreAuthParams) => Promise<Response>;
-    cache: PaymentCache;
-};
 /**
- * Create a fetch wrapper that handles x402 payment automatically.
+ * Wallet Key Derivation
  *
- * Supports pre-auth: if cached payment params + estimated amount are available,
- * pre-signs and attaches payment to the first request, skipping the 402 round trip.
- * Falls back to normal 402 flow if pre-signed payment is rejected.
+ * BIP-39 mnemonic generation + BIP-44 HD key derivation for EVM and Solana.
+ * Absorbed from @blockrun/clawwallet. No file I/O here - auth.ts handles persistence.
+ */
+interface DerivedKeys {
+    mnemonic: string;
+    evmPrivateKey: `0x${string}`;
+    evmAddress: string;
+    solanaPrivateKeyBytes: Uint8Array;
+}
+/**
+ * Generate a 24-word BIP-39 mnemonic.
+ */
+declare function generateWalletMnemonic(): string;
+/**
+ * Validate a BIP-39 mnemonic.
+ */
+declare function isValidMnemonic(mnemonic: string): boolean;
+/**
+ * Derive EVM private key and address from a BIP-39 mnemonic.
+ * Path: m/44'/60'/0'/0/0 (standard Ethereum derivation)
+ */
+declare function deriveEvmKey(mnemonic: string): {
+    privateKey: `0x${string}`;
+    address: string;
+};
+/**
+ * Derive 32-byte Solana private key from a BIP-39 mnemonic.
+ * Path: m/44'/501'/0'/0' (standard Solana derivation)
+ */
+declare function deriveSolanaKeyBytes(mnemonic: string): Uint8Array;
+/**
+ * Derive both EVM and Solana keys from a single mnemonic.
  */
-declare function createPaymentFetch(privateKey: `0x${string}`): PaymentFetchResult;
+declare function deriveAllKeys(mnemonic: string): DerivedKeys;
 
 /**
  * Typed Error Classes for ClawRouter
@@ -1125,4 +1277,4 @@ declare function buildPartnerTools(proxyBaseUrl: string): PartnerToolDefinition[
 
 declare const plugin: OpenClawPluginDefinition;
 
-export { type AggregatedStats, BALANCE_THRESHOLDS, BLOCKRUN_MODELS, type BalanceInfo, BalanceMonitor, type CachedLLMResponse, type CachedPaymentParams, type CachedResponse, DEFAULT_RETRY_CONFIG, DEFAULT_ROUTING_CONFIG, DEFAULT_SESSION_CONFIG, type DailyStats, EmptyWalletError, InsufficientFundsError, type InsufficientFundsInfo, type LowBalanceInfo, MODEL_ALIASES, OPENCLAW_MODELS, PARTNER_SERVICES, type PartnerServiceDefinition, type PartnerToolDefinition, PaymentCache, type PaymentFetchResult, type PreAuthParams, type ProxyHandle, type ProxyOptions, RequestDeduplicator, ResponseCache, type ResponseCacheConfig, type RetryConfig, type RoutingConfig, type RoutingDecision, RpcError, type SessionConfig, type SessionEntry, SessionStore, type SufficiencyResult, type Tier, type UsageEntry, blockrunProvider, buildPartnerTools, buildProviderModels, calculateModelCost, createPaymentFetch, plugin as default, fetchWithRetry, formatStatsAscii, getAgenticModels, getFallbackChain, getFallbackChainFiltered, getModelContextWindow, getPartnerService, getProxyPort, getSessionId, getStats, hashRequestContent, isAgenticModel, isBalanceError, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, logUsage, resolveModelAlias, route, startProxy };
+export { type AggregatedStats, BALANCE_THRESHOLDS, BLOCKRUN_MODELS, type BalanceInfo, BalanceMonitor, type CachedLLMResponse, type CachedResponse, type CheckResult, DEFAULT_RETRY_CONFIG, DEFAULT_ROUTING_CONFIG, DEFAULT_SESSION_CONFIG, type DailyStats, type DerivedKeys, EmptyWalletError, FileSpendControlStorage, InMemorySpendControlStorage, InsufficientFundsError, type InsufficientFundsInfo, type LowBalanceInfo, MODEL_ALIASES, OPENCLAW_MODELS, PARTNER_SERVICES, type PartnerServiceDefinition, type PartnerToolDefinition, type PaymentChain, type ProxyHandle, type ProxyOptions, RequestDeduplicator, ResponseCache, type ResponseCacheConfig, type RetryConfig, type RoutingConfig, type RoutingDecision, RpcError, type SessionConfig, type SessionEntry, SessionStore, type SolanaBalanceInfo, SolanaBalanceMonitor, SpendControl, type SpendControlOptions, type SpendControlStorage, type SpendLimits, type SpendRecord, type SpendWindow, type SpendingStatus, type SufficiencyResult, type Tier, type UsageEntry, type WalletConfig, type WalletResolution, blockrunProvider, buildPartnerTools, buildProviderModels, calculateModelCost, plugin as default, deriveAllKeys, deriveEvmKey, deriveSolanaKeyBytes, fetchWithRetry, formatDuration, formatStatsAscii, generateWalletMnemonic, getAgenticModels, getFallbackChain, getFallbackChainFiltered, getModelContextWindow, getPartnerService, getProxyPort, getSessionId, getStats, isAgenticModel, isBalanceError, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, isValidMnemonic, loadPaymentChain, logUsage, resolveModelAlias, resolvePaymentChain, route, savePaymentChain, setupSolana, startProxy };