@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,33 @@
1
+ /**
2
+ * Pure free-tier constants — NO imports, no side effects.
3
+ *
4
+ * Split out of free-models.ts so the PUBLIC plugin SDK can name the free
5
+ * default without dragging core internals in behind it. free-models.ts imports
6
+ * gateway-models.ts, which imports config.ts, which does a `readFileSync` and
7
+ * builds `~/.blockrun` paths AT MODULE LOAD. Before this split, importing
8
+ * `@blockrun/franklin/plugin-sdk` just to read DEFAULT_MODEL_TIERS triggered
9
+ * that filesystem I/O — a side effect the SDK never had when the tier was a
10
+ * bare string literal, and a coupling the plugin-sdk header explicitly forbids
11
+ * ("Core stays plugin-agnostic").
12
+ *
13
+ * This keeps ONE definition, which is the point of the whole module: the
14
+ * alternative was copying the literal back into the SDK and re-acquiring the
15
+ * drift this file was created to end.
16
+ *
17
+ * Rationale, measurements and the routing logic all stay in free-models.ts,
18
+ * which re-exports everything here.
19
+ */
20
+ /**
21
+ * The free model Franklin asks for by default. Chosen for AVAILABILITY, not
22
+ * for being the best — see the full note in free-models.ts.
23
+ */
24
+ export const FREE_DEFAULT_MODEL = 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning';
25
+ /** Free models in preference order, best first. See free-models.ts. */
26
+ export const FREE_PREFERENCE_ORDER = [
27
+ 'nvidia/nemotron-3-nano-30b', // 5/5 healthy, fastest
28
+ FREE_DEFAULT_MODEL, // the floor this never drops below
29
+ 'poolside/laguna-xs-2.1', // different provider
30
+ 'cohere/north-mini-code', // different provider; needs max_tokens >= 1200
31
+ ];
32
+ /** Context budget for ANY free-tier request. See free-models.ts. */
33
+ export const FREE_POOL_CONTEXT_FLOOR = 131_072;
@@ -0,0 +1,320 @@
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 { FREE_DEFAULT_MODEL, FREE_POOL_CONTEXT_FLOOR, FREE_PREFERENCE_ORDER } from './free-models.constants.js';
63
+ export { FREE_DEFAULT_MODEL, FREE_POOL_CONTEXT_FLOOR, FREE_PREFERENCE_ORDER };
64
+ /**
65
+ * The free model Franklin asks for by default.
66
+ *
67
+ * nemotron-3-nano-omni is chosen for AVAILABILITY, not for being the best: it
68
+ * is the only free id present in both the Base and the Solana catalogs. Every
69
+ * other free model is Base-only and 400s on Solana, and Franklin ships with
70
+ * either chain selectable. Base users are upgraded to the stronger model at
71
+ * runtime by freeChain() — see FREE_PREFERENCE_ORDER.
72
+ *
73
+ * Verified on POST /api/v1/messages (Franklin's own endpoint) on both chains:
74
+ * answers as itself, no leaked reasoning, tool calls work.
75
+ */
76
+ /**
77
+ * Free models in preference order, best first.
78
+ *
79
+ * FREE_DEFAULT_MODEL is the id that survived on both chains through the
80
+ * 2026-08-30 rotation window; the rest were Base-only during it. freeChain()
81
+ * filters this against the live catalog for the CURRENT chain, so the list can
82
+ * name ids one gateway lacks without breaking the other.
83
+ *
84
+ * Ordering rationale — AVAILABILITY FIRST, quality second. Measured on
85
+ * /v1/messages, Base, max_tokens 300, 5 calls each (2026-08-31):
86
+ *
87
+ * nemotron-3-nano-30b 5/5 healthy, 0.8-2.9s
88
+ * nemotron-3-nano-omni 2/5 healthy, three HTTP 503s
89
+ * nemotron-3-ultra-550b 0/5 healthy — every call timed out at 40s
90
+ *
91
+ * - nemotron-3-nano-30b leads on Base. It is the pool's own backing model,
92
+ * which is why it is the one id that never comes back as a substitute and
93
+ * the one that stays up when the rest of the pool is congested.
94
+ * - nemotron-3-ultra-550b is NOT in this list, and that reverses an earlier
95
+ * revision which had it leading. It gives the best answers when it answers
96
+ * — the only free model to name Aerodrome for "three Base-chain DEXes"
97
+ * while the others hallucinated Uniswap forks — but a model you cannot
98
+ * reach is not a better model. The andy session measured it independently
99
+ * at 1/3 and 1/5, with NVIDIA congestion relayed as HTTP 200; here it was
100
+ * 0/5 with hard timeouts. It stays reachable by explicit pin
101
+ * (`/model ultra-550b`), it just cannot lead a chain.
102
+ * - the two non-NVIDIA rungs are last on purpose: they are what keeps the
103
+ * chain alive through an NVIDIA-wide outage instead of it being four names
104
+ * for one upstream.
105
+ *
106
+ * Not listed, and why:
107
+ * - nvidia/nemotron-3.5-lightning — LATENCY, and only latency. Measured
108
+ * 10.9s / 12.2s / 22.5s for a one-sentence answer at max_tokens 800,
109
+ * against ~0.8-3s for the rest of the pool. Its name is a lie. (An
110
+ * earlier revision of this file quarantined it for leaking reasoning
111
+ * prose; that was wrong — see TRUNCATION below.)
112
+ * - nvidia/llama-3.2-11b-vision — catalogued as vision, cannot accept an
113
+ * image (see freeVisionModel), and is otherwise the weakest text model in
114
+ * the pool.
115
+ *
116
+ * TRUNCATION: THE FREE POOL NEEDS ROOM TO THINK
117
+ * ---------------------------------------------
118
+ * Every free model here is a reasoning model, and a tight max_tokens makes
119
+ * them look broken in two different ways that are the SAME bug. Measured on
120
+ * chat/completions, 2026-08-31:
121
+ *
122
+ * nemotron-3-nano-30b, "what does approve() do":
123
+ * max_tokens 20 -> finish_reason "length", content is truncated thinking
124
+ * ("Okay, the user is asking about...")
125
+ * max_tokens 120 -> finish_reason "length", still truncated thinking
126
+ * max_tokens 300 -> finish_reason "stop", content is a clean answer and
127
+ * the thinking sits in reasoning_content
128
+ *
129
+ * cohere/north-mini-code, "name three Base-chain DEXes":
130
+ * max_tokens 200 -> EMPTY stream, 0 content chunks, 6 of 8 calls
131
+ * max_tokens 2000 -> 6 of 6 clean, finish_reason "stop"
132
+ *
133
+ * So "leaks chain-of-thought into content" and "returns an empty stream" are
134
+ * both the budget running out before the model stops reasoning. Neither is a
135
+ * property of the model, and neither is worth a workaround — give the call
136
+ * room. This is why the router's tier classifier no longer asks for a
137
+ * one-word answer in 8 tokens (see router/index.ts).
138
+ *
139
+ * The andy session traced the mechanism further, and it changes what the
140
+ * discriminator is. Probed three ways at max_tokens 20: the NIM upstream
141
+ * returns a clean `content: "OK"` with finish_reason "stop", while sol's
142
+ * /chat/completions returns the thinking in `content` with finish_reason
143
+ * "length". The upstream separates the fields correctly; the GATEWAY's
144
+ * extractor falls back to reasoning text when the answer field is empty. So
145
+ * raising max_tokens does not fix the bug, it stops triggering it, and
146
+ * finish_reason "length" is the real discriminator — treat any truncated
147
+ * free-tier reply as suspect regardless of budget.
148
+ *
149
+ * One claim of theirs did NOT reproduce here: they reported /v1/messages
150
+ * leaking on nano-omni at a small budget. Probed at max_tokens 20, 60 and 300
151
+ * on both chains, /v1/messages came back clean 12 of 12, with proper
152
+ * thinking+text block separation and stop_reason "end_turn". Recording the
153
+ * disagreement rather than picking a winner — if it resurfaces, the block
154
+ * separation is the thing to check.
155
+ *
156
+ * Credit: the andy session, which re-measured across budgets, then retracted
157
+ * its own retraction with the three-way upstream probe, and the clawrouter
158
+ * session, which nearly shipped a textual <tool_call> extractor for a model
159
+ * that returns a clean structured tool_calls array once given room.
160
+ */
161
+ /**
162
+ * Context budget for ANY free-tier request, regardless of the catalogued
163
+ * window of the id we asked for.
164
+ *
165
+ * The strongest free model is catalogued at 1M, but the free tier is a pool:
166
+ * on chat/completions a request for it can be served by the 131K
167
+ * nemotron-3-nano-30b with no warning, and the chain-safe default is 256K.
168
+ * Sizing compaction off 1M would build a prompt the substitute cannot accept,
169
+ * and it would fail mid-session on a user who never chose the substitute.
170
+ * 131_072 is the floor of every model in FREE_PREFERENCE_ORDER. The one free
171
+ * id below it (llama-3.2-11b-vision, 128_000) is vision-only and never routed
172
+ * as a text rung, so it is sized from its own catalog entry in tokens.ts.
173
+ */
174
+ /**
175
+ * Catalogued free ids Franklin will not route to, with the reason each was
176
+ * rejected in the 2026-08-30 probe. These are real, billable-at-$0 ids — they
177
+ * are excluded on behaviour, not availability.
178
+ */
179
+ export declare const QUARANTINED_FREE_MODELS: readonly string[];
180
+ /**
181
+ * Free ids Franklin used to name. The gateway still answers for all of them
182
+ * (via substitution), but they are gone from /api/v1/models. Kept so old
183
+ * session-cost records still price at $0 and so stale aliases can be remapped
184
+ * rather than handed back to the user as-is.
185
+ */
186
+ export declare const LEGACY_FREE_MODEL_IDS: readonly string[];
187
+ /**
188
+ * Every free id in the live Base catalog as of 2026-08-30, mapped to its
189
+ * catalogued context window. Used for metadata display; NOT for sizing a
190
+ * request — use FREE_POOL_CONTEXT_FLOOR for that.
191
+ */
192
+ export declare const FREE_MODEL_CONTEXT_WINDOWS: Readonly<Record<string, number>>;
193
+ /**
194
+ * The free model that can accept an image, or null when this chain has none.
195
+ *
196
+ * Chain-aware because the gateways are at different deploy states, not
197
+ * because the models differ. The original defect was gateway-side: both
198
+ * NVIDIA paths dropped every `image_url` unconditionally under a stale
199
+ * comment, which is why it presented as a confident wrong answer with no
200
+ * error. The allow-list fix reached Solana first.
201
+ *
202
+ * FOUR measurement passes, each of which reversed the previous conclusion.
203
+ * The history stays because the reversals are the lesson:
204
+ *
205
+ * 1. 2x2 PNG, both ids fail. INVALID — images under 10px per side
206
+ * are rejected upstream, so the fixture proved nothing.
207
+ * 2. 64x64, 5 calls, llama 5/5 sol. Shipped. Too small a sample.
208
+ * 3. 64x64, 10 calls, llama 5/10. Reverted. A real bad window: the
209
+ * gateway fix was still settling. Fixture validated, so not a repeat
210
+ * of mistake 1.
211
+ * 4. 64x64, 30 calls across both RE-ENABLED. See below.
212
+ * HTTP paths and three runs.
213
+ *
214
+ * Pass 4, validated fixture (`sips` decodes it, and every PNG chunk CRC
215
+ * checks against zlib.crc32 — `file` reports dimensions from the header and
216
+ * will happily accept a corrupt image, which is how a broken fixture
217
+ * masquerades as a broken product):
218
+ *
219
+ * sol llama-3.2-11b-vision /v1/messages 10/10 sees, 0/10 substituted
220
+ * sol llama-3.2-11b-vision /chat/completions 10/10 sees, 0/10 substituted
221
+ * sol llama-3.2-11b-vision /v1/messages (repeat) 10/10 sees, 0/10 substituted
222
+ * base llama-3.2-11b-vision /v1/messages 0/10 sees, 0/10 substituted
223
+ * sol nemotron-3-nano-omni /v1/messages 6/10 sees, 0/10 substituted
224
+ * sol nemotron-3-nano-omni /chat/completions 4/10 sees, 7/10 SUBSTITUTED
225
+ *
226
+ * Re-probed 2026-08-31 after the gateway's vision-routing fix: nano-omni now
227
+ * returns an explicit 400 on image input on /v1/messages ("served text-only on
228
+ * NVIDIA"), refused BEFORE payment. The silent-drop mode is gone on our path —
229
+ * a loud refusal is the outcome this module wanted all along. llama-3.2-11b-vision
230
+ * re-verified 6/6 in the same window, so the bare-call number still holds.
231
+ *
232
+ * So Solana gets llama-3.2-11b-vision and Base honestly reports none. On
233
+ * Base the model serves itself and simply cannot see — 0 substitutions, so
234
+ * this is the missing allow-list fix, not a cascade problem.
235
+ *
236
+ * nano-omni is NEVER used for vision despite its catalog tag. On
237
+ * chat/completions it is substituted 7 times in 10 by nemotron-3-nano-30b,
238
+ * a model with no vision at all (the andy session captured the same thing
239
+ * 3/3), and even unsubstituted it only sees the image 6 times in 10.
240
+ *
241
+ * ACCEPTANCE BAR for changing any of this — all four are required, and each
242
+ * one exists because skipping it produced a wrong answer above:
243
+ * - a fixture >=64x64 that a real decoder accepts and whose CRCs verify;
244
+ * - at least 10 calls (5 is inside the noise);
245
+ * - assert the served `model` echoes the id you requested;
246
+ * - assert the answer is actually right, not merely non-empty.
247
+ *
248
+ * AND YET THIS RETURNS NULL. Pass 5 measured the thing that actually
249
+ * matters — the whole feature, end to end through the binary, not the API
250
+ * call — and it is 1 in 5:
251
+ *
252
+ * bare vision call, validated fixture 30/30
253
+ * end-to-end `franklin --model free` 1/5
254
+ *
255
+ * llama-3.2-11b-vision is reliable as a vision CALL and too weak to drive an
256
+ * agent turn. Given the full tool set it re-called `Read` on the same path
257
+ * until the repeat guard fired. Given no tools after the image was in
258
+ * history (the one-shot path below, which is implemented and stays) it
259
+ * stopped looping and instead ended the turn after `Read` without producing
260
+ * an answer at all. So the blocker is no longer the gateway — it is
261
+ * Franklin's own wiring, which hands a vision turn to a weak model by
262
+ * swapping the AGENT model for the whole turn.
263
+ *
264
+ * A capability that works 30/30 in isolation and 1/5 in the product is not a
265
+ * capability. By the rule this file already applies to nano-omni — an
266
+ * intermittent confident wrong answer is worse than declining, because the
267
+ * caller cannot tell which half they got — Franklin declines and says the
268
+ * image was not seen.
269
+ *
270
+ * THE FIX, for whoever picks this up: do not swap the agent model. Make the
271
+ * vision turn a dedicated one-shot side-call — inline the image, ask the
272
+ * vision model directly, feed the answer back as context, and let the normal
273
+ * agent model finish the turn. The 30/30 says that call will work. The
274
+ * groundwork is in place: the one-shot tool suppression in agent/loop.ts
275
+ * fires whenever this function returns a model.
276
+ *
277
+ * FRANKLIN_FREE_VISION_MODEL overrides ('none' disables), so the whole path
278
+ * above can be exercised without a code change.
279
+ */
280
+ export declare function freeVisionModel(): string | null;
281
+ /**
282
+ * Is this id billed at $0?
283
+ *
284
+ * Replaces the `m.startsWith('nvidia/')` heuristic that was spread across the
285
+ * subagent tool, the /model command and the compaction picker. That heuristic
286
+ * was wrong in both directions once the pool rotated:
287
+ *
288
+ * - nvidia/kimi-k2.5 is a PAID model ($0.55/$2.50 per 1M). Treating it as
289
+ * free meant `/model kimi-k2.5` skipped the "charges from your wallet"
290
+ * warning, and a free-tier parent could hand compaction a paid model.
291
+ * - poolside/laguna-xs-2.1 and cohere/north-mini-code are free and carry no
292
+ * `nvidia/` prefix, so they were treated as paid.
293
+ *
294
+ * The live catalog is consulted first (it is authoritative and picks up new
295
+ * free ids without a release); the static sets answer when the cache is cold.
296
+ */
297
+ export declare function isFreeModelId(id: string | undefined | null): boolean;
298
+ /**
299
+ * The free chain to try right now, best first, filtered to what the CURRENT
300
+ * chain's gateway actually lists.
301
+ *
302
+ * peekGatewayModel reads the cached catalog and never triggers a fetch, so
303
+ * this is safe on the hot path and in sync callers. When the cache is cold
304
+ * there is no evidence either way, and the answer is the one id that exists
305
+ * on both chains — guessing the Base-only model there would 400 every Solana
306
+ * user's first turn, which is the exact failure this function exists to
307
+ * prevent.
308
+ *
309
+ * `exclude` drops rungs that already failed this turn.
310
+ */
311
+ export declare function freeChain(exclude?: ReadonlySet<string>): string[];
312
+ /**
313
+ * Pick the single free model to request right now. See freeChain().
314
+ *
315
+ * Returns undefined when every candidate is excluded — it must NEVER hand back
316
+ * a model the caller listed in `exclude`. The previous `?? FREE_DEFAULT_MODEL`
317
+ * fallback did exactly that on a cold cache, which would spin a retry loop on
318
+ * a model the caller had just watched fail.
319
+ */
320
+ export declare function resolveFreeModel(exclude?: ReadonlySet<string>): string | undefined;