@blockrun/franklin 3.42.2 → 3.43.1
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 +5 -5
- package/dist/agent/commands.js +2 -2
- package/dist/agent/compact.js +6 -3
- package/dist/agent/context.js +1 -1
- package/dist/agent/evaluator.js +2 -1
- package/dist/agent/llm.js +4 -3
- package/dist/agent/loop.js +82 -14
- package/dist/agent/nemotron-prose-stripper.d.ts +26 -0
- package/dist/agent/nemotron-prose-stripper.js +39 -1
- package/dist/agent/tokens.js +22 -5
- package/dist/agent/turn-analyzer.js +18 -6
- package/dist/agent/verification.js +2 -1
- package/dist/brain/extract.js +2 -1
- package/dist/commands/slack.js +2 -1
- package/dist/commands/social.js +2 -1
- package/dist/commands/telegram.js +2 -1
- package/dist/free-models.constants.d.ts +28 -0
- package/dist/free-models.constants.js +33 -0
- package/dist/free-models.d.ts +320 -0
- package/dist/free-models.js +407 -0
- package/dist/gateway-models.js +15 -3
- package/dist/learnings/extractor.js +3 -2
- package/dist/plugin-sdk/workflow.js +5 -2
- package/dist/pricing.js +18 -9
- package/dist/proxy/fallback.d.ts +8 -1
- package/dist/proxy/fallback.js +35 -3
- package/dist/proxy/server.js +42 -3
- package/dist/router/index.d.ts +3 -1
- package/dist/router/index.js +140 -89
- package/dist/router/vision.js +35 -10
- package/dist/serve/server.js +1 -4
- package/dist/tools/moa.js +9 -3
- package/dist/tools/subagent.js +6 -5
- package/dist/ui/model-picker.js +75 -74
- package/package.json +2 -2
|
@@ -0,0 +1,407 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Single source of truth for the BlockRun free tier.
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS FILE EXISTS
|
|
5
|
+
* --------------------
|
|
6
|
+
* The free default used to be a bare string literal repeated 63 times across
|
|
7
|
+
* 21 files. Every time NVIDIA rotated its free pool — 2026-06-07, 07-11,
|
|
8
|
+
* 07-14, 08-12, 08-19, 08-29 — someone had to find and edit all 63. That is
|
|
9
|
+
* the sixth rotation in three months, and each one shipped with a few stale
|
|
10
|
+
* copies left behind. One constant, imported everywhere, ends that.
|
|
11
|
+
*
|
|
12
|
+
* WHAT THE 2026-08-30 PROBE FOUND
|
|
13
|
+
* -------------------------------
|
|
14
|
+
* Every free id Franklin named had left the Base catalog, and the gateway was
|
|
15
|
+
* answering for them with a different model:
|
|
16
|
+
*
|
|
17
|
+
* nvidia/nemotron-nano-9b-v2 -> nvidia/nemotron-3-nano-30b
|
|
18
|
+
* nvidia/mistral-nemotron -> nvidia/nemotron-3-super-120b-a12b-free
|
|
19
|
+
* nvidia/nemotron-nano-12b-v2-vl -> nvidia/nemotron-3-nano-omni-...
|
|
20
|
+
* nvidia/step-3.7-flash -> nvidia/nemotron-3.5-lightning
|
|
21
|
+
*
|
|
22
|
+
* That redirection is DELIBERATE upstream, not a gateway bug: the free tier
|
|
23
|
+
* sits on NVIDIA's on-demand NIM tier, which EOLs models (410), pulls
|
|
24
|
+
* deployments (404) and lets cold ones hang, so blockrun runs a self-healing
|
|
25
|
+
* circuit breaker (src/lib/free-health.ts) that routes around dead free
|
|
26
|
+
* models at runtime. It replaced a hand-maintained redirect list precisely
|
|
27
|
+
* because that list was always stale. The substitution is also disclosed —
|
|
28
|
+
* the response's `model` field names whatever actually served the call.
|
|
29
|
+
*
|
|
30
|
+
* So the failure was ours: Franklin named ids that no longer exist and never
|
|
31
|
+
* read that field back. What follows is about not doing that again.
|
|
32
|
+
*
|
|
33
|
+
* Two findings shape everything below, and BOTH were invisible until the
|
|
34
|
+
* probe ran against the endpoint and the chain Franklin actually uses.
|
|
35
|
+
*
|
|
36
|
+
* 1. THE CHAINS DRIFT. When this landed, Base listed 7 free models and Solana
|
|
37
|
+
* listed exactly ONE — nemotron-3-nano-omni — and 400'd ("Unknown model")
|
|
38
|
+
* on the other six. Solana caught up later the same day (both list 7 as of
|
|
39
|
+
* 2026-08-31), but the gap was real for hours and will recur: the two
|
|
40
|
+
* gateways deploy independently. A default picked from the Base catalog is
|
|
41
|
+
* a hard failure on a Solana user's first turn during such a window, which
|
|
42
|
+
* is why FREE_DEFAULT_MODEL is the id that survived on BOTH chains and the
|
|
43
|
+
* Base-only models are a runtime upgrade rather than a committed literal.
|
|
44
|
+
*
|
|
45
|
+
* 2. SUBSTITUTION IS ENDPOINT-SPECIFIC. The pooling above reproduces on
|
|
46
|
+
* POST /api/v1/chat/completions. On POST /api/v1/messages — the endpoint
|
|
47
|
+
* Franklin's ModelClient uses — every id answered as ITSELF across
|
|
48
|
+
* repeated calls on both chains, with no leaked chain-of-thought. So
|
|
49
|
+
* "which id serves itself" has a different answer per endpoint, and a
|
|
50
|
+
* probe is only evidence for the path it was run against.
|
|
51
|
+
*
|
|
52
|
+
* What this file does about it:
|
|
53
|
+
*
|
|
54
|
+
* 1. One constant, imported everywhere, instead of 63 string literals.
|
|
55
|
+
* 2. A chain-safe static default, upgraded from the LIVE catalog at runtime
|
|
56
|
+
* (freeChain / resolveFreeModel), so a Base user gets the stronger model
|
|
57
|
+
* and a Solana user gets one that exists.
|
|
58
|
+
* 3. Context sized by the pool floor, not the catalogued window
|
|
59
|
+
* (FREE_POOL_CONTEXT_FLOOR).
|
|
60
|
+
* 4. No free vision — see freeVisionModel().
|
|
61
|
+
*/
|
|
62
|
+
import { peekGatewayModel } from './gateway-models.js';
|
|
63
|
+
import { FREE_DEFAULT_MODEL, FREE_POOL_CONTEXT_FLOOR, FREE_PREFERENCE_ORDER, } from './free-models.constants.js';
|
|
64
|
+
// Re-exported so every consumer keeps importing from ONE place. The constants
|
|
65
|
+
// live in a zero-import leaf only so the public plugin SDK can read them
|
|
66
|
+
// without pulling core's filesystem-touching config module in behind them.
|
|
67
|
+
export { FREE_DEFAULT_MODEL, FREE_POOL_CONTEXT_FLOOR, FREE_PREFERENCE_ORDER };
|
|
68
|
+
/**
|
|
69
|
+
* The free model Franklin asks for by default.
|
|
70
|
+
*
|
|
71
|
+
* nemotron-3-nano-omni is chosen for AVAILABILITY, not for being the best: it
|
|
72
|
+
* is the only free id present in both the Base and the Solana catalogs. Every
|
|
73
|
+
* other free model is Base-only and 400s on Solana, and Franklin ships with
|
|
74
|
+
* either chain selectable. Base users are upgraded to the stronger model at
|
|
75
|
+
* runtime by freeChain() — see FREE_PREFERENCE_ORDER.
|
|
76
|
+
*
|
|
77
|
+
* Verified on POST /api/v1/messages (Franklin's own endpoint) on both chains:
|
|
78
|
+
* answers as itself, no leaked reasoning, tool calls work.
|
|
79
|
+
*/
|
|
80
|
+
// (defined in ./free-models.constants.ts, re-exported above)
|
|
81
|
+
/**
|
|
82
|
+
* Free models in preference order, best first.
|
|
83
|
+
*
|
|
84
|
+
* FREE_DEFAULT_MODEL is the id that survived on both chains through the
|
|
85
|
+
* 2026-08-30 rotation window; the rest were Base-only during it. freeChain()
|
|
86
|
+
* filters this against the live catalog for the CURRENT chain, so the list can
|
|
87
|
+
* name ids one gateway lacks without breaking the other.
|
|
88
|
+
*
|
|
89
|
+
* Ordering rationale — AVAILABILITY FIRST, quality second. Measured on
|
|
90
|
+
* /v1/messages, Base, max_tokens 300, 5 calls each (2026-08-31):
|
|
91
|
+
*
|
|
92
|
+
* nemotron-3-nano-30b 5/5 healthy, 0.8-2.9s
|
|
93
|
+
* nemotron-3-nano-omni 2/5 healthy, three HTTP 503s
|
|
94
|
+
* nemotron-3-ultra-550b 0/5 healthy — every call timed out at 40s
|
|
95
|
+
*
|
|
96
|
+
* - nemotron-3-nano-30b leads on Base. It is the pool's own backing model,
|
|
97
|
+
* which is why it is the one id that never comes back as a substitute and
|
|
98
|
+
* the one that stays up when the rest of the pool is congested.
|
|
99
|
+
* - nemotron-3-ultra-550b is NOT in this list, and that reverses an earlier
|
|
100
|
+
* revision which had it leading. It gives the best answers when it answers
|
|
101
|
+
* — the only free model to name Aerodrome for "three Base-chain DEXes"
|
|
102
|
+
* while the others hallucinated Uniswap forks — but a model you cannot
|
|
103
|
+
* reach is not a better model. The andy session measured it independently
|
|
104
|
+
* at 1/3 and 1/5, with NVIDIA congestion relayed as HTTP 200; here it was
|
|
105
|
+
* 0/5 with hard timeouts. It stays reachable by explicit pin
|
|
106
|
+
* (`/model ultra-550b`), it just cannot lead a chain.
|
|
107
|
+
* - the two non-NVIDIA rungs are last on purpose: they are what keeps the
|
|
108
|
+
* chain alive through an NVIDIA-wide outage instead of it being four names
|
|
109
|
+
* for one upstream.
|
|
110
|
+
*
|
|
111
|
+
* Not listed, and why:
|
|
112
|
+
* - nvidia/nemotron-3.5-lightning — LATENCY, and only latency. Measured
|
|
113
|
+
* 10.9s / 12.2s / 22.5s for a one-sentence answer at max_tokens 800,
|
|
114
|
+
* against ~0.8-3s for the rest of the pool. Its name is a lie. (An
|
|
115
|
+
* earlier revision of this file quarantined it for leaking reasoning
|
|
116
|
+
* prose; that was wrong — see TRUNCATION below.)
|
|
117
|
+
* - nvidia/llama-3.2-11b-vision — catalogued as vision, cannot accept an
|
|
118
|
+
* image (see freeVisionModel), and is otherwise the weakest text model in
|
|
119
|
+
* the pool.
|
|
120
|
+
*
|
|
121
|
+
* TRUNCATION: THE FREE POOL NEEDS ROOM TO THINK
|
|
122
|
+
* ---------------------------------------------
|
|
123
|
+
* Every free model here is a reasoning model, and a tight max_tokens makes
|
|
124
|
+
* them look broken in two different ways that are the SAME bug. Measured on
|
|
125
|
+
* chat/completions, 2026-08-31:
|
|
126
|
+
*
|
|
127
|
+
* nemotron-3-nano-30b, "what does approve() do":
|
|
128
|
+
* max_tokens 20 -> finish_reason "length", content is truncated thinking
|
|
129
|
+
* ("Okay, the user is asking about...")
|
|
130
|
+
* max_tokens 120 -> finish_reason "length", still truncated thinking
|
|
131
|
+
* max_tokens 300 -> finish_reason "stop", content is a clean answer and
|
|
132
|
+
* the thinking sits in reasoning_content
|
|
133
|
+
*
|
|
134
|
+
* cohere/north-mini-code, "name three Base-chain DEXes":
|
|
135
|
+
* max_tokens 200 -> EMPTY stream, 0 content chunks, 6 of 8 calls
|
|
136
|
+
* max_tokens 2000 -> 6 of 6 clean, finish_reason "stop"
|
|
137
|
+
*
|
|
138
|
+
* So "leaks chain-of-thought into content" and "returns an empty stream" are
|
|
139
|
+
* both the budget running out before the model stops reasoning. Neither is a
|
|
140
|
+
* property of the model, and neither is worth a workaround — give the call
|
|
141
|
+
* room. This is why the router's tier classifier no longer asks for a
|
|
142
|
+
* one-word answer in 8 tokens (see router/index.ts).
|
|
143
|
+
*
|
|
144
|
+
* The andy session traced the mechanism further, and it changes what the
|
|
145
|
+
* discriminator is. Probed three ways at max_tokens 20: the NIM upstream
|
|
146
|
+
* returns a clean `content: "OK"` with finish_reason "stop", while sol's
|
|
147
|
+
* /chat/completions returns the thinking in `content` with finish_reason
|
|
148
|
+
* "length". The upstream separates the fields correctly; the GATEWAY's
|
|
149
|
+
* extractor falls back to reasoning text when the answer field is empty. So
|
|
150
|
+
* raising max_tokens does not fix the bug, it stops triggering it, and
|
|
151
|
+
* finish_reason "length" is the real discriminator — treat any truncated
|
|
152
|
+
* free-tier reply as suspect regardless of budget.
|
|
153
|
+
*
|
|
154
|
+
* One claim of theirs did NOT reproduce here: they reported /v1/messages
|
|
155
|
+
* leaking on nano-omni at a small budget. Probed at max_tokens 20, 60 and 300
|
|
156
|
+
* on both chains, /v1/messages came back clean 12 of 12, with proper
|
|
157
|
+
* thinking+text block separation and stop_reason "end_turn". Recording the
|
|
158
|
+
* disagreement rather than picking a winner — if it resurfaces, the block
|
|
159
|
+
* separation is the thing to check.
|
|
160
|
+
*
|
|
161
|
+
* Credit: the andy session, which re-measured across budgets, then retracted
|
|
162
|
+
* its own retraction with the three-way upstream probe, and the clawrouter
|
|
163
|
+
* session, which nearly shipped a textual <tool_call> extractor for a model
|
|
164
|
+
* that returns a clean structured tool_calls array once given room.
|
|
165
|
+
*/
|
|
166
|
+
// (defined in ./free-models.constants.ts, re-exported above)
|
|
167
|
+
/**
|
|
168
|
+
* Context budget for ANY free-tier request, regardless of the catalogued
|
|
169
|
+
* window of the id we asked for.
|
|
170
|
+
*
|
|
171
|
+
* The strongest free model is catalogued at 1M, but the free tier is a pool:
|
|
172
|
+
* on chat/completions a request for it can be served by the 131K
|
|
173
|
+
* nemotron-3-nano-30b with no warning, and the chain-safe default is 256K.
|
|
174
|
+
* Sizing compaction off 1M would build a prompt the substitute cannot accept,
|
|
175
|
+
* and it would fail mid-session on a user who never chose the substitute.
|
|
176
|
+
* 131_072 is the floor of every model in FREE_PREFERENCE_ORDER. The one free
|
|
177
|
+
* id below it (llama-3.2-11b-vision, 128_000) is vision-only and never routed
|
|
178
|
+
* as a text rung, so it is sized from its own catalog entry in tokens.ts.
|
|
179
|
+
*/
|
|
180
|
+
// (defined in ./free-models.constants.ts, re-exported above)
|
|
181
|
+
/**
|
|
182
|
+
* Catalogued free ids Franklin will not route to, with the reason each was
|
|
183
|
+
* rejected in the 2026-08-30 probe. These are real, billable-at-$0 ids — they
|
|
184
|
+
* are excluded on behaviour, not availability.
|
|
185
|
+
*/
|
|
186
|
+
export const QUARANTINED_FREE_MODELS = [
|
|
187
|
+
// Nothing is quarantined right now.
|
|
188
|
+
//
|
|
189
|
+
// llama-3.2-11b-vision was here until the gateway's image_url fix deployed
|
|
190
|
+
// to Solana; it is now the free VISION model there (5/5 on a valid 64x64
|
|
191
|
+
// PNG) and is reached through freeVisionModel(), not through the text
|
|
192
|
+
// chain. It stays out of FREE_PREFERENCE_ORDER because it is the weakest
|
|
193
|
+
// text model in the pool, which is a ranking, not a ban.
|
|
194
|
+
//
|
|
195
|
+
// Released, deliberately, though an earlier revision quarantined both — the
|
|
196
|
+
// evidence was a measurement artifact, see the TRUNCATION note above:
|
|
197
|
+
// nvidia/nemotron-3.5-lightning — the "CoT leak" was max_tokens truncation.
|
|
198
|
+
// It is merely slow, which keeps it out of FREE_PREFERENCE_ORDER but is
|
|
199
|
+
// no reason to refuse to route to it if a user asks.
|
|
200
|
+
// cohere/north-mini-code — the "empty stream" was the same truncation, and
|
|
201
|
+
// it is a cascade rung other BlockRun components depend on.
|
|
202
|
+
];
|
|
203
|
+
/**
|
|
204
|
+
* Free ids Franklin used to name. The gateway still answers for all of them
|
|
205
|
+
* (via substitution), but they are gone from /api/v1/models. Kept so old
|
|
206
|
+
* session-cost records still price at $0 and so stale aliases can be remapped
|
|
207
|
+
* rather than handed back to the user as-is.
|
|
208
|
+
*/
|
|
209
|
+
export const LEGACY_FREE_MODEL_IDS = [
|
|
210
|
+
'nvidia/nemotron-nano-9b-v2',
|
|
211
|
+
'nvidia/mistral-nemotron',
|
|
212
|
+
'nvidia/nemotron-nano-12b-v2-vl',
|
|
213
|
+
'nvidia/step-3.7-flash',
|
|
214
|
+
'nvidia/nemotron-3-super-120b',
|
|
215
|
+
'nvidia/nemotron-3-super-120b-a12b-free',
|
|
216
|
+
];
|
|
217
|
+
/**
|
|
218
|
+
* Every free id in the live Base catalog as of 2026-08-30, mapped to its
|
|
219
|
+
* catalogued context window. Used for metadata display; NOT for sizing a
|
|
220
|
+
* request — use FREE_POOL_CONTEXT_FLOOR for that.
|
|
221
|
+
*/
|
|
222
|
+
export const FREE_MODEL_CONTEXT_WINDOWS = {
|
|
223
|
+
'nvidia/nemotron-3-ultra-550b': 1_000_000,
|
|
224
|
+
'nvidia/nemotron-3.5-lightning': 1_000_000,
|
|
225
|
+
'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning': 256_000,
|
|
226
|
+
'cohere/north-mini-code': 256_000,
|
|
227
|
+
'nvidia/nemotron-3-nano-30b': 131_072,
|
|
228
|
+
'poolside/laguna-xs-2.1': 131_072,
|
|
229
|
+
'nvidia/llama-3.2-11b-vision': 128_000,
|
|
230
|
+
};
|
|
231
|
+
/**
|
|
232
|
+
* The free model that can accept an image, or null when this chain has none.
|
|
233
|
+
*
|
|
234
|
+
* Chain-aware because the gateways are at different deploy states, not
|
|
235
|
+
* because the models differ. The original defect was gateway-side: both
|
|
236
|
+
* NVIDIA paths dropped every `image_url` unconditionally under a stale
|
|
237
|
+
* comment, which is why it presented as a confident wrong answer with no
|
|
238
|
+
* error. The allow-list fix reached Solana first.
|
|
239
|
+
*
|
|
240
|
+
* FOUR measurement passes, each of which reversed the previous conclusion.
|
|
241
|
+
* The history stays because the reversals are the lesson:
|
|
242
|
+
*
|
|
243
|
+
* 1. 2x2 PNG, both ids fail. INVALID — images under 10px per side
|
|
244
|
+
* are rejected upstream, so the fixture proved nothing.
|
|
245
|
+
* 2. 64x64, 5 calls, llama 5/5 sol. Shipped. Too small a sample.
|
|
246
|
+
* 3. 64x64, 10 calls, llama 5/10. Reverted. A real bad window: the
|
|
247
|
+
* gateway fix was still settling. Fixture validated, so not a repeat
|
|
248
|
+
* of mistake 1.
|
|
249
|
+
* 4. 64x64, 30 calls across both RE-ENABLED. See below.
|
|
250
|
+
* HTTP paths and three runs.
|
|
251
|
+
*
|
|
252
|
+
* Pass 4, validated fixture (`sips` decodes it, and every PNG chunk CRC
|
|
253
|
+
* checks against zlib.crc32 — `file` reports dimensions from the header and
|
|
254
|
+
* will happily accept a corrupt image, which is how a broken fixture
|
|
255
|
+
* masquerades as a broken product):
|
|
256
|
+
*
|
|
257
|
+
* sol llama-3.2-11b-vision /v1/messages 10/10 sees, 0/10 substituted
|
|
258
|
+
* sol llama-3.2-11b-vision /chat/completions 10/10 sees, 0/10 substituted
|
|
259
|
+
* sol llama-3.2-11b-vision /v1/messages (repeat) 10/10 sees, 0/10 substituted
|
|
260
|
+
* base llama-3.2-11b-vision /v1/messages 0/10 sees, 0/10 substituted
|
|
261
|
+
* sol nemotron-3-nano-omni /v1/messages 6/10 sees, 0/10 substituted
|
|
262
|
+
* sol nemotron-3-nano-omni /chat/completions 4/10 sees, 7/10 SUBSTITUTED
|
|
263
|
+
*
|
|
264
|
+
* Re-probed 2026-08-31 after the gateway's vision-routing fix: nano-omni now
|
|
265
|
+
* returns an explicit 400 on image input on /v1/messages ("served text-only on
|
|
266
|
+
* NVIDIA"), refused BEFORE payment. The silent-drop mode is gone on our path —
|
|
267
|
+
* a loud refusal is the outcome this module wanted all along. llama-3.2-11b-vision
|
|
268
|
+
* re-verified 6/6 in the same window, so the bare-call number still holds.
|
|
269
|
+
*
|
|
270
|
+
* So Solana gets llama-3.2-11b-vision and Base honestly reports none. On
|
|
271
|
+
* Base the model serves itself and simply cannot see — 0 substitutions, so
|
|
272
|
+
* this is the missing allow-list fix, not a cascade problem.
|
|
273
|
+
*
|
|
274
|
+
* nano-omni is NEVER used for vision despite its catalog tag. On
|
|
275
|
+
* chat/completions it is substituted 7 times in 10 by nemotron-3-nano-30b,
|
|
276
|
+
* a model with no vision at all (the andy session captured the same thing
|
|
277
|
+
* 3/3), and even unsubstituted it only sees the image 6 times in 10.
|
|
278
|
+
*
|
|
279
|
+
* ACCEPTANCE BAR for changing any of this — all four are required, and each
|
|
280
|
+
* one exists because skipping it produced a wrong answer above:
|
|
281
|
+
* - a fixture >=64x64 that a real decoder accepts and whose CRCs verify;
|
|
282
|
+
* - at least 10 calls (5 is inside the noise);
|
|
283
|
+
* - assert the served `model` echoes the id you requested;
|
|
284
|
+
* - assert the answer is actually right, not merely non-empty.
|
|
285
|
+
*
|
|
286
|
+
* AND YET THIS RETURNS NULL. Pass 5 measured the thing that actually
|
|
287
|
+
* matters — the whole feature, end to end through the binary, not the API
|
|
288
|
+
* call — and it is 1 in 5:
|
|
289
|
+
*
|
|
290
|
+
* bare vision call, validated fixture 30/30
|
|
291
|
+
* end-to-end `franklin --model free` 1/5
|
|
292
|
+
*
|
|
293
|
+
* llama-3.2-11b-vision is reliable as a vision CALL and too weak to drive an
|
|
294
|
+
* agent turn. Given the full tool set it re-called `Read` on the same path
|
|
295
|
+
* until the repeat guard fired. Given no tools after the image was in
|
|
296
|
+
* history (the one-shot path below, which is implemented and stays) it
|
|
297
|
+
* stopped looping and instead ended the turn after `Read` without producing
|
|
298
|
+
* an answer at all. So the blocker is no longer the gateway — it is
|
|
299
|
+
* Franklin's own wiring, which hands a vision turn to a weak model by
|
|
300
|
+
* swapping the AGENT model for the whole turn.
|
|
301
|
+
*
|
|
302
|
+
* A capability that works 30/30 in isolation and 1/5 in the product is not a
|
|
303
|
+
* capability. By the rule this file already applies to nano-omni — an
|
|
304
|
+
* intermittent confident wrong answer is worse than declining, because the
|
|
305
|
+
* caller cannot tell which half they got — Franklin declines and says the
|
|
306
|
+
* image was not seen.
|
|
307
|
+
*
|
|
308
|
+
* THE FIX, for whoever picks this up: do not swap the agent model. Make the
|
|
309
|
+
* vision turn a dedicated one-shot side-call — inline the image, ask the
|
|
310
|
+
* vision model directly, feed the answer back as context, and let the normal
|
|
311
|
+
* agent model finish the turn. The 30/30 says that call will work. The
|
|
312
|
+
* groundwork is in place: the one-shot tool suppression in agent/loop.ts
|
|
313
|
+
* fires whenever this function returns a model.
|
|
314
|
+
*
|
|
315
|
+
* FRANKLIN_FREE_VISION_MODEL overrides ('none' disables), so the whole path
|
|
316
|
+
* above can be exercised without a code change.
|
|
317
|
+
*/
|
|
318
|
+
export function freeVisionModel() {
|
|
319
|
+
const override = process.env.FRANKLIN_FREE_VISION_MODEL;
|
|
320
|
+
if (!override || override === 'none')
|
|
321
|
+
return null;
|
|
322
|
+
// The override is NOT trusted blindly. Every caller treats this return value
|
|
323
|
+
// as free — router/vision.ts calls it vision-capable, the agent loop swaps a
|
|
324
|
+
// free-tier user onto it and prints "(still free)", the proxy does the same,
|
|
325
|
+
// and the router reports savings: 1.0. Handing back an unvalidated id would
|
|
326
|
+
// let this env var route a free-tier turn onto a PAID model while telling the
|
|
327
|
+
// user it costs nothing, which is the invariant this module exists to hold.
|
|
328
|
+
// Unknown-on-a-cold-cache fails CLOSED (decline vision) rather than open.
|
|
329
|
+
return isFreeModelId(override) ? override : null;
|
|
330
|
+
}
|
|
331
|
+
/**
|
|
332
|
+
* Is this id billed at $0?
|
|
333
|
+
*
|
|
334
|
+
* Replaces the `m.startsWith('nvidia/')` heuristic that was spread across the
|
|
335
|
+
* subagent tool, the /model command and the compaction picker. That heuristic
|
|
336
|
+
* was wrong in both directions once the pool rotated:
|
|
337
|
+
*
|
|
338
|
+
* - nvidia/kimi-k2.5 is a PAID model ($0.55/$2.50 per 1M). Treating it as
|
|
339
|
+
* free meant `/model kimi-k2.5` skipped the "charges from your wallet"
|
|
340
|
+
* warning, and a free-tier parent could hand compaction a paid model.
|
|
341
|
+
* - poolside/laguna-xs-2.1 and cohere/north-mini-code are free and carry no
|
|
342
|
+
* `nvidia/` prefix, so they were treated as paid.
|
|
343
|
+
*
|
|
344
|
+
* The live catalog is consulted first (it is authoritative and picks up new
|
|
345
|
+
* free ids without a release); the static sets answer when the cache is cold.
|
|
346
|
+
*/
|
|
347
|
+
export function isFreeModelId(id) {
|
|
348
|
+
// ORDER MATTERS. `!id` is true for '' as well as null/undefined, so the
|
|
349
|
+
// empty-string check has to come first or it is unreachable — which is
|
|
350
|
+
// exactly the bug this ordering fixes. '' means "no parent model registered
|
|
351
|
+
// yet", and tools/subagent.ts reads that through this predicate to decide
|
|
352
|
+
// whether a PAID sub-agent spawn needs the user's approval. Returning false
|
|
353
|
+
// for '' silently skipped that gate and let a paid spawn charge the wallet
|
|
354
|
+
// with no prompt and no fail-closed path.
|
|
355
|
+
if (id === '' || id === 'blockrun/free')
|
|
356
|
+
return true;
|
|
357
|
+
if (!id)
|
|
358
|
+
return false;
|
|
359
|
+
const entry = peekGatewayModel(id);
|
|
360
|
+
if (entry)
|
|
361
|
+
return entry.billing_mode === 'free';
|
|
362
|
+
if (id in FREE_MODEL_CONTEXT_WINDOWS)
|
|
363
|
+
return true;
|
|
364
|
+
return LEGACY_FREE_MODEL_IDS.includes(id);
|
|
365
|
+
}
|
|
366
|
+
/**
|
|
367
|
+
* The free chain to try right now, best first, filtered to what the CURRENT
|
|
368
|
+
* chain's gateway actually lists.
|
|
369
|
+
*
|
|
370
|
+
* peekGatewayModel reads the cached catalog and never triggers a fetch, so
|
|
371
|
+
* this is safe on the hot path and in sync callers. When the cache is cold
|
|
372
|
+
* there is no evidence either way, and the answer is the one id that exists
|
|
373
|
+
* on both chains — guessing the Base-only model there would 400 every Solana
|
|
374
|
+
* user's first turn, which is the exact failure this function exists to
|
|
375
|
+
* prevent.
|
|
376
|
+
*
|
|
377
|
+
* `exclude` drops rungs that already failed this turn.
|
|
378
|
+
*/
|
|
379
|
+
export function freeChain(exclude = new Set()) {
|
|
380
|
+
const candidates = FREE_PREFERENCE_ORDER.filter(id => !exclude.has(id));
|
|
381
|
+
const confirmed = candidates.filter(id => peekGatewayModel(id)?.billing_mode === 'free');
|
|
382
|
+
if (confirmed.length > 0)
|
|
383
|
+
return confirmed;
|
|
384
|
+
// No catalog evidence — cold cache (every turn-1 decision, and the whole
|
|
385
|
+
// session if the fetch fails, since gateway-models swallows that error).
|
|
386
|
+
//
|
|
387
|
+
// Prefer the id that survived on both gateways. But if the caller has
|
|
388
|
+
// already excluded it, fall through to the remaining candidates instead of
|
|
389
|
+
// returning nothing: an earlier revision returned [] here, which collapsed
|
|
390
|
+
// the free recovery chain from three rungs to ONE precisely when it was
|
|
391
|
+
// needed — a free user got a single rescue attempt on a 402 or rate limit
|
|
392
|
+
// and then the turn died. There is no evidence against the other rungs
|
|
393
|
+
// either; asking and being told "unknown model" beats not asking.
|
|
394
|
+
const preferred = candidates.filter(id => id === FREE_DEFAULT_MODEL);
|
|
395
|
+
return preferred.length > 0 ? preferred : candidates;
|
|
396
|
+
}
|
|
397
|
+
/**
|
|
398
|
+
* Pick the single free model to request right now. See freeChain().
|
|
399
|
+
*
|
|
400
|
+
* Returns undefined when every candidate is excluded — it must NEVER hand back
|
|
401
|
+
* a model the caller listed in `exclude`. The previous `?? FREE_DEFAULT_MODEL`
|
|
402
|
+
* fallback did exactly that on a cold cache, which would spin a retry loop on
|
|
403
|
+
* a model the caller had just watched fail.
|
|
404
|
+
*/
|
|
405
|
+
export function resolveFreeModel(exclude = new Set()) {
|
|
406
|
+
return freeChain(exclude)[0];
|
|
407
|
+
}
|
package/dist/gateway-models.js
CHANGED
|
@@ -53,11 +53,23 @@ export function clearGatewayModelsCache() {
|
|
|
53
53
|
export function peekGatewayModel(id) {
|
|
54
54
|
if (!cache)
|
|
55
55
|
return null;
|
|
56
|
+
// A catalog fetched for a different chain is not evidence about this one.
|
|
57
|
+
if (cache.chain !== currentChain())
|
|
58
|
+
return null;
|
|
56
59
|
return cache.models.find(m => m.id === id) ?? null;
|
|
57
60
|
}
|
|
61
|
+
/** loadChain() with the throw swallowed — this is a hot, sync path. */
|
|
62
|
+
function currentChain() {
|
|
63
|
+
try {
|
|
64
|
+
return loadChain();
|
|
65
|
+
}
|
|
66
|
+
catch {
|
|
67
|
+
return 'base';
|
|
68
|
+
}
|
|
69
|
+
}
|
|
58
70
|
/** Test helper — seed the cache without a network call. */
|
|
59
71
|
export function __primeGatewayModelsCache(models) {
|
|
60
|
-
cache = { models, expiresAt: Date.now() + CACHE_TTL_MS };
|
|
72
|
+
cache = { models, expiresAt: Date.now() + CACHE_TTL_MS, chain: currentChain() };
|
|
61
73
|
}
|
|
62
74
|
/**
|
|
63
75
|
* Fire-and-forget catalog warm. Populates the cache so the sync peek above has
|
|
@@ -98,13 +110,13 @@ async function doFetch() {
|
|
|
98
110
|
* the gateway at process start.
|
|
99
111
|
*/
|
|
100
112
|
export async function getGatewayModels() {
|
|
101
|
-
if (cache && cache.expiresAt > Date.now())
|
|
113
|
+
if (cache && cache.chain === currentChain() && cache.expiresAt > Date.now())
|
|
102
114
|
return cache.models;
|
|
103
115
|
if (inflight)
|
|
104
116
|
return inflight;
|
|
105
117
|
inflight = doFetch()
|
|
106
118
|
.then(models => {
|
|
107
|
-
cache = { models, expiresAt: Date.now() + CACHE_TTL_MS };
|
|
119
|
+
cache = { models, expiresAt: Date.now() + CACHE_TTL_MS, chain: currentChain() };
|
|
108
120
|
return models;
|
|
109
121
|
})
|
|
110
122
|
.catch(err => {
|
|
@@ -6,11 +6,12 @@ import fs from 'node:fs';
|
|
|
6
6
|
import path from 'node:path';
|
|
7
7
|
import os from 'node:os';
|
|
8
8
|
import { loadLearnings, mergeLearning, saveLearnings, loadSkills, saveSkill } from './store.js';
|
|
9
|
+
import { FREE_DEFAULT_MODEL } from '../free-models.js';
|
|
9
10
|
// Free models for learning extraction — JSON extraction is simple enough.
|
|
10
11
|
// Ordered by reliability: try the best free model first, fall back to others.
|
|
11
12
|
const EXTRACTION_MODELS = [
|
|
12
|
-
|
|
13
|
-
'
|
|
13
|
+
FREE_DEFAULT_MODEL, // Free lead — see src/free-models.ts
|
|
14
|
+
'poolside/laguna-xs-2.1', // Different provider, so the fallback survives an NVIDIA-wide outage
|
|
14
15
|
];
|
|
15
16
|
const VALID_CATEGORIES = new Set([
|
|
16
17
|
'language', 'model_preference', 'tool_pattern', 'coding_style',
|
|
@@ -4,8 +4,11 @@
|
|
|
4
4
|
* A workflow is a multi-step AI process: search → filter → generate → execute → track.
|
|
5
5
|
* Plugins implement Workflow; core orchestrates execution and provides infrastructure.
|
|
6
6
|
*/
|
|
7
|
+
// Zero-import leaf: naming the free default must not drag core's config
|
|
8
|
+
// module (and its module-load filesystem reads) into the public SDK.
|
|
9
|
+
import { FREE_DEFAULT_MODEL } from '../free-models.constants.js';
|
|
7
10
|
export const DEFAULT_MODEL_TIERS = {
|
|
8
|
-
free:
|
|
9
|
-
cheap:
|
|
11
|
+
free: FREE_DEFAULT_MODEL,
|
|
12
|
+
cheap: FREE_DEFAULT_MODEL, // Free by default; opt-in to paid flat-rate via 'zai/glm-5.1'.
|
|
10
13
|
premium: 'anthropic/claude-sonnet-5',
|
|
11
14
|
};
|
package/dist/pricing.js
CHANGED
|
@@ -8,16 +8,25 @@ export const MODEL_PRICING = {
|
|
|
8
8
|
// their parser mapping promotes them to Auto upstream of cost estimation.
|
|
9
9
|
'blockrun/auto': { input: 0.8, output: 4.0 },
|
|
10
10
|
'blockrun/free': { input: 0, output: 0 },
|
|
11
|
-
// FREE — BlockRun gateway free tier (refreshed 2026-08-
|
|
12
|
-
// /api/v1/models
|
|
13
|
-
//
|
|
14
|
-
//
|
|
15
|
-
//
|
|
16
|
-
'nvidia/nemotron-nano-
|
|
17
|
-
'nvidia/
|
|
18
|
-
'nvidia/nemotron-nano-12b-v2-vl': { input: 0, output: 0 },
|
|
11
|
+
// FREE — BlockRun gateway free tier (refreshed 2026-08-30 to match live
|
|
12
|
+
// /api/v1/models, which rotated the entire free pool). The routing order and
|
|
13
|
+
// the reasoning behind it live in src/free-models.ts; this table only has to
|
|
14
|
+
// price every id at $0 so no free call is ever reported as a charge.
|
|
15
|
+
'nvidia/nemotron-3-ultra-550b': { input: 0, output: 0 }, // strongest free model, but 0/5 reachable — NOT the default
|
|
16
|
+
'nvidia/nemotron-3-nano-30b': { input: 0, output: 0 }, // leads the free chain on Base (see free-models.ts)
|
|
17
|
+
'nvidia/nemotron-3.5-lightning': { input: 0, output: 0 },
|
|
19
18
|
'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning': { input: 0, output: 0 },
|
|
20
|
-
'nvidia/
|
|
19
|
+
'nvidia/llama-3.2-11b-vision': { input: 0, output: 0 },
|
|
20
|
+
'cohere/north-mini-code': { input: 0, output: 0 },
|
|
21
|
+
'poolside/laguna-xs-2.1': { input: 0, output: 0 },
|
|
22
|
+
// Substituted free models: gone from /api/v1/models on 2026-08-30, but the
|
|
23
|
+
// gateway still answers for them by serving a different model. Priced at $0
|
|
24
|
+
// for legacy session-cost records — do NOT route to them.
|
|
25
|
+
'nvidia/nemotron-nano-9b-v2': { input: 0, output: 0 }, // -> nemotron-3-nano-30b
|
|
26
|
+
'nvidia/mistral-nemotron': { input: 0, output: 0 }, // -> nemotron-3-super-120b-a12b-free
|
|
27
|
+
'nvidia/nemotron-nano-12b-v2-vl': { input: 0, output: 0 }, // -> nemotron-3-nano-omni
|
|
28
|
+
'nvidia/step-3.7-flash': { input: 0, output: 0 }, // -> nemotron-3.5-lightning
|
|
29
|
+
'nvidia/nemotron-3-super-120b-a12b-free': { input: 0, output: 0 }, // pool backing id, never listed
|
|
21
30
|
// Retired free models (kept at 0 for legacy session-cost records; gateway no
|
|
22
31
|
// longer serves these — do NOT route to them).
|
|
23
32
|
'nvidia/qwen3-next-80b-a3b-instruct': { input: 0, output: 0 }, // NVIDIA EOL 410, 2026-07-27
|
package/dist/proxy/fallback.d.ts
CHANGED
|
@@ -36,5 +36,12 @@ export declare const ROUTING_PROFILES: Set<string>;
|
|
|
36
36
|
* Build fallback chain starting from a specific model.
|
|
37
37
|
* Filters out routing profiles (blockrun/auto etc.) since the backend
|
|
38
38
|
* doesn't recognize them — they must be resolved by the smart router first.
|
|
39
|
+
*
|
|
40
|
+
* A FREE start model never falls back to a paid one. The default chain leads
|
|
41
|
+
* with paid rungs (deepseek, gemini), so a proxy client that explicitly asked
|
|
42
|
+
* for a free model and hit a 429 or a 5xx used to have its next attempt signed
|
|
43
|
+
* as an x402 payment — a wallet charge the caller never asked for, triggered by
|
|
44
|
+
* nothing more than provider overload. `blockrun/free` was already handled;
|
|
45
|
+
* a concrete free id was not.
|
|
39
46
|
*/
|
|
40
|
-
export declare function buildFallbackChain(startModel: string, config?: FallbackConfig): string[];
|
|
47
|
+
export declare function buildFallbackChain(startModel: string, config?: FallbackConfig, needsVision?: boolean): string[];
|
package/dist/proxy/fallback.js
CHANGED
|
@@ -3,11 +3,13 @@
|
|
|
3
3
|
* Automatically switches to backup models when primary fails (429, 5xx, etc.)
|
|
4
4
|
*/
|
|
5
5
|
import { logger } from '../logger.js';
|
|
6
|
+
import { FREE_DEFAULT_MODEL, isFreeModelId } from '../free-models.js';
|
|
7
|
+
import { isVisionModel } from '../router/vision.js';
|
|
6
8
|
export const DEFAULT_FALLBACK_CONFIG = {
|
|
7
9
|
chain: [
|
|
8
10
|
'deepseek/deepseek-chat', // Direct fallback — cheap & reliable
|
|
9
11
|
'google/gemini-2.5-flash', // Fast & capable
|
|
10
|
-
|
|
12
|
+
FREE_DEFAULT_MODEL, // Free model as ultimate fallback — see src/free-models.ts
|
|
11
13
|
],
|
|
12
14
|
retryOn: [429, 500, 502, 503, 504, 529],
|
|
13
15
|
maxRetries: 5,
|
|
@@ -115,10 +117,40 @@ export const ROUTING_PROFILES = new Set([
|
|
|
115
117
|
* Build fallback chain starting from a specific model.
|
|
116
118
|
* Filters out routing profiles (blockrun/auto etc.) since the backend
|
|
117
119
|
* doesn't recognize them — they must be resolved by the smart router first.
|
|
120
|
+
*
|
|
121
|
+
* A FREE start model never falls back to a paid one. The default chain leads
|
|
122
|
+
* with paid rungs (deepseek, gemini), so a proxy client that explicitly asked
|
|
123
|
+
* for a free model and hit a 429 or a 5xx used to have its next attempt signed
|
|
124
|
+
* as an x402 payment — a wallet charge the caller never asked for, triggered by
|
|
125
|
+
* nothing more than provider overload. `blockrun/free` was already handled;
|
|
126
|
+
* a concrete free id was not.
|
|
118
127
|
*/
|
|
119
|
-
export function buildFallbackChain(startModel, config = DEFAULT_FALLBACK_CONFIG) {
|
|
128
|
+
export function buildFallbackChain(startModel, config = DEFAULT_FALLBACK_CONFIG, needsVision = false) {
|
|
120
129
|
// Never include routing profiles in the chain — they'd cause 400s
|
|
121
|
-
|
|
130
|
+
let safeChain = config.chain.filter(m => !ROUTING_PROFILES.has(m));
|
|
131
|
+
// A request carrying images must not fall back onto a text-only model.
|
|
132
|
+
//
|
|
133
|
+
// The pre-request guard in proxy/server.ts swaps a text-only pick for a
|
|
134
|
+
// vision sibling, but it runs ONCE, before the call. This chain is walked
|
|
135
|
+
// AFTER a failure, so the guard was bypassed on every retry: an image sent
|
|
136
|
+
// to claude-sonnet-4.6 that hit a 429 fell straight to
|
|
137
|
+
// deepseek/deepseek-chat, which cannot read images at all.
|
|
138
|
+
//
|
|
139
|
+
// That costs real money. The gateway does not always refuse these before
|
|
140
|
+
// payment — probed 2026-08-31, Base returns 402 (a payment quote) for an
|
|
141
|
+
// image request to deepseek/deepseek-chat and the whole zai/glm-5.x line,
|
|
142
|
+
// while Solana correctly 400s them pre-payment. So on Base the retry is
|
|
143
|
+
// quoted, signed, settled, and THEN rejected upstream — or worse, answered
|
|
144
|
+
// without the image. Same shape as the free-tier guard above: the chain has
|
|
145
|
+
// to know what the request needs, not just what it costs.
|
|
146
|
+
if (needsVision) {
|
|
147
|
+
safeChain = safeChain.filter(m => isVisionModel(m));
|
|
148
|
+
}
|
|
149
|
+
// Free start model → free-only chain. Ends the walk rather than reaching for
|
|
150
|
+
// a paid rung; the caller gets the failure instead of a surprise charge.
|
|
151
|
+
if (isFreeModelId(startModel)) {
|
|
152
|
+
return [startModel, ...safeChain.filter(m => m !== startModel && isFreeModelId(m))];
|
|
153
|
+
}
|
|
122
154
|
const index = safeChain.indexOf(startModel);
|
|
123
155
|
if (index >= 0) {
|
|
124
156
|
return safeChain.slice(index);
|