@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
@@ -27,7 +27,7 @@
27
27
  */
28
28
  import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
29
29
  import { loadChain, API_URLS, VERSION } from '../config.js';
30
- import { walletReservation } from '../wallet/reservation.js';
30
+ import { walletReservation, AMBIGUOUS_GRACE_MS } from '../wallet/reservation.js';
31
31
  import { recordUsage } from '../stats/tracker.js';
32
32
  import { logger } from '../logger.js';
33
33
  // ─── Pricing table (probed from /.well-known/x402 + 402 responses) ─────────
@@ -63,6 +63,11 @@ class SessionSandboxTracker {
63
63
  }
64
64
  export const sessionSandboxTracker = new SessionSandboxTracker();
65
65
  // ─── x402 payment signing — same shape as imagegen's helper ───────────────
66
+ /** Indirection so tests can stub the signer without a funded wallet. */
67
+ let paymentSigner = (...args) => signPayment(...args);
68
+ export function _setPaymentSignerForTests(fn) {
69
+ paymentSigner = fn ?? ((...args) => signPayment(...args));
70
+ }
66
71
  async function signPayment(response, chain, endpoint, resourceDescription) {
67
72
  try {
68
73
  const paymentHeader = await extractPaymentReq(response);
@@ -118,8 +123,18 @@ async function extractPaymentReq(response) {
118
123
  * first POST gets a 402 with payment requirements; we sign and retry once
119
124
  * with the X-PAYMENT header. Returns the parsed JSON body and the raw
120
125
  * Response (callers may need status code).
126
+ *
127
+ * `reservation` is the caller's wallet hold for this call. If the signed
128
+ * (paid) request has been dispatched and the call then aborts or times out
129
+ * before a response, or the response arrives but its body is cut off, the
130
+ * outcome is ambiguous — the gateway may already have settled the payment.
131
+ * The hold is marked ambiguous so the reservation layer keeps counting it
132
+ * (see reservation.ts) instead of the caller's `finally` releasing it as if
133
+ * nothing was spent. Failures that provably never left this machine (signal
134
+ * already aborted before dispatch, DNS / connection-refused) are NOT
135
+ * ambiguous and release normally.
121
136
  */
122
- async function postWithPayment(endpoint, body, resourceDescription, abortSignal, timeoutMs) {
137
+ export async function postWithPayment(endpoint, body, resourceDescription, abortSignal, timeoutMs, reservation) {
123
138
  const chain = loadChain();
124
139
  const headers = {
125
140
  'Content-Type': 'application/json',
@@ -129,14 +144,21 @@ async function postWithPayment(endpoint, body, resourceDescription, abortSignal,
129
144
  const onParentAbort = () => ctrl.abort();
130
145
  abortSignal.addEventListener('abort', onParentAbort, { once: true });
131
146
  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
147
+ let paymentDispatched = false;
132
148
  try {
133
149
  const payload = JSON.stringify(body);
134
150
  let response = await fetch(endpoint, { method: 'POST', signal: ctrl.signal, headers, body: payload });
135
151
  if (response.status === 402) {
136
- const paymentHeaders = await signPayment(response, chain, endpoint, resourceDescription);
152
+ const paymentHeaders = await paymentSigner(response, chain, endpoint, resourceDescription);
137
153
  if (!paymentHeaders) {
138
154
  return { ok: false, status: 402, body: { error: 'payment signing failed' }, raw: '' };
139
155
  }
156
+ // Signing can take a while (wallet load, Solana RPC). If the budget
157
+ // expired meanwhile, fetch rejects before writing a byte — that is a
158
+ // definite non-payment, not an ambiguous one.
159
+ if (ctrl.signal.aborted)
160
+ throw signalError(ctrl.signal);
161
+ paymentDispatched = true;
140
162
  response = await fetch(endpoint, {
141
163
  method: 'POST',
142
164
  signal: ctrl.signal,
@@ -144,7 +166,17 @@ async function postWithPayment(endpoint, body, resourceDescription, abortSignal,
144
166
  body: payload,
145
167
  });
146
168
  }
147
- const raw = await response.text().catch(() => '');
169
+ let raw = '';
170
+ try {
171
+ raw = await response.text();
172
+ }
173
+ catch (err) {
174
+ // A paid 2xx whose body was cut off (abort mid-stream) is still a
175
+ // settled payment with an unknown result — e.g. a sandbox we were never
176
+ // told the id of. Surface it instead of returning ok:true with {}.
177
+ if (paymentDispatched)
178
+ throw err;
179
+ }
148
180
  let parsed = {};
149
181
  try {
150
182
  parsed = raw ? JSON.parse(raw) : {};
@@ -152,12 +184,57 @@ async function postWithPayment(endpoint, body, resourceDescription, abortSignal,
152
184
  catch { /* leave as {} */ }
153
185
  return { ok: response.ok, status: response.status, body: parsed, raw };
154
186
  }
187
+ catch (err) {
188
+ if (paymentDispatched && reservation && !definitelyNotSent(err)) {
189
+ // Signed request went out; abort/timeout hit before we saw the result.
190
+ // Money may be gone — keep the hold counted rather than releasing it.
191
+ // Window = this call's own timeout (the gateway may still be running
192
+ // the paid work and settle when it finishes) + settlement margin.
193
+ walletReservation.markAmbiguous(reservation, timeoutMs + AMBIGUOUS_GRACE_MS);
194
+ logger.warn(`[franklin] Modal payment outcome ambiguous (${err.message}); ` +
195
+ `holding ${reservation.amountUsd.toFixed(4)} USDC reservation until balance refresh`);
196
+ }
197
+ throw err;
198
+ }
155
199
  finally {
156
200
  clearTimeout(timer);
157
201
  abortSignal.removeEventListener('abort', onParentAbort);
158
202
  }
159
203
  }
160
204
  // ─── Helpers ─────────────────────────────────────────────────────────────
205
+ /** Explain why hold() refused, so the agent does not loop on "wait". */
206
+ function describeHeadroom() {
207
+ const snap = walletReservation.snapshot();
208
+ const parts = [];
209
+ if (snap.count > 0)
210
+ parts.push(`${snap.count} in-flight paid call(s) hold ${fmtUsd(snap.totalUsd - snap.ambiguousUsd)}`);
211
+ if (snap.ambiguousCount > 0) {
212
+ parts.push(`${fmtUsd(snap.ambiguousUsd)} is held for ${snap.ambiguousCount} recent payment(s) whose settlement is ` +
213
+ `unconfirmed (released automatically after the on-chain balance refreshes)`);
214
+ }
215
+ if (parts.length === 0)
216
+ return 'Fund the wallet.';
217
+ return parts.join('; ') + ' — wait for those to clear or fund the wallet.';
218
+ }
219
+ function signalError(signal) {
220
+ const reason = signal.reason;
221
+ if (reason instanceof Error)
222
+ return reason;
223
+ const e = new Error('This operation was aborted');
224
+ e.name = 'AbortError';
225
+ return e;
226
+ }
227
+ /**
228
+ * Errors whose cause proves the request never reached the network: the
229
+ * payment cannot have settled, so the reservation should release normally.
230
+ * Anything else after dispatch (abort, timeout, reset, unknown) errs tight.
231
+ */
232
+ const NOT_SENT_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'ENETUNREACH', 'EHOSTUNREACH', 'ERR_INVALID_URL']);
233
+ function definitelyNotSent(err) {
234
+ const cause = err?.cause;
235
+ const code = typeof cause?.code === 'string' ? cause.code : '';
236
+ return NOT_SENT_CODES.has(code);
237
+ }
161
238
  function modalEndpoint(path) {
162
239
  const chain = loadChain();
163
240
  return `${API_URLS[chain]}/v1/modal/sandbox/${path}`;
@@ -309,7 +386,7 @@ export const modalCreateCapability = {
309
386
  if (!reservation) {
310
387
  return {
311
388
  output: `Insufficient USDC for ModalCreate (${tier}, ~${fmtUsd(price)}). ` +
312
- `Other in-flight paid calls may be holding your balance — wait or fund the wallet.`,
389
+ describeHeadroom(),
313
390
  isError: true,
314
391
  };
315
392
  }
@@ -326,7 +403,8 @@ export const modalCreateCapability = {
326
403
  if (typeof memoryCoerced === 'number')
327
404
  body.memory = memoryCoerced;
328
405
  const callStartedAt = Date.now();
329
- const res = await postWithPayment(modalEndpoint('create'), body, 'Franklin Modal sandbox create', ctx.abortSignal, 90_000);
406
+ const res = await postWithPayment(modalEndpoint('create'), body, 'Franklin Modal sandbox create', ctx.abortSignal, 90_000, // 90s — sandbox cold-start can be slow on fresh GPU pulls
407
+ reservation);
330
408
  const latencyMs = Date.now() - callStartedAt;
331
409
  if (!res.ok) {
332
410
  const err = res.body.error ? String(res.body.error) : res.raw.slice(0, 300);
@@ -451,7 +529,7 @@ export const modalExecCapability = {
451
529
  if (coercedTimeout !== undefined)
452
530
  body.timeout = coercedTimeout;
453
531
  const callStartedAt = Date.now();
454
- const res = await postWithPayment(modalEndpoint('exec'), body, 'Franklin Modal sandbox exec', ctx.abortSignal, Math.max(30_000, ((coercedTimeout ?? 300) + 30) * 1000));
532
+ const res = await postWithPayment(modalEndpoint('exec'), body, 'Franklin Modal sandbox exec', ctx.abortSignal, Math.max(30_000, ((coercedTimeout ?? 300) + 30) * 1000), reservation);
455
533
  const latencyMs = Date.now() - callStartedAt;
456
534
  if (!res.ok) {
457
535
  // 400 here usually means the agent built the wrong shape (bad
@@ -532,7 +610,7 @@ export const modalStatusCapability = {
532
610
  catch { /* ignore */ }
533
611
  try {
534
612
  const callStartedAt = Date.now();
535
- const res = await postWithPayment(modalEndpoint('status'), { sandbox_id }, 'Franklin Modal sandbox status', ctx.abortSignal, 30_000);
613
+ const res = await postWithPayment(modalEndpoint('status'), { sandbox_id }, 'Franklin Modal sandbox status', ctx.abortSignal, 30_000, reservation);
536
614
  const latencyMs = Date.now() - callStartedAt;
537
615
  if (!res.ok) {
538
616
  const err = res.body.error ? String(res.body.error) : res.raw.slice(0, 300);
@@ -580,7 +658,7 @@ export const modalTerminateCapability = {
580
658
  catch { /* ignore */ }
581
659
  try {
582
660
  const callStartedAt = Date.now();
583
- const res = await postWithPayment(modalEndpoint('terminate'), { sandbox_id }, 'Franklin Modal sandbox terminate', ctx.abortSignal, 30_000);
661
+ const res = await postWithPayment(modalEndpoint('terminate'), { sandbox_id }, 'Franklin Modal sandbox terminate', ctx.abortSignal, 30_000, reservation);
584
662
  const latencyMs = Date.now() - callStartedAt;
585
663
  // Always remove from tracker — even on failure, retrying is wasteful.
586
664
  sessionSandboxTracker.remove(sandbox_id);
@@ -3,22 +3,23 @@
3
3
  */
4
4
  import { ModelClient } from '../agent/llm.js';
5
5
  import { assembleInstructions } from '../agent/context.js';
6
+ import { FREE_DEFAULT_MODEL, isFreeModelId } from '../free-models.js';
6
7
  // These will be injected at registration time
7
8
  let registeredApiUrl = '';
8
9
  let registeredChain = 'base';
9
10
  let registeredParentModel = '';
10
11
  let registeredCapabilities = [];
11
- // Heuristic: which model IDs are free?
12
- function isFreeModel(m) {
13
- return m.startsWith('nvidia/') || m === 'blockrun/free' || m === '';
14
- }
12
+ // Which model IDs are billed at $0? See src/free-models.ts — the old
13
+ // `startsWith('nvidia/')` heuristic mis-classified paid nvidia SKUs as free
14
+ // and the new poolside/cohere free ids as paid.
15
+ const isFreeModel = isFreeModelId;
15
16
  async function execute(input, ctx) {
16
17
  const { prompt, description, model } = input;
17
18
  if (!prompt) {
18
19
  return { output: 'Error: prompt is required', isError: true };
19
20
  }
20
21
  // Resolve which model the sub-agent will actually run on
21
- const subModel = model || registeredParentModel || 'nvidia/nemotron-nano-9b-v2';
22
+ const subModel = model || registeredParentModel || FREE_DEFAULT_MODEL;
22
23
  // Cost gate: if parent is free but sub-agent wants paid, ask user first.
23
24
  // Prevents silent charges when the agent decides to spawn a more capable sub-agent.
24
25
  if (isFreeModel(registeredParentModel) && !isFreeModel(subModel)) {
@@ -5,6 +5,7 @@
5
5
  import readline from 'node:readline';
6
6
  import chalk from 'chalk';
7
7
  import { getGatewayModels } from '../gateway-models.js';
8
+ import { FREE_DEFAULT_MODEL } from '../free-models.js';
8
9
  // ─── Model Shortcuts (same as proxy) ───────────────────────────────────────
9
10
  export const MODEL_SHORTCUTS = {
10
11
  // Routing profiles — Auto is the only profile surfaced in the picker.
@@ -138,66 +139,60 @@ export const MODEL_SHORTCUTS = {
138
139
  // The free nvidia/deepseek-v4-flash SKU was EOL'd by the gateway (410).
139
140
  // Point the deepseek-free aliases at the current free default so muscle
140
141
  // memory keeps working without handing back a dead id.
141
- 'deepseek-v4': 'nvidia/nemotron-nano-9b-v2',
142
- 'deepseek-v4-flash': 'nvidia/nemotron-nano-9b-v2',
143
- dsv4: 'nvidia/nemotron-nano-9b-v2',
144
- 'deepseek-v3.2': 'nvidia/nemotron-nano-9b-v2',
145
- 'deepseek-v3': 'nvidia/nemotron-nano-9b-v2',
146
- // Free (agent-tested BlockRun gateway free tier — refreshed 2026-08-12 after
147
- // qwen3-next-80b-a3b-instruct hit NVIDIA's EOL, 410). `free` follows the
148
- // current free default (nemotron-nano-9b-v2: the one free model that
149
- // verifiably serves itself on the streaming path — mistral-nemotron is
150
- // DEGRADED upstream and 400s on stream). The qwen3-next / qwen3.5 aliases
151
- // follow the retired-free-id pattern and resolve here too. NOTE: every free
152
- // alias resolves to a $0 nvidia model — the free tier NEVER falls back to a
153
- // paid model.
154
- free: 'nvidia/nemotron-nano-9b-v2',
155
- qwen: 'nvidia/nemotron-nano-9b-v2',
156
- qwen3: 'nvidia/nemotron-nano-9b-v2',
157
- 'qwen3-next': 'nvidia/nemotron-nano-9b-v2',
158
- 'qwen3.5': 'nvidia/nemotron-nano-9b-v2',
159
- glm4: 'nvidia/nemotron-nano-9b-v2',
160
- 'deepseek-free': 'nvidia/nemotron-nano-9b-v2',
161
- 'qwen-coder': 'nvidia/nemotron-nano-9b-v2',
162
- 'qwen-think': 'nvidia/nemotron-nano-9b-v2',
163
- 'gpt-oss': 'nvidia/nemotron-nano-9b-v2',
164
- 'gpt-oss-small': 'nvidia/nemotron-nano-9b-v2',
165
- 'mistral-small': 'nvidia/mistral-nemotron',
166
- 'mistral-nemotron': 'nvidia/mistral-nemotron',
167
- // Verified-self-serving free secondaries (2026-08-12): the nano line answers
168
- // as itself on live probes, unlike the pooled 30B omni model.
169
- 'nano-9b': 'nvidia/nemotron-nano-9b-v2',
170
- 'nano-vl': 'nvidia/nemotron-nano-12b-v2-vl',
171
- 'free-vision': 'nvidia/nemotron-nano-12b-v2-vl',
172
- // Nemotron 3 Nano Omni started answering as ITSELF (re-probed 2026-08-19,
173
- // stream and non-stream) — it was pooled behind gpt-oss-120b when it was
174
- // last checked, which is why it had no alias until now. 31B/3.2B MoE,
175
- // text + image + video + audio in, 256K context.
176
- omni: 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning',
177
- 'free-omni': 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning',
178
- 'nano-omni': 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning',
179
- // Deliberately NOT aliased: nvidia/step-3.7-flash. It is in the catalog and
180
- // billed at $0, but live probes (2026-08-19) come back served by
181
- // nvidia/nemotron-3-super-120b — pointing users at it would promise a model
182
- // they don't get. Same rule that retired the maverick and qwen3-next ids.
183
- // Maverick left the gateway catalog on/before 2026-07-14. The id still
184
- // answers, but only because the free pool silently substitutes another model
185
- // for it — so pointing users at it would be promising a model they don't get.
186
- // Follow the established retired-free-id pattern instead: resolve to the
187
- // current free default so muscle memory keeps working.
188
- llama: 'nvidia/nemotron-nano-9b-v2',
189
- 'llama-4': 'nvidia/nemotron-nano-9b-v2',
190
- 'llama-4-maverick': 'nvidia/nemotron-nano-9b-v2',
191
- maverick: 'nvidia/nemotron-nano-9b-v2',
192
- // Backward-compatibility aliases for models the gateway retired or exposes
193
- // unreliably on /v1/messages. Map to agent-tested free models so shortcuts
194
- // keep working without silent paid fallback or empty tool-use turns.
195
- // Map to the closest current free model so old session records + user
196
- // muscle memory keep working.
197
- // `nemotron` resolves to the real Mistral Nemotron (in-catalog; currently
198
- // DEGRADED upstream, non-stream calls ride a disclosed gateway fallback).
199
- nemotron: 'nvidia/mistral-nemotron',
200
- devstral: 'nvidia/nemotron-nano-9b-v2',
142
+ 'deepseek-v4': FREE_DEFAULT_MODEL,
143
+ 'deepseek-v4-flash': FREE_DEFAULT_MODEL,
144
+ dsv4: FREE_DEFAULT_MODEL,
145
+ 'deepseek-v3.2': FREE_DEFAULT_MODEL,
146
+ 'deepseek-v3': FREE_DEFAULT_MODEL,
147
+ // Free tier. On 2026-08-30 the gateway rotated the ENTIRE free pool: every
148
+ // id these aliases used to name (nemotron-nano-9b-v2, mistral-nemotron,
149
+ // nemotron-nano-12b-v2-vl, step-3.7-flash) left the catalog and is now
150
+ // answered by a substitute. They all resolve to the current free default
151
+ // instead — the retired-free-id pattern this list has followed since the
152
+ // qwen3-next EOL. Evidence and ordering: src/free-models.ts.
153
+ //
154
+ // NOTE: every free alias resolves to a $0 model. The free tier NEVER falls
155
+ // back to a paid model.
156
+ free: FREE_DEFAULT_MODEL,
157
+ qwen: FREE_DEFAULT_MODEL,
158
+ qwen3: FREE_DEFAULT_MODEL,
159
+ 'qwen3-next': FREE_DEFAULT_MODEL,
160
+ 'qwen3.5': FREE_DEFAULT_MODEL,
161
+ glm4: FREE_DEFAULT_MODEL,
162
+ 'deepseek-free': FREE_DEFAULT_MODEL,
163
+ 'qwen-coder': FREE_DEFAULT_MODEL,
164
+ 'qwen-think': FREE_DEFAULT_MODEL,
165
+ 'gpt-oss': FREE_DEFAULT_MODEL,
166
+ 'gpt-oss-small': FREE_DEFAULT_MODEL,
167
+ 'mistral-small': FREE_DEFAULT_MODEL,
168
+ 'mistral-nemotron': FREE_DEFAULT_MODEL,
169
+ 'nano-9b': FREE_DEFAULT_MODEL,
170
+ // Free vision aliases kept as muscle memory, but they no longer promise
171
+ // vision: the gateway serves both free vision ids from a text-only model
172
+ // (see router/vision.ts). They resolve to the free default like every other
173
+ // retired free id.
174
+ 'nano-vl': FREE_DEFAULT_MODEL,
175
+ 'free-vision': FREE_DEFAULT_MODEL,
176
+ // omni IS the free default now (the only free id on both chains), so these
177
+ // are the same target rather than a redirect.
178
+ omni: FREE_DEFAULT_MODEL,
179
+ 'free-omni': FREE_DEFAULT_MODEL,
180
+ 'nano-omni': FREE_DEFAULT_MODEL,
181
+ // Base-only free ids. They 400 on Solana, which is a clear error rather than
182
+ // a silent wrong model, so the shortcuts stay honest and resolve to the id
183
+ // the user typed.
184
+ 'nano-30b': 'nvidia/nemotron-3-nano-30b',
185
+ laguna: 'poolside/laguna-xs-2.1',
186
+ 'ultra-550b': 'nvidia/nemotron-3-ultra-550b',
187
+ // Maverick left the gateway catalog on/before 2026-07-14 and the free pool
188
+ // silently substitutes for it, so pointing users at it would promise a model
189
+ // they don't get. Resolve to the current free default instead.
190
+ llama: FREE_DEFAULT_MODEL,
191
+ 'llama-4': FREE_DEFAULT_MODEL,
192
+ 'llama-4-maverick': FREE_DEFAULT_MODEL,
193
+ maverick: FREE_DEFAULT_MODEL,
194
+ nemotron: FREE_DEFAULT_MODEL,
195
+ devstral: FREE_DEFAULT_MODEL,
201
196
  // Others
202
197
  minimax: 'minimax/minimax-m3',
203
198
  'm3': 'minimax/minimax-m3',
@@ -426,20 +421,26 @@ export const PICKER_CATEGORIES = [
426
421
  // hit NVIDIA's EOL (410). All rows are $0 — the free tier never falls
427
422
  // back to paid.
428
423
  //
429
- // Caveat worth knowing before editing this list: the NVIDIA free pool
430
- // silently substitutes or degrades, so every row here is re-probed
431
- // before it ships. Re-probed 2026-08-19: the nano pair and the 30B omni
432
- // model all answer as THEMSELVES on both the streaming and non-streaming
433
- // paths (omni was pooled behind gpt-oss-120b in August and has since
434
- // been fixed upstream — hence its new row). mistral-nemotron still
435
- // comes back served by `nvidia/nemotron-3-super-120b`; it keeps its row
436
- // and its `nemotron` alias but must never lead a chain. The catalog's
437
- // fifth free id, nvidia/step-3.7-flash, is substituted the same way and
438
- // is deliberately absent from both this list and MODEL_SHORTCUTS.
439
- { id: 'nvidia/nemotron-nano-9b-v2', shortcut: 'free', label: 'Nemotron Nano 9B', price: 'FREE', highlight: true },
440
- { id: 'nvidia/nemotron-nano-12b-v2-vl', shortcut: 'nano-vl', label: 'Nemotron Nano VL', price: 'FREE' },
441
- { id: 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning', shortcut: 'omni', label: 'Nemotron 3 Nano Omni', price: 'FREE' },
442
- { id: 'nvidia/mistral-nemotron', shortcut: 'nemotron', label: 'Mistral Nemotron', price: 'FREE' },
424
+ // Caveat worth knowing before editing this list: only the FIRST row is
425
+ // available on both chains. The Solana gateway lists exactly one free
426
+ // model and 400s ("Unknown model") on the other three, which are
427
+ // Base-only as of the 2026-08-30 rotation. That is why `free` — and
428
+ // every legacy free alias — points at the chain-safe id, and why the
429
+ // ROUTER upgrades to the 550B at runtime from the live catalog rather
430
+ // than from this list (see src/free-models.ts, freeChain).
431
+ //
432
+ // The rows are still worth showing on both chains: the picker hydrates
433
+ // against the gateway catalog, and a user who pins a Base-only id on
434
+ // Solana gets a clear "Unknown model" rather than a silent wrong model.
435
+ //
436
+ // Deliberately absent (NOT quarantined — QUARANTINED_FREE_MODELS is
437
+ // empty): nemotron-3.5-lightning is merely slow, cohere/north-mini-code
438
+ // is a routable chain rung with no picker row, and llama-3.2-11b-vision
439
+ // is vision-only. Reasons per id live in src/free-models.ts.
440
+ { id: FREE_DEFAULT_MODEL, shortcut: 'free', label: 'Nemotron 3 Nano Omni', price: 'FREE', highlight: true },
441
+ { id: 'nvidia/nemotron-3-ultra-550b', shortcut: 'ultra-550b', label: 'Nemotron 3 Ultra 550B', price: 'FREE' },
442
+ { id: 'nvidia/nemotron-3-nano-30b', shortcut: 'nano-30b', label: 'Nemotron 3 Nano 30B', price: 'FREE' },
443
+ { id: 'poolside/laguna-xs-2.1', shortcut: 'laguna', label: 'Laguna XS 2.1', price: 'FREE' },
443
444
  ],
444
445
  },
445
446
  ];
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * WalletReservation — local accounting layer for concurrent paid tool calls.
3
3
  *
4
- * Problem this solves: when N batch tools (ImageGen / VideoGen) run in
5
- * parallel, each independently checks balance and dispatches its x402
6
- * payment. With balance $0.20 and 6 calls × $0.04 each, all 6 see "$0.20
4
+ * Problem this solves: when N paid tool calls (today: the Modal sandbox
5
+ * tools) run in parallel, each independently checks balance and dispatches
6
+ * its x402 payment. With balance $0.20 and 6 calls × $0.04 each, all 6 see "$0.20
7
7
  * available, $0.04 fits" and start; only 5 can actually settle on-chain,
8
8
  * the rest fail mid-flight with insufficient-funds and the user sees
9
9
  * partial completion with no preflight warning.
@@ -14,6 +14,16 @@
14
14
  * 1. Tool calls hold(amount) before paying.
15
15
  * 2. hold() refuses if (balance - sum(active reservations)) < amount.
16
16
  * 3. After payment succeeds OR fails, tool calls release(token).
17
+ * 4. If the outcome is AMBIGUOUS — the signed request was dispatched and
18
+ * then aborted / timed out before a response came back — the caller
19
+ * marks the token ambiguous instead. The gateway may have settled the
20
+ * payment on-chain, so the amount stays counted against headroom for
21
+ * a grace window and is dropped on the next fresh balance fetch that
22
+ * STARTED after the window closed (so the read reflects the real
23
+ * on-chain state). The window is sized by the caller from its own
24
+ * request timeout: the gateway may still be running the paid work when
25
+ * we abort, and settlement lands when that work finishes. The cap can
26
+ * only err tight, never loose.
17
27
  *
18
28
  * Single-process JS guarantees the check-and-set is atomic (no real race),
19
29
  * and balance is cached briefly so we don't hit the RPC for every hold.
@@ -22,10 +32,20 @@ export interface ReservationToken {
22
32
  id: string;
23
33
  amountUsd: number;
24
34
  }
35
+ /**
36
+ * Settlement margin added on top of the caller-supplied request timeout for
37
+ * an ambiguous-settlement hold. The window starts at OUR abort, not at the
38
+ * gateway's settlement: if the gateway settles after the paid work finishes,
39
+ * that can be up to the request timeout later, plus on-chain confirmation.
40
+ * Callers pass `graceMs = timeoutMs + AMBIGUOUS_GRACE_MS`.
41
+ */
42
+ export declare const AMBIGUOUS_GRACE_MS = 30000;
25
43
  declare class WalletReservationManager {
26
44
  private reserved;
45
+ private ambiguous;
27
46
  private cachedBalance;
28
47
  private balanceFetchInflight;
48
+ private balanceFetcher;
29
49
  private fetchBalance;
30
50
  private totalReserved;
31
51
  /**
@@ -39,13 +59,30 @@ declare class WalletReservationManager {
39
59
  * Invalidate the balance cache so the next hold sees up-to-date state.
40
60
  */
41
61
  release(token: ReservationToken | string | null | undefined): void;
62
+ /**
63
+ * Mark a hold as ambiguous: the signed payment was dispatched but the
64
+ * request aborted / timed out before we saw the outcome. The money may be
65
+ * gone, so keep the amount counted against headroom (see header) for
66
+ * `graceMs` (default AMBIGUOUS_GRACE_MS; callers add their request
67
+ * timeout). A later release() of the same token is a no-op — the ambiguous
68
+ * entry outlives it. Idempotent: a second call for the same id is a no-op.
69
+ */
70
+ markAmbiguous(token: ReservationToken | string | null | undefined, graceMs?: number): void;
42
71
  /** Force the next hold() to refetch balance from chain. */
43
72
  invalidateBalance(): void;
44
73
  /** Snapshot of current reservation state — diagnostic / testing only. */
45
74
  snapshot(): {
46
75
  count: number;
47
76
  totalUsd: number;
77
+ ambiguousCount: number;
78
+ ambiguousUsd: number;
48
79
  };
80
+ /** Testing only — reset all bookkeeping and cached balance. */
81
+ _resetForTests(fetcher?: () => Promise<number>): void;
82
+ /** Testing only — seed the balance cache so hold() never touches RPC. */
83
+ _seedBalanceForTests(value: number): void;
84
+ /** Testing only — shift every ambiguous entry's expiry earlier by `ms`. */
85
+ _ageAmbiguousForTests(ms: number): void;
49
86
  }
50
87
  export declare const walletReservation: WalletReservationManager;
51
88
  export {};
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * WalletReservation — local accounting layer for concurrent paid tool calls.
3
3
  *
4
- * Problem this solves: when N batch tools (ImageGen / VideoGen) run in
5
- * parallel, each independently checks balance and dispatches its x402
6
- * payment. With balance $0.20 and 6 calls × $0.04 each, all 6 see "$0.20
4
+ * Problem this solves: when N paid tool calls (today: the Modal sandbox
5
+ * tools) run in parallel, each independently checks balance and dispatches
6
+ * its x402 payment. With balance $0.20 and 6 calls × $0.04 each, all 6 see "$0.20
7
7
  * available, $0.04 fits" and start; only 5 can actually settle on-chain,
8
8
  * the rest fail mid-flight with insufficient-funds and the user sees
9
9
  * partial completion with no preflight warning.
@@ -14,6 +14,16 @@
14
14
  * 1. Tool calls hold(amount) before paying.
15
15
  * 2. hold() refuses if (balance - sum(active reservations)) < amount.
16
16
  * 3. After payment succeeds OR fails, tool calls release(token).
17
+ * 4. If the outcome is AMBIGUOUS — the signed request was dispatched and
18
+ * then aborted / timed out before a response came back — the caller
19
+ * marks the token ambiguous instead. The gateway may have settled the
20
+ * payment on-chain, so the amount stays counted against headroom for
21
+ * a grace window and is dropped on the next fresh balance fetch that
22
+ * STARTED after the window closed (so the read reflects the real
23
+ * on-chain state). The window is sized by the caller from its own
24
+ * request timeout: the gateway may still be running the paid work when
25
+ * we abort, and settlement lands when that work finishes. The cap can
26
+ * only err tight, never loose.
17
27
  *
18
28
  * Single-process JS guarantees the check-and-set is atomic (no real race),
19
29
  * and balance is cached briefly so we don't hit the RPC for every hold.
@@ -21,25 +31,50 @@
21
31
  import { setupAgentWallet, setupAgentSolanaWallet } from '@blockrun/llm';
22
32
  import { loadChain } from '../config.js';
23
33
  const BALANCE_CACHE_MS = 5_000;
34
+ /**
35
+ * Settlement margin added on top of the caller-supplied request timeout for
36
+ * an ambiguous-settlement hold. The window starts at OUR abort, not at the
37
+ * gateway's settlement: if the gateway settles after the paid work finishes,
38
+ * that can be up to the request timeout later, plus on-chain confirmation.
39
+ * Callers pass `graceMs = timeoutMs + AMBIGUOUS_GRACE_MS`.
40
+ */
41
+ export const AMBIGUOUS_GRACE_MS = 30_000;
42
+ async function readChainBalance() {
43
+ if (loadChain() === 'solana') {
44
+ const client = await setupAgentSolanaWallet({ silent: true });
45
+ return client.getBalance();
46
+ }
47
+ const client = setupAgentWallet({ silent: true });
48
+ return client.getBalance();
49
+ }
24
50
  class WalletReservationManager {
25
51
  reserved = new Map();
52
+ ambiguous = new Map();
26
53
  cachedBalance = null;
27
54
  balanceFetchInflight = null;
55
+ balanceFetcher = readChainBalance;
28
56
  async fetchBalance() {
29
57
  if (this.cachedBalance && Date.now() - this.cachedBalance.fetchedAt < BALANCE_CACHE_MS) {
30
58
  return this.cachedBalance.value;
31
59
  }
32
60
  if (this.balanceFetchInflight)
33
61
  return this.balanceFetchInflight;
34
- const chain = loadChain();
62
+ // Sample the clock BEFORE the read goes out: a read that started inside
63
+ // an ambiguous entry's window cannot be trusted to reflect it, however
64
+ // long the RPC took to answer.
65
+ const startedAt = Date.now();
35
66
  this.balanceFetchInflight = (async () => {
36
67
  try {
37
- if (chain === 'solana') {
38
- const client = await setupAgentSolanaWallet({ silent: true });
39
- return await client.getBalance();
68
+ const v = await this.balanceFetcher();
69
+ // A real on-chain read already includes any ambiguous spend that
70
+ // settled; drop entries whose window closed before this read began
71
+ // so a genuinely-absent spend self-heals instead of pinning headroom.
72
+ // Only on a real read: the Infinity fallback below reflects nothing.
73
+ for (const [id, entry] of this.ambiguous) {
74
+ if (entry.expiresAt <= startedAt)
75
+ this.ambiguous.delete(id);
40
76
  }
41
- const client = setupAgentWallet({ silent: true });
42
- return await client.getBalance();
77
+ return v;
43
78
  }
44
79
  catch {
45
80
  // If balance fetch fails, return Infinity so reservations don't
@@ -59,6 +94,8 @@ class WalletReservationManager {
59
94
  let sum = 0;
60
95
  for (const v of this.reserved.values())
61
96
  sum += v;
97
+ for (const e of this.ambiguous.values())
98
+ sum += e.amountUsd;
62
99
  return sum;
63
100
  }
64
101
  /**
@@ -93,13 +130,57 @@ class WalletReservationManager {
93
130
  this.cachedBalance = null;
94
131
  }
95
132
  }
133
+ /**
134
+ * Mark a hold as ambiguous: the signed payment was dispatched but the
135
+ * request aborted / timed out before we saw the outcome. The money may be
136
+ * gone, so keep the amount counted against headroom (see header) for
137
+ * `graceMs` (default AMBIGUOUS_GRACE_MS; callers add their request
138
+ * timeout). A later release() of the same token is a no-op — the ambiguous
139
+ * entry outlives it. Idempotent: a second call for the same id is a no-op.
140
+ */
141
+ markAmbiguous(token, graceMs = AMBIGUOUS_GRACE_MS) {
142
+ if (!token)
143
+ return;
144
+ const id = typeof token === 'string' ? token : token.id;
145
+ const amountUsd = this.reserved.get(id);
146
+ if (amountUsd === undefined || amountUsd <= 0)
147
+ return;
148
+ this.reserved.delete(id);
149
+ this.ambiguous.set(id, { amountUsd, expiresAt: Date.now() + Math.max(0, graceMs) });
150
+ this.cachedBalance = null;
151
+ }
96
152
  /** Force the next hold() to refetch balance from chain. */
97
153
  invalidateBalance() {
98
154
  this.cachedBalance = null;
99
155
  }
100
156
  /** Snapshot of current reservation state — diagnostic / testing only. */
101
157
  snapshot() {
102
- return { count: this.reserved.size, totalUsd: this.totalReserved() };
158
+ let ambiguousUsd = 0;
159
+ for (const e of this.ambiguous.values())
160
+ ambiguousUsd += e.amountUsd;
161
+ return {
162
+ count: this.reserved.size,
163
+ totalUsd: this.totalReserved(),
164
+ ambiguousCount: this.ambiguous.size,
165
+ ambiguousUsd,
166
+ };
167
+ }
168
+ /** Testing only — reset all bookkeeping and cached balance. */
169
+ _resetForTests(fetcher) {
170
+ this.reserved.clear();
171
+ this.ambiguous.clear();
172
+ this.cachedBalance = null;
173
+ this.balanceFetchInflight = null;
174
+ this.balanceFetcher = fetcher ?? readChainBalance;
175
+ }
176
+ /** Testing only — seed the balance cache so hold() never touches RPC. */
177
+ _seedBalanceForTests(value) {
178
+ this.cachedBalance = { value, fetchedAt: Date.now() };
179
+ }
180
+ /** Testing only — shift every ambiguous entry's expiry earlier by `ms`. */
181
+ _ageAmbiguousForTests(ms) {
182
+ for (const e of this.ambiguous.values())
183
+ e.expiresAt -= ms;
103
184
  }
104
185
  }
105
186
  export const walletReservation = new WalletReservationManager();