@blockrun/franklin 3.46.0 → 3.48.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -54,8 +54,8 @@ Built by the [BlockRun](https://blockrun.ai) team. Apache-2.0. TypeScript. Ships
54
54
  > **YOPO — You Only Pay Outcome**
55
55
  >
56
56
  > Not a subscription (pay for access). Not a generic pay-per-call (pay for trying).
57
- > You pay only for the work Franklin Agent delivers. Provider cost + 5%, settled per action
58
- > in USDC. No monthly fees. No rate limits. No overdraft.
57
+ > You pay only for the work Franklin Agent delivers. Chat is provider cost with no markup, plus $0.001
58
+ > per call; media carries 5%. Settled per action in USDC. No monthly fees. No rate limits. No overdraft.
59
59
 
60
60
  ---
61
61
 
@@ -248,7 +248,7 @@ use the [dashboard](https://user.blockrun.ai/dashboard).
248
248
  | ----------------------- | -------------------------------------------- | ------------------------------------ |
249
249
  | AI subscription | Access. Paid whether you use it or not. | $20–200/month, rate-limited. |
250
250
  | Pay-per-call (OpenAI API, etc.) | Every attempt — even failed ones. | Hidden cost from retries, dead ends. |
251
- | **Franklin Agent (YOPO)** | **The outcome.** Each signed micropayment. | **Provider cost + 5%. No more.** |
251
+ | **Franklin Agent (YOPO)** | **The outcome.** Each signed micropayment. | **Provider cost on chat, no markup, + $0.001/call. Media +5%.** |
252
252
 
253
253
  Three consequences fall out of this:
254
254
 
@@ -382,7 +382,7 @@ Every tool call is itemized. Every token is priced. When the wallet hits zero, F
382
382
 
383
383
  ## Smart Router
384
384
 
385
- **<!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> models. One decision. Zero guesswork.**
385
+ **<!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models. One decision. Zero guesswork.**
386
386
 
387
387
  You don't pick models. Franklin picks for you.
388
388
 
@@ -463,7 +463,7 @@ No email. No phone. No KYC. Your Solana or Base address is your account — port
463
463
  | Writes code | ✅ | ✅ | ⚠️ | ✅ |
464
464
  | **Spends money for you** | ❌ | ❌ | ❌ | ✅ **USDC wallet, x402** |
465
465
  | **Buys data + APIs + images + search** | ❌ | ❌ | ❌ | ✅ **55+ APIs, one wallet** |
466
- | Picks best model per task | ❌ single-vendor | ❌ plan-tied | ❌ | ✅ **Smart Router, <!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> models** |
466
+ | Picks best model per task | ❌ single-vendor | ❌ plan-tied | ❌ | ✅ **Smart Router, <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models** |
467
467
  | Pricing model | Subscription | Subscription | Subscription | **YOPO** — per outcome, USDC |
468
468
  | Monthly fee | $20–$200 | $20–$40 | $20+ | **$0** |
469
469
  | Rate-limited | Yes | Yes | Yes | No — limited only by wallet |
@@ -491,14 +491,14 @@ Ask "what's BTC looking like?" — Franklin fetches live price data, computes RS
491
491
  **🎨 AI image generation**
492
492
  Ask "generate a logo" — Franklin calls DALL-E / GPT Image, saves the result locally, paid from your wallet.
493
493
 
494
- **🧠 <!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> models via one wallet**
494
+ **🧠 <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models via one wallet**
495
495
  Anthropic, OpenAI, Google, xAI, DeepSeek, GLM, Kimi, Minimax, NVIDIA free tier. One wallet, one interface, automatic fallback.
496
496
 
497
497
  **💳 x402 micropayments (YOPO)**
498
498
  HTTP 402 native. Every paid action is a signed USDC micropayment via EIP-712 — non-custodial, your keys never leave your machine. YOPO: you pay only for outcomes.
499
499
 
500
500
  **🧠 Learned model router**
501
- Trained on 2M+ real requests. Classifies your task and picks the best model from <!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> LLMs. Four profiles (auto/eco/premium/free). Adapts to your usage over time.
501
+ Trained on 2M+ real requests. Classifies your task and picks the best model from <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> LLMs. Four profiles (auto/eco/premium/free). Adapts to your usage over time.
502
502
 
503
503
  </td>
504
504
  <td width="50%" valign="top">
@@ -544,6 +544,12 @@ Core is workflow-agnostic. Add new verticals without touching the loop. Discover
544
544
  | `/insights [--days N]` | Rich usage analytics |
545
545
  | `/help` | Full command list |
546
546
 
547
+ `/model` takes a shortcut or any full gateway id. The newest models have
548
+ explicit version shortcuts: `opus-5.5`, `sonnet-5.5`, `fable-5.1`,
549
+ `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-5.1`, `grok-4.7` and `grok-4.6`
550
+ (e.g. `/model gpt-6-sol` or `/model anthropic/claude-opus-5.5`). Bare aliases
551
+ like `opus`, `gpt` and `grok` keep their current targets.
552
+
547
553
  ---
548
554
 
549
555
  ## How it works
@@ -554,13 +560,13 @@ Core is workflow-agnostic. Add new verticals without touching the loop. Discover
554
560
  │ Intent → Smart Router → Tool Use → Spend Control → Result │
555
561
  ├──────────────────────────────────────────────────────────────┤
556
562
  │ Learned Router │
557
- │ 2M+ requests · <!-- br:models.chatVisible@live -->78<!-- /br:models.chatVisible@live --> models · category detection · Elo scores │
563
+ │ 2M+ requests · <!-- br:models.chatVisible@live -->82<!-- /br:models.chatVisible@live --> models · category detection · Elo scores │
558
564
  ├──────────────────────────────────────────────────────────────┤
559
565
  │ Agent Loop │
560
566
  │ 16 tools · Sessions · Compaction · Pricing · Plugin SDK │
561
567
  ├──────────────────────────────────────────────────────────────┤
562
568
  │ BlockRun Gateway │
563
- │ <!-- br:models.chatVisible@live -->78<!-- /br:models.chatVisible@live --> LLMs · CoinGecko · Search · Image APIs · paid services │
569
+ │ <!-- br:models.chatVisible@live -->82<!-- /br:models.chatVisible@live --> LLMs · CoinGecko · Search · Image APIs · paid services │
564
570
  ├──────────────────────────────────────────────────────────────┤
565
571
  │ x402 Micropayment Protocol │
566
572
  │ HTTP 402 · USDC on Solana & Base · signed payment payloads │
@@ -604,7 +610,7 @@ src/
604
610
  ├── stats/ Usage tracking + insights engine
605
611
  ├── ui/ Ink-based terminal UI
606
612
  ├── proxy/ Payment proxy for external tools
607
- ├── router/ Learned model router (<!-- br:models.chatVisible@live -->78<!-- /br:models.chatVisible@live --> models, Elo scoring)
613
+ ├── router/ Learned model router (<!-- br:models.chatVisible@live -->82<!-- /br:models.chatVisible@live --> models, Elo scoring)
608
614
  ├── wallet/ Wallet management (Base + Solana)
609
615
  ├── mcp/ MCP server auto-discovery
610
616
  └── commands/ CLI subcommands
@@ -715,6 +721,35 @@ For the recommended live validation order and failure triage, see [docs/live-e2e
715
721
 
716
722
  ---
717
723
 
724
+ ## Shared model catalog
725
+
726
+ Franklin uses [BlockRun Model Core](https://github.com/BlockRunAI/model-catalog)
727
+ for model metadata, picker policy and price estimates. The runtime dependency
728
+ is pinned to an immutable commit. On refresh, Franklin reads the public policy
729
+ snapshot and the active gateway's catalog, so new models and prices can appear
730
+ without a Franklin release. Base, Solana and API accounts have separate caches.
731
+ The default picker shows Auto and curated groups; other available chat models
732
+ remain accessible through +more / Ctrl+A.
733
+
734
+ Existing Franklin shortcuts, including free aliases, retain their model targets.
735
+ Shared policy can add new shortcuts but cannot retarget one Franklin already
736
+ ships. Gateway price estimates still refresh for the selected model; a stable
737
+ shortcut does not freeze that model's price. Historical explicit IDs and cost
738
+ records remain usable.
739
+
740
+ Policy and gateway requests run concurrently, each with a four-second deadline.
741
+ Successful refreshes are cached for five minutes. If the policy host is
742
+ unreachable, Franklin keeps the last good policy and still refreshes live gateway
743
+ rows. If the gateway fails, the last valid catalog is retained; a cold start can
744
+ use the bundled snapshot, which is not presented as live gateway data. CLI
745
+ startup warms the catalog in the background.
746
+
747
+ `BLOCKRUN_MODEL_CATALOG_URL` overrides the policy snapshot URL; an empty value
748
+ disables remote policy updates. `FRANKLIN_CATALOG_OFFLINE=1` uses bundled data
749
+ without catalog network requests. Payment signing and settlement remain in
750
+ Franklin and its payment SDK. Auto routing's candidate policy remains separate
751
+ from the shared catalog.
752
+
718
753
  ## License
719
754
 
720
755
  Apache-2.0. See [LICENSE](LICENSE).
@@ -279,7 +279,7 @@ Use the built-in tools so the right host and credential are applied. Never switc
279
279
  - \`GET /.well-known/x402\` — x402 resource list with prices
280
280
 
281
281
  **LLM (POST, billed to ${chargedBy})**
282
- - \`POST /v1/chat/completions\` — OpenAI-compatible. Body: \`{ model, messages, stream?, tools?, max_tokens?, temperature? }\`. \`model\` MUST come from \`GET /v1/models\` (real frontier examples on the gateway, verified live 2026-08-30: \`anthropic/claude-sonnet-5\`, \`anthropic/claude-opus-5\`, \`openai/gpt-5.6-sol\`, \`deepseek/deepseek-v4-pro\`, \`zai/glm-5.3\`, \`zai/glm-5.3-flash\`, \`xai/grok-4.5\`, \`qwen/qwen3.7-flash\`, \`nvidia/nemotron-3-nano-omni-30b-a3b-reasoning\` (free, the only free id on BOTH the Base and Solana gateways — the other free models are Base-only)). Do NOT invent versions like \`openai/gpt-5.1\` or \`xai/grok-5\` — those don't exist; the gateway 400s with the valid list in the error body, so when in doubt fetch \`GET /v1/models\` first.
282
+ - \`POST /v1/chat/completions\` — OpenAI-compatible. Body: \`{ model, messages, stream?, tools?, max_tokens?, temperature? }\`. \`model\` MUST come from \`GET /v1/models\` (real frontier examples on the gateway, verified live 2026-08-30: \`anthropic/claude-sonnet-5\`, \`anthropic/claude-opus-5\`, \`openai/gpt-5.6-sol\`, \`deepseek/deepseek-v4-pro\`, \`zai/glm-5.3\`, \`zai/glm-5.3-flash\`, \`xai/grok-4.5\`, \`qwen/qwen3.7-flash\`, \`nvidia/nemotron-3-nano-omni-30b-a3b-reasoning\` (free, the only free id on BOTH the Base and Solana gateways — the other free models are Base-only)). Do NOT invent versions like \`openai/gpt-7\` or \`xai/grok-5\` — those don't exist; the gateway 400s with the valid list in the error body, so when in doubt fetch \`GET /v1/models\` first.
283
283
  - \`POST /v1/messages\` — Anthropic-compatible. Body: \`{ model, messages, max_tokens, system?, tools? }\`.
284
284
 
285
285
  **Media (POST, billed to ${chargedBy}; GET to poll async jobs)**
@@ -158,16 +158,17 @@ async function exaAnswerTry(query, client) {
158
158
  // tool framework because prefetch runs outside the agent loop — no
159
159
  // permission prompt, no streaming.
160
160
  const { loadChain } = await import('../config.js');
161
- const { gatewayBase, gatewayHeaders } = await import('../payments/auth-mode.js');
161
+ const { gatewayBase, gatewayHeaders, walletMayPay } = await import('../payments/auth-mode.js');
162
162
  const chain = loadChain();
163
163
  const apiUrl = gatewayBase();
164
164
  void client; // (future: unify the paid-endpoint client so we reuse wallet caching)
165
+ const requestHeaders = { 'Content-Type': 'application/json', ...gatewayHeaders() };
165
166
  const res = await fetch(`${apiUrl}/v1/exa/answer`, {
166
167
  method: 'POST',
167
- headers: { 'Content-Type': 'application/json', ...gatewayHeaders() },
168
+ headers: requestHeaders,
168
169
  body: JSON.stringify({ query }),
169
170
  });
170
- if (res.status === 402) {
171
+ if (res.status === 402 && walletMayPay(requestHeaders)) {
171
172
  const payHdr = await extractPaymentReq(res);
172
173
  if (!payHdr)
173
174
  return { text: null, costUsd: 0 };
package/dist/agent/llm.js CHANGED
@@ -5,7 +5,7 @@
5
5
  */
6
6
  import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
7
7
  import { USER_AGENT } from '../config.js';
8
- import { gatewayHeaders } from '../payments/auth-mode.js';
8
+ import { gatewayHeaders, walletMayPay } from '../payments/auth-mode.js';
9
9
  import { appendSettlementRow } from '../stats/cost-log.js';
10
10
  import { routeRequest, parseRoutingProfile } from '../router/index.js';
11
11
  import { ThinkTagStripper } from './think-tag-stripper.js';
@@ -657,10 +657,9 @@ export class ModelClient {
657
657
  body,
658
658
  signal: requestController.signal,
659
659
  }), requestController, createModelTimeoutError('request', request.model, requestTimeoutMs), requestTimeoutMs);
660
- // Handle x402 payment
661
- // Account 402 is a credit refusal. Only a request that started on
662
- // the wallet rail may initiate a signing handshake.
663
- if (response.status === 402 && !headers.Authorization) {
660
+ // Handle x402 payment. An account 402 is a credit refusal, never a
661
+ // challenge the wallet may answer.
662
+ if (response.status === 402 && walletMayPay(headers)) {
664
663
  if (this.debug)
665
664
  console.error('[franklin] Payment required — signing...');
666
665
  const signedPayment = await this.signPayment(response, request.model);
@@ -734,7 +733,8 @@ export class ModelClient {
734
733
  body: retryBody,
735
734
  signal: requestController.signal,
736
735
  }), requestController, createModelTimeoutError('request', request.model, requestTimeoutMs), requestTimeoutMs);
737
- if (response.status === 402) {
736
+ // A retry must preserve the request's original payment rail too.
737
+ if (response.status === 402 && walletMayPay(headers)) {
738
738
  const signedPayment = await this.signPayment(response, request.model);
739
739
  if (!signedPayment) {
740
740
  yield { kind: 'error', payload: { message: 'Payment signing failed' } };
@@ -199,6 +199,11 @@ const MODEL_CONTEXT_WINDOWS = {
199
199
  // a real >200k call has been verified end-to-end.
200
200
  // Fable 5 / Sonnet 5 advertise 1M at the gateway; keep the 200k safe baseline
201
201
  // (same rationale as Opus above) until a real >200k call is verified.
202
+ // Fable 5.1 / Opus 5.5 / Sonnet 5.5 (2026-10) also advertise 1M; same
203
+ // 200k baseline. Without a row the live catalog's 1M would win here.
204
+ 'anthropic/claude-fable-5.1': 200_000,
205
+ 'anthropic/claude-opus-5.5': 200_000,
206
+ 'anthropic/claude-sonnet-5.5': 200_000,
202
207
  'anthropic/claude-fable-5': 200_000,
203
208
  'anthropic/claude-opus-5': 200_000,
204
209
  'anthropic/claude-opus-4.8': 200_000,
@@ -217,6 +222,12 @@ const MODEL_CONTEXT_WINDOWS = {
217
222
  // gpt-5.5 advertises 1.05M context at the gateway, but Franklin keeps the
218
223
  // conservative 128k baseline matching every other gpt-5.x line — bump in
219
224
  // a separate change once a real >128k call has been verified end-to-end.
225
+ // GPT-6 (1.05M advertised; input above 272K bills at 2x) and GPT-5.1 (400K
226
+ // advertised) take the same 128k baseline until verified end-to-end.
227
+ 'openai/gpt-6-astra': 128_000,
228
+ 'openai/gpt-6-sol': 128_000,
229
+ 'openai/gpt-6-luna': 128_000,
230
+ 'openai/gpt-5.1': 128_000,
220
231
  'openai/gpt-5.6-sol': 128_000,
221
232
  'openai/gpt-5.6-terra': 128_000,
222
233
  'openai/gpt-5.6-luna': 128_000,
@@ -256,6 +267,8 @@ const MODEL_CONTEXT_WINDOWS = {
256
267
  // xAI. grok-4.5 / 4.3 / build were missing until 2026-08-20: neither matches
257
268
  // any inference pattern below, so a cold catalog cache fell through to the
258
269
  // blind 128k default and compacted a 500K–1M window ~4-8x too early.
270
+ 'xai/grok-4.7': 500_000,
271
+ 'xai/grok-4.6': 500_000,
259
272
  'xai/grok-4.5': 500_000,
260
273
  'xai/grok-4.3': 1_000_000,
261
274
  'xai/grok-build-0.1': 256_000,
@@ -1,7 +1,7 @@
1
1
  import chalk from 'chalk';
2
2
  import { loadChain } from '../config.js';
3
3
  import { gatewayBase } from '../payments/auth-mode.js';
4
- import { getGatewayModels, GATEWAY_MARGIN, } from '../gateway-models.js';
4
+ import { getGatewayModels, GATEWAY_MARGIN, GATEWAY_TRANSACTION_FEE_USD, } from '../gateway-models.js';
5
5
  /**
6
6
  * `franklin models` — the live catalog.
7
7
  *
@@ -172,6 +172,7 @@ export async function modelsCommand() {
172
172
  const unknown = models.filter(m => !known.has(m.billing_mode));
173
173
  printSection('Other billing modes (not yet modelled by this Franklin build)', unknown, m => chalk.dim(`${m.billing_mode}: ${JSON.stringify(m.pricing)}`));
174
174
  const margin = Math.round((GATEWAY_MARGIN - 1) * 100);
175
- console.log(chalk.dim(`${models.length} models available. Prices are gateway list — x402 settlement adds ~${margin}%.`));
175
+ console.log(chalk.dim(`${models.length} models available. Prices are gateway list — chat adds only the ` +
176
+ `$${GATEWAY_TRANSACTION_FEE_USD} per-call fee; media adds ${margin}% + $${GATEWAY_TRANSACTION_FEE_USD}.`));
176
177
  console.log(`${chalk.dim('Use:')} ${chalk.bold('franklin start --model <model-id>')}`);
177
178
  }
@@ -1,4 +1,5 @@
1
1
  import chalk from 'chalk';
2
+ import { refreshModelCatalog } from '../model-catalog.js';
2
3
  import fs from 'node:fs';
3
4
  import path from 'node:path';
4
5
  import { getOrCreateWallet, getOrCreateSolanaWallet } from '@blockrun/llm';
@@ -72,6 +73,9 @@ export async function startCommand(options) {
72
73
  chain = sessMeta.chain;
73
74
  }
74
75
  }
76
+ // Warm in the background: bundled data already covers startup, and the picker
77
+ // and pricing tables update in place when the refresh lands.
78
+ refreshModelCatalog({ network: chain }).catch(() => { });
75
79
  const apiUrl = gatewayBase();
76
80
  const config = loadConfig();
77
81
  // Resolve model. Priority: explicit --model > resumed session's model > user
@@ -59,6 +59,7 @@
59
59
  * (FREE_POOL_CONTEXT_FLOOR).
60
60
  * 4. No free vision — see freeVisionModel().
61
61
  */
62
+ import { getModelCatalog } from './model-catalog.js';
62
63
  import { peekGatewayModel } from './gateway-models.js';
63
64
  import { FREE_DEFAULT_MODEL, FREE_POOL_CONTEXT_FLOOR, FREE_PREFERENCE_ORDER, } from './free-models.constants.js';
64
65
  // Re-exported so every consumer keeps importing from ONE place. The constants
@@ -356,7 +357,7 @@ export function isFreeModelId(id) {
356
357
  return true;
357
358
  if (!id)
358
359
  return false;
359
- const entry = peekGatewayModel(id);
360
+ const entry = peekGatewayModel(id) ?? getModelCatalog().models.find(model => model.id === id);
360
361
  if (entry)
361
362
  return entry.billing_mode === 'free';
362
363
  if (id in FREE_MODEL_CONTEXT_WINDOWS)
@@ -9,8 +9,10 @@
9
9
  *
10
10
  * Per gateway team (2026-04-22): every model returns `billing_mode` and
11
11
  * a mode-specific `pricing` object. Dispatch on billing_mode to compute
12
- * an estimated charge. x402 adds a fixed 5% margin on top of base price,
13
- * plus a flat $0.001 per-transaction fee on paid calls (Base since
12
+ * an estimated charge. Token-metered chat is billed at the provider's list
13
+ * rate with no margin (since 2026-09-04); media (image/video/music/speech/
14
+ * sfx) and Live Search carry a 5% platform fee. Every paid call adds a flat
15
+ * $0.001 per-transaction fee (Base since
14
16
  * 2026-07-10; Solana instead enforces a $0.001 minimum per call with no
15
17
  * service fee — the flat-fee estimate over-counts there by ≤$0.001, which
16
18
  * is the safe direction for budget tracking).
@@ -100,11 +102,15 @@ export declare function getGatewayModels(): Promise<GatewayModel[]>;
100
102
  export declare function getModelsByCategory(category: string): Promise<GatewayModel[]>;
101
103
  /** Find a single model by ID, or null if it's not in the current catalog. */
102
104
  export declare function findModel(id: string): Promise<GatewayModel | null>;
103
- /** x402 gateway's fixed margin percentage applied on top of the base price. */
105
+ /**
106
+ * Platform fee multiplier on MEDIA (per_image / per_second / per_track /
107
+ * per_character / per_generation / flat) list prices. Token-metered chat
108
+ * carries no margin — the gateway bills it at the provider's list rate.
109
+ */
104
110
  export declare const GATEWAY_MARGIN = 1.05;
105
111
  /**
106
112
  * Flat per-transaction fee (USD) the gateway adds on top of the margined
107
- * price on every PAID call (no-op on $0 calls). Introduced upstream
113
+ * (media) or list (chat) price on every PAID call (no-op on $0 calls). Introduced upstream
108
114
  * 2026-07-10, briefly $0.002, back to $0.001 since 2026-07-29
109
115
  * (blockrun src/lib/transaction-fee.ts).
110
116
  */
@@ -119,7 +125,7 @@ export interface EstimateContext {
119
125
  }
120
126
  /**
121
127
  * Estimated USD charge to generate one response from this model under the
122
- * given context. Includes the 5% gateway margin and the flat $0.001
128
+ * given context. Includes the 5% media platform fee and the flat $0.001
123
129
  * per-transaction fee on paid calls. Returns 0 for free and token-metered
124
130
  * (paid) models where a pre-call estimate isn't meaningful.
125
131
  */
@@ -9,23 +9,24 @@
9
9
  *
10
10
  * Per gateway team (2026-04-22): every model returns `billing_mode` and
11
11
  * a mode-specific `pricing` object. Dispatch on billing_mode to compute
12
- * an estimated charge. x402 adds a fixed 5% margin on top of base price,
13
- * plus a flat $0.001 per-transaction fee on paid calls (Base since
12
+ * an estimated charge. Token-metered chat is billed at the provider's list
13
+ * rate with no margin (since 2026-09-04); media (image/video/music/speech/
14
+ * sfx) and Live Search carry a 5% platform fee. Every paid call adds a flat
15
+ * $0.001 per-transaction fee (Base since
14
16
  * 2026-07-10; Solana instead enforces a $0.001 minimum per call with no
15
17
  * service fee — the flat-fee estimate over-counts there by ≤$0.001, which
16
18
  * is the safe direction for budget tracking).
17
19
  */
18
- import { loadChain, USER_AGENT } from './config.js';
19
- import { gatewayBase, gatewayHeaders } from './payments/auth-mode.js';
20
+ import { refreshModelCatalog, clearModelCatalogCache, getModelCatalogIdentity } from './model-catalog.js';
20
21
  // ─── Cache ──────────────────────────────────────────────────────────────
21
22
  const CACHE_TTL_MS = 5 * 60_000; // 5 min — gateway rotates models, but not often
22
- const FETCH_TIMEOUT_MS = 4_000; // one-shot on init; don't let a slow gateway hang startup
23
- let cache = null;
24
- let inflight = null;
23
+ const cache = new Map();
24
+ const inflight = new Map();
25
25
  /** Test / reset helper. */
26
26
  export function clearGatewayModelsCache() {
27
- cache = null;
28
- inflight = null;
27
+ cache.clear();
28
+ inflight.clear();
29
+ clearModelCatalogCache();
29
30
  }
30
31
  /**
31
32
  * Synchronous, cache-only lookup. Returns null when the catalog has never been
@@ -52,25 +53,11 @@ export function clearGatewayModelsCache() {
52
53
  * Treat this as "better than a blind default", nothing more.
53
54
  */
54
55
  export function peekGatewayModel(id) {
55
- if (!cache)
56
- return null;
57
- // A catalog fetched for a different chain is not evidence about this one.
58
- if (cache.chain !== currentChain())
59
- return null;
60
- return cache.models.find(m => m.id === id) ?? null;
61
- }
62
- /** loadChain() with the throw swallowed — this is a hot, sync path. */
63
- function currentChain() {
64
- try {
65
- return loadChain();
66
- }
67
- catch {
68
- return 'base';
69
- }
56
+ return cache.get(getModelCatalogIdentity())?.models.find(m => m.id === id) ?? null;
70
57
  }
71
58
  /** Test helper — seed the cache without a network call. */
72
59
  export function __primeGatewayModelsCache(models) {
73
- cache = { models, expiresAt: Date.now() + CACHE_TTL_MS, chain: currentChain() };
60
+ cache.set(getModelCatalogIdentity(), { models, expiresAt: Date.now() + CACHE_TTL_MS });
74
61
  }
75
62
  /**
76
63
  * Fire-and-forget catalog warm. Populates the cache so the sync peek above has
@@ -81,33 +68,13 @@ export function warmGatewayModelsCache() {
81
68
  }
82
69
  // ─── Fetch ──────────────────────────────────────────────────────────────
83
70
  async function doFetch() {
84
- const chain = loadChain();
85
- // `gatewayBase()` already carries the `/api` segment on the x402 hosts and
86
- // deliberately omits it on the API-key host, so append `/v1/...` to it
87
- // directly rather than stripping and re-adding a prefix that only one of the
88
- // two hosts has.
89
- //
90
- // The schema/JSON gate: without ?format=json the gateway returns a
91
- // typed schema placeholder instead of the data envelope. Documented
92
- // quirk across other endpoints too.
93
- const url = `${gatewayBase()}/v1/models?format=json`;
94
- const ctrl = new AbortController();
95
- const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
96
- try {
97
- const res = await fetch(url, {
98
- signal: ctrl.signal,
99
- headers: { ...gatewayHeaders(), 'User-Agent': USER_AGENT, Accept: 'application/json' },
100
- });
101
- if (!res.ok)
102
- throw new Error(`Gateway models list returned HTTP ${res.status}`);
103
- const body = (await res.json());
104
- if (!Array.isArray(body.data))
105
- throw new Error('Gateway models list missing data[]');
106
- return body.data;
107
- }
108
- finally {
109
- clearTimeout(timer);
110
- }
71
+ const state = await refreshModelCatalog();
72
+ // Bundled rows are not gateway evidence. Surface the failure so callers keep
73
+ // their existing fallbacks (stale cache, static picker) instead of treating
74
+ // the packaged snapshot as a live catalog for five minutes.
75
+ if (state.source !== 'live')
76
+ throw new Error(state.lastError ?? 'Gateway model catalog unavailable');
77
+ return state.models;
111
78
  }
112
79
  /**
113
80
  * Fetch the model catalog, honoring the 5-minute cache. Concurrent callers
@@ -115,24 +82,27 @@ async function doFetch() {
115
82
  * the gateway at process start.
116
83
  */
117
84
  export async function getGatewayModels() {
118
- if (cache && cache.chain === currentChain() && cache.expiresAt > Date.now())
119
- return cache.models;
120
- if (inflight)
121
- return inflight;
122
- inflight = doFetch()
123
- .then(models => {
124
- cache = { models, expiresAt: Date.now() + CACHE_TTL_MS, chain: currentChain() };
85
+ const identity = getModelCatalogIdentity();
86
+ const previous = cache.get(identity);
87
+ if (previous && previous.expiresAt > Date.now())
88
+ return previous.models;
89
+ const pending = inflight.get(identity);
90
+ if (pending)
91
+ return pending;
92
+ const request = doFetch().then(models => {
93
+ // A request completing after an account/chain switch only updates its own cache.
94
+ cache.set(identity, { models, expiresAt: Date.now() + CACHE_TTL_MS });
125
95
  return models;
126
- })
127
- .catch(err => {
128
- // On failure, keep the last good cache if we have one (serve stale
129
- // rather than break the agent). Only hard-fail cold start.
130
- if (cache)
131
- return cache.models;
96
+ }).catch(err => {
97
+ if (previous)
98
+ return previous.models;
132
99
  throw err;
133
- })
134
- .finally(() => { inflight = null; });
135
- return inflight;
100
+ }).finally(() => {
101
+ if (inflight.get(identity) === request)
102
+ inflight.delete(identity);
103
+ });
104
+ inflight.set(identity, request);
105
+ return request;
136
106
  }
137
107
  /** Return models filtered to a specific category (e.g. 'image', 'video', 'music'). */
138
108
  export async function getModelsByCategory(category) {
@@ -145,18 +115,22 @@ export async function findModel(id) {
145
115
  return all.find(m => m.id === id) ?? null;
146
116
  }
147
117
  // ─── Cost estimation ────────────────────────────────────────────────────
148
- /** x402 gateway's fixed margin percentage applied on top of the base price. */
118
+ /**
119
+ * Platform fee multiplier on MEDIA (per_image / per_second / per_track /
120
+ * per_character / per_generation / flat) list prices. Token-metered chat
121
+ * carries no margin — the gateway bills it at the provider's list rate.
122
+ */
149
123
  export const GATEWAY_MARGIN = 1.05;
150
124
  /**
151
125
  * Flat per-transaction fee (USD) the gateway adds on top of the margined
152
- * price on every PAID call (no-op on $0 calls). Introduced upstream
126
+ * (media) or list (chat) price on every PAID call (no-op on $0 calls). Introduced upstream
153
127
  * 2026-07-10, briefly $0.002, back to $0.001 since 2026-07-29
154
128
  * (blockrun src/lib/transaction-fee.ts).
155
129
  */
156
130
  export const GATEWAY_TRANSACTION_FEE_USD = 0.001;
157
131
  /**
158
132
  * Estimated USD charge to generate one response from this model under the
159
- * given context. Includes the 5% gateway margin and the flat $0.001
133
+ * given context. Includes the 5% media platform fee and the flat $0.001
160
134
  * per-transaction fee on paid calls. Returns 0 for free and token-metered
161
135
  * (paid) models where a pre-call estimate isn't meaningful.
162
136
  */
@@ -0,0 +1,10 @@
1
+ /** Shared model facts and policy; payment credentials stay in Franklin. */
2
+ import { type CatalogState, type Network } from '@blockrun/model-catalog';
3
+ export declare function getModelCatalogIdentity(): string;
4
+ export declare function getModelCatalog(): CatalogState;
5
+ export declare function onModelCatalogChange(listener: (state: CatalogState) => void): () => void;
6
+ export declare function refreshModelCatalog(options?: {
7
+ network?: Network;
8
+ force?: boolean;
9
+ }): Promise<CatalogState>;
10
+ export declare function clearModelCatalogCache(): void;
@@ -0,0 +1,77 @@
1
+ /** Shared model facts and policy; payment credentials stay in Franklin. */
2
+ import { createCatalogClient } from '@blockrun/model-catalog';
3
+ import { API_URLS, loadChain, USER_AGENT } from './config.js';
4
+ import { gatewayHeaders, resolvePayMode } from './payments/auth-mode.js';
5
+ const clients = new Map();
6
+ const bundled = new Map();
7
+ function bundledState() {
8
+ const network = sessionNetwork ?? loadChain();
9
+ let state = bundled.get(network);
10
+ if (!state) {
11
+ state = createCatalogClient({ network }).current();
12
+ bundled.set(network, state);
13
+ }
14
+ return state;
15
+ }
16
+ const listeners = new Set();
17
+ let sessionNetwork;
18
+ function activeClient() {
19
+ const mode = resolvePayMode();
20
+ const network = sessionNetwork ?? loadChain();
21
+ const gatewayUrl = `${mode.kind === 'key' ? mode.apiBase : API_URLS[network]}/v1/models?format=json`;
22
+ const catalogUrl = process.env.BLOCKRUN_MODEL_CATALOG_URL
23
+ ?? 'https://raw.githubusercontent.com/BlockRunAI/model-catalog/main/dist/snapshot.v1.json';
24
+ // Separate caches for each chain, endpoint and API account; keys never leave memory.
25
+ const identity = JSON.stringify([network, gatewayUrl, catalogUrl, mode.kind === 'key' ? mode.key : '']);
26
+ let client = clients.get(identity);
27
+ if (!client) {
28
+ const headers = { ...gatewayHeaders(mode), 'User-Agent': USER_AGENT };
29
+ client = createCatalogClient({
30
+ network, gatewayUrl, catalogUrl,
31
+ fetch: (url, init) => globalThis.fetch(url, {
32
+ ...init,
33
+ // A separately hosted public snapshot must never receive the API key.
34
+ headers: String(url) === gatewayUrl ? { ...init?.headers, ...headers } : init?.headers,
35
+ }),
36
+ });
37
+ clients.set(identity, client);
38
+ }
39
+ return { identity, client };
40
+ }
41
+ export function getModelCatalogIdentity() {
42
+ try {
43
+ return activeClient().identity;
44
+ }
45
+ catch {
46
+ return `unconfigured:${sessionNetwork ?? loadChain()}`;
47
+ }
48
+ }
49
+ export function getModelCatalog() {
50
+ // Metadata imports precede CLI flag parsing. An invalid saved key must not
51
+ // prevent --help or --wallet from running; request-time refresh still validates auth.
52
+ try {
53
+ return activeClient().client.current();
54
+ }
55
+ catch {
56
+ return bundledState();
57
+ }
58
+ }
59
+ export function onModelCatalogChange(listener) {
60
+ listeners.add(listener);
61
+ return () => { listeners.delete(listener); };
62
+ }
63
+ export async function refreshModelCatalog(options = {}) {
64
+ if (options.network)
65
+ sessionNetwork = options.network;
66
+ const { identity, client } = activeClient();
67
+ const state = process.env.FRANKLIN_CATALOG_OFFLINE === '1'
68
+ ? client.current() : await client.refresh({ force: options.force });
69
+ if (identity === activeClient().identity)
70
+ for (const listener of listeners)
71
+ listener(state);
72
+ return state;
73
+ }
74
+ export function clearModelCatalogCache() {
75
+ clients.clear();
76
+ sessionNetwork = undefined;
77
+ }
@@ -74,6 +74,15 @@ export declare function walletBase(chain?: Chain): string;
74
74
  * where payment rides on the PAYMENT-SIGNATURE header instead.
75
75
  */
76
76
  export declare function gatewayHeaders(mode?: PayMode): Record<string, string>;
77
+ /**
78
+ * Whether a 402 on a request sent with these headers may be answered from the
79
+ * wallet. A request that carried an account key gets a credit refusal, not an
80
+ * x402 challenge, and an account failure is never permission to spend from a
81
+ * wallet — the 402 must surface as an error. Branch on the request's own
82
+ * headers rather than re-resolving the mode, so the decision always matches the
83
+ * rail the request actually went out on.
84
+ */
85
+ export declare function walletMayPay(requestHeaders: Record<string, string>): boolean;
77
86
  /**
78
87
  * A key's credit standing, from GET /v1/credits. The authoritative figure for
79
88
  * display — the per-response `x-blockrun-credit-remaining-usd` header can
@@ -140,6 +140,17 @@ export function gatewayHeaders(mode = resolvePayMode()) {
140
140
  headers['Authorization'] = `Bearer ${mode.key}`;
141
141
  return headers;
142
142
  }
143
+ /**
144
+ * Whether a 402 on a request sent with these headers may be answered from the
145
+ * wallet. A request that carried an account key gets a credit refusal, not an
146
+ * x402 challenge, and an account failure is never permission to spend from a
147
+ * wallet — the 402 must surface as an error. Branch on the request's own
148
+ * headers rather than re-resolving the mode, so the decision always matches the
149
+ * rail the request actually went out on.
150
+ */
151
+ export function walletMayPay(requestHeaders) {
152
+ return !requestHeaders['Authorization'];
153
+ }
143
154
  /**
144
155
  * Fetch the key's credit standing. Null when there is no key, the gateway is
145
156
  * unreachable, or it answers with something unexpected — callers show what they