@blockrun/llm 3.24.10 → 3.25.0

package/README.md

@@ -723,6 +723,7 @@ await client.closeBatchChannel();
 - **Never pays twice.** Anything that goes wrong before a batch payment is sent falls back to `exact`. Once one is sent, a call whose payment may have been charged throws `BatchPaymentUnresolvedError` and is never paid again (no new payment, no `exact`, no fallback model).
 - **Non-streaming chat only.** `chat`, `chatCompletion`, `smartChat` and `smartChatCompletion` use batch; `stream()` and media jobs pay `exact`.
 - **One channel per wallet.** All clients for a wallet share one channel, saved to `~/.blockrun/solana-batch/<wallet>.json` (mode `0600`) so a restart reuses it.
+- **One process per wallet.** The process that opens the channel holds its store's lock until it exits. Other processes on that wallet (worker pools, PM2/cluster workers, parallel runs) pay `exact`, reported as `channel_store_locked`. Give each worker its own wallet, or route calls through one process. `batch.onLocked: "wait"` waits up to `batch.lockWaitMs` (default 60 s) for the lock, and `"throw"` raises `BatchChannelLockedError` (unpaid, nothing signed) instead of paying `exact`.
 - **Observable.** Every fallback, backoff, recovery and re-read writes one stderr line; `batch.onEvent` and `client.getBatchStats()` expose the same events and counters.
 
 The full runtime contract (the answer-by-answer table, payment-identifier

package/dist/index.cjs

@@ -36,11 +36,13 @@ __export(index_exports, {
   AnthropicClient: () => AnthropicClient,
   BASE_CHAIN_ID: () => BASE_CHAIN_ID,
   BLOCKRUN_SOL_OPERATOR: () => BLOCKRUN_SOL_OPERATOR,
+  BatchChannelLockedError: () => BatchChannelLockedError,
   BatchCloseDeferredError: () => BatchCloseDeferredError,
   BatchPaymentUnresolvedError: () => BatchPaymentUnresolvedError,
   BlockrunClient: () => BlockrunClient,
   BlockrunError: () => BlockrunError,
   DEFAULT_BATCH_IN_DOUBT: () => DEFAULT_BATCH_IN_DOUBT,
+  DEFAULT_BATCH_LOCK_WAIT_MS: () => DEFAULT_BATCH_LOCK_WAIT_MS,
   DEFAULT_BATCH_RATE_LIMIT: () => DEFAULT_BATCH_RATE_LIMIT,
   EVM_NETWORKS: () => EVM_NETWORKS,
   ImageClient: () => ImageClient,
@@ -5120,7 +5122,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.24.10";
+var SDK_VERSION = "3.25.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -10222,6 +10224,8 @@ var BATCH_SCHEME = "batch-settlement";
 var BLOCKRUN_SOL_OPERATOR = "5YKPQUFjw5WQqhSUkEGKNNfYYVqnRRNbpYyL71qQ1vm3";
 var DEFAULT_BATCH_RATE_LIMIT = { maxAttempts: 3, maxWaitMs: 6e4 };
 var DEFAULT_BATCH_IN_DOUBT = { maxWaitMs: 3e5 };
+var DEFAULT_BATCH_LOCK_WAIT_MS = 6e4;
+var LOCK_POLL_MS = 500;
 var BatchPaymentUnresolvedError = class extends PaymentError {
   /** The {@link SolanaBatchEvent.reason} of the `unresolved` event reported with it. */
   reason;
@@ -10267,6 +10271,22 @@ var BatchCloseDeferredError = class extends BlockrunError {
     this.channelIds = init.channelIds ?? [];
   }
 };
+var BatchChannelLockedError = class extends BlockrunError {
+  /** The paying wallet's address. */
+  wallet;
+  /** The live owner's pid, when the SDK knows it. */
+  ownerPid;
+  /** How long this call waited for the lock, in ms (0 unless `onLocked` is `"wait"`). */
+  waitedMs;
+  constructor(init) {
+    super(`batch-settlement unavailable for wallet ${init.wallet}: ${init.detail}`);
+    this.name = "BatchChannelLockedError";
+    this.wallet = init.wallet;
+    if (init.ownerPid !== void 0) this.ownerPid = init.ownerPid;
+    this.waitedMs = init.waitedMs;
+    withDisposition(this, "unpaid");
+  }
+};
 var INSTALL_HINT2 = "npm install @x402/core@~2.28.0 @x402/svm@~2.28.0 @solana/kit";
 async function load(pkg, importer) {
   try {
@@ -11331,12 +11351,22 @@ var SolanaBatchPayer = class {
     if (!Number.isFinite(this.inDoubtMaxWaitMs) || this.inDoubtMaxWaitMs < 0) {
       throw new Error("batch.inDoubt.maxWaitMs must be a finite number of ms >= 0");
     }
+    this.onLocked = init.options.onLocked ?? "exact";
+    if (this.onLocked !== "exact" && this.onLocked !== "wait" && this.onLocked !== "throw") {
+      throw new Error('batch.onLocked must be "exact", "wait" or "throw"');
+    }
+    this.lockWaitMs = init.options.lockWaitMs ?? DEFAULT_BATCH_LOCK_WAIT_MS;
+    if (!Number.isFinite(this.lockWaitMs) || this.lockWaitMs < 0) {
+      throw new Error("batch.lockWaitMs must be a finite number of ms >= 0");
+    }
   }
   init;
   state;
   maxAttempts;
   maxWaitMs;
   inDoubtMaxWaitMs;
+  onLocked;
+  lockWaitMs;
   counters = {
     fallbacks: 0,
     fallbacksByReason: {},
@@ -11385,6 +11415,7 @@ var SolanaBatchPayer = class {
         if (owner !== void 0) {
           return {
             reason: "channel_store_locked",
+            ownerPid: owner,
             detail: owner === process.pid ? `channel store ${file} is in use by another copy of @blockrun/llm in this process (or by a process that had this pid and died: remove ${file}.lock if nothing uses it)` : `channel store ${file} is in use by process ${owner}`
           };
         }
@@ -11730,12 +11761,23 @@ var SolanaBatchPayer = class {
     const unavailable = batchUnavailable(paymentRequired);
     if (unavailable) return this.fallback(unavailable);
     let wallet;
+    let waitedMs = 0;
     try {
       wallet = await this.wallet();
+      if ("reason" in wallet && wallet.reason === "channel_store_locked" && this.onLocked === "wait") {
+        const started = Date.now();
+        wallet = await this.waitForLock(wallet);
+        waitedMs = Date.now() - started;
+      }
     } catch (err) {
       return this.fallback(creationFailure(err));
     }
-    if ("reason" in wallet) return this.fallback({ reason: wallet.reason, detail: wallet.detail });
+    if ("reason" in wallet) {
+      if (wallet.reason === "channel_store_locked" && this.onLocked !== "exact") {
+        return this.lockedOut(wallet.detail, wallet.ownerPid, waitedMs);
+      }
+      return this.fallback({ reason: wallet.reason, detail: wallet.detail });
+    }
     if (closesAtStart !== void 0 && wallet.closes !== closesAtStart) {
       return this.fallback({
         reason: "closed_during_call",
@@ -11752,6 +11794,40 @@ var SolanaBatchPayer = class {
       wallet.active -= 1;
     }
   }
+  /**
+   * `onLocked: "wait"`: try the wallet's channel store again every
+   * {@link LOCK_POLL_MS} until its owner lets go of it or `lockWaitMs` runs
+   * out. Reported once as a `backoff` event (`channel_store_locked`).
+   */
+  async waitForLock(refusal) {
+    const deadline = Date.now() + this.lockWaitMs;
+    let current = refusal;
+    if (this.lockWaitMs > 0) {
+      await this.report({
+        type: "backoff",
+        reason: "channel_store_locked",
+        retryAfterMs: this.lockWaitMs,
+        detail: refusal.detail
+      });
+    }
+    while ("reason" in current && current.reason === "channel_store_locked") {
+      const left = deadline - Date.now();
+      if (left <= 0) break;
+      await sleep2(Math.min(LOCK_POLL_MS, left));
+      current = await this.wallet();
+    }
+    return current;
+  }
+  /** `onLocked` other than `"exact"`: the call's `"unpaid"` error, nothing signed. */
+  async lockedOut(detail, ownerPid, waitedMs) {
+    const error = new BatchChannelLockedError({
+      wallet: await this.init.address(),
+      detail,
+      waitedMs,
+      ...ownerPid !== void 0 ? { ownerPid } : {}
+    });
+    return { kind: "failed", error };
+  }
   /**
    * The close fence for a call about to send its first request: how many
    * closes this wallet has completed so far, to hand to {@link pay}.
@@ -11842,11 +11918,9 @@ var SolanaBatchPayer = class {
         }
         if (wallet.busy) return fallback({ reason: "channel_busy", attempt: budget.attempt });
         if (wallet.file && !holdsChannelFile(wallet.file)) {
-          return fallback({
-            reason: "channel_store_locked",
-            attempt: budget.attempt,
-            detail: `this process no longer holds the lock on ${wallet.file}; another owner may be paying into its channels`
-          });
+          const detail = `this process no longer holds the lock on ${wallet.file}; another owner may be paying into its channels`;
+          if (this.onLocked !== "exact") return this.lockedOut(detail, void 0, 0);
+          return fallback({ reason: "channel_store_locked", attempt: budget.attempt, detail });
         }
         wallet.busy = true;
         holding = true;
@@ -14701,11 +14775,13 @@ var AnthropicClient = class {
   AnthropicClient,
   BASE_CHAIN_ID,
   BLOCKRUN_SOL_OPERATOR,
+  BatchChannelLockedError,
   BatchCloseDeferredError,
   BatchPaymentUnresolvedError,
   BlockrunClient,
   BlockrunError,
   DEFAULT_BATCH_IN_DOUBT,
+  DEFAULT_BATCH_LOCK_WAIT_MS,
   DEFAULT_BATCH_RATE_LIMIT,
   EVM_NETWORKS,
   ImageClient,

package/dist/index.d.cts

@@ -2923,6 +2923,27 @@ interface SolanaBatchOptions {
      *   by scanning the chain for it.
      */
     channelStore?: string | false;
+    /**
+     * What a call does when another live process owns this wallet's channel
+     * store (`channel_store_locked`). One process per wallet pays with batch:
+     * it holds the store's lock until it exits, so worker pools, PM2/cluster
+     * workers or parallel runs on one wallet must each use their own wallet
+     * (or route their calls through one process).
+     * - `"exact"` (default): the call pays with `exact`, as before.
+     * - `"wait"`: the call waits up to {@link lockWaitMs} for the lock (the
+     *   owner has to exit), then pays with batch, or raises
+     *   {@link BatchChannelLockedError} once the wait runs out.
+     * - `"throw"`: the call raises {@link BatchChannelLockedError} at once.
+     *
+     * The error is raised before anything is signed, so it is `"unpaid"`:
+     * `fallbackModels` (and `smartChat()`'s chain) may move on, and will meet
+     * the same lock. A process that loses its lock to another owner raises it
+     * too unless `onLocked` is `"exact"` (waiting cannot give it back).
+     * Locks between clients of one process do not apply: they share a channel.
+     */
+    onLocked?: "exact" | "wait" | "throw";
+    /** Most time, in ms, one call waits for the lock under `onLocked: "wait"`. Default 60000. */
+    lockWaitMs?: number;
     /**
      * How a call rides out an HTTP 429 (rate limited, or channel capacity
      * exhausted) on a batch payment before it pays with `exact`. The call waits
@@ -2982,6 +3003,8 @@ declare const DEFAULT_BATCH_RATE_LIMIT: {
 declare const DEFAULT_BATCH_IN_DOUBT: {
     readonly maxWaitMs: 300000;
 };
+/** Default {@link SolanaBatchOptions.lockWaitMs}. */
+declare const DEFAULT_BATCH_LOCK_WAIT_MS = 60000;
 /**
  * One observable batch-settlement event.
  *
@@ -2996,7 +3019,10 @@ declare const DEFAULT_BATCH_IN_DOUBT: {
  *   (`reason: "rate_limited"`) or because another call for the wallet hit one
  *   (`reason: "cooldown"`), or before each replay of a payment in doubt that
  *   carries a payment identifier (`reason: "in_doubt"`, or `rate_limited`
- *   after a 429), with the answer's `status` and the wait in `retryAfterMs`.
+ *   after a 429), with the answer's `status` and the wait in `retryAfterMs`;
+ *   or, once, when a call starts waiting up to `lockWaitMs` for another
+ *   process's channel store lock (`reason: "channel_store_locked"`,
+ *   `onLocked: "wait"`).
  * - `recovered`: a call that backed off was then paid with batch (`reason:
  *   "in_doubt"` when the replay of a payment in doubt resolved it), or its
  *   fresh challenge after the wait was served without a payment (`reason:
@@ -3167,6 +3193,26 @@ declare class BatchCloseDeferredError extends BlockrunError {
         detail: string;
     });
 }
+/**
+ * Batch is on, another owner holds this wallet's channel store, and the
+ * client's `batch.onLocked` is `"wait"` (the wait ran out) or `"throw"`.
+ * Raised before anything is signed: nothing was paid for the call, and its
+ * {@link RetryDisposition} is `"unpaid"`.
+ */
+declare class BatchChannelLockedError extends BlockrunError {
+    /** The paying wallet's address. */
+    readonly wallet: string;
+    /** The live owner's pid, when the SDK knows it. */
+    readonly ownerPid?: number;
+    /** How long this call waited for the lock, in ms (0 unless `onLocked` is `"wait"`). */
+    readonly waitedMs: number;
+    constructor(init: {
+        wallet: string;
+        detail: string;
+        ownerPid?: number;
+        waitedMs: number;
+    });
+}
 /**
  * The outcome of one batch attempt.
  *
@@ -3270,6 +3316,8 @@ declare class SolanaBatchPayer {
     private readonly maxAttempts;
     private readonly maxWaitMs;
     private readonly inDoubtMaxWaitMs;
+    private readonly onLocked;
+    private readonly lockWaitMs;
     private readonly counters;
     private readonly hooks;
     constructor(init: SolanaBatchPayerInit);
@@ -3387,6 +3435,14 @@ declare class SolanaBatchPayer {
      *   open a channel the caller believes is closed.
      */
     pay(paymentRequired: PaymentRequired, send: (headers: Record<string, string>) => Promise<Response>, rechallenge: () => Promise<Rechallenge>, closesAtStart?: number): Promise<BatchAttempt>;
+    /**
+     * `onLocked: "wait"`: try the wallet's channel store again every
+     * {@link LOCK_POLL_MS} until its owner lets go of it or `lockWaitMs` runs
+     * out. Reported once as a `backoff` event (`channel_store_locked`).
+     */
+    private waitForLock;
+    /** `onLocked` other than `"exact"`: the call's `"unpaid"` error, nothing signed. */
+    private lockedOut;
     /**
      * The close fence for a call about to send its first request: how many
      * closes this wallet has completed so far, to hand to {@link pay}.
@@ -4490,4 +4546,4 @@ declare function readSettlement(response: Response, quotedUsd: number, scheme: S
     settlement: Settlement;
 };
 
-export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, type BatchAttempt, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, 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, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, 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, PORTAL_URL, 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 Rechallenge, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, 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 Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, SolanaBatchPayer, type SolanaBatchPayerInit, type SolanaBatchStats, 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_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, 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 WebSearchTool, type X402ClientLike, type X402HookContext, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, type BatchAttempt, BatchChannelLockedError, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, 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, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_LOCK_WAIT_MS, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, 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, PORTAL_URL, 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 Rechallenge, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, 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 Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, SolanaBatchPayer, type SolanaBatchPayerInit, type SolanaBatchStats, 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_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, 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 WebSearchTool, type X402ClientLike, type X402HookContext, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.d.ts

@@ -2923,6 +2923,27 @@ interface SolanaBatchOptions {
      *   by scanning the chain for it.
      */
     channelStore?: string | false;
+    /**
+     * What a call does when another live process owns this wallet's channel
+     * store (`channel_store_locked`). One process per wallet pays with batch:
+     * it holds the store's lock until it exits, so worker pools, PM2/cluster
+     * workers or parallel runs on one wallet must each use their own wallet
+     * (or route their calls through one process).
+     * - `"exact"` (default): the call pays with `exact`, as before.
+     * - `"wait"`: the call waits up to {@link lockWaitMs} for the lock (the
+     *   owner has to exit), then pays with batch, or raises
+     *   {@link BatchChannelLockedError} once the wait runs out.
+     * - `"throw"`: the call raises {@link BatchChannelLockedError} at once.
+     *
+     * The error is raised before anything is signed, so it is `"unpaid"`:
+     * `fallbackModels` (and `smartChat()`'s chain) may move on, and will meet
+     * the same lock. A process that loses its lock to another owner raises it
+     * too unless `onLocked` is `"exact"` (waiting cannot give it back).
+     * Locks between clients of one process do not apply: they share a channel.
+     */
+    onLocked?: "exact" | "wait" | "throw";
+    /** Most time, in ms, one call waits for the lock under `onLocked: "wait"`. Default 60000. */
+    lockWaitMs?: number;
     /**
      * How a call rides out an HTTP 429 (rate limited, or channel capacity
      * exhausted) on a batch payment before it pays with `exact`. The call waits
@@ -2982,6 +3003,8 @@ declare const DEFAULT_BATCH_RATE_LIMIT: {
 declare const DEFAULT_BATCH_IN_DOUBT: {
     readonly maxWaitMs: 300000;
 };
+/** Default {@link SolanaBatchOptions.lockWaitMs}. */
+declare const DEFAULT_BATCH_LOCK_WAIT_MS = 60000;
 /**
  * One observable batch-settlement event.
  *
@@ -2996,7 +3019,10 @@ declare const DEFAULT_BATCH_IN_DOUBT: {
  *   (`reason: "rate_limited"`) or because another call for the wallet hit one
  *   (`reason: "cooldown"`), or before each replay of a payment in doubt that
  *   carries a payment identifier (`reason: "in_doubt"`, or `rate_limited`
- *   after a 429), with the answer's `status` and the wait in `retryAfterMs`.
+ *   after a 429), with the answer's `status` and the wait in `retryAfterMs`;
+ *   or, once, when a call starts waiting up to `lockWaitMs` for another
+ *   process's channel store lock (`reason: "channel_store_locked"`,
+ *   `onLocked: "wait"`).
  * - `recovered`: a call that backed off was then paid with batch (`reason:
  *   "in_doubt"` when the replay of a payment in doubt resolved it), or its
  *   fresh challenge after the wait was served without a payment (`reason:
@@ -3167,6 +3193,26 @@ declare class BatchCloseDeferredError extends BlockrunError {
         detail: string;
     });
 }
+/**
+ * Batch is on, another owner holds this wallet's channel store, and the
+ * client's `batch.onLocked` is `"wait"` (the wait ran out) or `"throw"`.
+ * Raised before anything is signed: nothing was paid for the call, and its
+ * {@link RetryDisposition} is `"unpaid"`.
+ */
+declare class BatchChannelLockedError extends BlockrunError {
+    /** The paying wallet's address. */
+    readonly wallet: string;
+    /** The live owner's pid, when the SDK knows it. */
+    readonly ownerPid?: number;
+    /** How long this call waited for the lock, in ms (0 unless `onLocked` is `"wait"`). */
+    readonly waitedMs: number;
+    constructor(init: {
+        wallet: string;
+        detail: string;
+        ownerPid?: number;
+        waitedMs: number;
+    });
+}
 /**
  * The outcome of one batch attempt.
  *
@@ -3270,6 +3316,8 @@ declare class SolanaBatchPayer {
     private readonly maxAttempts;
     private readonly maxWaitMs;
     private readonly inDoubtMaxWaitMs;
+    private readonly onLocked;
+    private readonly lockWaitMs;
     private readonly counters;
     private readonly hooks;
     constructor(init: SolanaBatchPayerInit);
@@ -3387,6 +3435,14 @@ declare class SolanaBatchPayer {
      *   open a channel the caller believes is closed.
      */
     pay(paymentRequired: PaymentRequired, send: (headers: Record<string, string>) => Promise<Response>, rechallenge: () => Promise<Rechallenge>, closesAtStart?: number): Promise<BatchAttempt>;
+    /**
+     * `onLocked: "wait"`: try the wallet's channel store again every
+     * {@link LOCK_POLL_MS} until its owner lets go of it or `lockWaitMs` runs
+     * out. Reported once as a `backoff` event (`channel_store_locked`).
+     */
+    private waitForLock;
+    /** `onLocked` other than `"exact"`: the call's `"unpaid"` error, nothing signed. */
+    private lockedOut;
     /**
      * The close fence for a call about to send its first request: how many
      * closes this wallet has completed so far, to hand to {@link pay}.
@@ -4490,4 +4546,4 @@ declare function readSettlement(response: Response, quotedUsd: number, scheme: S
     settlement: Settlement;
 };
 
-export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, type BatchAttempt, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, 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, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, 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, PORTAL_URL, 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 Rechallenge, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, 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 Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, SolanaBatchPayer, type SolanaBatchPayerInit, type SolanaBatchStats, 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_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, 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 WebSearchTool, type X402ClientLike, type X402HookContext, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, type BatchAttempt, BatchChannelLockedError, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, 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, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_LOCK_WAIT_MS, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, 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, PORTAL_URL, 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 Rechallenge, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, 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 Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, SolanaBatchPayer, type SolanaBatchPayerInit, type SolanaBatchStats, 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_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, 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 WebSearchTool, type X402ClientLike, type X402HookContext, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.js

@@ -4989,7 +4989,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.24.10";
+var SDK_VERSION = "3.25.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -10091,6 +10091,8 @@ var BATCH_SCHEME = "batch-settlement";
 var BLOCKRUN_SOL_OPERATOR = "5YKPQUFjw5WQqhSUkEGKNNfYYVqnRRNbpYyL71qQ1vm3";
 var DEFAULT_BATCH_RATE_LIMIT = { maxAttempts: 3, maxWaitMs: 6e4 };
 var DEFAULT_BATCH_IN_DOUBT = { maxWaitMs: 3e5 };
+var DEFAULT_BATCH_LOCK_WAIT_MS = 6e4;
+var LOCK_POLL_MS = 500;
 var BatchPaymentUnresolvedError = class extends PaymentError {
   /** The {@link SolanaBatchEvent.reason} of the `unresolved` event reported with it. */
   reason;
@@ -10136,6 +10138,22 @@ var BatchCloseDeferredError = class extends BlockrunError {
     this.channelIds = init.channelIds ?? [];
   }
 };
+var BatchChannelLockedError = class extends BlockrunError {
+  /** The paying wallet's address. */
+  wallet;
+  /** The live owner's pid, when the SDK knows it. */
+  ownerPid;
+  /** How long this call waited for the lock, in ms (0 unless `onLocked` is `"wait"`). */
+  waitedMs;
+  constructor(init) {
+    super(`batch-settlement unavailable for wallet ${init.wallet}: ${init.detail}`);
+    this.name = "BatchChannelLockedError";
+    this.wallet = init.wallet;
+    if (init.ownerPid !== void 0) this.ownerPid = init.ownerPid;
+    this.waitedMs = init.waitedMs;
+    withDisposition(this, "unpaid");
+  }
+};
 var INSTALL_HINT2 = "npm install @x402/core@~2.28.0 @x402/svm@~2.28.0 @solana/kit";
 async function load(pkg, importer) {
   try {
@@ -11200,12 +11218,22 @@ var SolanaBatchPayer = class {
     if (!Number.isFinite(this.inDoubtMaxWaitMs) || this.inDoubtMaxWaitMs < 0) {
       throw new Error("batch.inDoubt.maxWaitMs must be a finite number of ms >= 0");
     }
+    this.onLocked = init.options.onLocked ?? "exact";
+    if (this.onLocked !== "exact" && this.onLocked !== "wait" && this.onLocked !== "throw") {
+      throw new Error('batch.onLocked must be "exact", "wait" or "throw"');
+    }
+    this.lockWaitMs = init.options.lockWaitMs ?? DEFAULT_BATCH_LOCK_WAIT_MS;
+    if (!Number.isFinite(this.lockWaitMs) || this.lockWaitMs < 0) {
+      throw new Error("batch.lockWaitMs must be a finite number of ms >= 0");
+    }
   }
   init;
   state;
   maxAttempts;
   maxWaitMs;
   inDoubtMaxWaitMs;
+  onLocked;
+  lockWaitMs;
   counters = {
     fallbacks: 0,
     fallbacksByReason: {},
@@ -11254,6 +11282,7 @@ var SolanaBatchPayer = class {
         if (owner !== void 0) {
           return {
             reason: "channel_store_locked",
+            ownerPid: owner,
             detail: owner === process.pid ? `channel store ${file} is in use by another copy of @blockrun/llm in this process (or by a process that had this pid and died: remove ${file}.lock if nothing uses it)` : `channel store ${file} is in use by process ${owner}`
           };
         }
@@ -11599,12 +11628,23 @@ var SolanaBatchPayer = class {
     const unavailable = batchUnavailable(paymentRequired);
     if (unavailable) return this.fallback(unavailable);
     let wallet;
+    let waitedMs = 0;
     try {
       wallet = await this.wallet();
+      if ("reason" in wallet && wallet.reason === "channel_store_locked" && this.onLocked === "wait") {
+        const started = Date.now();
+        wallet = await this.waitForLock(wallet);
+        waitedMs = Date.now() - started;
+      }
     } catch (err) {
       return this.fallback(creationFailure(err));
     }
-    if ("reason" in wallet) return this.fallback({ reason: wallet.reason, detail: wallet.detail });
+    if ("reason" in wallet) {
+      if (wallet.reason === "channel_store_locked" && this.onLocked !== "exact") {
+        return this.lockedOut(wallet.detail, wallet.ownerPid, waitedMs);
+      }
+      return this.fallback({ reason: wallet.reason, detail: wallet.detail });
+    }
     if (closesAtStart !== void 0 && wallet.closes !== closesAtStart) {
       return this.fallback({
         reason: "closed_during_call",
@@ -11621,6 +11661,40 @@ var SolanaBatchPayer = class {
       wallet.active -= 1;
     }
   }
+  /**
+   * `onLocked: "wait"`: try the wallet's channel store again every
+   * {@link LOCK_POLL_MS} until its owner lets go of it or `lockWaitMs` runs
+   * out. Reported once as a `backoff` event (`channel_store_locked`).
+   */
+  async waitForLock(refusal) {
+    const deadline = Date.now() + this.lockWaitMs;
+    let current = refusal;
+    if (this.lockWaitMs > 0) {
+      await this.report({
+        type: "backoff",
+        reason: "channel_store_locked",
+        retryAfterMs: this.lockWaitMs,
+        detail: refusal.detail
+      });
+    }
+    while ("reason" in current && current.reason === "channel_store_locked") {
+      const left = deadline - Date.now();
+      if (left <= 0) break;
+      await sleep2(Math.min(LOCK_POLL_MS, left));
+      current = await this.wallet();
+    }
+    return current;
+  }
+  /** `onLocked` other than `"exact"`: the call's `"unpaid"` error, nothing signed. */
+  async lockedOut(detail, ownerPid, waitedMs) {
+    const error = new BatchChannelLockedError({
+      wallet: await this.init.address(),
+      detail,
+      waitedMs,
+      ...ownerPid !== void 0 ? { ownerPid } : {}
+    });
+    return { kind: "failed", error };
+  }
   /**
    * The close fence for a call about to send its first request: how many
    * closes this wallet has completed so far, to hand to {@link pay}.
@@ -11711,11 +11785,9 @@ var SolanaBatchPayer = class {
         }
         if (wallet.busy) return fallback({ reason: "channel_busy", attempt: budget.attempt });
         if (wallet.file && !holdsChannelFile(wallet.file)) {
-          return fallback({
-            reason: "channel_store_locked",
-            attempt: budget.attempt,
-            detail: `this process no longer holds the lock on ${wallet.file}; another owner may be paying into its channels`
-          });
+          const detail = `this process no longer holds the lock on ${wallet.file}; another owner may be paying into its channels`;
+          if (this.onLocked !== "exact") return this.lockedOut(detail, void 0, 0);
+          return fallback({ reason: "channel_store_locked", attempt: budget.attempt, detail });
         }
         wallet.busy = true;
         holding = true;
@@ -14569,11 +14641,13 @@ export {
   AnthropicClient,
   BASE_CHAIN_ID,
   BLOCKRUN_SOL_OPERATOR,
+  BatchChannelLockedError,
   BatchCloseDeferredError,
   BatchPaymentUnresolvedError,
   BlockrunClient,
   BlockrunError,
   DEFAULT_BATCH_IN_DOUBT,
+  DEFAULT_BATCH_LOCK_WAIT_MS,
   DEFAULT_BATCH_RATE_LIMIT,
   EVM_NETWORKS,
   ImageClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.24.10",
+  "version": "3.25.0",
   "type": "module",
   "description": "TypeScript SDK for BlockRun - every frontier model behind one OpenAI-compatible client. Pay with a BlockRun API key or per-call in USDC. Smart routing picks the cheapest capable model. No rate limits.",
   "main": "dist/index.cjs",