@blockrun/franklin 3.42.0 → 3.42.2

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 CHANGED
@@ -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
 
@@ -261,8 +261,12 @@ const MODEL_CONTEXT_WINDOWS = {
261
261
  // xAI 3.x / 4-0709 / 4-1-fast: hidden from /v1/models since 2026-08 but
262
262
  // still served and charged (probed 2026-08-29) — keep their windows.
263
263
  'xai/grok-3': 131_072,
264
+ 'xai/grok-3-mini': 131_072,
264
265
  'xai/grok-4-0709': 131_072,
265
266
  'xai/grok-4-1-fast-reasoning': 131_072,
267
+ 'xai/grok-4-1-fast-non-reasoning': 131_072,
268
+ 'xai/grok-4-fast-reasoning': 131_072,
269
+ 'xai/grok-4-fast-non-reasoning': 131_072,
266
270
  // Others
267
271
  'zai/glm-5.3': 1_000_000, // flagship 2026-08 — 1M context, always-on reasoning
268
272
  'zai/glm-5.3-flash': 1_000_000, // 2026-08-29 catalog sync — 1M context, vision, $0.15/$0.5
package/dist/pricing.js CHANGED
@@ -148,6 +148,13 @@ export const MODEL_PRICING = {
148
148
  'xai/grok-4-fast-reasoning': { input: 0.2, output: 0.5 }, // (probed)
149
149
  'xai/grok-4-1-fast': { input: 0.2, output: 0.5 },
150
150
  'xai/grok-4-1-fast-reasoning': { input: 0.2, output: 0.5 }, // (probed)
151
+ // The two non-reasoning ids sit in the shared Router's SIMPLE chains and
152
+ // were charged today, yet had no row here — Franklin reported them as $0
153
+ // and the portfolio scorer, which treats an unpriced id as infinitely
154
+ // expensive, could never pick them over a priced rung. Priced with their
155
+ // reasoning siblings (xAI bills the pair identically).
156
+ 'xai/grok-4-1-fast-non-reasoning': { input: 0.2, output: 0.5 }, // (probed)
157
+ 'xai/grok-4-fast-non-reasoning': { input: 0.2, output: 0.5 }, // (probed)
151
158
  'xai/grok-4-0709': { input: 3.0, output: 15.0 }, // (probed) gateway lists $3/$15 (was mispriced here at $0.2/$1.5)
152
159
  'xai/grok-3-mini': { input: 0.3, output: 0.5 }, // (probed)
153
160
  'xai/grok-2-vision': { input: 2.0, output: 10.0 },
@@ -7,7 +7,8 @@ import { MODEL_SHORTCUTS } from '../ui/model-picker.js';
7
7
  import { appendSettlementRow } from '../stats/cost-log.js';
8
8
  import { appendAudit } from '../stats/audit.js';
9
9
  import { buildFallbackChain, DEFAULT_FALLBACK_CONFIG, ROUTING_PROFILES, } from './fallback.js';
10
- import { routeRequest, parseRoutingProfile, isVisionModel, messagesNeedVision, pickVisionSibling, } from '../router/index.js';
10
+ import { routeRequest, parseRoutingProfile, isVisionModel, messagesNeedVision, pickVisionSibling, markModelUnavailable, } from '../router/index.js';
11
+ import { classifyAgentError } from '../agent/error-classifier.js';
11
12
  import { estimateCost } from '../pricing.js';
12
13
  import { getMaxOutputTokens } from '../agent/optimize.js';
13
14
  import { VERSION } from '../config.js';
@@ -523,6 +524,16 @@ export function createProxy(options) {
523
524
  else {
524
525
  // Wrap in Anthropic error format
525
526
  const errorMsg = parsed.error?.message || parsed.message || rawText.slice(0, 500);
527
+ // The proxy's fallback chain only retries 429/5xx, so a routed
528
+ // id the gateway rejects outright (400 "Unknown model", 404,
529
+ // 410) reaches here untouched. Feed the router's dead-rung
530
+ // kill-switch so the next routed request skips it; a client
531
+ // that pinned the id by name is left alone.
532
+ if (routerCandidates.length > 0 && classifyAgentError(String(errorMsg)).modelUnavailable) {
533
+ if (markModelUnavailable(finalModel)) {
534
+ logger.warn(`[franklin] ${finalModel} rejected by the gateway as unavailable — removed from routing for this process`);
535
+ }
536
+ }
526
537
  errorBody = JSON.stringify({
527
538
  type: 'error',
528
539
  error: {
@@ -11,13 +11,13 @@
11
11
  */
12
12
  import fs from 'node:fs';
13
13
  import path from 'node:path';
14
- import { DEFAULT_ROUTING_CONFIG as SHARED_ROUTING_CONFIG, route as routeWithSharedCore, } from '@blockrun/router-core';
14
+ import { DEFAULT_MODEL_CAPABILITIES as SHARED_MODEL_CAPABILITIES_BASE, DEFAULT_ROUTING_CONFIG as SHARED_ROUTING_CONFIG, route as routeWithSharedCore, } from '@blockrun/router-core';
15
15
  import { MODEL_PRICING, OPUS_PRICING } from '../pricing.js';
16
16
  import { BLOCKRUN_DIR } from '../config.js';
17
17
  import { detectCategory, mapCategoryToTier } from './categories.js';
18
18
  import { selectModel } from './selector.js';
19
19
  import { computeLocalElo, blendElo } from './local-elo.js';
20
- import { isVisionModel } from './vision.js';
20
+ import { isVisionModel, pickVisionSibling } from './vision.js';
21
21
  export { isVisionModel, messageNeedsVision, messagesNeedVision, pickVisionSibling } from './vision.js';
22
22
  // ─── Learned Weights Loading ───
23
23
  const WEIGHTS_FILE = path.join(BLOCKRUN_DIR, 'router-weights.json');
@@ -118,6 +118,19 @@ export function isModelUnavailable(model) {
118
118
  export function resetUnavailableModels() {
119
119
  observedUnavailable.clear();
120
120
  }
121
+ // The core's capability snapshot decides vision eligibility inside the
122
+ // portfolio, but it lags the catalog (36 gateway chat ids have no entry as of
123
+ // 2026-08-29, and it disagrees with Franklin's allowlist on gpt-5-mini / o3 /
124
+ // grok-4-0709, all of which accept images). Franklin's allowlist in vision.ts
125
+ // is the maintained source, so its verdict overrides `supportsVision` on
126
+ // every entry the core knows. Ids the core does not know fail OPEN inside
127
+ // the core (`isEligible` returns true) — that gap is closed by the
128
+ // post-selection guard in routeRequest, not by inventing context/output
129
+ // numbers here that would silently change eligibility.
130
+ const SHARED_MODEL_CAPABILITIES = Object.fromEntries(Object.entries(SHARED_MODEL_CAPABILITIES_BASE).map(([id, caps]) => [
131
+ id,
132
+ { ...caps, supportsVision: isVisionModel(id) },
133
+ ]));
121
134
  function normalizeRoutingContext(context) {
122
135
  return typeof context === 'boolean' ? { needsVision: context } : context;
123
136
  }
@@ -616,6 +629,7 @@ export function routeRequest(prompt, profile = 'auto', context = false) {
616
629
  strategy: process.env.FRANKLIN_ROUTER_STRATEGY === 'rules' ? 'rules' : 'portfolio',
617
630
  },
618
631
  modelPricing: SHARED_MODEL_PRICING,
632
+ modelCapabilities: SHARED_MODEL_CAPABILITIES,
619
633
  routingProfile: 'auto',
620
634
  hasTools: normalizedContext.hasTools ?? toolNames.length > 0,
621
635
  toolCount: toolNames.length,
@@ -628,14 +642,30 @@ export function routeRequest(prompt, profile = 'auto', context = false) {
628
642
  unavailableModels: getUnavailableModels(normalizedContext.unavailableModels),
629
643
  });
630
644
  const category = detectCategory(prompt, loadLearnedWeights()?.category_keywords).category;
645
+ let model = decision.model;
646
+ let candidates = decision.candidates ?? [decision.model];
647
+ const signals = [decision.routerVersion ?? decision.method, ...(decision.taskType ? [decision.taskType] : [])];
648
+ // Vision is a hard requirement, and the core fails open for any id
649
+ // missing from its capability snapshot (see SHARED_MODEL_CAPABILITIES).
650
+ // Before this guard an image turn could land on a text-only model the
651
+ // core simply had no opinion about — zai/glm-5.2 sits in the long-context
652
+ // evidence list, for instance — and the model would then hallucinate
653
+ // from the `Image file: <path>` stub. Walk the core's own recovery chain
654
+ // for the first model that can see; fall back to the family sibling.
655
+ if (normalizedContext.needsVision && !isVisionModel(model)) {
656
+ const sighted = candidates.filter(isVisionModel);
657
+ model = sighted[0] ?? pickVisionSibling(model);
658
+ candidates = sighted.length > 0 ? sighted : [model];
659
+ signals.push('vision-required');
660
+ }
631
661
  return {
632
- model: decision.model,
662
+ model,
633
663
  tier: decision.tier,
634
664
  confidence: decision.confidence,
635
- signals: [decision.routerVersion ?? decision.method, ...(decision.taskType ? [decision.taskType] : [])],
636
- savings: decision.savings,
665
+ signals,
666
+ savings: model === decision.model ? decision.savings : computeSavings(model),
637
667
  category,
638
- candidates: decision.candidates ?? [decision.model],
668
+ candidates,
639
669
  taskType: decision.taskType,
640
670
  routerVersion: decision.routerVersion,
641
671
  reasoning: decision.reasoning,
@@ -26,6 +26,7 @@
26
26
  * the SessionSandboxTracker registry.
27
27
  */
28
28
  import type { CapabilityHandler } from '../agent/types.js';
29
+ import { type ReservationToken } from '../wallet/reservation.js';
29
30
  export interface SandboxRecord {
30
31
  id: string;
31
32
  gpu: string;
@@ -41,6 +42,30 @@ declare class SessionSandboxTracker {
41
42
  drainIds(): string[];
42
43
  }
43
44
  export declare const sessionSandboxTracker: SessionSandboxTracker;
45
+ export declare function _setPaymentSignerForTests(fn: typeof signPayment | null): void;
46
+ declare function signPayment(response: Response, chain: 'base' | 'solana', endpoint: string, resourceDescription: string): Promise<Record<string, string> | null>;
47
+ /**
48
+ * Generic POST-with-x402-retry helper used by all four Modal endpoints. The
49
+ * first POST gets a 402 with payment requirements; we sign and retry once
50
+ * with the X-PAYMENT header. Returns the parsed JSON body and the raw
51
+ * Response (callers may need status code).
52
+ *
53
+ * `reservation` is the caller's wallet hold for this call. If the signed
54
+ * (paid) request has been dispatched and the call then aborts or times out
55
+ * before a response, or the response arrives but its body is cut off, the
56
+ * outcome is ambiguous — the gateway may already have settled the payment.
57
+ * The hold is marked ambiguous so the reservation layer keeps counting it
58
+ * (see reservation.ts) instead of the caller's `finally` releasing it as if
59
+ * nothing was spent. Failures that provably never left this machine (signal
60
+ * already aborted before dispatch, DNS / connection-refused) are NOT
61
+ * ambiguous and release normally.
62
+ */
63
+ export declare function postWithPayment(endpoint: string, body: Record<string, unknown>, resourceDescription: string, abortSignal: AbortSignal, timeoutMs: number, reservation?: ReservationToken | null): Promise<{
64
+ ok: boolean;
65
+ status: number;
66
+ body: Record<string, unknown>;
67
+ raw: string;
68
+ }>;
44
69
  export declare const modalCreateCapability: CapabilityHandler;
45
70
  export declare const modalExecCapability: CapabilityHandler;
46
71
  export declare const modalStatusCapability: CapabilityHandler;
@@ -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);
@@ -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();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blockrun/franklin",
3
- "version": "3.42.0",
3
+ "version": "3.42.2",
4
4
  "description": "Franklin Agent — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
5
5
  "type": "module",
6
6
  "exports": {
@@ -38,7 +38,7 @@
38
38
  "desktop:package:win": "npm run dist:win --workspace @blockrun/franklin-desktop",
39
39
  "dev": "tsc --watch",
40
40
  "start": "node dist/index.js",
41
- "test": "npm run build && node --test --test-concurrency=4 --test-reporter=spec test/local.mjs test/serve-security.local.mjs test/skills.local.mjs test/repair.mjs test/model-resolver.mjs test/exa.local.mjs test/audit-batch.local.mjs test/polymarket.local.mjs test/market.local.mjs test/hooks.local.mjs test/scheduler.local.mjs test/trade-plan.local.mjs test/goal.local.mjs test/memory.local.mjs test/agent-host.local.mjs",
41
+ "test": "npm run build && node --test --test-concurrency=4 --test-reporter=spec test/local.mjs test/serve-security.local.mjs test/skills.local.mjs test/repair.mjs test/model-resolver.mjs test/exa.local.mjs test/audit-batch.local.mjs test/polymarket.local.mjs test/market.local.mjs test/hooks.local.mjs test/scheduler.local.mjs test/trade-plan.local.mjs test/goal.local.mjs test/memory.local.mjs test/agent-host.local.mjs test/reservation.local.mjs",
42
42
  "test:e2e": "npm run build && node --test --test-reporter=spec test/e2e.mjs",
43
43
  "e2e:polymarket:readonly": "npm run build && node scripts/polymarket-e2e-readonly.mjs",
44
44
  "test:free-models": "npm run build && node --test --test-reporter=spec test/free-model-matrix.mjs",