@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.
- package/README.md +7 -9
- package/dist/agent/commands.js +2 -2
- package/dist/agent/compact.js +6 -3
- package/dist/agent/context.js +1 -1
- package/dist/agent/evaluator.js +2 -1
- package/dist/agent/llm.js +4 -3
- package/dist/agent/loop.js +82 -14
- package/dist/agent/nemotron-prose-stripper.d.ts +26 -0
- package/dist/agent/nemotron-prose-stripper.js +39 -1
- package/dist/agent/tokens.js +22 -5
- package/dist/agent/turn-analyzer.js +18 -6
- package/dist/agent/verification.js +2 -1
- package/dist/brain/extract.js +2 -1
- package/dist/commands/slack.js +2 -1
- package/dist/commands/social.js +2 -1
- package/dist/commands/telegram.js +2 -1
- package/dist/free-models.constants.d.ts +28 -0
- package/dist/free-models.constants.js +33 -0
- package/dist/free-models.d.ts +320 -0
- package/dist/free-models.js +407 -0
- package/dist/gateway-models.js +15 -3
- package/dist/learnings/extractor.js +3 -2
- package/dist/plugin-sdk/workflow.js +5 -2
- package/dist/pricing.js +18 -9
- package/dist/proxy/fallback.d.ts +7 -0
- package/dist/proxy/fallback.js +14 -1
- package/dist/proxy/server.js +15 -2
- package/dist/router/index.d.ts +3 -1
- package/dist/router/index.js +140 -89
- package/dist/router/vision.js +35 -10
- package/dist/serve/server.js +1 -4
- package/dist/tools/moa.js +9 -3
- package/dist/tools/modal.d.ts +25 -0
- package/dist/tools/modal.js +87 -9
- package/dist/tools/subagent.js +6 -5
- package/dist/ui/model-picker.js +75 -74
- package/dist/wallet/reservation.d.ts +40 -3
- package/dist/wallet/reservation.js +91 -10
- package/package.json +3 -3
package/dist/tools/modal.js
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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);
|
package/dist/tools/subagent.js
CHANGED
|
@@ -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
|
-
//
|
|
12
|
-
|
|
13
|
-
|
|
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 ||
|
|
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)) {
|
package/dist/ui/model-picker.js
CHANGED
|
@@ -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':
|
|
142
|
-
'deepseek-v4-flash':
|
|
143
|
-
dsv4:
|
|
144
|
-
'deepseek-v3.2':
|
|
145
|
-
'deepseek-v3':
|
|
146
|
-
// Free
|
|
147
|
-
//
|
|
148
|
-
//
|
|
149
|
-
//
|
|
150
|
-
//
|
|
151
|
-
//
|
|
152
|
-
//
|
|
153
|
-
//
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
'qwen3
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
'
|
|
162
|
-
'qwen-
|
|
163
|
-
'
|
|
164
|
-
'gpt-oss
|
|
165
|
-
'
|
|
166
|
-
'mistral-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
//
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
//
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
'
|
|
179
|
-
|
|
180
|
-
//
|
|
181
|
-
//
|
|
182
|
-
//
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
//
|
|
187
|
-
//
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
'llama-4
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
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
|
|
430
|
-
//
|
|
431
|
-
//
|
|
432
|
-
//
|
|
433
|
-
//
|
|
434
|
-
//
|
|
435
|
-
//
|
|
436
|
-
//
|
|
437
|
-
//
|
|
438
|
-
//
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
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
|
|
5
|
-
* parallel, each independently checks balance and dispatches
|
|
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
|
|
5
|
-
* parallel, each independently checks balance and dispatches
|
|
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
|
-
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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();
|