@blockrun/llm 3.9.0 → 3.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @blockrun/llm (TypeScript SDK)
 
-> **@blockrun/llm** is a TypeScript/Node.js SDK for accessing <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> large language models (GPT-5, Claude, Gemini, Grok, DeepSeek, Kimi, and more) with automatic pay-per-request USDC micropayments via the x402 protocol. No API keys required — your wallet signature is your authentication. Supports **streaming**, smart routing, Base and Solana chains.
+> **@blockrun/llm** is a TypeScript/Node.js SDK for accessing <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> large language models (GPT-5, Claude, Gemini, Grok, DeepSeek, Kimi, and more) with automatic pay-per-request USDC micropayments via the x402 protocol. No API keys required — your wallet signature is your authentication. Supports **streaming**, smart routing, Base and Solana chains.
 >
 > 🆓 **Includes 7 fully-free NVIDIA-hosted models** (5 visible in `/v1/models`, 2 hidden but directly callable) — DeepSeek V4 Flash (1M context), Nemotron Nano Omni (vision), Qwen3 Coder, Llama 4, Mistral, plus the gpt-oss pair. Zero USDC, no rate-limit gimmicks. Use `routingProfile: 'free'` or call any `nvidia/*` model directly.
 
@@ -21,7 +21,7 @@
 ## Installation
 
 ```bash
-# Base and Solana support (optional Solana deps auto-installed)
+# Base / EVM payments — nothing else needed
 npm install @blockrun/llm
 # or
 pnpm add @blockrun/llm
@@ -29,6 +29,21 @@ pnpm add @blockrun/llm
 yarn add @blockrun/llm
 ```
 
+**Solana payments** need two more packages. They are optional peer dependencies,
+so npm will not install them for you:
+
+```bash
+npm install @blockrun/llm @solana/web3.js @solana/spl-token
+```
+
+Why they are not automatic: `@solana/spl-token` pulls in `bigint-buffer`, whose
+native `toBigIntLE()` has an unpatched buffer overflow
+([GHSA-3gc7-fjrx-p6mg](https://github.com/advisories/GHSA-3gc7-fjrx-p6mg)) with no
+fixed release anywhere. As an optional *dependency* it landed in the lockfile of
+every consumer, including projects that only ever pay on Base. As an optional
+*peer* it reaches only the projects that ask for Solana. Calling a Solana path
+without them throws an error naming the exact install command.
+
 ## Quick Start (Base - Default)
 
 ```typescript
@@ -221,7 +236,24 @@ Every paid request is a real on-chain USDC transfer — look up your wallet addr
 
 ## Smart Routing (ClawRouter)
 
-Let the SDK automatically pick the cheapest capable model for each request:
+Let the SDK automatically pick the cheapest capable model for each request — **<!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->% cheaper than pinning Claude Opus 5** for the same traffic on `auto`, **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** on `eco`.
+
+Not an "up to" figure. The baseline, the workload mix and the token ratio are
+published in [`savings-mix.json`](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json),
+priced against the live catalog, so anyone can recompute the claim and get the
+same answer.
+
+Smart routing is powered by [ClawRouter](https://github.com/BlockRunAI/ClawRouter) —
+the open-source, agent-first LLM router: wallet signatures instead of API keys,
+USDC micropayments instead of credit cards, and <1ms fully-local routing with
+zero external calls. In this SDK it is an **optional peer dependency** —
+install it alongside the SDK:
+
+```bash
+npm install @blockrun/clawrouter
+```
+
+Only `smartChat()` needs it: every other API works without it, and the package is loaded lazily, so a missing or broken router can never break `import '@blockrun/llm'`. Calling `smartChat()` without it throws an error naming the package instead of a cryptic module-load failure.
 
 ```typescript
 import { LLMClient } from '@blockrun/llm';
@@ -232,23 +264,28 @@ const client = new LLMClient();
 const result = await client.smartChat('What is 2+2?');
 console.log(result.response);     // '4'
 console.log(result.model);        // 'moonshot/kimi-k2.5' (cheap, fast)
-console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 87%'
+console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 88%'
 
 // Complex reasoning task -> routes to reasoning model
 const complex = await client.smartChat('Prove the Riemann hypothesis step by step');
 console.log(complex.model);  // 'xai/grok-4-1-fast-reasoning'
 
+// Inspect how the request was classified and ranked (Router v3.4 portfolio).
+console.log(complex.routing.method);     // 'portfolio'
+console.log(complex.routing.taskType);   // 'reasoning'
+console.log(complex.routing.candidates); // ranked, capability-eligible models
+
 // Inspect the fallback chain SmartChat will walk on transient errors.
 console.log(complex.routing.fallbacks);  // ['anthropic/claude-opus-4.7', ...]
 ```
 
 ### Automatic Fallback on Transient Errors
 
-`smartChat()` populates a tier-specific fallback chain and `chat()` /
-`chatCompletion()` walk it automatically when the primary model returns a
-transient error — timeouts, network failures, or 5xx responses (502/503/504/
-522/524). 4xx errors and `PaymentError` propagate immediately so wallet /
-auth issues surface fast.
+`smartChat()` populates a fallback chain from the portfolio ranking and
+`chat()` / `chatCompletion()` walk it automatically when the primary model
+returns a transient error — timeouts, network failures, 429 rate limits, or
+5xx responses (502/503/504/522/524). Other 4xx errors and `PaymentError`
+propagate immediately so wallet / auth issues surface fast.
 
 ```typescript
 // Manually pass a fallback chain to chat() / chatCompletion()
@@ -261,12 +298,12 @@ const reply = await client.chat('nvidia/deepseek-v4-flash', 'hello', {
 
 ### Routing Profiles
 
-| Profile | Description | Best For |
-|---------|-------------|----------|
-| `free` | NVIDIA free tier — smart-routes across <!-- br:models.free -->8<!-- /br:models.free --> models (DeepSeek V4 Flash, Nemotron Nano Omni, Qwen3, Llama 4, Mistral, plus 2 hidden gpt-oss) | Zero-cost testing, dev, prod |
-| `eco` | Cheapest models per tier (DeepSeek, xAI) | Cost-sensitive production |
-| `auto` | Best balance of cost/quality (default) | General use |
-| `premium` | Top-tier models (OpenAI, Anthropic) | Quality-critical tasks |
+| Profile | Strategy | Savings vs Opus 5 | Best For |
+|---------|----------|-------------------|----------|
+| `free` | NVIDIA free tier — smart-routes across <!-- br:models.free -->6<!-- /br:models.free --> models (DeepSeek V4 Flash, Nemotron Nano Omni, Qwen3, Llama 4, Mistral, plus 2 hidden gpt-oss) | **100%** | Zero-cost testing, dev, prod |
+| `eco` | Cheapest capable model per tier | **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** | Cost-sensitive production |
+| `auto` | Best balance of cost/quality (default) | **<!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->%** | General use |
+| `premium` | Top-tier models (OpenAI, Anthropic) | 0% | Quality-critical tasks |
 
 ```typescript
 // Use premium models for complex tasks
@@ -279,23 +316,78 @@ console.log(result.model);  // 'anthropic/claude-opus-4.7'
 
 ### How ClawRouter Works
 
-ClawRouter uses a 14-dimension rule-based classifier to analyze each request:
-
-- **Token count** - Short vs long prompts
-- **Code presence** - Programming keywords
-- **Reasoning markers** - "prove", "step by step", etc.
-- **Technical terms** - Architecture, optimization, etc.
-- **Creative markers** - Story, poem, brainstorm, etc.
-- **Agentic patterns** - Multi-step, tool use indicators
-
-The classifier runs in <1ms, 100% locally, and routes to one of four tiers:
-
-| Tier | Example Tasks | Auto Profile Model |
-|------|---------------|-------------------|
-| SIMPLE | "What is 2+2?", definitions | moonshot/kimi-k2.5 |
-| MEDIUM | Code snippets, explanations | xai/grok-code-fast-1 |
-| COMPLEX | Architecture, long documents | google/gemini-3.1-pro |
-| REASONING | Proofs, multi-step reasoning | xai/grok-4-1-fast-reasoning |
+Since ClawRouter v0.12.242, Auto uses the deterministic **Router v3.4 portfolio
+strategy**: it classifies the task shape locally across
+<!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions
+(token count, code presence, reasoning markers, technical/creative terms,
+agentic patterns, …), enforces tool / vision / structured-output / context
+constraints as **hard filters**, then ranks an ordered candidate portfolio.
+The winner becomes `routing.model`; the rest surface as `routing.candidates`
+and feed SmartChat's transient-error fallback chain. Routing stays 100% local
+and deterministic — <1ms, no extra model call, no network hop.
+
+Classification still maps to one of four tiers (`routing.tier`). Each
+tier × profile has a designated primary (what the rules strategy —
+`routing.method: 'rules'`, the rollback lever — routes to directly, and what
+anchors the portfolio's candidate pool):
+
+| Tier | Example Tasks | ECO | AUTO | PREMIUM |
+|------|---------------|-----|------|---------|
+| SIMPLE | "What is 2+2?", definitions | free/gpt-oss-120b † (**FREE**) | gemini-2.5-flash ($0.30/$2.50) | kimi-k2.7 † ($0.95/$4.00) |
+| MEDIUM | Code snippets, explanations | gemini-3.1-flash-lite ($0.25/$1.50) | kimi-k2.7 ($0.95/$4.00) | gpt-5.3-codex ($1.75/$14.00) |
+| COMPLEX | Architecture, long documents | gemini-3.1-flash-lite ($0.25/$1.50) | gemini-3.1-pro ($2/$12) | claude-fable-5 ($10/$50) |
+| REASONING | Proofs, multi-step reasoning | grok-4-1-fast-reasoning † ($0.20/$0.50) | grok-4-1-fast-reasoning † ($0.20/$0.50) | claude-sonnet-4.6 ($3/$15) |
+
+† Withheld from `/v1/models` — the router still calls it by direct ID, but you
+will not find it on the public pricing page. The published savings claim is
+priced on visible models only.
+
+This table mirrors ClawRouter's tier configs at the version this SDK pins;
+the [ClawRouter README](https://github.com/BlockRunAI/ClawRouter#how-it-works)
+is the live source of truth as models and prices move.
+
+### Routing Metadata Reference
+
+Every `smartChat()` result carries the full decision on `result.routing`
+(type `RoutingDecision`) — enough to log, audit, or replay why a model was
+picked:
+
+| Field | Description |
+|-------|-------------|
+| `model` | Selected model id (same as `result.model`) |
+| `method` | `'portfolio'` (the Auto default), `'rules'` (rollback strategy), or `'llm'` |
+| `tier` | Task tier: `'SIMPLE'`, `'MEDIUM'`, `'COMPLEX'`, or `'REASONING'` |
+| `taskType` | Portfolio task classification: `'chat'`, `'extraction'`, `'code_edit'`, `'code_agent'`, `'tool_agent'`, `'debug'`, `'reasoning'`, `'reasoning_math'`, `'long_context'`, `'vision'`, … |
+| `candidates` | Ordered, capability-eligible models ranked by the portfolio router; the first entry is `model` |
+| `candidateScores` | Per-candidate score breakdown (`quality` / `cost` / `speed` / `reliability`), ordered with `candidates` |
+| `fallbacks` | The chain `chat()` walks on transient errors (timeout / network / 429 / 5xx) — `candidates` minus the primary, with ClawRouter's proxy-namespace `free/*` ids mapped to their `nvidia/*` gateway ids (SDK-computed) |
+| `savings` | 0–1 fraction saved vs the premium baseline |
+| `costEstimate` / `baselineCost` | Estimated cost of the pick vs that baseline, in USD |
+| `confidence` | Sigmoid-calibrated classifier confidence, 0–1 |
+| `routerVersion` | `'v3-portfolio'` or `'v2-rules'` |
+| `profile` | Routing profile applied: `'auto'`, `'eco'`, `'premium'`, or `'agentic'` |
+| `reasoning` | Human-readable explanation of the decision |
+| `tierConfigs` | The tier → primary/fallback map the decision was made against |
+
+### TypeScript Types
+
+`RoutingDecision`, `RoutingProfile`, `RoutingTier`, `RoutingTaskType`, and
+`RoutingTierConfig` are exported from `@blockrun/llm`. They are derived from
+[`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) — the
+routing engine ClawRouter bundles — pinned to the exact commit ClawRouter's
+published build inlines, and shipped **inlined in this SDK's declaration
+files**. You do not need to install `@blockrun/clawrouter` (or router-core,
+which is not on npm) for your project to typecheck against these types; the
+runtime package is only needed to actually call `smartChat()`.
+
+### Going Deeper
+
+- [ClawRouter](https://github.com/BlockRunAI/ClawRouter) — the router itself: OpenClaw plugin, standalone proxy for Cursor / continue.dev / any OpenAI-compatible client, Telegram integration
+- [Routing profiles in depth](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/routing-profiles.md) — ECO / AUTO / PREMIUM details
+- [How the routing engine works](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/smart-llm-router-14-dimension-classifier.md) — the classifier, dimension by dimension
+- [Router benchmark](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/llm-router-benchmark-46-models-sub-1ms-routing.md) — sub-1ms routing across the catalog
+- [ClawRouter vs OpenRouter](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/clawrouter-vs-openrouter-llm-routing-comparison.md) — head-to-head comparison
+- [`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) — the deterministic routing engine both share
 
 ## Available Models
 
@@ -858,7 +950,7 @@ const response2 = await client.chat('anthropic/claude-sonnet-4', 'Write a haiku'
 
 ### Smart Routing (ClawRouter)
 
-Save up to <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% on inference costs with intelligent model routing. ClawRouter uses a <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension rule-based scoring algorithm to select the cheapest model that can handle your request (<1ms, 100% local).
+Save up to <!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->% on inference costs with intelligent model routing. ClawRouter's deterministic portfolio router (v3.4, default since ClawRouter v0.12.242) classifies each request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions, applies hard capability filters, and ranks the cheapest capable models (<1ms, 100% local). Requires the optional peer dependency: `npm install @blockrun/clawrouter`.
 
 ```typescript
 import { LLMClient } from '@blockrun/llm';
@@ -870,7 +962,7 @@ const result = await client.smartChat('What is 2+2?');
 console.log(result.response);     // '4'
 console.log(result.model);        // 'google/gemini-2.5-flash'
 console.log(result.routing.tier); // 'SIMPLE'
-console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 87%'
+console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 88%'
 
 // Routing profiles
 const free = await client.smartChat('Hello!', { routingProfile: 'free' });     // Zero cost
@@ -883,7 +975,7 @@ const premium = await client.smartChat('Write a legal brief', { routingProfile:
 
 | Profile | Description | Best For |
 |---------|-------------|----------|
-| `free` | NVIDIA free tier (<!-- br:models.free -->8<!-- /br:models.free --> models, smart-routed) | Zero-cost testing, dev, prod |
+| `free` | NVIDIA free tier (<!-- br:models.free -->6<!-- /br:models.free --> models, smart-routed) | Zero-cost testing, dev, prod |
 | `eco` | Budget-optimized | Cost-sensitive workloads |
 | `auto` | Intelligent routing (default) | General use |
 | `premium` | Best quality models | Critical tasks |
@@ -1427,7 +1519,7 @@ The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch
 When you make an API call, the SDK automatically handles x402 payment. It signs a USDC transaction locally using your wallet private key (which never leaves your machine), and includes the payment proof in the request header. Settlement is non-custodial and instant on Base or Solana.
 
 ### What is smart routing / ClawRouter?
-ClawRouter is a built-in smart routing engine that analyzes your request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% on LLM costs compared to using premium models for every request.
+ClawRouter is the SDK's smart routing engine, shipped as the optional `@blockrun/clawrouter` peer dependency (`npm install @blockrun/clawrouter` — only `smartChat()` needs it). It analyzes your request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to <!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->% on LLM costs compared to using premium models for every request.
 
 ### Does it support streaming?
 Yes — as of v1.6.1. Use `client.chatCompletionStream()` for native streaming or `stream: true` in the OpenAI-compatible client. Payment is handled automatically: the SDK signs USDC payment before streaming begins, and caches payment requirements per model so subsequent calls skip the 402 round-trip (~200ms faster).

package/dist/index.cjs

@@ -48,6 +48,7 @@ __export(index_exports, {
   PortraitClient: () => PortraitClient,
   PriceClient: () => PriceClient,
   RPC_PRICE_USD: () => RPC_PRICE_USD,
+  RetiredEndpointError: () => RetiredEndpointError,
   RpcClient: () => RpcClient,
   SOLANA_NETWORK: () => SOLANA_NETWORK,
   SOLANA_WALLET_FILE_PATH: () => SOLANA_WALLET_FILE,
@@ -121,6 +122,12 @@ var BlockrunError = class extends Error {
     this.name = "BlockrunError";
   }
 };
+var RetiredEndpointError = class extends BlockrunError {
+  constructor(message) {
+    super(message);
+    this.name = "RetiredEndpointError";
+  }
+};
 var PaymentError = class extends BlockrunError {
   constructor(message) {
     super(message);
@@ -140,6 +147,35 @@ var APIError = class extends BlockrunError {
 
 // src/x402.ts
 var import_accounts = require("viem/accounts");
+
+// src/solana-deps.ts
+var INSTALL_HINT = "npm install @solana/web3.js @solana/spl-token   (or pnpm add / yarn add)";
+function missing(pkg, what, cause) {
+  return new Error(
+    `@blockrun/llm: ${what} requires the optional peer dependency "${pkg}", which is not installed.
+
+  ${INSTALL_HINT}
+
+Solana packages are optional peers so that consumers who only use Base/EVM payments do not inherit them. If you only make Base payments, you should not be reaching this code path \u2014 check which chain you passed.
+Original error: ${cause instanceof Error ? cause.message : String(cause)}`
+  );
+}
+async function loadSolanaWeb3(what) {
+  try {
+    return await import("@solana/web3.js");
+  } catch (err) {
+    throw missing("@solana/web3.js", what, err);
+  }
+}
+async function loadSplToken(what) {
+  try {
+    return await import("@solana/spl-token");
+  } catch (err) {
+    throw missing("@solana/spl-token", what, err);
+  }
+}
+
+// src/x402.ts
 var BASE_CHAIN_ID = 8453;
 var USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 var SOLANA_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
@@ -268,9 +304,17 @@ async function createPaymentPayload(privateKey, fromAddress, recipient, amount,
   return btoa(JSON.stringify(paymentData));
 }
 async function createSolanaPaymentPayload(secretKey, fromAddress, recipient, amount, feePayer, options = {}) {
-  const { Connection, PublicKey, TransactionMessage, VersionedTransaction, ComputeBudgetProgram } = await import("@solana/web3.js");
-  const { getAssociatedTokenAddress, createTransferCheckedInstruction } = await import("@solana/spl-token");
-  const { Keypair } = await import("@solana/web3.js");
+  const {
+    Connection,
+    PublicKey,
+    TransactionMessage,
+    VersionedTransaction,
+    ComputeBudgetProgram,
+    Keypair
+  } = await loadSolanaWeb3("createSolanaPaymentPayload()");
+  const { getAssociatedTokenAddress, createTransferCheckedInstruction } = await loadSplToken(
+    "createSolanaPaymentPayload()"
+  );
   const rpcUrl = options.rpcUrl || "https://sol.blockrun.ai/api/v1/solana/rpc";
   const connection = options.rpcHeaders ? new Connection(rpcUrl, { httpHeaders: options.rpcHeaders }) : new Connection(rpcUrl);
   const keypair = Keypair.fromSecretKey(secretKey);
@@ -564,14 +608,14 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.9.0";
+var SDK_VERSION = "3.11.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
 function isTransientError(err) {
   if (err instanceof PaymentError) return false;
   if (err instanceof APIError) {
-    return [502, 503, 504, 522, 524].includes(err.statusCode);
+    return [429, 502, 503, 504, 522, 524].includes(err.statusCode);
   }
   if (err instanceof Error) {
     if (err.name === "AbortError") return true;
@@ -698,8 +742,11 @@ var LLMClient = class _LLMClient {
   /**
    * Smart chat with automatic model routing.
    *
-   * Uses ClawRouter's 14-dimension rule-based scoring algorithm (<1ms, 100% local)
-   * to select the cheapest model that can handle your request.
+   * Uses ClawRouter's deterministic portfolio router (Router v3.4, the Auto
+   * default since v0.12.242): it classifies the task shape locally (<1ms, no
+   * extra model call), enforces capability constraints as hard filters, and
+   * ranks an ordered candidate portfolio — the cheapest model that can handle
+   * the request wins, and the rest become the transient-error fallback chain.
    *
    * @param prompt - User message
    * @param options - Optional chat and routing parameters
@@ -709,7 +756,8 @@ var LLMClient = class _LLMClient {
    * ```ts
    * const result = await client.smartChat('What is 2+2?');
    * console.log(result.response); // '4'
-   * console.log(result.model); // 'google/gemini-2.5-flash-lite'
+   * console.log(result.model); // 'google/gemini-3.5-flash'
+   * console.log(result.routing.method); // 'portfolio'
    * console.log(result.routing.savings); // 0.78 (78% savings)
    * ```
    *
@@ -741,11 +789,15 @@ var LLMClient = class _LLMClient {
       routingProfile: options?.routingProfile
     });
     const tierConfigs = decision.tierConfigs ?? DEFAULT_ROUTING_CONFIG.tiers;
-    const fullChain = getFallbackChain(decision.tier, tierConfigs);
-    const fallbacks = fullChain.filter(
-      (id) => id !== decision.model && modelPricing.has(id)
-    );
-    const response = await this.chat(decision.model, prompt, {
+    const ranked = decision.candidates?.length ? decision.candidates : [decision.model, ...getFallbackChain(decision.tier, tierConfigs)];
+    const callable = [];
+    for (const id of ranked) {
+      const resolved = !id.startsWith("free/") ? id : modelPricing.has(`nvidia/${id.slice(5)}`) ? `nvidia/${id.slice(5)}` : null;
+      if (resolved && !callable.includes(resolved)) callable.push(resolved);
+    }
+    const primary = callable[0] ?? decision.model;
+    const fallbacks = callable.slice(1);
+    const response = await this.chat(primary, prompt, {
       system: options?.system,
       maxTokens: options?.maxTokens,
       temperature: options?.temperature,
@@ -758,8 +810,8 @@ var LLMClient = class _LLMClient {
     });
     return {
       response,
-      model: decision.model,
-      routing: { ...decision, fallbacks }
+      model: primary,
+      routing: { ...decision, model: primary, fallbacks }
     };
   }
   /**
@@ -1783,20 +1835,38 @@ var LLMClient = class _LLMClient {
   }
   // ── PM convenience helpers (Predexon v2) ─────────────────────────────────
   // Thin wrappers over pm() / pmQuery() for the most common v2 endpoints.
-  /** List canonical cross-venue markets (Predexon v2). Tier 1 ($0.001/call).
-   * Filter with venue, status, category, league, event_id, pagination_key. */
-  async pmMarkets(params) {
-    return this.pm("markets", params);
+  /** RETIRED — `/v1/pm/markets` no longer exists.
+   *
+   * Predexon sunset market matching on 2026-07-20 and the whole canonical layer
+   * went with it, so this path returns 410 upstream. Use
+   * `pm("markets/search", { q })` for cross-venue lookups.
+   *
+   * Kept as a throwing stub rather than deleted so upgrading does not break
+   * property access; it throws before any network I/O.
+   *
+   * @throws {RetiredEndpointError} always. */
+  async pmMarkets(_params) {
+    throw new RetiredEndpointError(
+      '/v1/pm/markets was sunset by Predexon on 2026-07-20 (upstream 410). Use pm("markets/search", { q }) for cross-venue lookups.'
+    );
   }
-  /** List venue-native executable listings flattened across canonical markets
-   * (Predexon v2). Tier 1 ($0.001/call). */
-  async pmListings(params) {
-    return this.pm("markets/listings", params);
+  /** RETIRED — `/v1/pm/markets/listings` no longer exists (410, sunset
+   * 2026-07-20 with market matching). Use `pm("markets/search", { q })`.
+   *
+   * @throws {RetiredEndpointError} always. */
+  async pmListings(_params) {
+    throw new RetiredEndpointError(
+      '/v1/pm/markets/listings was sunset by Predexon on 2026-07-20 (upstream 410). Use pm("markets/search", { q }) for cross-venue lookups.'
+    );
   }
-  /** Resolve a canonical Predexon outcome ID to its market context and venue
-   * listings. Tier 1 ($0.001/call). */
-  async pmOutcome(predexonId) {
-    return this.pm(`outcomes/${predexonId}`);
+  /** RETIRED — `/v1/pm/outcomes/{predexonId}` no longer exists (410, sunset
+   * 2026-07-20 with market matching). Use `pm("markets/search", { q })`.
+   *
+   * @throws {RetiredEndpointError} always. */
+  async pmOutcome(_predexonId) {
+    throw new RetiredEndpointError(
+      '/v1/pm/outcomes/{predexon_id} was sunset by Predexon on 2026-07-20 (upstream 410). Use pm("markets/search", { q }) for cross-venue lookups.'
+    );
   }
   /** Polymarket markets with cursor-based keyset pagination (use pagination_key).
    * Tier 1 ($0.001/call). */
@@ -1808,12 +1878,18 @@ var LLMClient = class _LLMClient {
   async pmPolymarketEventsKeyset(params) {
     return this.pm("polymarket/events/keyset", params);
   }
-  /** List available sports categories. Tier 1 ($0.001/call). */
+  /** List available sports categories. Tier 1 ($0.001/call).
+   *
+   * NOTE: upstream returns 500 for every `sports/*` path as of 2026-08-04.
+   * The route still resolves, so this works again the moment Predexon restores
+   * it, but do not build on it yet. */
   async pmSportsCategories() {
     return this.pm("sports/categories");
   }
   /** List sports markets grouped by game. Filter with league, sport_type,
-   * status, venue. Tier 1 ($0.001/call). */
+   * status, venue. Tier 1 ($0.001/call).
+   *
+   * NOTE: upstream returns 500 for every `sports/*` path as of 2026-08-04. */
   async pmSportsMarkets(params) {
     return this.pm("sports/markets", params);
   }
@@ -4894,7 +4970,7 @@ var os3 = __toESM(require("os"), 1);
 var WALLET_DIR2 = path3.join(os3.homedir(), ".blockrun");
 var SOLANA_WALLET_FILE = path3.join(WALLET_DIR2, ".solana-session");
 async function createSolanaWallet() {
-  const { Keypair } = await import("@solana/web3.js");
+  const { Keypair } = await loadSolanaWeb3("Solana wallet operations");
   const bs58 = await import("bs58");
   const keypair = Keypair.generate();
   return {
@@ -4951,7 +5027,7 @@ async function solanaKeyToBytes(privateKey) {
   }
 }
 async function solanaPublicKey(privateKey) {
-  const { Keypair } = await import("@solana/web3.js");
+  const { Keypair } = await loadSolanaWeb3("Solana wallet operations");
   const bytes = await solanaKeyToBytes(privateKey);
   return Keypair.fromSecretKey(bytes).publicKey.toBase58();
 }
@@ -6245,6 +6321,7 @@ var AnthropicClient = class {
   PortraitClient,
   PriceClient,
   RPC_PRICE_USD,
+  RetiredEndpointError,
   RpcClient,
   SOLANA_NETWORK,
   SOLANA_WALLET_FILE_PATH,