@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
package/README.md CHANGED
@@ -286,7 +286,7 @@ Every tool call is itemized. Every token is priced. When the wallet hits zero, F
286
286
 
287
287
  ## Smart Router
288
288
 
289
- **<!-- br:models.chatVisible -->72<!-- /br:models.chatVisible --> models. One decision. Zero guesswork.**
289
+ **<!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models. One decision. Zero guesswork.**
290
290
 
291
291
  You don't pick models. Franklin picks for you.
292
292
 
@@ -345,7 +345,7 @@ You don't subscribe to electricity, you pay for what you use. Franklin brings th
345
345
 
346
346
  ### 🧠 &nbsp;Multi-model is the future
347
347
 
348
- No single model is best at everything. Sonnet writes better code, Gemini handles longer context, DeepSeek costs 20x less for simple tasks. The Smart Router routes every request to the optimal model in <1ms — <!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->% cheaper than pinning Claude Opus 5 for every request.
348
+ No single model is best at everything. Sonnet writes better code, Gemini handles longer context, DeepSeek costs 20x less for simple tasks. The Smart Router routes every request to the optimal model in <1ms — <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% cheaper than pinning Claude Opus 5 for every request.
349
349
 
350
350
  </td>
351
351
  <td width="33%" valign="top">
@@ -367,7 +367,7 @@ No email. No phone. No KYC. Your Base or Solana address is your account — port
367
367
  | Writes code | ✅ | ✅ | ⚠️ | ✅ |
368
368
  | **Spends money for you** | ❌ | ❌ | ❌ | ✅ **USDC wallet, x402** |
369
369
  | **Buys data + APIs + images + search** | ❌ | ❌ | ❌ | ✅ **55+ APIs, one wallet** |
370
- | Picks best model per task | ❌ single-vendor | ❌ plan-tied | ❌ | ✅ **Smart Router, <!-- br:models.chatVisible -->72<!-- /br:models.chatVisible --> models** |
370
+ | Picks best model per task | ❌ single-vendor | ❌ plan-tied | ❌ | ✅ **Smart Router, <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models** |
371
371
  | Pricing model | Subscription | Subscription | Subscription | **YOPO** — per outcome, USDC |
372
372
  | Monthly fee | $20–$200 | $20–$40 | $20+ | **$0** |
373
373
  | Rate-limited | Yes | Yes | Yes | No — limited only by wallet |
@@ -395,14 +395,14 @@ Ask "what's BTC looking like?" — Franklin fetches live price data, computes RS
395
395
  **🎨 AI image generation**
396
396
  Ask "generate a logo" — Franklin calls DALL-E / GPT Image, saves the result locally, paid from your wallet.
397
397
 
398
- **🧠 <!-- br:models.chatVisible -->72<!-- /br:models.chatVisible --> models via one wallet**
398
+ **🧠 <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models via one wallet**
399
399
  Anthropic, OpenAI, Google, xAI, DeepSeek, GLM, Kimi, Minimax, NVIDIA free tier. One wallet, one interface, automatic fallback.
400
400
 
401
401
  **💳 x402 micropayments (YOPO)**
402
402
  HTTP 402 native. Every paid action is a signed USDC micropayment via EIP-712 — non-custodial, your keys never leave your machine. YOPO: you pay only for outcomes.
403
403
 
404
404
  **🧠 Learned model router**
405
- Trained on 2M+ real requests. Classifies your task and picks the best model from <!-- br:models.chatVisible -->72<!-- /br:models.chatVisible --> LLMs. Four profiles (auto/eco/premium/free). Adapts to your usage over time.
405
+ Trained on 2M+ real requests. Classifies your task and picks the best model from <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> LLMs. Four profiles (auto/eco/premium/free). Adapts to your usage over time.
406
406
 
407
407
  </td>
408
408
  <td width="50%" valign="top">
@@ -571,11 +571,9 @@ Full BlockRun docs: **https://blockrun.ai/docs**
571
571
 
572
572
  ## Contributors
573
573
 
574
- External contributors whose work has shipped into Franklin:
574
+ Franklin ships work from outside the core team on a regular basis: typed Phone & Voice tools, the `/market` command, the model picker catalog, Jupiter precision guards, and the bug reports behind the prompt-caching, stream-timeout, and wallet-reservation fixes.
575
575
 
576
- - [**@KillerQueen-Z**](https://github.com/KillerQueen-Z) — typed Phone & Voice tools (#58), permissions classifier + internal VoiceStatus polling (#59), inline-paste threshold (#60), voicemail controls (#61), PredictionMarket / Predexon v2 schema realignment + agent-loop retry guard (#62)
577
- - [**@BeneficialVast1048**](https://github.com/BeneficialVast1048) — VoiceCall `interruption_threshold` + `model` controls (#66)
578
- - [**@TateLyman**](https://github.com/TateLyman) — test path-with-spaces fix (#57)
576
+ The full list, with what each person shipped, lives in [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md). Thank you.
579
577
 
580
578
  PRs welcome — see the Development section below for the local loop.
581
579
 
@@ -14,6 +14,7 @@ import { estimateHistoryTokens, getAnchoredTokenCount, getContextWindow, resetTo
14
14
  import { forceCompact } from './compact.js';
15
15
  import { getStatsSummary, recordUsage } from '../stats/tracker.js';
16
16
  import { resolveModel } from '../ui/model-picker.js';
17
+ import { isFreeModelId } from '../free-models.js';
17
18
  import { listSessions, loadSessionHistory, } from '../session/storage.js';
18
19
  import { matchSkill } from '../skills/invoke.js';
19
20
  // ─── Git helpers ──────────────────────────────────────────────────────────
@@ -1049,8 +1050,7 @@ export async function handleSlashCommand(input, ctx) {
1049
1050
  ctx.config.baseModel = newModel; // Update recovery target so loop doesn't reset
1050
1051
  ctx.config.onModelChange?.(newModel, 'user');
1051
1052
  // Warn when switching from free to paid so users know charges start now
1052
- const isFree = (m) => m.startsWith('nvidia/') || m === 'blockrun/free';
1053
- const paidWarning = !isFree(newModel)
1053
+ const paidWarning = !isFreeModelId(newModel)
1054
1054
  ? ` ⚠️ (paid — charges from your wallet per call)`
1055
1055
  : '';
1056
1056
  ctx.onEvent({ kind: 'text_delta', text: `Model → **${newModel}**${paidWarning}\n` });
@@ -5,6 +5,7 @@
5
5
  */
6
6
  import { existsSync, readFileSync } from 'node:fs';
7
7
  import { estimateHistoryTokens, getCompactionThreshold, COMPACTION_SUMMARY_RESERVE, } from './tokens.js';
8
+ import { FREE_DEFAULT_MODEL, isFreeModelId } from '../free-models.js';
8
9
  /** Max files to restore after compaction */
9
10
  const POST_COMPACT_MAX_FILES = 5;
10
11
  /** Max tokens to spend on post-compact file restoration */
@@ -454,9 +455,11 @@ function formatCompactSummary(raw) {
454
455
  * so users don't get silent charges when their context fills up.
455
456
  */
456
457
  function pickCompactionModel(primaryModel) {
457
- // Free parent → free compaction (no silent charge)
458
- if (primaryModel.startsWith('nvidia/') || primaryModel === 'blockrun/free') {
459
- return 'nvidia/nemotron-nano-9b-v2';
458
+ // Free parent → free compaction (no silent charge). Uses the shared
459
+ // predicate: `startsWith('nvidia/')` would have sent a free-tier user's
460
+ // compaction to the PAID nvidia/kimi-k2.5 without a warning.
461
+ if (isFreeModelId(primaryModel)) {
462
+ return FREE_DEFAULT_MODEL;
460
463
  }
461
464
  // Use cheapest capable model for summarization to save cost
462
465
  // Tier down: opus/pro → sonnet, sonnet → haiku, everything else → flash (cheapest capable)
@@ -242,7 +242,7 @@ You run on the BlockRun AI Gateway. When the user asks you to "test the BlockRun
242
242
  - \`GET /.well-known/x402\` — x402 resource list with prices
243
243
 
244
244
  **LLM (POST, x402-paid)**
245
- - \`POST /v1/chat/completions\` — OpenAI-compatible. Body: \`{ model, messages, stream?, tools?, max_tokens?, temperature? }\`. \`model\` MUST come from \`GET /v1/models\` (real frontier examples on the gateway, verified live 2026-08-29: \`anthropic/claude-sonnet-5\`, \`anthropic/claude-opus-5\`, \`openai/gpt-5.6-sol\`, \`deepseek/deepseek-v4-pro\`, \`zai/glm-5.3\`, \`zai/glm-5.3-flash\`, \`xai/grok-4.5\`, \`qwen/qwen3.7-flash\`, \`nvidia/nemotron-nano-9b-v2\` (free)). Do NOT invent versions like \`openai/gpt-5.1\` or \`xai/grok-5\` — those don't exist; the gateway 400s with the valid list in the error body, so when in doubt fetch \`GET /v1/models\` first.
245
+ - \`POST /v1/chat/completions\` — OpenAI-compatible. Body: \`{ model, messages, stream?, tools?, max_tokens?, temperature? }\`. \`model\` MUST come from \`GET /v1/models\` (real frontier examples on the gateway, verified live 2026-08-30: \`anthropic/claude-sonnet-5\`, \`anthropic/claude-opus-5\`, \`openai/gpt-5.6-sol\`, \`deepseek/deepseek-v4-pro\`, \`zai/glm-5.3\`, \`zai/glm-5.3-flash\`, \`xai/grok-4.5\`, \`qwen/qwen3.7-flash\`, \`nvidia/nemotron-3-nano-omni-30b-a3b-reasoning\` (free, the only free id on BOTH the Base and Solana gateways — the other free models are Base-only)). Do NOT invent versions like \`openai/gpt-5.1\` or \`xai/grok-5\` — those don't exist; the gateway 400s with the valid list in the error body, so when in doubt fetch \`GET /v1/models\` first.
246
246
  - \`POST /v1/messages\` — Anthropic-compatible. Body: \`{ model, messages, max_tokens, system?, tools? }\`.
247
247
 
248
248
  **Media (POST, x402-paid; GET to poll async jobs)**
@@ -21,6 +21,7 @@
21
21
  * PASS) is a v2 concern once we know v1 catches real cases without
22
22
  * false-positive noise.
23
23
  */
24
+ import { FREE_DEFAULT_MODEL } from '../free-models.js';
24
25
  // ─── Evaluator system prompt ─────────────────────────────────────────────
25
26
  //
26
27
  // Principle-based, not example-enumerating. Specific tickers or phrasings
@@ -249,7 +250,7 @@ export function parseGroundingResponse(raw) {
249
250
  * choice so both quality gates have the same cost profile. Override via
250
251
  * `FRANKLIN_EVALUATOR_MODEL` to experiment with accuracy/cost trade-offs. */
251
252
  export function evaluatorModel() {
252
- return process.env.FRANKLIN_EVALUATOR_MODEL || 'nvidia/nemotron-nano-9b-v2';
253
+ return process.env.FRANKLIN_EVALUATOR_MODEL || FREE_DEFAULT_MODEL;
253
254
  }
254
255
  // ─── Run grounding check ─────────────────────────────────────────────────
255
256
  const MAX_EVAL_TOKENS = 512;
package/dist/agent/llm.js CHANGED
@@ -10,6 +10,7 @@ import { routeRequest, parseRoutingProfile } from '../router/index.js';
10
10
  import { ThinkTagStripper } from './think-tag-stripper.js';
11
11
  import { isNemotronProseModel, stripNemotronProse } from './nemotron-prose-stripper.js';
12
12
  import { repairAndParseArgs } from './repair/index.js';
13
+ import { FREE_DEFAULT_MODEL } from '../free-models.js';
13
14
  // Reasoning-tier models the gateway routes to that reject `tool_choice`
14
15
  // outright. Pattern: OpenAI o1/o3 family + DeepSeek's reasoner variant.
15
16
  // Add new entries as their 400 errors appear in real sessions; this is
@@ -465,10 +466,10 @@ export class ModelClient {
465
466
  // `blockrun/premium` strings (now retired routing profiles) end up at the
466
467
  // same place without needing dedicated entries.
467
468
  const FALLBACKS = {
468
- 'blockrun/auto': 'nvidia/nemotron-nano-9b-v2',
469
- 'blockrun/free': 'nvidia/nemotron-nano-9b-v2',
469
+ 'blockrun/auto': FREE_DEFAULT_MODEL,
470
+ 'blockrun/free': FREE_DEFAULT_MODEL,
470
471
  };
471
- return FALLBACKS[model] || 'nvidia/nemotron-nano-9b-v2';
472
+ return FALLBACKS[model] || FREE_DEFAULT_MODEL;
472
473
  }
473
474
  /**
474
475
  * USDC actually charged for the most recent stream. 0 if no payment
@@ -43,7 +43,7 @@ import { writeLiveAgent } from '../session/live-registry.js';
43
43
  import { estimateCost, OPUS_PRICING } from '../pricing.js';
44
44
  import { maybeMidSessionExtract } from '../learnings/extractor.js';
45
45
  import { extractMentions, buildEntityContext, loadEntities } from '../brain/store.js';
46
- import { routeRequest, parseRoutingProfile, getFallbackChain, pickFreeFallback, isVisionModel, messageNeedsVision, pickVisionSibling, markModelUnavailable } from '../router/index.js';
46
+ import { routeRequest, parseRoutingProfile, getFallbackChain, pickFreeFallback, isVisionModel, messageNeedsVision, messagesNeedVision, pickVisionSibling, markModelUnavailable } from '../router/index.js';
47
47
  import { recordOutcome } from '../router/local-elo.js';
48
48
  import { shouldPlan, getPlanningPrompt, getExecutorModel, isExecutorStuck, toolCallSignature } from './planner.js';
49
49
  import { shouldVerify, runVerification } from './verification.js';
@@ -53,6 +53,7 @@ import { analyzeTurn } from './turn-analyzer.js';
53
53
  import { evaluateTimeoutRetry } from './retry-policy.js';
54
54
  import { MAX_AUTO_CONTINUATIONS_PER_TURN, buildContinuationPrompt, isAutoContinuationDisabled, } from './continuation.js';
55
55
  import { createSessionId, appendToSession, updateSessionMeta, pruneOldSessions, loadSessionHistory, loadSessionMeta, } from '../session/storage.js';
56
+ import { freeVisionModel, isFreeModelId } from '../free-models.js';
56
57
  /**
57
58
  * Atomically replace all elements in a history array.
58
59
  * Safer than `history.length = 0; history.push(...)` because if push throws
@@ -473,9 +474,11 @@ function formatModelSwitch(alias, resolved, reason, newModel) {
473
474
  */
474
475
  export function isWeakModel(model) {
475
476
  const m = model.toLowerCase();
476
- // NVIDIA-hosted open models have been observed confabulating tool calls.
477
- // `blockrun/free` resolves to an NVIDIA model before the API call, so
478
- // catching the `nvidia/` prefix also catches the free-profile path.
477
+ // Free-tier open models have been observed confabulating tool calls. The
478
+ // whole free pool qualifies, including the non-NVIDIA rungs (poolside,
479
+ // cohere) added when the pool rotated on 2026-08-30.
480
+ if (isFreeModelId(model))
481
+ return true;
479
482
  if (m.startsWith('nvidia/'))
480
483
  return true;
481
484
  if (m.includes('nemotron-ultra'))
@@ -1392,11 +1395,26 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1392
1395
  lastRoutedModel = routing.model;
1393
1396
  lastRoutedCategory = routing.category || '';
1394
1397
  if (loopCount === 1) {
1395
- const visionTag = turnNeedsVision ? ' 👁️' : '';
1398
+ // A free-profile vision turn is routed to a TEXT model on purpose:
1399
+ // the gateway has no free model that honours an image (see
1400
+ // router/vision.ts). Say so instead of showing the 👁️ tag over a
1401
+ // model that will answer from the text stub alone — and never fall
1402
+ // back to a paid model, which the free profile must not do.
1403
+ const visionUnavailable = routing.signals.includes('free-vision-unavailable');
1404
+ const visionTag = turnNeedsVision && !visionUnavailable ? ' 👁️' : '';
1396
1405
  onEvent({
1397
1406
  kind: 'text_delta',
1398
1407
  text: `*Auto → ${routing.model}${visionTag}*\n\n`,
1399
1408
  });
1409
+ if (visionUnavailable) {
1410
+ onEvent({
1411
+ kind: 'text_delta',
1412
+ text: '*⚠️ No free vision model is available — the free vision ids drop the ' +
1413
+ 'image on about half of all calls and answer anyway. This turn answers ' +
1414
+ 'from text only, so treat anything said about the image as a guess. ' +
1415
+ 'Switch to a paid model (e.g. `/model haiku`) to send it.*\n\n',
1416
+ });
1417
+ }
1400
1418
  }
1401
1419
  }
1402
1420
  else if (turnNeedsVision && !isVisionModel(resolvedModel)) {
@@ -1409,13 +1427,42 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1409
1427
  // overridden). Always emit a visible notice so the user knows their
1410
1428
  // pick was overridden and why.
1411
1429
  const original = resolvedModel;
1412
- const visionSwap = pickVisionSibling(original);
1413
- resolvedModel = visionSwap;
1414
- config.model = visionSwap;
1415
- onEvent({
1416
- kind: 'text_delta',
1417
- text: `*⚠️ ${original} can't see images — using ${visionSwap} for this turn.*\n\n`,
1418
- });
1430
+ // A free-tier model must NEVER be swapped for a paid one. There is no
1431
+ // free vision model (router/vision.ts), so pickVisionSibling would
1432
+ // return the paid default and start charging a user who explicitly
1433
+ // chose the free tier — silently, mid-turn. Say so and stay free.
1434
+ if (isFreeModelId(original)) {
1435
+ // Stay on the free tier: swap to the chain's free vision model if it
1436
+ // has one, otherwise say so. Never swap a free model for a paid one.
1437
+ const freeVision = freeVisionModel();
1438
+ if (freeVision) {
1439
+ resolvedModel = freeVision;
1440
+ config.model = freeVision;
1441
+ onEvent({
1442
+ kind: 'text_delta',
1443
+ text: `*⚠️ ${original} can't see images — using ${freeVision} for this turn (still free).*\n\n`,
1444
+ });
1445
+ }
1446
+ else {
1447
+ onEvent({
1448
+ kind: 'text_delta',
1449
+ text: `*⚠️ ${original} can't see images, and no free vision model ` +
1450
+ 'is reliable right now — the free vision ids drop the image on ' +
1451
+ 'about half of all calls and answer anyway. Answering from ' +
1452
+ 'text only, so treat anything said about the image as a guess; ' +
1453
+ 'switch to a paid model (e.g. `/model haiku`) to send it.*\n\n',
1454
+ });
1455
+ }
1456
+ }
1457
+ else {
1458
+ const visionSwap = pickVisionSibling(original);
1459
+ resolvedModel = visionSwap;
1460
+ config.model = visionSwap;
1461
+ onEvent({
1462
+ kind: 'text_delta',
1463
+ text: `*⚠️ ${original} can't see images — using ${visionSwap} for this turn.*\n\n`,
1464
+ });
1465
+ }
1419
1466
  }
1420
1467
  // The pre-routing cap was calculated from the virtual profile name.
1421
1468
  // Re-apply it to the concrete pick so capability filtering and the
@@ -1463,6 +1510,22 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1463
1510
  // answer (and waste the spend). Opt-in per config. Ordered last so a
1464
1511
  // forced turn intentionally rebuilds the prompt from the base (dropping
1465
1512
  // the skill hints above); normal turns keep them.
1513
+ // ── Free vision is a ONE-SHOT ──
1514
+ // llama-3.2-11b-vision reads an image reliably as a bare call (30/30 on
1515
+ // a validated fixture) and confabulates in a tool loop: handed the full
1516
+ // tool set it re-called `Read` on the same path until the repeat guard
1517
+ // stopped the turn, in one run out of two. Once the image is actually in
1518
+ // the history there is nothing left to fetch, so take the tools away and
1519
+ // let it answer. Read still runs on the first pass — this only fires
1520
+ // after an image block exists.
1521
+ if (resolvedModel === freeVisionModel() &&
1522
+ callToolDefs.length > 0 &&
1523
+ messagesNeedVision(history)) {
1524
+ callToolDefs = [];
1525
+ callSystemPrompt = systemPrompt +
1526
+ '\n\nThe image is already included above. Answer the question about it ' +
1527
+ 'directly. Do not call any tools.';
1528
+ }
1466
1529
  const onFinalTurn = config.forceAnswerOnFinalTurn && loopCount === maxTurns;
1467
1530
  const toolBudgetSpent = config.maxToolCalls != null && turnToolCalls >= config.maxToolCalls;
1468
1531
  if ((onFinalTurn || toolBudgetSpent) && callToolDefs.length > 0) {
@@ -1588,8 +1651,13 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
1588
1651
  if (!hasText && !hasTools && !hasThinking) {
1589
1652
  // Free-only recovery chain — a free/empty-response session must NEVER
1590
1653
  // fall back to a paid model (would silently charge the wallet). Both
1591
- // entries are $0 nvidia models.
1592
- const EMPTY_FALLBACK_MODELS = ['nvidia/nemotron-nano-9b-v2', 'nvidia/mistral-nemotron'];
1654
+ // entries are $0 free-tier ids; the second is deliberately a different
1655
+ // PROVIDER (poolside), not another NVIDIA id.
1656
+ // Built from the live chain, not a literal list: the second rung used
1657
+ // to be a hardcoded `poolside/laguna-xs-2.1`, which is absent from
1658
+ // some gateways and 400s there — so the rescue was guaranteed to fail
1659
+ // on exactly the chains it was meant to rescue.
1660
+ const EMPTY_FALLBACK_MODELS = getFallbackChain('SIMPLE', 'free');
1593
1661
  const nextModel = EMPTY_FALLBACK_MODELS.find(m => m !== config.model && !turnFailedModels.has(m));
1594
1662
  if (nextModel && recoveryAttempts < 2 && !config.disableModelFallback) {
1595
1663
  recoveryAttempts++;
@@ -16,6 +16,32 @@
16
16
  * `thinking` so it can be routed to the thinking display channel; the
17
17
  * remainder is the user-facing `answer`.
18
18
  */
19
+ /**
20
+ * Which models can put chain-of-thought in `content`?
21
+ *
22
+ * Scope correction (2026-08-31). A previous revision widened this to the
23
+ * whole free tier on the theory that the pool leaks. Re-measured across token
24
+ * budgets, that was wrong: the "leak" is max_tokens TRUNCATION. A Nemotron
25
+ * reasoning model cut off mid-thought emits the partial trace in `content`
26
+ * with finish_reason "length"; given room it returns a clean answer with
27
+ * finish_reason "stop" and the trace in `reasoning_content`.
28
+ *
29
+ * nemotron-3-nano-30b, same prompt, chat/completions:
30
+ * max_tokens 120 -> "length", content = "Okay, the user is asking..."
31
+ * max_tokens 300 -> "stop", content = the actual answer
32
+ *
33
+ * So the fix is to give free calls room (see router/index.ts's classifier
34
+ * budget and turn-analyzer.ts's), not to scrub output. This stays narrow — the
35
+ * Nemotron family, the only models observed producing untagged prose — because
36
+ * a wider net plus an opener match could truncate a legitimate answer that
37
+ * happens to begin "The user asks...".
38
+ *
39
+ * KNOWN LIMITATION: the real discriminator is `finish_reason === "length"`,
40
+ * which this module never sees — the streaming call site in agent/llm.ts
41
+ * decides whether to strip before the finish reason arrives. Until that is
42
+ * plumbed through, the opener list is the proxy for it, which is why the
43
+ * openers must stay specific enough that an untruncated answer cannot match.
44
+ */
19
45
  export declare function isNemotronProseModel(model: string): boolean;
20
46
  export declare function stripNemotronProse(text: string): {
21
47
  thinking: string;
@@ -18,6 +18,18 @@
18
18
  */
19
19
  const REASONING_OPENERS = [
20
20
  /^the user (asks|wants|says|requested|is asking|wants me|wrote|just|said)/i,
21
+ // Observed live 2026-08-30 on truncated (finish_reason "length") replies
22
+ // from nemotron-3-nano-30b and nemotron-3.5-lightning.
23
+ //
24
+ // `/^hmm,?\s/` and a bare `/^we need to/` were tried here and REMOVED: they
25
+ // match ordinary answers ("We need to bump the timeout first…"), and because
26
+ // stripNemotronProse discards everything up to the LAST answer-introducer, a
27
+ // false positive silently deletes real content rather than degrading it. The
28
+ // surviving patterns all name the user or the request explicitly, which an
29
+ // answer addressed TO the user does not do.
30
+ /^here'?s\s+(?:a|my|the)\s+thinking process/i,
31
+ /^user (asks|says|wants|requested|wrote)/i,
32
+ /^we need to (classify|answer|determine|decide|figure out|respond)\b/i,
21
33
  /^looking at (this|the)/i,
22
34
  /^based on (the|this)/i,
23
35
  /^according to/i,
@@ -38,8 +50,34 @@ const ANSWER_INTRODUCERS = [
38
50
  /(?:^|[\s.])(?:output|response|answer|reply|token)\s*:\s*/gi,
39
51
  /\bi(?:'ll| will| shall)\s+(?:output|respond|say|reply|return|emit|write|give|print)\s+(?:the|a|with|out|to|exactly|back|only)?\s*(?:token|word|answer|response|string|text|output|message)?\s*:?\s*/gi,
40
52
  ];
53
+ /**
54
+ * Which models can put chain-of-thought in `content`?
55
+ *
56
+ * Scope correction (2026-08-31). A previous revision widened this to the
57
+ * whole free tier on the theory that the pool leaks. Re-measured across token
58
+ * budgets, that was wrong: the "leak" is max_tokens TRUNCATION. A Nemotron
59
+ * reasoning model cut off mid-thought emits the partial trace in `content`
60
+ * with finish_reason "length"; given room it returns a clean answer with
61
+ * finish_reason "stop" and the trace in `reasoning_content`.
62
+ *
63
+ * nemotron-3-nano-30b, same prompt, chat/completions:
64
+ * max_tokens 120 -> "length", content = "Okay, the user is asking..."
65
+ * max_tokens 300 -> "stop", content = the actual answer
66
+ *
67
+ * So the fix is to give free calls room (see router/index.ts's classifier
68
+ * budget and turn-analyzer.ts's), not to scrub output. This stays narrow — the
69
+ * Nemotron family, the only models observed producing untagged prose — because
70
+ * a wider net plus an opener match could truncate a legitimate answer that
71
+ * happens to begin "The user asks...".
72
+ *
73
+ * KNOWN LIMITATION: the real discriminator is `finish_reason === "length"`,
74
+ * which this module never sees — the streaming call site in agent/llm.ts
75
+ * decides whether to strip before the finish reason arrives. Until that is
76
+ * plumbed through, the opener list is the proxy for it, which is why the
77
+ * openers must stay specific enough that an untruncated answer cannot match.
78
+ */
41
79
  export function isNemotronProseModel(model) {
42
- return /^nvidia\/nemotron-3-nano-omni/i.test(model);
80
+ return /^nvidia\/nemotron/i.test(model);
43
81
  }
44
82
  export function stripNemotronProse(text) {
45
83
  if (!text)
@@ -4,6 +4,7 @@
4
4
  * Anchors to actual API counts when available, estimates on top for new messages.
5
5
  */
6
6
  import { peekGatewayModel, warmGatewayModelsCache } from '../gateway-models.js';
7
+ import { FREE_POOL_CONTEXT_FLOOR } from '../free-models.js';
7
8
  const DEFAULT_BYTES_PER_TOKEN = 4;
8
9
  /**
9
10
  * Model-specific bytes-per-token ratios for more accurate estimation.
@@ -281,17 +282,33 @@ const MODEL_CONTEXT_WINDOWS = {
281
282
  'moonshot/kimi-k2.5': 128_000,
282
283
  'minimax/minimax-m3': 1_000_000,
283
284
  'minimax/minimax-m2.7': 128_000,
284
- // NVIDIA-hosted free tier (refreshed 2026-08-12 to match live /api/v1/models).
285
- // Dead ids (qwen3-next, qwen3.5-122b, seed-oss, maverick, mistral-large) are
286
- // kept so legacy session records still get a sane window.
285
+ // Free tier (refreshed 2026-08-30 — the gateway rotated the whole pool).
286
+ //
287
+ // Every current free id is pinned to FREE_POOL_CONTEXT_FLOOR rather than its
288
+ // catalogued window, deliberately. A request for the 1M-context default is
289
+ // served by the 131K nemotron-3-nano-30b whenever the pool is under load,
290
+ // with no signal to the client — so sizing compaction off 1M would build a
291
+ // prompt the substitute cannot accept, and it would fail mid-session on a
292
+ // user who never picked the substitute. The catalogued windows are recorded
293
+ // in free-models.ts (FREE_MODEL_CONTEXT_WINDOWS) for display.
294
+ //
295
+ // Dead and substituted ids are kept so legacy session records still get a
296
+ // sane window.
297
+ 'nvidia/nemotron-3-ultra-550b': FREE_POOL_CONTEXT_FLOOR, // catalogued 1M; pool floor applies
298
+ 'nvidia/nemotron-3-nano-30b': FREE_POOL_CONTEXT_FLOOR,
299
+ 'nvidia/nemotron-3.5-lightning': FREE_POOL_CONTEXT_FLOOR, // catalogued 1M; pool floor applies
300
+ 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning': FREE_POOL_CONTEXT_FLOOR,
301
+ 'nvidia/llama-3.2-11b-vision': 128_000,
302
+ 'cohere/north-mini-code': FREE_POOL_CONTEXT_FLOOR,
303
+ 'poolside/laguna-xs-2.1': FREE_POOL_CONTEXT_FLOOR,
287
304
  'nvidia/qwen3-next-80b-a3b-instruct': 262_144, // NVIDIA EOL 410, 2026-07-27
288
305
  'nvidia/qwen3.5-122b-a10b': 131_072,
289
- 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning': 256_000,
290
306
  'nvidia/mistral-nemotron': 131_072,
291
307
  'nvidia/step-3.7-flash': 131_072,
292
308
  'nvidia/seed-oss-36b': 131_072,
293
- 'nvidia/nemotron-nano-9b-v2': 131_072, // current free default
309
+ 'nvidia/nemotron-nano-9b-v2': 131_072,
294
310
  'nvidia/nemotron-nano-12b-v2-vl': 131_072,
311
+ 'nvidia/nemotron-3-super-120b-a12b-free': 131_072,
295
312
  'nvidia/llama-4-maverick': 131_072,
296
313
  'nvidia/mistral-large-3-675b': 131_072,
297
314
  // Qwen (paid) — Max tier is 1M ctx; the generic `qwen` fallback below is
@@ -26,6 +26,7 @@
26
26
  * - 30s in-memory cache keyed on the three anchors so back-to-back near-
27
27
  * identical turns don't re-pay the latency.
28
28
  */
29
+ import { FREE_DEFAULT_MODEL } from '../free-models.js';
29
30
  /**
30
31
  * Safe default returned when the analyzer call fails (timeout, parse error,
31
32
  * gateway down). Chosen to be neutral:
@@ -45,8 +46,17 @@ const CONSERVATIVE_DEFAULT = {
45
46
  const MAX_CURRENT_CHARS = 800;
46
47
  const MAX_PREV_REPLY_CHARS = 300;
47
48
  const MAX_GOAL_CHARS = 200;
48
- const TIMEOUT_MS = 2_500;
49
- const MAX_ANALYZER_TOKENS = 128;
49
+ // 2.5s did not leave a reasoning model room to finish and emit its JSON; the
50
+ // abort landed mid-thought and the analyzer silently degraded. See
51
+ // MAX_ANALYZER_TOKENS below.
52
+ const TIMEOUT_MS = 8_000;
53
+ // Raised from 128 on 2026-08-31. The free pool is reasoning models now: cut
54
+ // off mid-thought they emit a partial trace instead of the single-line JSON
55
+ // this parser needs, and a parse failure here is SILENT — it disables pushback
56
+ // handling, ticker/live-data prefetch and planning detection with no error
57
+ // surfaced. Same truncation bug the router classifier had; fixing it there and
58
+ // not here left two thirds of the lesson unapplied. Costs nothing at $0.
59
+ const MAX_ANALYZER_TOKENS = 1_024;
50
60
  const CACHE_TTL_MS = 30_000;
51
61
  const CACHE_MAX_SIZE = 64;
52
62
  // ─── Analyzer prompt ────────────────────────────────────────────────────
@@ -54,10 +64,12 @@ const CACHE_MAX_SIZE = 64;
54
64
  // Design: one compact prompt, a few precise examples, instruct the model to
55
65
  // emit a single-line JSON. The backbone must produce plain-text structured
56
66
  // output under tight max_tokens (thinking-first models leave text empty).
57
- // Nemotron Nano 9B took over 2026-08-12: qwen3-next-80b-a3b-instruct hit
58
- // NVIDIA's EOL (410) and mistral-nemotron is DEGRADED upstream (stream calls
59
- // 400). Nano 9B verifiably serves itself — verified live through the binary.
60
- const ANALYZER_MODEL_DEFAULT = process.env.FRANKLIN_ANALYZER_MODEL || 'nvidia/nemotron-nano-9b-v2';
67
+ // Follows FREE_DEFAULT_MODEL since 2026-08-31 (the ids this comment used to
68
+ // name were all retired in the 2026-08-30 pool rotation). NOTE: the free pool
69
+ // is now reasoning models that need room — see the TRUNCATION note in
70
+ // src/free-models.ts. MAX_ANALYZER_TOKENS/TIMEOUT_MS below have NOT been
71
+ // re-tuned for that and may truncate; see the review finding on this file.
72
+ const ANALYZER_MODEL_DEFAULT = process.env.FRANKLIN_ANALYZER_MODEL || FREE_DEFAULT_MODEL;
61
73
  const ANALYZER_SYSTEM = `You analyze ONE user message for Franklin's routing + prefetch harness. Output ONE LINE of compact JSON — no explanation, no markdown, no code fences.
62
74
 
63
75
  ## Fields
@@ -8,6 +8,7 @@
8
8
  * If FAIL: injects feedback into conversation so the main agent can fix issues.
9
9
  * If PASS: work is considered verified.
10
10
  */
11
+ import { FREE_DEFAULT_MODEL } from '../free-models.js';
11
12
  // ─── Verification System Prompt ───────────────────────────────────────────
12
13
  const VERIFICATION_PROMPT = `You are a VERIFICATION agent. Your job is NOT to confirm that code works — it is to TRY TO BREAK IT.
13
14
 
@@ -113,7 +114,7 @@ export async function runVerification(history, handlers, client, config) {
113
114
  ];
114
115
  config.onEvent?.({ kind: 'text_delta', text: '\n*Verifying...*\n' });
115
116
  // Use agent-tested free model for verification.
116
- const verificationModel = 'nvidia/nemotron-nano-9b-v2';
117
+ const verificationModel = FREE_DEFAULT_MODEL;
117
118
  try {
118
119
  // Simple single-turn verification call
119
120
  const response = await client.complete({
@@ -3,6 +3,7 @@
3
3
  * Uses cheap model to detect people, projects, companies from conversation.
4
4
  */
5
5
  import { loadEntities, saveEntities, upsertEntity, addObservation, upsertRelation, isJunkEntityName, } from './store.js';
6
+ import { FREE_DEFAULT_MODEL } from '../free-models.js';
6
7
  // Last entry is the free safety net. nvidia/nemotron-super-49b held it until
7
8
  // 2026-08-20, by which point it had left the catalog entirely — the free pool
8
9
  // answers for it with a substitute, so the "free fallback" was neither the
@@ -11,7 +12,7 @@ import { loadEntities, saveEntities, upsertEntity, addObservation, upsertRelatio
11
12
  const EXTRACTION_MODELS = [
12
13
  'google/gemini-2.5-flash-lite',
13
14
  'google/gemini-2.5-flash',
14
- 'nvidia/nemotron-nano-9b-v2',
15
+ FREE_DEFAULT_MODEL,
15
16
  ];
16
17
  const VALID_TYPES = new Set(['person', 'project', 'company', 'product', 'concept']);
17
18
  const BRAIN_PROMPT = `You are analyzing a conversation between a user and an AI agent. Extract entities (people, projects, companies, products, concepts) mentioned in the conversation.
@@ -16,6 +16,7 @@ import { connectMcpServers, disconnectMcpServers } from '../mcp/client.js';
16
16
  import { loadConfig } from './config.js';
17
17
  import { runSlackBot } from '../channel/slack.js';
18
18
  import { findLatestSessionByChannel } from '../session/storage.js';
19
+ import { FREE_DEFAULT_MODEL } from '../free-models.js';
19
20
  export async function slackCommand(opts) {
20
21
  const botToken = process.env.SLACK_BOT_TOKEN;
21
22
  const appToken = process.env.SLACK_APP_TOKEN;
@@ -41,7 +42,7 @@ export async function slackCommand(opts) {
41
42
  const config = loadConfig();
42
43
  const model = opts.model ||
43
44
  config['default-model'] ||
44
- 'nvidia/nemotron-nano-9b-v2';
45
+ FREE_DEFAULT_MODEL;
45
46
  const workingDir = process.cwd();
46
47
  const systemInstructions = assembleInstructions(workingDir, model);
47
48
  // Connect MCP servers (Notion, etc.) so the bot exposes their tools — mirrors
@@ -21,6 +21,7 @@ import { runX } from '../social/x.js';
21
21
  import { getStats } from '../social/db.js';
22
22
  import { loadChain, API_URLS } from '../config.js';
23
23
  import { loadConfig as loadAppConfig } from './config.js';
24
+ import { FREE_DEFAULT_MODEL } from '../free-models.js';
24
25
  /**
25
26
  * Entry point wired from src/index.ts as `franklin social [action] [arg]`.
26
27
  */
@@ -159,7 +160,7 @@ async function runCommand(options) {
159
160
  const chain = loadChain();
160
161
  const apiUrl = API_URLS[chain];
161
162
  const appConfig = loadAppConfig();
162
- const model = options.model || appConfig['default-model'] || 'nvidia/nemotron-nano-9b-v2';
163
+ const model = options.model || appConfig['default-model'] || FREE_DEFAULT_MODEL;
163
164
  console.log(chalk.dim(` Model: ${model}`));
164
165
  console.log('');
165
166
  let result;
@@ -14,6 +14,7 @@ import { allCapabilities } from '../tools/index.js';
14
14
  import { loadConfig } from './config.js';
15
15
  import { runTelegramBot } from '../channel/telegram.js';
16
16
  import { findLatestSessionByChannel } from '../session/storage.js';
17
+ import { FREE_DEFAULT_MODEL } from '../free-models.js';
17
18
  export async function telegramCommand(opts) {
18
19
  const token = process.env.TELEGRAM_BOT_TOKEN;
19
20
  const ownerRaw = process.env.TELEGRAM_OWNER_ID;
@@ -44,7 +45,7 @@ export async function telegramCommand(opts) {
44
45
  // Model: --model flag > config default > free default.
45
46
  const model = opts.model ||
46
47
  config['default-model'] ||
47
- 'nvidia/nemotron-nano-9b-v2';
48
+ FREE_DEFAULT_MODEL;
48
49
  const workingDir = process.cwd();
49
50
  const systemInstructions = assembleInstructions(workingDir, model);
50
51
  // Resume the most recent session tagged for THIS owner so a process
@@ -0,0 +1,28 @@
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 declare 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 declare const FREE_PREFERENCE_ORDER: readonly string[];
27
+ /** Context budget for ANY free-tier request. See free-models.ts. */
28
+ export declare const FREE_POOL_CONTEXT_FLOOR = 131072;