@blockrun/llm 3.7.1 → 3.8.1

package/README.md

@@ -1330,10 +1330,30 @@ belonging to other applications on this system:
 ...
 ```
 
-Import it deliberately with `export BLOCKRUN_WALLET_KEY=<private-key>`, or by
-writing the key to `~/.blockrun/.session`. Addresses in that notice are derived
-from the discovered key itself, so a wallet file cannot claim an address it
-cannot sign for.
+Adopt one deliberately:
+
+```typescript
+import { listDiscoveredWallets, importWallet } from '@blockrun/llm';
+
+for (const w of listDiscoveredWallets()) {
+  console.log(w.address, 'from', w.source);
+}
+
+importWallet('0x88f9B82462f6C4bf4a0Fb15e5c3971559a316e7f');
+```
+
+`importWallet()` writes your current wallet to
+`~/.blockrun/.session.backup-<timestamp>` before switching, so adopting a wallet
+never strands funds in the old one. Solana: `listDiscoveredSolanaWallets()` and
+`importSolanaWallet()`.
+
+Addresses shown are derived from the discovered key itself, and `importWallet()`
+matches on that derived address — so a wallet file cannot claim an address it
+cannot sign for, nor be adopted by one. `listDiscoveredWallets()` never returns
+private keys.
+
+For a single run without changing anything, use
+`export BLOCKRUN_WALLET_KEY=<private-key>`.
 
 ## Response Caching
 

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   ImageClient: () => ImageClient,
   KNOWN_PROVIDERS: () => KNOWN_PROVIDERS,
   LLMClient: () => LLMClient,
+  MAX_TOKENS_SANITY_LIMIT: () => MAX_TOKENS_SANITY_LIMIT,
   MusicClient: () => MusicClient,
   NETWORK_ALIASES: () => NETWORK_ALIASES,
   OpenAI: () => OpenAI,
@@ -84,6 +85,10 @@ __export(index_exports, {
   getOrCreateWallet: () => getOrCreateWallet,
   getPaymentLinks: () => getPaymentLinks,
   getWalletAddress: () => getWalletAddress,
+  importSolanaWallet: () => importSolanaWallet,
+  importWallet: () => importWallet,
+  listDiscoveredSolanaWallets: () => listDiscoveredSolanaWallets,
+  listDiscoveredWallets: () => listDiscoveredWallets,
   loadSolanaWallet: () => loadSolanaWallet,
   loadWallet: () => loadWallet,
   logCost: () => logCost,
@@ -351,6 +356,7 @@ function validateModel(model) {
     throw new Error("Model must be a non-empty string");
   }
 }
+var MAX_TOKENS_SANITY_LIMIT = 1e6;
 function validateMaxTokens(maxTokens) {
   if (maxTokens === void 0 || maxTokens === null) {
     return;
@@ -361,8 +367,13 @@ function validateMaxTokens(maxTokens) {
   if (maxTokens < 1) {
     throw new Error("maxTokens must be positive (minimum: 1)");
   }
-  if (maxTokens > 1e5) {
-    throw new Error("maxTokens too large (maximum: 100000)");
+  if (maxTokens > MAX_TOKENS_SANITY_LIMIT) {
+    throw Object.assign(
+      new Error(
+        `maxTokens implausibly large (client-side sanity limit: ${MAX_TOKENS_SANITY_LIMIT}). This is not a model limit \u2014 the gateway enforces the real per-model ceiling and reports it.`
+      ),
+      { code: "MAX_TOKENS_SANITY_LIMIT", limit: MAX_TOKENS_SANITY_LIMIT }
+    );
   }
 }
 function validateTemperature(temperature) {
@@ -762,6 +773,7 @@ var LLMClient = class _LLMClient {
    * @returns ChatResponse object with choices and usage
    */
   async chatCompletion(model, messages, options) {
+    validateMaxTokens(options?.maxTokens);
     const buildBody = (m) => {
       const body = {
         model: m,
@@ -1032,6 +1044,7 @@ var LLMClient = class _LLMClient {
    * @returns Raw fetch Response with a streaming SSE body.
    */
   async chatCompletionStream(model, messages, options) {
+    validateMaxTokens(options?.maxTokens);
     const url = `${this.apiUrl}/v1/chat/completions`;
     const body = {
       model,
@@ -4631,7 +4644,7 @@ function scanWallets() {
         const addr = data.address || "";
         if (pk && addr) {
           const mtime = fs2.statSync(walletFile).mtimeMs;
-          results.push({ mtime, privateKey: pk, address: addr });
+          results.push({ mtime, privateKey: pk, address: addr, source: walletFile });
         }
       } catch {
         continue;
@@ -4640,7 +4653,46 @@ function scanWallets() {
   } catch {
   }
   results.sort((a, b) => b.mtime - a.mtime);
-  return results.map(({ privateKey, address }) => ({ privateKey, address }));
+  return results.map(({ privateKey, address, source }) => ({ privateKey, address, source }));
+}
+function listDiscoveredWallets() {
+  const listed = [];
+  for (const entry of scanWallets()) {
+    try {
+      listed.push({
+        address: (0, import_accounts15.privateKeyToAccount)(entry.privateKey).address,
+        source: entry.source
+      });
+    } catch {
+      continue;
+    }
+  }
+  return listed;
+}
+function importWallet(address) {
+  const wanted = address.trim().toLowerCase();
+  for (const entry of scanWallets()) {
+    let derived;
+    try {
+      derived = (0, import_accounts15.privateKeyToAccount)(entry.privateKey).address;
+    } catch {
+      continue;
+    }
+    if (derived.toLowerCase() !== wanted) continue;
+    if (fs2.existsSync(WALLET_FILE)) {
+      const current = fs2.readFileSync(WALLET_FILE, "utf-8").trim();
+      if (current && current !== entry.privateKey) {
+        const backup = path2.join(WALLET_DIR, `.session.backup-${Math.floor(Date.now() / 1e3)}`);
+        fs2.writeFileSync(backup, current, { mode: 384 });
+      }
+    }
+    saveWallet(entry.privateKey);
+    return derived;
+  }
+  const available = listDiscoveredWallets().map((w) => w.address);
+  throw new Error(
+    `No discovered wallet controls ${address}. Available: ${available.length ? available.join(", ") : "none"}`
+  );
 }
 function loadWallet() {
   if (fs2.existsSync(WALLET_FILE)) {
@@ -4685,11 +4737,13 @@ Discovered wallets are never adopted automatically \u2014 one may belong to a
 different application, or have been planted to make you fund an address you
 do not control.
 
-If an address above is yours and holds your USDC, import it deliberately:
+If an address above is yours and holds your USDC, adopt it deliberately:
 
-  export BLOCKRUN_WALLET_KEY=<private-key>
+  import { importWallet } from '@blockrun/llm';
+  importWallet("<address-from-the-list-above>");
 
-or write that key to ~/.blockrun/.session
+Your current wallet is backed up first. You can also set
+BLOCKRUN_WALLET_KEY=<private-key> for a single run without changing anything.
 `;
 }
 function getOrCreateWallet() {
@@ -4834,7 +4888,7 @@ function scanSolanaWallets() {
           const addr = data.address || "";
           if (pk && addr) {
             const mtime = fs3.statSync(solanaWalletFile).mtimeMs;
-            results.push({ mtime, secretKey: pk, publicKey: addr });
+            results.push({ mtime, secretKey: pk, publicKey: addr, source: solanaWalletFile });
           }
         } catch {
         }
@@ -4848,7 +4902,7 @@ function scanSolanaWallets() {
             const addr = data.address || "";
             if (pk && addr) {
               const mtime = fs3.statSync(brccWalletFile).mtimeMs;
-              results.push({ mtime, secretKey: pk, publicKey: addr });
+              results.push({ mtime, secretKey: pk, publicKey: addr, source: brccWalletFile });
             }
           } catch {
           }
@@ -4858,7 +4912,7 @@ function scanSolanaWallets() {
   } catch {
   }
   results.sort((a, b) => b.mtime - a.mtime);
-  return results.map(({ secretKey, publicKey }) => ({ secretKey, publicKey }));
+  return results.map(({ secretKey, publicKey, source }) => ({ secretKey, publicKey, source }));
 }
 function loadSolanaWallet() {
   if (fs3.existsSync(SOLANA_WALLET_FILE)) {
@@ -4867,6 +4921,45 @@ function loadSolanaWallet() {
   }
   return null;
 }
+async function listDiscoveredSolanaWallets() {
+  const listed = [];
+  for (const entry of scanSolanaWallets()) {
+    try {
+      listed.push({ address: await solanaPublicKey(entry.secretKey), source: entry.source });
+    } catch {
+      continue;
+    }
+  }
+  return listed;
+}
+async function importSolanaWallet(address) {
+  const wanted = address.trim();
+  for (const entry of scanSolanaWallets()) {
+    let derived;
+    try {
+      derived = await solanaPublicKey(entry.secretKey);
+    } catch {
+      continue;
+    }
+    if (derived !== wanted) continue;
+    if (fs3.existsSync(SOLANA_WALLET_FILE)) {
+      const current = fs3.readFileSync(SOLANA_WALLET_FILE, "utf-8").trim();
+      if (current && current !== entry.secretKey) {
+        const backup = path3.join(
+          WALLET_DIR2,
+          `.solana-session.backup-${Math.floor(Date.now() / 1e3)}`
+        );
+        fs3.writeFileSync(backup, current, { mode: 384 });
+      }
+    }
+    saveSolanaWallet(entry.secretKey);
+    return derived;
+  }
+  const available = (await listDiscoveredSolanaWallets()).map((w) => w.address);
+  throw new Error(
+    `No discovered wallet controls ${address}. Available: ${available.length ? available.join(", ") : "none"}`
+  );
+}
 async function formatSolanaWalletMigrationNotice(newAddress) {
   let discovered;
   try {
@@ -4898,11 +4991,13 @@ Discovered wallets are never adopted automatically \u2014 one may belong to a
 different application, or have been planted to make you fund an address you
 do not control.
 
-If an address above is yours and holds your USDC, import it deliberately:
+If an address above is yours and holds your USDC, adopt it deliberately:
 
-  export SOLANA_WALLET_KEY=<private-key>
+  import { importSolanaWallet } from '@blockrun/llm';
+  await importSolanaWallet("<address-from-the-list-above>");
 
-or write that key to ~/.blockrun/.solana-session
+Your current wallet is backed up first. You can also set
+SOLANA_WALLET_KEY=<private-key> for a single run without changing anything.
 `;
 }
 async function getOrCreateSolanaWallet() {
@@ -5001,6 +5096,7 @@ var SolanaLLMClient = class {
   }
   /** Full chat completion (OpenAI-compatible). */
   async chatCompletion(model, messages, options) {
+    validateMaxTokens(options?.maxTokens);
     const body = {
       model,
       messages,
@@ -6043,6 +6139,7 @@ var AnthropicClient = class {
   ImageClient,
   KNOWN_PROVIDERS,
   LLMClient,
+  MAX_TOKENS_SANITY_LIMIT,
   MusicClient,
   NETWORK_ALIASES,
   OpenAI,
@@ -6088,6 +6185,10 @@ var AnthropicClient = class {
   getOrCreateWallet,
   getPaymentLinks,
   getWalletAddress,
+  importSolanaWallet,
+  importWallet,
+  listDiscoveredSolanaWallets,
+  listDiscoveredWallets,
   loadSolanaWallet,
   loadWallet,
   logCost,

package/dist/index.d.cts

@@ -2539,7 +2539,39 @@ declare function saveWallet(privateKey: string): string;
 declare function scanWallets(): Array<{
     privateKey: string;
     address: string;
+    source: string;
 }>;
+/**
+ * List wallets from other applications, safe to show to a user.
+ *
+ * Unlike `scanWallets()`, no private key is returned and the address is derived
+ * from the key rather than read from the file, so a wallet file cannot claim an
+ * address it has no key for.
+ *
+ * Nothing here is active. Adopt one deliberately with `importWallet()`.
+ *
+ * @returns Discovered wallets as `{ address, source }`, most recent first
+ */
+declare function listDiscoveredWallets(): Array<{
+    address: string;
+    source: string;
+}>;
+/**
+ * Adopt a discovered wallet by address, making it the active BlockRun wallet.
+ *
+ * This is the deliberate migration path: automatic selection never adopts a
+ * discovered wallet, but you can choose one whose funds you want to spend.
+ * Matching is done against the address *derived from each discovered key*, so a
+ * wallet file claiming someone else's address can never be selected by it.
+ *
+ * The current `~/.blockrun/.session` is backed up beside itself before being
+ * overwritten, so adopting a wallet can't strand the funds in the old one.
+ *
+ * @param address Address to adopt, as shown by `listDiscoveredWallets()`
+ * @returns The adopted address
+ * @throws If no discovered wallet derives to that address
+ */
+declare function importWallet(address: string): string;
 /**
  * Load wallet private key from file.
  *
@@ -2850,8 +2882,34 @@ declare function saveSolanaWallet(privateKey: string): string;
 declare function scanSolanaWallets(): Array<{
     secretKey: string;
     publicKey: string;
+    source: string;
 }>;
 declare function loadSolanaWallet(): string | null;
+/**
+ * List Solana wallets from other applications, safe to show to a user.
+ *
+ * Solana counterpart of `listDiscoveredWallets()`: no secret key is returned
+ * and the address is derived from the key rather than trusted from the file.
+ * Nothing here is active — adopt one with `importSolanaWallet()`.
+ *
+ * @returns Discovered wallets as `{ address, source }`, most recent first
+ */
+declare function listDiscoveredSolanaWallets(): Promise<Array<{
+    address: string;
+    source: string;
+}>>;
+/**
+ * Adopt a discovered Solana wallet, making it the active BlockRun wallet.
+ *
+ * Solana counterpart of `importWallet()`. Matching is done against the address
+ * derived from each discovered key, and the current
+ * `~/.blockrun/.solana-session` is backed up before being overwritten.
+ *
+ * @param address Address to adopt, as shown by `listDiscoveredSolanaWallets()`
+ * @returns The adopted address
+ * @throws If no discovered wallet derives to that address
+ */
+declare function importSolanaWallet(address: string): Promise<string>;
 /**
  * Warn when a new Solana wallet was created while provider wallets exist.
  *
@@ -3103,7 +3161,34 @@ declare const KNOWN_PROVIDERS: Set<string>;
  */
 declare function validateModel(model: string): void;
 /**
- * Validates that max_tokens is an integer between 1 and 100,000.
+ * Client-side typo guard, NOT a model limit. The gateway already enforces the
+ * real per-model ceiling and rejects with that model's own number, so anything
+ * hardcoded here can only be wrong in one direction: too low.
+ *
+ * This was 100000. Note what it was and was not doing: until this change no
+ * client called `validateMaxTokens` at all, so the bound bound nothing on a
+ * real request — it only rejected callers who imported the validator directly
+ * off the package's public surface. The guard is now wired into
+ * `LLMClient.chatCompletion`, `LLMClient.chatCompletionStream`, and
+ * `SolanaLLMClient.chatCompletion`, which is exactly why the number had to go
+ * up first: at 100000 it would have started rejecting real requests.
+ *
+ * Verified against the live gateway 2026-07-21
+ * with the guard bypassed: zai/glm-5.2 accepted 262144, and the whole 128000
+ * class accepted 128000 (claude-opus-4.8, claude-sonnet-5, claude-fable-5,
+ * gpt-5.6-sol/terra/luna, gpt-5.5, gpt-5.4, gpt-5.3-codex, glm-5/5.1/5-turbo).
+ * 19 models advertised above 100000; all 19 accepted their ceiling. Those are
+ * as-of-date probe results, not a maintained invariant — nothing in this repo
+ * ships a model catalog, so CI cannot detect when they go stale.
+ *
+ * Keep a bound so an obvious mistake (1e9, a byte count, a timestamp) fails
+ * fast locally instead of becoming a payment quote. Set it far above any real
+ * model so it can never be the binding constraint again.
+ */
+declare const MAX_TOKENS_SANITY_LIMIT = 1000000;
+/**
+ * Validates that max_tokens is a positive integer no larger than
+ * {@link MAX_TOKENS_SANITY_LIMIT}.
  *
  * @param maxTokens - Maximum number of tokens to generate
  * @throws {Error} If maxTokens is invalid
@@ -3133,4 +3218,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, MAX_TOKENS_SANITY_LIMIT, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.d.ts

@@ -2539,7 +2539,39 @@ declare function saveWallet(privateKey: string): string;
 declare function scanWallets(): Array<{
     privateKey: string;
     address: string;
+    source: string;
 }>;
+/**
+ * List wallets from other applications, safe to show to a user.
+ *
+ * Unlike `scanWallets()`, no private key is returned and the address is derived
+ * from the key rather than read from the file, so a wallet file cannot claim an
+ * address it has no key for.
+ *
+ * Nothing here is active. Adopt one deliberately with `importWallet()`.
+ *
+ * @returns Discovered wallets as `{ address, source }`, most recent first
+ */
+declare function listDiscoveredWallets(): Array<{
+    address: string;
+    source: string;
+}>;
+/**
+ * Adopt a discovered wallet by address, making it the active BlockRun wallet.
+ *
+ * This is the deliberate migration path: automatic selection never adopts a
+ * discovered wallet, but you can choose one whose funds you want to spend.
+ * Matching is done against the address *derived from each discovered key*, so a
+ * wallet file claiming someone else's address can never be selected by it.
+ *
+ * The current `~/.blockrun/.session` is backed up beside itself before being
+ * overwritten, so adopting a wallet can't strand the funds in the old one.
+ *
+ * @param address Address to adopt, as shown by `listDiscoveredWallets()`
+ * @returns The adopted address
+ * @throws If no discovered wallet derives to that address
+ */
+declare function importWallet(address: string): string;
 /**
  * Load wallet private key from file.
  *
@@ -2850,8 +2882,34 @@ declare function saveSolanaWallet(privateKey: string): string;
 declare function scanSolanaWallets(): Array<{
     secretKey: string;
     publicKey: string;
+    source: string;
 }>;
 declare function loadSolanaWallet(): string | null;
+/**
+ * List Solana wallets from other applications, safe to show to a user.
+ *
+ * Solana counterpart of `listDiscoveredWallets()`: no secret key is returned
+ * and the address is derived from the key rather than trusted from the file.
+ * Nothing here is active — adopt one with `importSolanaWallet()`.
+ *
+ * @returns Discovered wallets as `{ address, source }`, most recent first
+ */
+declare function listDiscoveredSolanaWallets(): Promise<Array<{
+    address: string;
+    source: string;
+}>>;
+/**
+ * Adopt a discovered Solana wallet, making it the active BlockRun wallet.
+ *
+ * Solana counterpart of `importWallet()`. Matching is done against the address
+ * derived from each discovered key, and the current
+ * `~/.blockrun/.solana-session` is backed up before being overwritten.
+ *
+ * @param address Address to adopt, as shown by `listDiscoveredSolanaWallets()`
+ * @returns The adopted address
+ * @throws If no discovered wallet derives to that address
+ */
+declare function importSolanaWallet(address: string): Promise<string>;
 /**
  * Warn when a new Solana wallet was created while provider wallets exist.
  *
@@ -3103,7 +3161,34 @@ declare const KNOWN_PROVIDERS: Set<string>;
  */
 declare function validateModel(model: string): void;
 /**
- * Validates that max_tokens is an integer between 1 and 100,000.
+ * Client-side typo guard, NOT a model limit. The gateway already enforces the
+ * real per-model ceiling and rejects with that model's own number, so anything
+ * hardcoded here can only be wrong in one direction: too low.
+ *
+ * This was 100000. Note what it was and was not doing: until this change no
+ * client called `validateMaxTokens` at all, so the bound bound nothing on a
+ * real request — it only rejected callers who imported the validator directly
+ * off the package's public surface. The guard is now wired into
+ * `LLMClient.chatCompletion`, `LLMClient.chatCompletionStream`, and
+ * `SolanaLLMClient.chatCompletion`, which is exactly why the number had to go
+ * up first: at 100000 it would have started rejecting real requests.
+ *
+ * Verified against the live gateway 2026-07-21
+ * with the guard bypassed: zai/glm-5.2 accepted 262144, and the whole 128000
+ * class accepted 128000 (claude-opus-4.8, claude-sonnet-5, claude-fable-5,
+ * gpt-5.6-sol/terra/luna, gpt-5.5, gpt-5.4, gpt-5.3-codex, glm-5/5.1/5-turbo).
+ * 19 models advertised above 100000; all 19 accepted their ceiling. Those are
+ * as-of-date probe results, not a maintained invariant — nothing in this repo
+ * ships a model catalog, so CI cannot detect when they go stale.
+ *
+ * Keep a bound so an obvious mistake (1e9, a byte count, a timestamp) fails
+ * fast locally instead of becoming a payment quote. Set it far above any real
+ * model so it can never be the binding constraint again.
+ */
+declare const MAX_TOKENS_SANITY_LIMIT = 1000000;
+/**
+ * Validates that max_tokens is a positive integer no larger than
+ * {@link MAX_TOKENS_SANITY_LIMIT}.
  *
  * @param maxTokens - Maximum number of tokens to generate
  * @throws {Error} If maxTokens is invalid
@@ -3133,4 +3218,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, MAX_TOKENS_SANITY_LIMIT, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.js

@@ -242,6 +242,7 @@ function validateModel(model) {
     throw new Error("Model must be a non-empty string");
   }
 }
+var MAX_TOKENS_SANITY_LIMIT = 1e6;
 function validateMaxTokens(maxTokens) {
   if (maxTokens === void 0 || maxTokens === null) {
     return;
@@ -252,8 +253,13 @@ function validateMaxTokens(maxTokens) {
   if (maxTokens < 1) {
     throw new Error("maxTokens must be positive (minimum: 1)");
   }
-  if (maxTokens > 1e5) {
-    throw new Error("maxTokens too large (maximum: 100000)");
+  if (maxTokens > MAX_TOKENS_SANITY_LIMIT) {
+    throw Object.assign(
+      new Error(
+        `maxTokens implausibly large (client-side sanity limit: ${MAX_TOKENS_SANITY_LIMIT}). This is not a model limit \u2014 the gateway enforces the real per-model ceiling and reports it.`
+      ),
+      { code: "MAX_TOKENS_SANITY_LIMIT", limit: MAX_TOKENS_SANITY_LIMIT }
+    );
   }
 }
 function validateTemperature(temperature) {
@@ -653,6 +659,7 @@ var LLMClient = class _LLMClient {
    * @returns ChatResponse object with choices and usage
    */
   async chatCompletion(model, messages, options) {
+    validateMaxTokens(options?.maxTokens);
     const buildBody = (m) => {
       const body = {
         model: m,
@@ -923,6 +930,7 @@ var LLMClient = class _LLMClient {
    * @returns Raw fetch Response with a streaming SSE body.
    */
   async chatCompletionStream(model, messages, options) {
+    validateMaxTokens(options?.maxTokens);
     const url = `${this.apiUrl}/v1/chat/completions`;
     const body = {
       model,
@@ -4522,7 +4530,7 @@ function scanWallets() {
         const addr = data.address || "";
         if (pk && addr) {
           const mtime = fs2.statSync(walletFile).mtimeMs;
-          results.push({ mtime, privateKey: pk, address: addr });
+          results.push({ mtime, privateKey: pk, address: addr, source: walletFile });
         }
       } catch {
         continue;
@@ -4531,7 +4539,46 @@ function scanWallets() {
   } catch {
   }
   results.sort((a, b) => b.mtime - a.mtime);
-  return results.map(({ privateKey, address }) => ({ privateKey, address }));
+  return results.map(({ privateKey, address, source }) => ({ privateKey, address, source }));
+}
+function listDiscoveredWallets() {
+  const listed = [];
+  for (const entry of scanWallets()) {
+    try {
+      listed.push({
+        address: privateKeyToAccount14(entry.privateKey).address,
+        source: entry.source
+      });
+    } catch {
+      continue;
+    }
+  }
+  return listed;
+}
+function importWallet(address) {
+  const wanted = address.trim().toLowerCase();
+  for (const entry of scanWallets()) {
+    let derived;
+    try {
+      derived = privateKeyToAccount14(entry.privateKey).address;
+    } catch {
+      continue;
+    }
+    if (derived.toLowerCase() !== wanted) continue;
+    if (fs2.existsSync(WALLET_FILE)) {
+      const current = fs2.readFileSync(WALLET_FILE, "utf-8").trim();
+      if (current && current !== entry.privateKey) {
+        const backup = path2.join(WALLET_DIR, `.session.backup-${Math.floor(Date.now() / 1e3)}`);
+        fs2.writeFileSync(backup, current, { mode: 384 });
+      }
+    }
+    saveWallet(entry.privateKey);
+    return derived;
+  }
+  const available = listDiscoveredWallets().map((w) => w.address);
+  throw new Error(
+    `No discovered wallet controls ${address}. Available: ${available.length ? available.join(", ") : "none"}`
+  );
 }
 function loadWallet() {
   if (fs2.existsSync(WALLET_FILE)) {
@@ -4576,11 +4623,13 @@ Discovered wallets are never adopted automatically \u2014 one may belong to a
 different application, or have been planted to make you fund an address you
 do not control.
 
-If an address above is yours and holds your USDC, import it deliberately:
+If an address above is yours and holds your USDC, adopt it deliberately:
 
-  export BLOCKRUN_WALLET_KEY=<private-key>
+  import { importWallet } from '@blockrun/llm';
+  importWallet("<address-from-the-list-above>");
 
-or write that key to ~/.blockrun/.session
+Your current wallet is backed up first. You can also set
+BLOCKRUN_WALLET_KEY=<private-key> for a single run without changing anything.
 `;
 }
 function getOrCreateWallet() {
@@ -4725,7 +4774,7 @@ function scanSolanaWallets() {
           const addr = data.address || "";
           if (pk && addr) {
             const mtime = fs3.statSync(solanaWalletFile).mtimeMs;
-            results.push({ mtime, secretKey: pk, publicKey: addr });
+            results.push({ mtime, secretKey: pk, publicKey: addr, source: solanaWalletFile });
           }
         } catch {
         }
@@ -4739,7 +4788,7 @@ function scanSolanaWallets() {
             const addr = data.address || "";
             if (pk && addr) {
               const mtime = fs3.statSync(brccWalletFile).mtimeMs;
-              results.push({ mtime, secretKey: pk, publicKey: addr });
+              results.push({ mtime, secretKey: pk, publicKey: addr, source: brccWalletFile });
             }
           } catch {
           }
@@ -4749,7 +4798,7 @@ function scanSolanaWallets() {
   } catch {
   }
   results.sort((a, b) => b.mtime - a.mtime);
-  return results.map(({ secretKey, publicKey }) => ({ secretKey, publicKey }));
+  return results.map(({ secretKey, publicKey, source }) => ({ secretKey, publicKey, source }));
 }
 function loadSolanaWallet() {
   if (fs3.existsSync(SOLANA_WALLET_FILE)) {
@@ -4758,6 +4807,45 @@ function loadSolanaWallet() {
   }
   return null;
 }
+async function listDiscoveredSolanaWallets() {
+  const listed = [];
+  for (const entry of scanSolanaWallets()) {
+    try {
+      listed.push({ address: await solanaPublicKey(entry.secretKey), source: entry.source });
+    } catch {
+      continue;
+    }
+  }
+  return listed;
+}
+async function importSolanaWallet(address) {
+  const wanted = address.trim();
+  for (const entry of scanSolanaWallets()) {
+    let derived;
+    try {
+      derived = await solanaPublicKey(entry.secretKey);
+    } catch {
+      continue;
+    }
+    if (derived !== wanted) continue;
+    if (fs3.existsSync(SOLANA_WALLET_FILE)) {
+      const current = fs3.readFileSync(SOLANA_WALLET_FILE, "utf-8").trim();
+      if (current && current !== entry.secretKey) {
+        const backup = path3.join(
+          WALLET_DIR2,
+          `.solana-session.backup-${Math.floor(Date.now() / 1e3)}`
+        );
+        fs3.writeFileSync(backup, current, { mode: 384 });
+      }
+    }
+    saveSolanaWallet(entry.secretKey);
+    return derived;
+  }
+  const available = (await listDiscoveredSolanaWallets()).map((w) => w.address);
+  throw new Error(
+    `No discovered wallet controls ${address}. Available: ${available.length ? available.join(", ") : "none"}`
+  );
+}
 async function formatSolanaWalletMigrationNotice(newAddress) {
   let discovered;
   try {
@@ -4789,11 +4877,13 @@ Discovered wallets are never adopted automatically \u2014 one may belong to a
 different application, or have been planted to make you fund an address you
 do not control.
 
-If an address above is yours and holds your USDC, import it deliberately:
+If an address above is yours and holds your USDC, adopt it deliberately:
 
-  export SOLANA_WALLET_KEY=<private-key>
+  import { importSolanaWallet } from '@blockrun/llm';
+  await importSolanaWallet("<address-from-the-list-above>");
 
-or write that key to ~/.blockrun/.solana-session
+Your current wallet is backed up first. You can also set
+SOLANA_WALLET_KEY=<private-key> for a single run without changing anything.
 `;
 }
 async function getOrCreateSolanaWallet() {
@@ -4892,6 +4982,7 @@ var SolanaLLMClient = class {
   }
   /** Full chat completion (OpenAI-compatible). */
   async chatCompletion(model, messages, options) {
+    validateMaxTokens(options?.maxTokens);
     const body = {
       model,
       messages,
@@ -5933,6 +6024,7 @@ export {
   ImageClient,
   KNOWN_PROVIDERS,
   LLMClient,
+  MAX_TOKENS_SANITY_LIMIT,
   MusicClient,
   NETWORK_ALIASES,
   OpenAI,
@@ -5979,6 +6071,10 @@ export {
   getOrCreateWallet,
   getPaymentLinks,
   getWalletAddress,
+  importSolanaWallet,
+  importWallet,
+  listDiscoveredSolanaWallets,
+  listDiscoveredWallets,
   loadSolanaWallet,
   loadWallet,
   logCost,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.7.1",
+  "version": "3.8.1",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music, Voice) via x402 on Base and Solana",
   "main": "dist/index.cjs",