@blockrun/clawrouter 0.11.13 → 0.12.0

package/dist/index.d.ts

@@ -147,6 +147,7 @@ type RoutingDecision = {
     costEstimate: number;
     baselineCost: number;
     savings: number;
+    agenticScore?: number;
 };
 type TierConfig = {
     primary: string;
@@ -463,6 +464,48 @@ declare class BalanceMonitor {
     private buildInfo;
 }
 
+/**
+ * Solana USDC Balance Monitor
+ *
+ * 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;
+};
+/** Result from checkSufficient() */
+type SolanaSufficiencyResult = {
+    sufficient: boolean;
+    info: SolanaBalanceInfo;
+    shortfall?: string;
+};
+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>;
+    /**
+     * Check if balance is sufficient for an estimated cost.
+     */
+    checkSufficient(estimatedCostMicros: bigint): Promise<SolanaSufficiencyResult>;
+    /**
+     * Format USDC amount (in micros) as "$X.XX".
+     */
+    formatUSDC(amountMicros: bigint): string;
+    getWalletAddress(): string;
+    private fetchBalance;
+    private buildInfo;
+}
+
 /**
  * Session Persistence Store
  *
@@ -476,6 +519,9 @@ type SessionEntry = {
     createdAt: number;
     lastUsedAt: number;
     requestCount: number;
+    recentHashes: string[];
+    strikes: number;
+    escalated: boolean;
 };
 type SessionConfig = {
     /** Enable session persistence (default: false) */
@@ -529,6 +575,21 @@ 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.
      */
@@ -538,6 +599,12 @@ 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
@@ -560,6 +627,9 @@ declare function getSessionId(headers: Record<string, string | string[] | undefi
  *   - Usage logging: log every request as JSON line to ~/.openclaw/blockrun/logs/
  */
 
+/** Union type for chain-agnostic balance monitoring */
+type AnyBalanceMonitor = BalanceMonitor | SolanaBalanceMonitor;
+
 /**
  * Get the proxy port from pre-loaded configuration.
  * Port is validated at module load time, this just returns the cached value.
@@ -641,7 +711,7 @@ type ProxyHandle = {
     baseUrl: string;
     walletAddress: string;
     solanaAddress?: string;
-    balanceMonitor: BalanceMonitor;
+    balanceMonitor: AnyBalanceMonitor;
     close: () => Promise<void>;
 };
 /**
@@ -690,6 +760,8 @@ type WalletResolution = {
     source: "saved" | "env" | "generated";
     mnemonic?: string;
     solanaPrivateKeyBytes?: Uint8Array;
+    /** Legacy (secp256k1) Solana key bytes, present when migration is needed. */
+    legacySolanaKeyBytes?: Uint8Array;
 };
 /**
  * Set up Solana wallet for existing EVM-only users.
@@ -765,6 +837,13 @@ 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[];
 /**
@@ -810,6 +889,8 @@ 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 */
@@ -854,34 +935,6 @@ declare class RequestDeduplicator {
     private prune;
 }
 
-/**
- * Solana USDC Balance Monitor
- *
- * 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 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;
-}
-
 /**
  * Spend Control - Time-windowed spending limits
  *
@@ -999,6 +1052,9 @@ declare function formatDuration(seconds: number): string;
  *
  * 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.
+ *
+ * Solana uses SLIP-10 Ed25519 derivation (Phantom/Solflare/Backpack compatible).
+ * EVM uses standard BIP-32 secp256k1 derivation.
  */
 interface DerivedKeys {
     mnemonic: string;
@@ -1023,15 +1079,58 @@ declare function deriveEvmKey(mnemonic: string): {
     address: string;
 };
 /**
- * Derive 32-byte Solana private key from a BIP-39 mnemonic.
- * Path: m/44'/501'/0'/0' (standard Solana derivation)
+ * Derive 32-byte Solana private key using SLIP-10 Ed25519 derivation.
+ * Path: m/44'/501'/0'/0' (Phantom / Solflare / Backpack compatible)
+ *
+ * Algorithm (SLIP-0010 for Ed25519):
+ *   1. Master: HMAC-SHA512(key="ed25519 seed", data=bip39_seed) → IL=key, IR=chainCode
+ *   2. For each hardened child index:
+ *      HMAC-SHA512(key=chainCode, data=0x00 || key || ser32(index)) → split again
+ *   3. Final IL (32 bytes) = Ed25519 private key seed
  */
 declare function deriveSolanaKeyBytes(mnemonic: string): Uint8Array;
+/**
+ * Legacy Solana key derivation using secp256k1 BIP-32 (incorrect for Solana).
+ * Kept for migration: sweeping funds from wallets derived with the old method.
+ */
+declare function deriveSolanaKeyBytesLegacy(mnemonic: string): Uint8Array;
 /**
  * Derive both EVM and Solana keys from a single mnemonic.
  */
 declare function deriveAllKeys(mnemonic: string): DerivedKeys;
 
+/**
+ * Solana Wallet Sweep — migrate USDC from legacy (secp256k1) to new (SLIP-10) wallet.
+ *
+ * Used when upgrading from the old BIP-32 secp256k1 derivation to correct
+ * SLIP-10 Ed25519 derivation. Transfers all USDC from the old address to the new one.
+ *
+ * Uses raw instruction encoding to avoid @solana-program/token dependency.
+ */
+type SweepResult = {
+    transferred: string;
+    transferredMicros: bigint;
+    txSignature: string;
+    oldAddress: string;
+    newAddress: string;
+};
+type SweepError = {
+    error: string;
+    oldAddress: string;
+    newAddress?: string;
+    solBalance?: bigint;
+    usdcBalance?: bigint;
+};
+/**
+ * Sweep all USDC from old (legacy secp256k1) wallet to new (SLIP-10) wallet.
+ *
+ * @param oldKeyBytes - 32-byte private key from legacy derivation
+ * @param newAddress - Solana address of the new (correct) wallet
+ * @param rpcUrl - Optional RPC URL override
+ * @returns SweepResult on success, SweepError on failure
+ */
+declare function sweepSolanaWallet(oldKeyBytes: Uint8Array, newAddress: string, rpcUrl?: string): Promise<SweepResult | SweepError>;
+
 /**
  * Typed Error Classes for ClawRouter
  *
@@ -1277,4 +1376,4 @@ declare function buildPartnerTools(proxyBaseUrl: string): PartnerToolDefinition[
 
 declare const plugin: OpenClawPluginDefinition;
 
-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 };
+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 SweepError, type SweepResult, type Tier, type UsageEntry, type WalletConfig, type WalletResolution, blockrunProvider, buildPartnerTools, buildProviderModels, calculateModelCost, plugin as default, deriveAllKeys, deriveEvmKey, deriveSolanaKeyBytes, deriveSolanaKeyBytesLegacy, fetchWithRetry, formatDuration, formatStatsAscii, generateWalletMnemonic, getAgenticModels, getFallbackChain, getFallbackChainFiltered, getModelContextWindow, getPartnerService, getProxyPort, getSessionId, getStats, hashRequestContent, isAgenticModel, isBalanceError, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, isValidMnemonic, loadPaymentChain, logUsage, resolveModelAlias, resolvePaymentChain, route, savePaymentChain, setupSolana, startProxy, sweepSolanaWallet };