@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 +45 -10
- package/dist/agent/context.js +1 -1
- package/dist/agent/intent-prefetch.js +4 -3
- package/dist/agent/llm.js +6 -6
- package/dist/agent/tokens.js +13 -0
- package/dist/commands/models.js +3 -2
- package/dist/commands/start.js +4 -0
- package/dist/free-models.js +2 -1
- package/dist/gateway-models.d.ts +11 -5
- package/dist/gateway-models.js +45 -71
- package/dist/model-catalog.d.ts +10 -0
- package/dist/model-catalog.js +77 -0
- package/dist/payments/auth-mode.d.ts +9 -0
- package/dist/payments/auth-mode.js +11 -0
- package/dist/pricing.d.ts +2 -6
- package/dist/pricing.js +41 -14
- package/dist/router/index.js +4 -3
- package/dist/router/vision.js +22 -1
- package/dist/tools/blockrun.js +2 -2
- package/dist/tools/defillama.js +2 -2
- package/dist/tools/exa.js +2 -2
- package/dist/tools/imagegen.js +2 -2
- package/dist/tools/modal.js +2 -2
- package/dist/tools/musicgen.js +2 -2
- package/dist/tools/phone.js +2 -2
- package/dist/tools/prediction.js +2 -2
- package/dist/tools/realface.js +2 -2
- package/dist/tools/rpc.js +2 -2
- package/dist/tools/surf.js +2 -2
- package/dist/tools/videogen.js +2 -2
- package/dist/tools/voice.js +2 -2
- package/dist/trading/providers/blockrun/client.js +2 -2
- package/dist/ui/model-picker.d.ts +1 -2
- package/dist/ui/model-picker.js +51 -121
- package/package.json +6 -4
- package/dist/payments/account.d.ts +0 -17
- package/dist/payments/account.js +0 -105
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.
|
|
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
|
|
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 -->
|
|
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 -->
|
|
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 -->
|
|
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 -->
|
|
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 -->
|
|
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 -->
|
|
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 -->
|
|
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).
|
package/dist/agent/context.js
CHANGED
|
@@ -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-
|
|
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:
|
|
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
|
-
//
|
|
662
|
-
|
|
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
|
-
|
|
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' } };
|
package/dist/agent/tokens.js
CHANGED
|
@@ -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,
|
package/dist/commands/models.js
CHANGED
|
@@ -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 —
|
|
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
|
}
|
package/dist/commands/start.js
CHANGED
|
@@ -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
|
package/dist/free-models.js
CHANGED
|
@@ -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)
|
package/dist/gateway-models.d.ts
CHANGED
|
@@ -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.
|
|
13
|
-
*
|
|
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
|
-
/**
|
|
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%
|
|
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
|
*/
|
package/dist/gateway-models.js
CHANGED
|
@@ -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.
|
|
13
|
-
*
|
|
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 {
|
|
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
|
|
23
|
-
|
|
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
|
|
28
|
-
inflight
|
|
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
|
-
|
|
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
|
|
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
|
|
85
|
-
//
|
|
86
|
-
//
|
|
87
|
-
//
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
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
|
-
|
|
119
|
-
|
|
120
|
-
if (
|
|
121
|
-
return
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
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
|
-
|
|
128
|
-
|
|
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
|
-
.
|
|
135
|
-
|
|
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
|
-
/**
|
|
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%
|
|
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
|