@blockrun/franklin 3.42.1 → 3.43.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.
Files changed (39) hide show
  1. package/README.md +7 -9
  2. package/dist/agent/commands.js +2 -2
  3. package/dist/agent/compact.js +6 -3
  4. package/dist/agent/context.js +1 -1
  5. package/dist/agent/evaluator.js +2 -1
  6. package/dist/agent/llm.js +4 -3
  7. package/dist/agent/loop.js +82 -14
  8. package/dist/agent/nemotron-prose-stripper.d.ts +26 -0
  9. package/dist/agent/nemotron-prose-stripper.js +39 -1
  10. package/dist/agent/tokens.js +22 -5
  11. package/dist/agent/turn-analyzer.js +18 -6
  12. package/dist/agent/verification.js +2 -1
  13. package/dist/brain/extract.js +2 -1
  14. package/dist/commands/slack.js +2 -1
  15. package/dist/commands/social.js +2 -1
  16. package/dist/commands/telegram.js +2 -1
  17. package/dist/free-models.constants.d.ts +28 -0
  18. package/dist/free-models.constants.js +33 -0
  19. package/dist/free-models.d.ts +320 -0
  20. package/dist/free-models.js +407 -0
  21. package/dist/gateway-models.js +15 -3
  22. package/dist/learnings/extractor.js +3 -2
  23. package/dist/plugin-sdk/workflow.js +5 -2
  24. package/dist/pricing.js +18 -9
  25. package/dist/proxy/fallback.d.ts +7 -0
  26. package/dist/proxy/fallback.js +14 -1
  27. package/dist/proxy/server.js +15 -2
  28. package/dist/router/index.d.ts +3 -1
  29. package/dist/router/index.js +140 -89
  30. package/dist/router/vision.js +35 -10
  31. package/dist/serve/server.js +1 -4
  32. package/dist/tools/moa.js +9 -3
  33. package/dist/tools/modal.d.ts +25 -0
  34. package/dist/tools/modal.js +87 -9
  35. package/dist/tools/subagent.js +6 -5
  36. package/dist/ui/model-picker.js +75 -74
  37. package/dist/wallet/reservation.d.ts +40 -3
  38. package/dist/wallet/reservation.js +91 -10
  39. package/package.json +3 -3
@@ -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
+ }
@@ -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
- 'nvidia/nemotron-nano-9b-v2', // Serves itself on every path (verified live 2026-08-12)
13
- 'nvidia/mistral-nemotron', // Fallback: DEGRADED upstream but non-stream calls ride the gateway fallback
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: 'nvidia/nemotron-nano-9b-v2',
9
- cheap: 'nvidia/nemotron-nano-9b-v2', // Free by default; opt-in to paid flat-rate via 'zai/glm-5.1'.
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 to match live
12
- // /api/v1/models). nemotron-nano-9b-v2 is the current free default — the
13
- // one free model that verifiably serves itself on the streaming path
14
- // (mistral-nemotron is DEGRADED upstream: stream calls 400, non-stream
15
- // rides a disclosed gateway fallback).
16
- 'nvidia/nemotron-nano-9b-v2': { input: 0, output: 0 },
17
- 'nvidia/mistral-nemotron': { input: 0, output: 0 },
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/step-3.7-flash': { input: 0, output: 0 },
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
@@ -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
47
  export declare function buildFallbackChain(startModel: string, config?: FallbackConfig): string[];
@@ -3,11 +3,12 @@
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';
6
7
  export const DEFAULT_FALLBACK_CONFIG = {
7
8
  chain: [
8
9
  'deepseek/deepseek-chat', // Direct fallback — cheap & reliable
9
10
  'google/gemini-2.5-flash', // Fast & capable
10
- 'nvidia/nemotron-nano-9b-v2', // Free model as ultimate fallback (reliable instruction-follower)
11
+ FREE_DEFAULT_MODEL, // Free model as ultimate fallback — see src/free-models.ts
11
12
  ],
12
13
  retryOn: [429, 500, 502, 503, 504, 529],
13
14
  maxRetries: 5,
@@ -115,10 +116,22 @@ export const ROUTING_PROFILES = new Set([
115
116
  * Build fallback chain starting from a specific model.
116
117
  * Filters out routing profiles (blockrun/auto etc.) since the backend
117
118
  * doesn't recognize them — they must be resolved by the smart router first.
119
+ *
120
+ * A FREE start model never falls back to a paid one. The default chain leads
121
+ * with paid rungs (deepseek, gemini), so a proxy client that explicitly asked
122
+ * for a free model and hit a 429 or a 5xx used to have its next attempt signed
123
+ * as an x402 payment — a wallet charge the caller never asked for, triggered by
124
+ * nothing more than provider overload. `blockrun/free` was already handled;
125
+ * a concrete free id was not.
118
126
  */
119
127
  export function buildFallbackChain(startModel, config = DEFAULT_FALLBACK_CONFIG) {
120
128
  // Never include routing profiles in the chain — they'd cause 400s
121
129
  const safeChain = config.chain.filter(m => !ROUTING_PROFILES.has(m));
130
+ // Free start model → free-only chain. Ends the walk rather than reaching for
131
+ // a paid rung; the caller gets the failure instead of a surprise charge.
132
+ if (isFreeModelId(startModel)) {
133
+ return [startModel, ...safeChain.filter(m => m !== startModel && isFreeModelId(m))];
134
+ }
122
135
  const index = safeChain.indexOf(startModel);
123
136
  if (index >= 0) {
124
137
  return safeChain.slice(index);
@@ -10,6 +10,7 @@ import { buildFallbackChain, DEFAULT_FALLBACK_CONFIG, ROUTING_PROFILES, } from '
10
10
  import { routeRequest, parseRoutingProfile, isVisionModel, messagesNeedVision, pickVisionSibling, markModelUnavailable, } from '../router/index.js';
11
11
  import { classifyAgentError } from '../agent/error-classifier.js';
12
12
  import { estimateCost } from '../pricing.js';
13
+ import { freeVisionModel, isFreeModelId } from '../free-models.js';
13
14
  import { getMaxOutputTokens } from '../agent/optimize.js';
14
15
  import { VERSION } from '../config.js';
15
16
  // User-Agent for backend requests
@@ -377,11 +378,23 @@ export function createProxy(options) {
377
378
  // sending the image would tokenize as base64 text and produce
378
379
  // a hallucinated answer. Same swap policy as the agent loop's
379
380
  // interactive path so behavior is consistent across surfaces.
381
+ //
382
+ // Exception: a FREE model is never swapped for a paid one. There
383
+ // is no free vision model (router/vision.ts), so the sibling
384
+ // lookup returns the paid default — swapping would start
385
+ // charging a user who explicitly chose the free tier.
380
386
  const original = requestModel;
381
- const visionSwap = pickVisionSibling(original);
387
+ const visionSwap = isFreeModelId(original)
388
+ ? (freeVisionModel() ?? original)
389
+ : pickVisionSibling(original);
382
390
  parsed.model = visionSwap;
383
391
  requestModel = visionSwap;
384
- logger.warn(`[franklin] 👁️ Vision swap: ${original} can't see images → ${visionSwap}`);
392
+ logger.warn(visionSwap === original
393
+ // Free tier with no free vision model: nothing to swap to, and
394
+ // we must not reach for a paid one. Say that, rather than
395
+ // logging a swap that did not happen.
396
+ ? `[franklin] 👁️ ${original} can't see images and no free vision model is available — answering from text only`
397
+ : `[franklin] 👁️ Vision swap: ${original} can't see images → ${visionSwap}`);
385
398
  }
386
399
  {
387
400
  const original = parsed.max_tokens;
@@ -91,7 +91,9 @@ export declare function getFallbackChain(tier: Tier, profile?: RoutingProfile):
91
91
  * free models have already failed this turn. Returns undefined when every
92
92
  * candidate has been exhausted (caller should surface an error to user).
93
93
  */
94
- export declare function pickFreeFallback(category: string, alreadyFailed: Set<string>): string | undefined;
94
+ export declare function pickFreeFallback(
95
+ /** @deprecated Ignored — the free chain no longer varies by category. */
96
+ category: string, alreadyFailed: Set<string>): string | undefined;
95
97
  /**
96
98
  * Parse routing profile from model string
97
99
  */