@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 +2 -4
- package/dist/tools/modal.d.ts +25 -0
- package/dist/tools/modal.js +87 -9
- package/dist/wallet/reservation.d.ts +40 -3
- package/dist/wallet/reservation.js +91 -10
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -571,11 +571,9 @@ Full BlockRun docs: **https://blockrun.ai/docs**
|
|
|
571
571
|
|
|
572
572
|
## Contributors
|
|
573
573
|
|
|
574
|
-
|
|
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
|
-
|
|
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
|
|
package/dist/tools/modal.d.ts
CHANGED
|
@@ -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;
|
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);
|
|
@@ -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();
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@blockrun/franklin",
|
|
3
|
-
"version": "3.42.
|
|
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",
|