@blockrun/llm 3.7.0 → 3.8.0

package/README.md

@@ -1295,9 +1295,10 @@ await status();
 // Balance: $5.30 USDC
 ```
 
-## Wallet Scanning
+## Wallet Discovery and Migration
 
-The SDK auto-detects wallets from any provider on your system:
+The SDK can discover compatible wallets for an explicit, user-confirmed
+migration. It never automatically makes a discovered provider wallet active:
 
 ```typescript
 import { scanWallets, scanSolanaWallets } from '@blockrun/llm';
@@ -1309,7 +1310,50 @@ const baseWallets = scanWallets();
 const solWallets = scanSolanaWallets();
 ```
 
-`getOrCreateWallet()` checks scanned wallets first, so if you already have a wallet from another BlockRun tool, it will be reused automatically.
+`getOrCreateWallet()` always uses `~/.blockrun/.session` (or an explicit
+wallet environment variable, or the legacy `~/.blockrun/wallet.key`). Review
+the discovered addresses and import one explicitly if you intend to switch
+wallets.
+
+### Upgrading from a provider wallet
+
+Earlier versions adopted the most recently written provider wallet
+automatically. If you relied on that, the first run after upgrading creates a
+fresh BlockRun wallet and prints the addresses it found, so you can import the
+one you actually own:
+
+```
+NOTICE: BlockRun created a new wallet, but also found existing wallet(s)
+belonging to other applications on this system:
+
+  0x88f9B82462f6C4bf4a0Fb15e5c3971559a316e7f
+...
+```
+
+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

@@ -72,7 +72,9 @@ __export(index_exports, {
   extractPaymentDetails: () => extractPaymentDetails,
   formatFundingMessageCompact: () => formatFundingMessageCompact,
   formatNeedsFundingMessage: () => formatNeedsFundingMessage,
+  formatSolanaWalletMigrationNotice: () => formatSolanaWalletMigrationNotice,
   formatWalletCreatedMessage: () => formatWalletCreatedMessage,
+  formatWalletMigrationNotice: () => formatWalletMigrationNotice,
   getCached: () => getCached,
   getCachedByRequest: () => getCachedByRequest,
   getCostLogSummary: () => getCostLogSummary,
@@ -82,6 +84,10 @@ __export(index_exports, {
   getOrCreateWallet: () => getOrCreateWallet,
   getPaymentLinks: () => getPaymentLinks,
   getWalletAddress: () => getWalletAddress,
+  importSolanaWallet: () => importSolanaWallet,
+  importWallet: () => importWallet,
+  listDiscoveredSolanaWallets: () => listDiscoveredSolanaWallets,
+  listDiscoveredWallets: () => listDiscoveredWallets,
   loadSolanaWallet: () => loadSolanaWallet,
   loadWallet: () => loadWallet,
   logCost: () => logCost,
@@ -4629,7 +4635,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;
@@ -4638,11 +4644,48 @@ 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() {
-  const wallets = scanWallets();
-  if (wallets.length > 0) return wallets[0].privateKey;
   if (fs2.existsSync(WALLET_FILE)) {
     const key = fs2.readFileSync(WALLET_FILE, "utf-8").trim();
     if (key) return key;
@@ -4654,6 +4697,46 @@ function loadWallet() {
   }
   return null;
 }
+function formatWalletMigrationNotice(newAddress) {
+  let discovered;
+  try {
+    discovered = scanWallets();
+  } catch {
+    return null;
+  }
+  const addresses = [];
+  for (const entry of discovered) {
+    try {
+      addresses.push((0, import_accounts15.privateKeyToAccount)(entry.privateKey).address);
+    } catch {
+      continue;
+    }
+  }
+  if (addresses.length === 0) return null;
+  const found = addresses.map((addr) => `  ${addr}`).join("\n");
+  return `
+NOTICE: BlockRun created a new wallet, but also found existing wallet(s)
+belonging to other applications on this system:
+
+${found}
+
+BlockRun now uses only its own wallet:
+
+  ${newAddress}
+
+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, adopt it deliberately:
+
+  import { importWallet } from '@blockrun/llm';
+  importWallet("<address-from-the-list-above>");
+
+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() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
@@ -4796,7 +4879,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 {
         }
@@ -4810,7 +4893,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 {
           }
@@ -4820,27 +4903,100 @@ 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() {
-  const wallets = scanSolanaWallets();
-  if (wallets.length > 0) return wallets[0].secretKey;
   if (fs3.existsSync(SOLANA_WALLET_FILE)) {
     const key = fs3.readFileSync(SOLANA_WALLET_FILE, "utf-8").trim();
     if (key) return key;
   }
   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 {
+    discovered = scanSolanaWallets();
+  } catch {
+    return null;
+  }
+  const addresses = [];
+  for (const entry of discovered) {
+    try {
+      addresses.push(await solanaPublicKey(entry.secretKey));
+    } catch {
+      continue;
+    }
+  }
+  if (addresses.length === 0) return null;
+  const found = addresses.map((addr) => `  ${addr}`).join("\n");
+  return `
+NOTICE: BlockRun created a new Solana wallet, but also found existing
+wallet(s) belonging to other applications on this system:
+
+${found}
+
+BlockRun now uses only its own wallet:
+
+  ${newAddress}
+
+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, adopt it deliberately:
+
+  import { importSolanaWallet } from '@blockrun/llm';
+  await importSolanaWallet("<address-from-the-list-above>");
+
+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() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.SOLANA_WALLET_KEY : void 0;
   if (envKey) {
     const address2 = await solanaPublicKey(envKey);
     return { privateKey: envKey, address: address2, isNew: false };
   }
-  const wallets = scanSolanaWallets();
-  if (wallets.length > 0) {
-    return { privateKey: wallets[0].secretKey, address: wallets[0].publicKey, isNew: false };
-  }
   if (fs3.existsSync(SOLANA_WALLET_FILE)) {
     const fileKey = fs3.readFileSync(SOLANA_WALLET_FILE, "utf-8").trim();
     if (fileKey) {
@@ -5665,27 +5821,35 @@ function getCostLogSummary() {
 // src/setup.ts
 function setupAgentWallet(options) {
   const { address, privateKey, isNew } = getOrCreateWallet();
-  if (isNew && !options?.silent) {
-    console.error(
-      `
+  if (isNew) {
+    const notice = formatWalletMigrationNotice(address);
+    if (notice) console.error(notice);
+    if (!options?.silent) {
+      console.error(
+        `
 BlockRun Agent Wallet Created!
 Address: ${address}
 Send USDC on Base to get started.
 `
-    );
+      );
+    }
   }
   return new LLMClient({ privateKey });
 }
 async function setupAgentSolanaWallet(options) {
   const result = await getOrCreateSolanaWallet();
-  if (result.isNew && !options?.silent) {
-    console.error(
-      `
+  if (result.isNew) {
+    const notice = await formatSolanaWalletMigrationNotice(result.address);
+    if (notice) console.error(notice);
+    if (!options?.silent) {
+      console.error(
+        `
 BlockRun Solana Agent Wallet Created!
 Address: ${result.address}
 Send USDC on Solana to get started.
 `
-    );
+      );
+    }
   }
   return new SolanaLLMClient({ privateKey: result.privateKey });
 }
@@ -5998,7 +6162,9 @@ var AnthropicClient = class {
   extractPaymentDetails,
   formatFundingMessageCompact,
   formatNeedsFundingMessage,
+  formatSolanaWalletMigrationNotice,
   formatWalletCreatedMessage,
+  formatWalletMigrationNotice,
   getCached,
   getCachedByRequest,
   getCostLogSummary,
@@ -6008,6 +6174,10 @@ var AnthropicClient = class {
   getOrCreateWallet,
   getPaymentLinks,
   getWalletAddress,
+  importSolanaWallet,
+  importWallet,
+  listDiscoveredSolanaWallets,
+  listDiscoveredWallets,
   loadSolanaWallet,
   loadWallet,
   logCost,

package/dist/index.d.cts

@@ -2527,37 +2527,86 @@ declare function createWallet(): {
  */
 declare function saveWallet(privateKey: string): string;
 /**
- * Scan ~/.<dir>/wallet.json files from any provider (agentcash, etc.).
+ * Discover ~/.<dir>/wallet.json files from other providers.
  *
  * Each file should contain JSON with "privateKey" and "address" fields.
- * Results are sorted by modification time (most recent first).
+ * Results are sorted by modification time (most recent first). Discovery is
+ * intentionally opt-in: a provider wallet must never replace the canonical
+ * BlockRun wallet merely because it was written more recently.
  *
  * @returns Array of wallet objects with privateKey and address
  */
 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.
  *
  * Priority:
- * 1. Scan ~/.* /wallet.json (any provider)
- * 2. Legacy ~/.blockrun/.session
- * 3. Legacy ~/.blockrun/wallet.key
+ * 1. ~/.blockrun/.session
+ * 2. ~/.blockrun/wallet.key (legacy)
  *
  * @returns Private key string or null if not found
  */
 declare function loadWallet(): string | null;
+/**
+ * Warn when a new wallet was created while other provider wallets exist.
+ *
+ * Automatic selection deliberately ignores wallets discovered in other
+ * applications' directories, so a user who previously relied on that discovery
+ * would otherwise land on an empty wallet with no explanation of where their
+ * funds went. This notice names the discovered addresses and tells them how to
+ * import one on purpose.
+ *
+ * Addresses are derived from the discovered private key rather than read from
+ * the file's "address" field, so a file claiming an address it cannot sign for
+ * cannot trick the user into importing it.
+ *
+ * @param newAddress Address of the wallet that was just created
+ * @returns Formatted notice, or null if nothing was discovered
+ */
+declare function formatWalletMigrationNotice(newAddress: string): string | null;
 /**
  * Get existing wallet or create new one.
  *
  * Priority:
  * 1. BLOCKRUN_WALLET_KEY environment variable
- * 2. Scan wallet.json files from providers
- * 3. ~/.blockrun/.session file
- * 4. ~/.blockrun/wallet.key file - legacy
- * 5. Create new wallet
+ * 2. ~/.blockrun/.session file
+ * 3. ~/.blockrun/wallet.key file - legacy
+ * 4. Create new wallet
  *
  * @returns WalletInfo with address, privateKey, and isNew flag
  */
@@ -2821,19 +2870,57 @@ declare function solanaKeyToBytes(privateKey: string): Promise<Uint8Array>;
 declare function solanaPublicKey(privateKey: string): Promise<string>;
 declare function saveSolanaWallet(privateKey: string): string;
 /**
- * Scan ~/.<dir>/solana-wallet.json files from any provider.
+ * Discover ~/.<dir>/solana-wallet.json files from other providers.
  *
  * Each file should contain JSON with "privateKey" and "address" fields.
  * Also checks ~/.brcc/wallet.json for BRCC wallets.
- * Results are sorted by modification time (most recent first).
+ * Results are sorted by modification time (most recent first). Discovery is
+ * opt-in and never changes the active BlockRun wallet automatically.
  *
  * @returns Array of wallet objects with secretKey and publicKey
  */
 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.
+ *
+ * Solana counterpart of `formatWalletMigrationNotice`. Addresses are derived
+ * from the discovered secret key rather than trusted from the file's "address"
+ * field.
+ *
+ * @param newAddress Address of the wallet that was just created
+ * @returns Formatted notice, or null if nothing was discovered
+ */
+declare function formatSolanaWalletMigrationNotice(newAddress: string): Promise<string | null>;
 declare function getOrCreateSolanaWallet(): Promise<SolanaWalletInfo>;
 
 declare function getCached(key: string): unknown | null;
@@ -3104,4 +3191,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, formatWalletCreatedMessage, 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, 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

@@ -2527,37 +2527,86 @@ declare function createWallet(): {
  */
 declare function saveWallet(privateKey: string): string;
 /**
- * Scan ~/.<dir>/wallet.json files from any provider (agentcash, etc.).
+ * Discover ~/.<dir>/wallet.json files from other providers.
  *
  * Each file should contain JSON with "privateKey" and "address" fields.
- * Results are sorted by modification time (most recent first).
+ * Results are sorted by modification time (most recent first). Discovery is
+ * intentionally opt-in: a provider wallet must never replace the canonical
+ * BlockRun wallet merely because it was written more recently.
  *
  * @returns Array of wallet objects with privateKey and address
  */
 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.
  *
  * Priority:
- * 1. Scan ~/.* /wallet.json (any provider)
- * 2. Legacy ~/.blockrun/.session
- * 3. Legacy ~/.blockrun/wallet.key
+ * 1. ~/.blockrun/.session
+ * 2. ~/.blockrun/wallet.key (legacy)
  *
  * @returns Private key string or null if not found
  */
 declare function loadWallet(): string | null;
+/**
+ * Warn when a new wallet was created while other provider wallets exist.
+ *
+ * Automatic selection deliberately ignores wallets discovered in other
+ * applications' directories, so a user who previously relied on that discovery
+ * would otherwise land on an empty wallet with no explanation of where their
+ * funds went. This notice names the discovered addresses and tells them how to
+ * import one on purpose.
+ *
+ * Addresses are derived from the discovered private key rather than read from
+ * the file's "address" field, so a file claiming an address it cannot sign for
+ * cannot trick the user into importing it.
+ *
+ * @param newAddress Address of the wallet that was just created
+ * @returns Formatted notice, or null if nothing was discovered
+ */
+declare function formatWalletMigrationNotice(newAddress: string): string | null;
 /**
  * Get existing wallet or create new one.
  *
  * Priority:
  * 1. BLOCKRUN_WALLET_KEY environment variable
- * 2. Scan wallet.json files from providers
- * 3. ~/.blockrun/.session file
- * 4. ~/.blockrun/wallet.key file - legacy
- * 5. Create new wallet
+ * 2. ~/.blockrun/.session file
+ * 3. ~/.blockrun/wallet.key file - legacy
+ * 4. Create new wallet
  *
  * @returns WalletInfo with address, privateKey, and isNew flag
  */
@@ -2821,19 +2870,57 @@ declare function solanaKeyToBytes(privateKey: string): Promise<Uint8Array>;
 declare function solanaPublicKey(privateKey: string): Promise<string>;
 declare function saveSolanaWallet(privateKey: string): string;
 /**
- * Scan ~/.<dir>/solana-wallet.json files from any provider.
+ * Discover ~/.<dir>/solana-wallet.json files from other providers.
  *
  * Each file should contain JSON with "privateKey" and "address" fields.
  * Also checks ~/.brcc/wallet.json for BRCC wallets.
- * Results are sorted by modification time (most recent first).
+ * Results are sorted by modification time (most recent first). Discovery is
+ * opt-in and never changes the active BlockRun wallet automatically.
  *
  * @returns Array of wallet objects with secretKey and publicKey
  */
 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.
+ *
+ * Solana counterpart of `formatWalletMigrationNotice`. Addresses are derived
+ * from the discovered secret key rather than trusted from the file's "address"
+ * field.
+ *
+ * @param newAddress Address of the wallet that was just created
+ * @returns Formatted notice, or null if nothing was discovered
+ */
+declare function formatSolanaWalletMigrationNotice(newAddress: string): Promise<string | null>;
 declare function getOrCreateSolanaWallet(): Promise<SolanaWalletInfo>;
 
 declare function getCached(key: string): unknown | null;
@@ -3104,4 +3191,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, formatWalletCreatedMessage, 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, 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

@@ -4522,7 +4522,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,11 +4531,48 @@ 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() {
-  const wallets = scanWallets();
-  if (wallets.length > 0) return wallets[0].privateKey;
   if (fs2.existsSync(WALLET_FILE)) {
     const key = fs2.readFileSync(WALLET_FILE, "utf-8").trim();
     if (key) return key;
@@ -4547,6 +4584,46 @@ function loadWallet() {
   }
   return null;
 }
+function formatWalletMigrationNotice(newAddress) {
+  let discovered;
+  try {
+    discovered = scanWallets();
+  } catch {
+    return null;
+  }
+  const addresses = [];
+  for (const entry of discovered) {
+    try {
+      addresses.push(privateKeyToAccount14(entry.privateKey).address);
+    } catch {
+      continue;
+    }
+  }
+  if (addresses.length === 0) return null;
+  const found = addresses.map((addr) => `  ${addr}`).join("\n");
+  return `
+NOTICE: BlockRun created a new wallet, but also found existing wallet(s)
+belonging to other applications on this system:
+
+${found}
+
+BlockRun now uses only its own wallet:
+
+  ${newAddress}
+
+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, adopt it deliberately:
+
+  import { importWallet } from '@blockrun/llm';
+  importWallet("<address-from-the-list-above>");
+
+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() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
@@ -4689,7 +4766,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 {
         }
@@ -4703,7 +4780,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 {
           }
@@ -4713,27 +4790,100 @@ 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() {
-  const wallets = scanSolanaWallets();
-  if (wallets.length > 0) return wallets[0].secretKey;
   if (fs3.existsSync(SOLANA_WALLET_FILE)) {
     const key = fs3.readFileSync(SOLANA_WALLET_FILE, "utf-8").trim();
     if (key) return key;
   }
   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 {
+    discovered = scanSolanaWallets();
+  } catch {
+    return null;
+  }
+  const addresses = [];
+  for (const entry of discovered) {
+    try {
+      addresses.push(await solanaPublicKey(entry.secretKey));
+    } catch {
+      continue;
+    }
+  }
+  if (addresses.length === 0) return null;
+  const found = addresses.map((addr) => `  ${addr}`).join("\n");
+  return `
+NOTICE: BlockRun created a new Solana wallet, but also found existing
+wallet(s) belonging to other applications on this system:
+
+${found}
+
+BlockRun now uses only its own wallet:
+
+  ${newAddress}
+
+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, adopt it deliberately:
+
+  import { importSolanaWallet } from '@blockrun/llm';
+  await importSolanaWallet("<address-from-the-list-above>");
+
+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() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.SOLANA_WALLET_KEY : void 0;
   if (envKey) {
     const address2 = await solanaPublicKey(envKey);
     return { privateKey: envKey, address: address2, isNew: false };
   }
-  const wallets = scanSolanaWallets();
-  if (wallets.length > 0) {
-    return { privateKey: wallets[0].secretKey, address: wallets[0].publicKey, isNew: false };
-  }
   if (fs3.existsSync(SOLANA_WALLET_FILE)) {
     const fileKey = fs3.readFileSync(SOLANA_WALLET_FILE, "utf-8").trim();
     if (fileKey) {
@@ -5558,27 +5708,35 @@ function getCostLogSummary() {
 // src/setup.ts
 function setupAgentWallet(options) {
   const { address, privateKey, isNew } = getOrCreateWallet();
-  if (isNew && !options?.silent) {
-    console.error(
-      `
+  if (isNew) {
+    const notice = formatWalletMigrationNotice(address);
+    if (notice) console.error(notice);
+    if (!options?.silent) {
+      console.error(
+        `
 BlockRun Agent Wallet Created!
 Address: ${address}
 Send USDC on Base to get started.
 `
-    );
+      );
+    }
   }
   return new LLMClient({ privateKey });
 }
 async function setupAgentSolanaWallet(options) {
   const result = await getOrCreateSolanaWallet();
-  if (result.isNew && !options?.silent) {
-    console.error(
-      `
+  if (result.isNew) {
+    const notice = await formatSolanaWalletMigrationNotice(result.address);
+    if (notice) console.error(notice);
+    if (!options?.silent) {
+      console.error(
+        `
 BlockRun Solana Agent Wallet Created!
 Address: ${result.address}
 Send USDC on Solana to get started.
 `
-    );
+      );
+    }
   }
   return new SolanaLLMClient({ privateKey: result.privateKey });
 }
@@ -5891,7 +6049,9 @@ export {
   extractPaymentDetails,
   formatFundingMessageCompact,
   formatNeedsFundingMessage,
+  formatSolanaWalletMigrationNotice,
   formatWalletCreatedMessage,
+  formatWalletMigrationNotice,
   getCached,
   getCachedByRequest,
   getCostLogSummary,
@@ -5901,6 +6061,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.0",
+  "version": "3.8.0",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music, Voice) via x402 on Base and Solana",
   "main": "dist/index.cjs",