@blockrun/franklin 3.42.1 → 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
 
@@ -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.1",
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",