@blockrun/franklin 3.49.26 → 3.49.29

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.
@@ -311,10 +311,11 @@ export class SessionToolGuard {
311
311
  }
312
312
  async beforeExecute(invocation, scope) {
313
313
  // Hard-block tools that have failed too many times this session.
314
- // Modal lifecycle tools are exempt: orphan sandboxes keep billing
315
- // GPU time, and ModalTerminate is the only way to recover from
316
- // agent-side. Auto-disabling it after 3 transient errors would
317
- // strand a $0.40/hr H100 until the session ends. Same logic for
314
+ // Modal lifecycle tools are exempt: ModalTerminate is the only way to
315
+ // stop a sandbox agent-side. A sandbox's whole lifetime is charged
316
+ // upfront at create (terminating refunds nothing), but auto-disabling
317
+ // ModalTerminate after 3 transient errors would leave a GPU sandbox
318
+ // running, holding resources, until its timeout. Same logic for
318
319
  // media-gen tools: failures are usually transient (gateway hiccup,
319
320
  // prompt rejection) and the user often wants to retry.
320
321
  const FAILURE_EXEMPT = new Set([
@@ -4,15 +4,20 @@
4
4
  * status, terminate}. See https://modal.com/docs/guide/sandboxes for the
5
5
  * underlying primitives.
6
6
  *
7
- * Pricing (per-call, USDC):
8
- * create at up to 1 CPU and 1024 MB: $0.01 (CPU) / $0.05 (T4) / $0.08 (L4) / $0.10 (A10G) / $0.20 (A100) / $0.40 (H100)
9
- * create above that: hourly rate x lifetime, never below the flat rate:
10
- * $4 (T4) / $4.50 (L4) / $5 (A10G) / $7 (A100) / $9 (H100) per hour
7
+ * Pricing (per-call, USDC; the Base gateway adds a $0.001 transaction fee):
8
+ * create with timeout <= 300s, cpu <= 1 and memory <= 1024 MB (flat):
9
+ * $0.01 (CPU) / $0.05 (T4) / $0.08 (L4) / $0.10 (A10G) / $0.20 (A100) / $0.40 (H100)
10
+ * any other create: hourly rate x the full requested lifetime, upfront, never
11
+ * below the flat rate, no refund on early terminate:
12
+ * $0.25 (CPU) / $4 (T4) / $4.50 (L4) / $5 (A10G) / $7 (A100) / $9 (H100) per hour
11
13
  * exec: $0.001
12
14
  * status: $0.001
13
15
  * terminate: $0.001
14
16
  *
15
- * Gateway constraints (probed 2026-05-02):
17
+ * Gateway constraints (probed 2026-05-02; lifetime re-probed 2026-11-13):
18
+ * - sandbox lifetime (create `timeout`): 10..86400 s (24 h). 86401 -> 400 on
19
+ * sol.blockrun.ai and blockrun.ai; 86400 -> 402 with a quote.
20
+ * - cpu >= 0.125 (Modal's own default; below that the Solana gateway 400s).
16
21
  * - image is fixed at python:3.11 — no custom containers yet.
17
22
  * - command is execve-style (string[]), not a shell string. We accept a
18
23
  * plain string from the LLM and auto-wrap to ["sh","-c", string].
@@ -21,22 +26,52 @@
21
26
  * - No upload/download endpoints — files in/out via exec heredoc / curl.
22
27
  *
23
28
  * Lifecycle:
24
- * ModalCreate → returns sandbox_id, charged at GPU tier
29
+ * ModalCreate → returns sandbox_id; the whole requested lifetime is charged
30
+ * here, upfront
25
31
  * ModalExec → sync, returns { stdout, stderr, exit_code }
26
32
  * ModalStatus → check running/terminated
27
- * ModalTerminate → release; called automatically at session end via
28
- * the SessionSandboxTracker registry.
33
+ * ModalTerminate → stops the sandbox and frees its resources. It refunds
34
+ * nothing: the lifetime was paid at create. Nothing calls
35
+ * it automatically today (terminateAllSessionSandboxes has
36
+ * no caller), so an unterminated sandbox runs until its
37
+ * timeout — already paid for, so no further charge.
29
38
  */
30
39
  import type { CapabilityHandler } from '../agent/types.js';
31
40
  import { type Chain } from '../config.js';
32
41
  import { type ReservationToken } from '../wallet/reservation.js';
42
+ /** Gateway bounds on create `timeout` (sol and base probed 2026-11-13; arc and nano share the schema). */
43
+ export declare const MODAL_MIN_TIMEOUT_SECONDS = 10;
44
+ export declare const MODAL_MAX_TIMEOUT_SECONDS = 86400;
45
+ export declare const MODAL_MIN_CPU = 0.125;
46
+ export interface ModalCreatePricing {
47
+ priceUsd: number;
48
+ model: 'flat' | 'hourly';
49
+ /** Set when model === 'hourly'. */
50
+ hourlyRateUsd?: number;
51
+ /**
52
+ * True when the request is NOT flat-eligible (lifetime > 300 s, cpu > 1 or
53
+ * memory > 1024 MB) but its hourly price is below the flat rate, so the flat
54
+ * rate applies as a floor. The flat-eligibility rule does not describe it.
55
+ */
56
+ flatFloor?: boolean;
57
+ }
33
58
  /**
34
- * What the gateway will ask for this create. The reservation and the confirm
35
- * dialog both read it, so it has to see size as well as GPU type: an 8-core T4
36
- * is $0.33, not the $0.05 a tier lookup says. Lifetime is capped at 300s here,
37
- * so the CPU tier is always flat.
59
+ * What the gateway will ask for this create — mirrors getModalCreatePricing.
60
+ * Flat only when the lifetime is <= 300 s AND the size is <= 1 CPU / 1024 MB;
61
+ * anything else is hourly x the full requested lifetime, floored at the flat
62
+ * rate. The reservation, the quote ceiling and the confirm dialog all read it.
38
63
  */
64
+ export declare function modalCreatePricing(tier: string, cpu?: number, memory?: number, timeoutSeconds?: number): ModalCreatePricing;
39
65
  export declare function modalCreatePriceUsd(tier: string, cpu?: number, memory?: number, timeoutSeconds?: number): number;
66
+ /**
67
+ * The most this client will sign for a call listed at `listPriceUsd`: the list
68
+ * price plus the Base transaction fee, rounded UP to USDC's 6 decimals, plus
69
+ * one atomic unit for the gateway's own round-up of an hourly quote. Returned
70
+ * in atomic units (1 USDC = 1_000_000).
71
+ */
72
+ export declare function maxSignableAtomic(listPriceUsd: number): bigint;
73
+ /** The ceiling as dollars — what the wallet reservation holds. */
74
+ export declare function maxSignableUsd(listPriceUsd: number): number;
40
75
  export interface SandboxRecord {
41
76
  id: string;
42
77
  gpu: string;
@@ -69,23 +104,51 @@ declare function signPayment(response: Response, chain: Chain, endpoint: string,
69
104
  * nothing was spent. Failures that provably never left this machine (signal
70
105
  * already aborted before dispatch, DNS / connection-refused) are NOT
71
106
  * ambiguous and release normally.
107
+ *
108
+ * `maxPriceUsd` is the list price this client expects for the call, and it is
109
+ * required: the 402's quote is checked BEFORE anything is signed. A quote above
110
+ * maxSignableAtomic(maxPriceUsd), an unreadable quote, or a maxPriceUsd that is
111
+ * missing or not a finite non-negative number, and nothing is signed or sent —
112
+ * the call returns 402 with `quote_exceeds_expected`. Without the check a
113
+ * gateway quoting a long-lifetime create at $216 would be signed blind while
114
+ * the reservation held a fraction of that.
115
+ *
116
+ * `chargedUsd` / `signedUsd` report what this call actually cost, for the
117
+ * caller's "charged:" line and recordUsage (see modalCharge).
72
118
  */
73
- export declare function postWithPayment(endpoint: string, body: Record<string, unknown>, resourceDescription: string, abortSignal: AbortSignal, timeoutMs: number, reservation?: ReservationToken | null): Promise<{
119
+ export interface ModalPostResult {
74
120
  ok: boolean;
75
121
  status: number;
76
122
  body: Record<string, unknown>;
77
123
  raw: string;
78
- }>;
124
+ /** The gateway's own statement of the charge (`x-blockrun-cost-usd`), or null. */
125
+ chargedUsd: number | null;
126
+ /** The 402 quote this client signed and sent, in USD; null when nothing was signed. */
127
+ signedUsd: number | null;
128
+ }
129
+ export declare function postWithPayment(endpoint: string, body: Record<string, unknown>, resourceDescription: string, abortSignal: AbortSignal, timeoutMs: number, reservation: ReservationToken | null, maxPriceUsd: number): Promise<ModalPostResult>;
130
+ /**
131
+ * What a successful Modal call cost, for the "charged:" line and recordUsage.
132
+ * The gateway's `x-blockrun-cost-usd` wins; next the 402 quote this client
133
+ * signed (an exact-scheme payment settles that amount); otherwise the client's
134
+ * list price, flagged as an estimate. The list price is the sol/arc/nano rate
135
+ * and the Base gateway's hourly rates are lower, so presenting it as the
136
+ * settled amount overstated Base hourly creates by up to ~2.5x.
137
+ */
138
+ export declare function modalCharge(res: Pick<ModalPostResult, 'chargedUsd' | 'signedUsd'>, listPriceUsd: number): {
139
+ usd: number;
140
+ estimated: boolean;
141
+ };
79
142
  export declare const modalCreateCapability: CapabilityHandler;
80
143
  export declare const modalExecCapability: CapabilityHandler;
81
144
  export declare const modalStatusCapability: CapabilityHandler;
82
145
  export declare const modalTerminateCapability: CapabilityHandler;
83
146
  /**
84
- * Terminate every sandbox the current session has created. Called from
85
- * vscode-session.ts at session end (and the SessionToolGuard cleanup path)
86
- * so a missed agent ModalTerminate doesn't leave Modal billing the user
87
- * up to the per-sandbox timeout. Best-effort: failures are logged but
88
- * don't block session shutdown.
147
+ * Terminate every sandbox the current session has created. Written for a
148
+ * session-end hook that no longer exists, so nothing calls it today.
149
+ * Terminating refunds nothing (each lifetime was charged upfront at create);
150
+ * it only stops sandboxes left running. Best-effort: failures are returned,
151
+ * not thrown.
89
152
  */
90
153
  export declare function terminateAllSessionSandboxes(opts?: {
91
154
  abortSignal?: AbortSignal;
@@ -4,15 +4,20 @@
4
4
  * status, terminate}. See https://modal.com/docs/guide/sandboxes for the
5
5
  * underlying primitives.
6
6
  *
7
- * Pricing (per-call, USDC):
8
- * create at up to 1 CPU and 1024 MB: $0.01 (CPU) / $0.05 (T4) / $0.08 (L4) / $0.10 (A10G) / $0.20 (A100) / $0.40 (H100)
9
- * create above that: hourly rate x lifetime, never below the flat rate:
10
- * $4 (T4) / $4.50 (L4) / $5 (A10G) / $7 (A100) / $9 (H100) per hour
7
+ * Pricing (per-call, USDC; the Base gateway adds a $0.001 transaction fee):
8
+ * create with timeout <= 300s, cpu <= 1 and memory <= 1024 MB (flat):
9
+ * $0.01 (CPU) / $0.05 (T4) / $0.08 (L4) / $0.10 (A10G) / $0.20 (A100) / $0.40 (H100)
10
+ * any other create: hourly rate x the full requested lifetime, upfront, never
11
+ * below the flat rate, no refund on early terminate:
12
+ * $0.25 (CPU) / $4 (T4) / $4.50 (L4) / $5 (A10G) / $7 (A100) / $9 (H100) per hour
11
13
  * exec: $0.001
12
14
  * status: $0.001
13
15
  * terminate: $0.001
14
16
  *
15
- * Gateway constraints (probed 2026-05-02):
17
+ * Gateway constraints (probed 2026-05-02; lifetime re-probed 2026-11-13):
18
+ * - sandbox lifetime (create `timeout`): 10..86400 s (24 h). 86401 -> 400 on
19
+ * sol.blockrun.ai and blockrun.ai; 86400 -> 402 with a quote.
20
+ * - cpu >= 0.125 (Modal's own default; below that the Solana gateway 400s).
16
21
  * - image is fixed at python:3.11 — no custom containers yet.
17
22
  * - command is execve-style (string[]), not a shell string. We accept a
18
23
  * plain string from the LLM and auto-wrap to ["sh","-c", string].
@@ -21,11 +26,15 @@
21
26
  * - No upload/download endpoints — files in/out via exec heredoc / curl.
22
27
  *
23
28
  * Lifecycle:
24
- * ModalCreate → returns sandbox_id, charged at GPU tier
29
+ * ModalCreate → returns sandbox_id; the whole requested lifetime is charged
30
+ * here, upfront
25
31
  * ModalExec → sync, returns { stdout, stderr, exit_code }
26
32
  * ModalStatus → check running/terminated
27
- * ModalTerminate → release; called automatically at session end via
28
- * the SessionSandboxTracker registry.
33
+ * ModalTerminate → stops the sandbox and frees its resources. It refunds
34
+ * nothing: the lifetime was paid at create. Nothing calls
35
+ * it automatically today (terminateAllSessionSandboxes has
36
+ * no caller), so an unterminated sandbox runs until its
37
+ * timeout — already paid for, so no further charge.
29
38
  */
30
39
  import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
31
40
  import { loadChain, VERSION, DASHBOARD_URL } from '../config.js';
@@ -34,6 +43,8 @@ import { walletReservation, AMBIGUOUS_GRACE_MS } from '../wallet/reservation.js'
34
43
  import { recordUsage } from '../stats/tracker.js';
35
44
  import { logger } from '../logger.js';
36
45
  import { noChargeNote } from '../payments/billing-copy.js';
46
+ import { GATEWAY_TRANSACTION_FEE_USD } from '../gateway-models.js';
47
+ import { chargeFromResponse } from '../payments/price-catalog.js';
37
48
  // ─── Pricing table (probed from /.well-known/x402 + 402 responses) ─────────
38
49
  const CREATE_PRICE_USD = {
39
50
  cpu: 0.01,
@@ -43,9 +54,14 @@ const CREATE_PRICE_USD = {
43
54
  A100: 0.20,
44
55
  H100: 0.40,
45
56
  };
46
- // The gateway bills a larger sandbox by the hour for its whole lifetime. Keep in
47
- // step with getModalCreatePricing in the gateway's src/lib/modal.ts.
48
- const GPU_HOURLY_PRICE_USD = {
57
+ // The gateway bills every create outside the flat tier by the hour for its whole
58
+ // requested lifetime. Keep in step with getModalCreatePricing in the gateway's
59
+ // src/lib/modal.ts (sol, arc and nano carry these rates; the Base gateway's are
60
+ // lower, so these never under-reserve there). The quote guard in
61
+ // postWithPayment refuses to sign anything above this table, so a gateway price
62
+ // rise surfaces as a clear refusal rather than a silent over-charge.
63
+ const HOURLY_PRICE_USD = {
64
+ cpu: 0.25,
49
65
  T4: 4.00,
50
66
  L4: 4.50,
51
67
  A10G: 5.00,
@@ -54,20 +70,65 @@ const GPU_HOURLY_PRICE_USD = {
54
70
  };
55
71
  const FLAT_RATE_MAX_CPU = 1;
56
72
  const FLAT_RATE_MAX_MEMORY_MB = 1024;
73
+ const FLAT_RATE_MAX_SECONDS = 300;
57
74
  const DEFAULT_TIMEOUT_SECONDS = 300;
75
+ /** Gateway bounds on create `timeout` (sol and base probed 2026-11-13; arc and nano share the schema). */
76
+ export const MODAL_MIN_TIMEOUT_SECONDS = 10;
77
+ export const MODAL_MAX_TIMEOUT_SECONDS = 86_400;
78
+ export const MODAL_MIN_CPU = 0.125;
58
79
  /**
59
- * What the gateway will ask for this create. The reservation and the confirm
60
- * dialog both read it, so it has to see size as well as GPU type: an 8-core T4
61
- * is $0.33, not the $0.05 a tier lookup says. Lifetime is capped at 300s here,
62
- * so the CPU tier is always flat.
80
+ * Per-call transaction fee the Base gateway adds to every quote (the Solana
81
+ * gateway charges none). The quote guard allows it on top of the list price.
63
82
  */
64
- export function modalCreatePriceUsd(tier, cpu, memory, timeoutSeconds = DEFAULT_TIMEOUT_SECONDS) {
83
+ const QUOTE_FEE_ALLOWANCE_USD = GATEWAY_TRANSACTION_FEE_USD;
84
+ /**
85
+ * What the gateway will ask for this create — mirrors getModalCreatePricing.
86
+ * Flat only when the lifetime is <= 300 s AND the size is <= 1 CPU / 1024 MB;
87
+ * anything else is hourly x the full requested lifetime, floored at the flat
88
+ * rate. The reservation, the quote ceiling and the confirm dialog all read it.
89
+ */
90
+ export function modalCreatePricing(tier, cpu, memory, timeoutSeconds = DEFAULT_TIMEOUT_SECONDS) {
91
+ // Fail closed: an unknown tier has no price, and an undefined price would
92
+ // reach the reservation and the quote ceiling as NaN.
93
+ if (!Object.prototype.hasOwnProperty.call(CREATE_PRICE_USD, tier)) {
94
+ throw new RangeError(`no Modal price for tier ${JSON.stringify(tier)}`);
95
+ }
65
96
  const flat = CREATE_PRICE_USD[tier];
66
- const hourly = GPU_HOURLY_PRICE_USD[tier];
67
- const small = (cpu ?? 1) <= FLAT_RATE_MAX_CPU && (memory ?? 512) <= FLAT_RATE_MAX_MEMORY_MB;
68
- if (small || hourly === undefined)
69
- return flat;
70
- return Math.max(flat, hourly * (timeoutSeconds / 3600));
97
+ const flatEligible = timeoutSeconds <= FLAT_RATE_MAX_SECONDS &&
98
+ (cpu ?? 1) <= FLAT_RATE_MAX_CPU &&
99
+ (memory ?? 512) <= FLAT_RATE_MAX_MEMORY_MB;
100
+ if (!flatEligible) {
101
+ const hourlyRateUsd = HOURLY_PRICE_USD[tier];
102
+ const hourlyPrice = hourlyRateUsd * (timeoutSeconds / 3600);
103
+ if (hourlyPrice > flat)
104
+ return { priceUsd: hourlyPrice, model: 'hourly', hourlyRateUsd };
105
+ return { priceUsd: flat, model: 'flat', flatFloor: true };
106
+ }
107
+ return { priceUsd: flat, model: 'flat' };
108
+ }
109
+ export function modalCreatePriceUsd(tier, cpu, memory, timeoutSeconds = DEFAULT_TIMEOUT_SECONDS) {
110
+ return modalCreatePricing(tier, cpu, memory, timeoutSeconds).priceUsd;
111
+ }
112
+ /**
113
+ * The most this client will sign for a call listed at `listPriceUsd`: the list
114
+ * price plus the Base transaction fee, rounded UP to USDC's 6 decimals, plus
115
+ * one atomic unit for the gateway's own round-up of an hourly quote. Returned
116
+ * in atomic units (1 USDC = 1_000_000).
117
+ */
118
+ export function maxSignableAtomic(listPriceUsd) {
119
+ // Fail closed on a price that is not a real number: NaN would otherwise
120
+ // throw deep inside BigInt() where a caller may swallow it.
121
+ if (typeof listPriceUsd !== 'number' || !Number.isFinite(listPriceUsd) || listPriceUsd < 0) {
122
+ throw new RangeError(`no quote ceiling for list price ${String(listPriceUsd)}`);
123
+ }
124
+ // Round the micro-dollar figure to 3 places first so float noise
125
+ // (0.1 + 0.001 = 0.10100000000000001) does not ceil an exact figure up a unit.
126
+ const micro = Math.ceil(Number(((listPriceUsd + QUOTE_FEE_ALLOWANCE_USD) * 1e6).toFixed(3)));
127
+ return BigInt(micro) + 1n;
128
+ }
129
+ /** The ceiling as dollars — what the wallet reservation holds. */
130
+ export function maxSignableUsd(listPriceUsd) {
131
+ return Number(maxSignableAtomic(listPriceUsd)) / 1e6;
71
132
  }
72
133
  const EXEC_PRICE_USD = 0.001;
73
134
  const STATUS_PRICE_USD = 0.001;
@@ -103,6 +164,9 @@ async function signPayment(response, chain, endpoint, resourceDescription) {
103
164
  const paymentHeader = await extractPaymentReq(response);
104
165
  if (!paymentHeader)
105
166
  return null;
167
+ // maxTimeoutSeconds below is the x402 authorization validity window the 402
168
+ // quotes (300 s), NOT the sandbox lifetime: a 24 h create still settles
169
+ // within seconds of signing, so it needs no change for long lifetimes.
106
170
  if (chain === 'solana') {
107
171
  const wallet = await getOrCreateSolanaWallet();
108
172
  const paymentRequired = parsePaymentRequired(paymentHeader);
@@ -149,22 +213,26 @@ async function extractPaymentReq(response) {
149
213
  return header;
150
214
  }
151
215
  /**
152
- * Generic POST-with-x402-retry helper used by all four Modal endpoints. The
153
- * first POST gets a 402 with payment requirements; we sign and retry once
154
- * with the X-PAYMENT header. Returns the parsed JSON body and the raw
155
- * Response (callers may need status code).
156
- *
157
- * `reservation` is the caller's wallet hold for this call. If the signed
158
- * (paid) request has been dispatched and the call then aborts or times out
159
- * before a response, or the response arrives but its body is cut off, the
160
- * outcome is ambiguous — the gateway may already have settled the payment.
161
- * The hold is marked ambiguous so the reservation layer keeps counting it
162
- * (see reservation.ts) instead of the caller's `finally` releasing it as if
163
- * nothing was spent. Failures that provably never left this machine (signal
164
- * already aborted before dispatch, DNS / connection-refused) are NOT
165
- * ambiguous and release normally.
216
+ * The amount (atomic USDC) a 402 asks for, picked the same way signPayment
217
+ * picks its option. Null when the 402 carries no readable quote.
166
218
  */
167
- export async function postWithPayment(endpoint, body, resourceDescription, abortSignal, timeoutMs, reservation) {
219
+ async function quotedAtomic(response, chain) {
220
+ try {
221
+ const header = await extractPaymentReq(response.clone());
222
+ if (!header)
223
+ return null;
224
+ const details = extractPaymentDetails(parsePaymentRequired(header), chain === 'solana' ? SOLANA_NETWORK : undefined);
225
+ const amount = String(details.amount ?? '');
226
+ return /^\d+$/.test(amount) ? BigInt(amount) : null;
227
+ }
228
+ catch {
229
+ return null;
230
+ }
231
+ }
232
+ function atomicToUsd(n) {
233
+ return `$${(Number(n) / 1e6).toFixed(6)}`;
234
+ }
235
+ export async function postWithPayment(endpoint, body, resourceDescription, abortSignal, timeoutMs, reservation, maxPriceUsd) {
168
236
  const chain = loadChain();
169
237
  const headers = {
170
238
  ...gatewayHeaders(),
@@ -176,14 +244,39 @@ export async function postWithPayment(endpoint, body, resourceDescription, abort
176
244
  abortSignal.addEventListener('abort', onParentAbort, { once: true });
177
245
  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
178
246
  let paymentDispatched = false;
247
+ let signedUsd = null;
248
+ const refuse = (error) => {
249
+ logger.warn(`[franklin] Modal ${endpoint}: ${error}`);
250
+ return { ok: false, status: 402, body: { error }, raw: '', chargedUsd: null, signedUsd: null };
251
+ };
179
252
  try {
180
253
  const payload = JSON.stringify(body);
181
254
  let response = await fetch(endpoint, { method: 'POST', signal: ctrl.signal, headers, body: payload });
182
255
  if (response.status === 402 && walletMayPay(headers)) {
256
+ // Fail closed: no computable ceiling means no signature, never a blind one.
257
+ let ceiling;
258
+ try {
259
+ ceiling = maxSignableAtomic(maxPriceUsd);
260
+ }
261
+ catch {
262
+ return refuse(`quote_exceeds_expected: this client has no expected price for the call ` +
263
+ `(${String(maxPriceUsd)}), so nothing was signed`);
264
+ }
265
+ const quoted = await quotedAtomic(response, chain);
266
+ if (quoted === null) {
267
+ return refuse('quote_exceeds_expected: the 402 carried no readable amount, so nothing was signed');
268
+ }
269
+ if (quoted > ceiling) {
270
+ return refuse(`quote_exceeds_expected: the gateway asked ${atomicToUsd(quoted)}, above the ` +
271
+ `${atomicToUsd(ceiling)} this client expected, so nothing was signed`);
272
+ }
183
273
  const paymentHeaders = await paymentSigner(response, chain, endpoint, resourceDescription);
184
274
  if (!paymentHeaders) {
185
- return { ok: false, status: 402, body: { error: 'payment signing failed' }, raw: '' };
275
+ return { ok: false, status: 402, body: { error: 'payment signing failed' }, raw: '', chargedUsd: null, signedUsd: null };
186
276
  }
277
+ // signPayment signs the amount quotedAtomic just read (same option
278
+ // selection), so this is the figure the settlement moves.
279
+ signedUsd = Number(quoted) / 1e6;
187
280
  // Signing can take a while (wallet load, Solana RPC). If the budget
188
281
  // expired meanwhile, fetch rejects before writing a byte — that is a
189
282
  // definite non-payment, not an ambiguous one.
@@ -213,7 +306,14 @@ export async function postWithPayment(endpoint, body, resourceDescription, abort
213
306
  parsed = raw ? JSON.parse(raw) : {};
214
307
  }
215
308
  catch { /* leave as {} */ }
216
- return { ok: response.ok, status: response.status, body: parsed, raw };
309
+ return {
310
+ ok: response.ok,
311
+ status: response.status,
312
+ body: parsed,
313
+ raw,
314
+ chargedUsd: chargeFromResponse(response),
315
+ signedUsd,
316
+ };
217
317
  }
218
318
  catch (err) {
219
319
  if (paymentDispatched && reservation && !definitelyNotSent(err)) {
@@ -232,6 +332,31 @@ export async function postWithPayment(endpoint, body, resourceDescription, abort
232
332
  abortSignal.removeEventListener('abort', onParentAbort);
233
333
  }
234
334
  }
335
+ /**
336
+ * What a successful Modal call cost, for the "charged:" line and recordUsage.
337
+ * The gateway's `x-blockrun-cost-usd` wins; next the 402 quote this client
338
+ * signed (an exact-scheme payment settles that amount); otherwise the client's
339
+ * list price, flagged as an estimate. The list price is the sol/arc/nano rate
340
+ * and the Base gateway's hourly rates are lower, so presenting it as the
341
+ * settled amount overstated Base hourly creates by up to ~2.5x.
342
+ */
343
+ export function modalCharge(res, listPriceUsd) {
344
+ if (typeof res.chargedUsd === 'number')
345
+ return { usd: res.chargedUsd, estimated: false };
346
+ if (typeof res.signedUsd === 'number')
347
+ return { usd: res.signedUsd, estimated: false };
348
+ return { usd: listPriceUsd, estimated: true };
349
+ }
350
+ /** A settled amount to the micro-dollar, trailing zeros trimmed, at least 2 places. */
351
+ function fmtUsdExact(n) {
352
+ const [whole, frac = ''] = n.toFixed(6).split('.');
353
+ return `$${whole}.${frac.replace(/0+$/, '').padEnd(2, '0')}`;
354
+ }
355
+ function describeCharge(charge) {
356
+ return charge.estimated
357
+ ? `~${fmtUsd(charge.usd)} estimated (list price; the gateway did not report the settled amount)`
358
+ : fmtUsdExact(charge.usd);
359
+ }
235
360
  // ─── Helpers ─────────────────────────────────────────────────────────────
236
361
  /** Explain why hold() refused, so the agent does not loop on "wait". */
237
362
  function describeHeadroom() {
@@ -302,23 +427,26 @@ export const modalCreateCapability = {
302
427
  spec: {
303
428
  name: 'ModalCreate',
304
429
  description: 'Create a Modal Python 3.11 sandbox (CPU or GPU) via the BlockRun gateway. ' +
305
- 'Returns a sandbox_id you pass to ModalExec. Charged once per create. Up to 1 CPU and ' +
306
- '1024 MB: CPU $0.01, T4 $0.05, L4 $0.08, A10G $0.10, A100 $0.20, H100 $0.40. Larger GPU ' +
307
- 'sandboxes pay hourly for the lifetime, at least the same: T4 $4, L4 $4.50, A10G $5, A100 $7, H100 $9 per hour. ' +
308
- 'IMPORTANT — current limitations (BlockRun gateway is in early-access for sandboxes):\n' +
309
- ' - sandbox lifetime: 5 minutes MAX (gateway hard-cap, regardless of GPU tier)\n' +
310
- ' - per ModalExec call: 60 seconds MAX wall-clock\n' +
430
+ 'Returns a sandbox_id you pass to ModalExec. Charged ONCE, UPFRONT, at create.\n' +
431
+ 'BILLING — `timeout` is the BILLED lifetime, not an idle timeout:\n' +
432
+ ' - timeout <= 300 s AND cpu <= 1 AND memory <= 1024 MB: flat rate. ' +
433
+ 'CPU $0.01, T4 $0.05, L4 $0.08, A10G $0.10, A100 $0.20, H100 $0.40.\n' +
434
+ ' - Anything else (timeout > 300 s, OR cpu > 1, OR memory > 1024 MB): hourly rate x the FULL ' +
435
+ 'requested timeout, charged upfront, never below the flat rate, NO refund when you terminate early. ' +
436
+ 'Per hour: CPU $0.25, T4 $4, L4 $4.50, A10G $5, A100 $7, H100 $9.\n' +
437
+ ' - Examples: {timeout: 600, gpu: "A100"} = $1.17; {timeout: 1200, gpu: "H100"} = $3.00; ' +
438
+ '{timeout: 86400, gpu: "H100"} = $216 even if the job finishes in a minute.\n' +
439
+ ' - Ask for the time the work needs, not a safe-looking ceiling. Keep timeout <= 300 with ' +
440
+ 'default size for short tasks.\n' +
441
+ 'Limits:\n' +
442
+ ' - sandbox lifetime: 10 s to 86400 s (24 h); default 300 s\n' +
443
+ ' - per ModalExec call: 60 seconds MAX wall-clock (use fire-and-poll below)\n' +
311
444
  ' - Python 3.11 only, no custom images yet\n' +
312
- ' - 1 vCPU, 1 GiB RAM defaults\n' +
313
- ' - GPU access is preview-tier (officially "coming later" in docs)\n' +
445
+ ' - 1 vCPU, 512 MB RAM defaults\n' +
314
446
  ' - No setup-time provisioning — every sandbox starts empty\n' +
315
- 'These limits make this tool suitable for: GPU benchmarks (nvidia-smi, matmul), ' +
316
- 'small model inference (≤3B params if weights pre-cached), CUDA kernel validation, ' +
317
- 'short ad-hoc Python tasks. NOT suitable for: full LoRA / fine-tuning runs, ' +
318
- 'pip install + model download + training (pip alone burns 1-2 min of the 5-min budget). ' +
319
- 'Custom images + longer lifetime + GPU production tier are documented as "coming later" ' +
320
- 'by BlockRun — for serious ML workloads tell the user to use Modal directly until then. ' +
321
- 'Always call ModalTerminate when done. ' +
447
+ 'Good for: GPU benchmarks, CUDA kernel validation, model inference, ad-hoc Python, and ' +
448
+ 'longer jobs (pip install + model download + training) when the user accepts the hourly cost. ' +
449
+ 'Always call ModalTerminate when done (it stops the sandbox; it does not refund the lifetime). ' +
322
450
  'Long-running command pattern: each ModalExec call is itself capped at 60s wall-clock. ' +
323
451
  'For work that takes >60s (pip install, model download, training), use the ' +
324
452
  'fire-and-poll pattern: ModalExec(["sh","-c","nohup <cmd> > /workspace/log 2>&1 &"]) ' +
@@ -327,7 +455,12 @@ export const modalCreateCapability = {
327
455
  type: 'object',
328
456
  properties: {
329
457
  gpu: { type: 'string', description: 'GPU tier. One of T4, L4, A10G, A100, H100. Omit for CPU-only ($0.01).' },
330
- timeout: { type: 'number', description: 'Lifetime cap in seconds. Default + Max = 300 (5 min). Gateway rejects values > 300 with HTTP 400.' },
458
+ timeout: {
459
+ type: 'number',
460
+ description: 'BILLED sandbox lifetime in seconds: charged upfront for the whole value, never refunded. ' +
461
+ 'Default 300, min 10, max 86400 (24 h). <= 300 (with cpu <= 1, memory <= 1024) is the flat rate; ' +
462
+ '> 300 bills hourly for the full value (e.g. 600 s on A100 = $1.17, 3600 s CPU = $0.25, 86400 s H100 = $216).',
463
+ },
331
464
  cpu: { type: 'number', description: 'Number of CPU cores. Default 1, min 0.125, max 1 for CPU sandboxes and 8 with a GPU. Above 1 bills hourly.' },
332
465
  memory: { type: 'number', description: 'Memory MB. Default 512, max 1024 for CPU sandboxes and 32768 with a GPU. Above 1024 bills hourly.' },
333
466
  },
@@ -342,17 +475,24 @@ export const modalCreateCapability = {
342
475
  // 400s on either, leaving the agent confused (it sees "Invalid
343
476
  // request body" with no actionable hint). Fix the obvious mistakes
344
477
  // before they leave the client.
345
- let gpu = raw.gpu;
346
- if (typeof gpu === 'string') {
347
- const matched = [...VALID_GPUS].find(g => g.toLowerCase() === gpu.toLowerCase());
348
- if (matched)
349
- gpu = matched;
478
+ // An absent, null or blank gpu means CPU. Anything else must name a GPU
479
+ // tier exactly (after case/whitespace folding): `gpu: ""` used to fall
480
+ // through as tier "" with no price, which crashed the confirm dialog and,
481
+ // headless, skipped both the reservation and the quote ceiling.
482
+ const rawGpu = raw.gpu;
483
+ let gpu;
484
+ if (rawGpu === undefined || rawGpu === null || (typeof rawGpu === 'string' && rawGpu.trim() === '')) {
485
+ gpu = undefined;
350
486
  }
351
- if (gpu && !VALID_GPUS.has(gpu)) {
352
- return {
353
- output: `Error: invalid gpu "${gpu}". Allowed: ${[...VALID_GPUS].join(', ')} (or omit for CPU).`,
354
- isError: true,
355
- };
487
+ else {
488
+ const wanted = typeof rawGpu === 'string' ? rawGpu.trim().toLowerCase() : null;
489
+ gpu = wanted === null ? undefined : [...VALID_GPUS].find(g => g.toLowerCase() === wanted);
490
+ if (!gpu) {
491
+ return {
492
+ output: `Error: invalid gpu ${JSON.stringify(rawGpu)}. Allowed: ${[...VALID_GPUS].join(', ')} (or omit for CPU).`,
493
+ isError: true,
494
+ };
495
+ }
356
496
  }
357
497
  const tier = gpu ?? 'cpu';
358
498
  // Coerce numeric fields. Reject NaN explicitly so we don't ship
@@ -374,34 +514,57 @@ export const modalCreateCapability = {
374
514
  return { output: `Error: ${c.error}`, isError: true };
375
515
  }
376
516
  }
377
- // Gateway hard-caps sandbox lifetime at 300s. Cap client-side so we
378
- // surface a clear error instead of letting the user pay $0.20 for a
379
- // create that 400s on the wire.
380
- const CREATE_TIMEOUT_MAX = 300;
381
- if (typeof timeoutCoerced === 'number' && timeoutCoerced > CREATE_TIMEOUT_MAX) {
517
+ // Mirror the gateway's create schema (integer timeout in 10..86400, cpu
518
+ // >= 0.125) so a bad value fails here with a clear message instead of a
519
+ // bare 400 from the gateway.
520
+ const timeoutSec = typeof timeoutCoerced === 'number' ? timeoutCoerced : DEFAULT_TIMEOUT_SECONDS;
521
+ if (!Number.isInteger(timeoutSec) ||
522
+ timeoutSec < MODAL_MIN_TIMEOUT_SECONDS ||
523
+ timeoutSec > MODAL_MAX_TIMEOUT_SECONDS) {
524
+ return {
525
+ output: `Error: timeout must be a whole number of seconds from ${MODAL_MIN_TIMEOUT_SECONDS} to ` +
526
+ `${MODAL_MAX_TIMEOUT_SECONDS} (24 h), got ${timeoutSec}. Remember it is the billed lifetime: ` +
527
+ `above 300 s it is charged hourly for the full value, upfront, with no refund.`,
528
+ isError: true,
529
+ };
530
+ }
531
+ if (typeof cpuCoerced === 'number' && cpuCoerced < MODAL_MIN_CPU) {
532
+ return { output: `Error: cpu must be at least ${MODAL_MIN_CPU}, got ${cpuCoerced}.`, isError: true };
533
+ }
534
+ // Fail closed: no price or no ceiling means no request at all. Both are
535
+ // computed here, before the dialog, the reservation or any network call,
536
+ // so nothing downstream can run with an undefined price.
537
+ let pricing;
538
+ let ceilingUsd;
539
+ try {
540
+ pricing = modalCreatePricing(tier, typeof cpuCoerced === 'number' ? cpuCoerced : undefined, typeof memoryCoerced === 'number' ? memoryCoerced : undefined, timeoutSec);
541
+ ceilingUsd = maxSignableUsd(pricing.priceUsd);
542
+ }
543
+ catch (err) {
382
544
  return {
383
- output: `Error: timeout ${timeoutCoerced}s exceeds gateway max of ${CREATE_TIMEOUT_MAX}s. ` +
384
- `BlockRun caps Modal sandbox lifetime at 5 minutes regardless of GPU tier. ` +
385
- `For longer workloads, the work must be split across multiple sandboxes ` +
386
- `(checkpoint + reload) or you need to ask BlockRun to lift this cap.`,
545
+ output: `Error: could not price this ModalCreate (${err.message}); nothing was sent or charged.`,
387
546
  isError: true,
388
547
  };
389
548
  }
390
- const price = modalCreatePriceUsd(tier, typeof cpuCoerced === 'number' ? cpuCoerced : undefined, typeof memoryCoerced === 'number' ? memoryCoerced : undefined, typeof timeoutCoerced === 'number' ? timeoutCoerced : undefined);
549
+ const price = pricing.priceUsd;
550
+ const billingLine = pricing.model === 'hourly'
551
+ ? `hourly: ${fmtUsd(pricing.hourlyRateUsd ?? 0)}/h x ${(timeoutSec / 3600).toFixed(2)} h, upfront, no refund on early terminate`
552
+ : pricing.flatFloor
553
+ ? 'flat floor: the hourly price for this size and lifetime is below the flat rate, so the flat rate is charged, upfront, no refund on early terminate'
554
+ : 'flat (timeout <= 300 s, cpu <= 1, memory <= 1024 MB)';
391
555
  // ── AskUser cost preview (skipped if env auto-approve or non-UI mode) ──
392
556
  const autoApprove = process.env.FRANKLIN_MEDIA_AUTO_APPROVE_ALL === '1';
393
557
  if (ctx.onAskUser && !autoApprove) {
394
- const timeoutSec = raw.timeout ?? 300;
395
558
  const lines = [
396
559
  `Create Modal sandbox?`,
397
560
  ``,
398
561
  ` Tier: ${tier === 'cpu' ? 'CPU only' : `GPU ${tier}`}`,
399
562
  ` Image: python:3.11`,
400
- ` Timeout: ${timeoutSec}s (${(timeoutSec / 60).toFixed(1)} min)`,
401
- ...(raw.cpu ? [` CPU cores: ${raw.cpu}`] : []),
402
- ...(raw.memory ? [` Memory: ${raw.memory} MB`] : []),
563
+ ` Timeout: ${timeoutSec}s (${(timeoutSec / 60).toFixed(1)} min) — billed lifetime`,
564
+ ...(typeof cpuCoerced === 'number' ? [` CPU cores: ${cpuCoerced}`] : []),
565
+ ...(typeof memoryCoerced === 'number' ? [` Memory: ${memoryCoerced} MB`] : []),
403
566
  ``,
404
- `Create cost: ${fmtUsd(price)} (one-time)`,
567
+ `Create cost: ${fmtUsd(price)} (one-time, ${billingLine})`,
405
568
  `Each exec: ${fmtUsd(EXEC_PRICE_USD)}`,
406
569
  `Terminate: ${fmtUsd(TERMINATE_PRICE_USD)}`,
407
570
  ];
@@ -417,18 +580,28 @@ export const modalCreateCapability = {
417
580
  }
418
581
  }
419
582
  // Wallet reservation — block over-spend if other in-flight calls hold balance.
583
+ // Hold the most we will sign (list price + Base fee), not the list price:
584
+ // the quote guard in postWithPayment refuses anything above that ceiling.
585
+ // A balance read that fails resolves to Infinity inside hold(), so a throw
586
+ // here is a bad amount, not an RPC blip: refuse rather than create with no
587
+ // hold.
420
588
  let reservation = null;
421
589
  try {
422
- reservation = await walletReservation.hold(price);
423
- if (!reservation) {
424
- return {
425
- output: `Insufficient ${isKeyMode() ? 'account credit' : 'USDC'} for ModalCreate (${tier}, ~${fmtUsd(price)}). ` +
426
- describeHeadroom(),
427
- isError: true,
428
- };
429
- }
590
+ reservation = await walletReservation.hold(ceilingUsd);
591
+ }
592
+ catch (err) {
593
+ return {
594
+ output: `Error: could not reserve funds for ModalCreate (${err.message}); nothing was sent or charged.`,
595
+ isError: true,
596
+ };
597
+ }
598
+ if (!reservation) {
599
+ return {
600
+ output: `Insufficient ${isKeyMode() ? 'account credit' : 'USDC'} for ModalCreate (${tier}, ~${fmtUsd(price)}). ` +
601
+ describeHeadroom(),
602
+ isError: true,
603
+ };
430
604
  }
431
- catch { /* fall through, x402 will surface real error */ }
432
605
  try {
433
606
  const body = {};
434
607
  if (gpu)
@@ -441,7 +614,7 @@ export const modalCreateCapability = {
441
614
  body.memory = memoryCoerced;
442
615
  const callStartedAt = Date.now();
443
616
  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
444
- reservation);
617
+ reservation, price);
445
618
  const latencyMs = Date.now() - callStartedAt;
446
619
  if (!res.ok) {
447
620
  const err = res.body.error ? String(res.body.error) : res.raw.slice(0, 300);
@@ -469,19 +642,21 @@ export const modalCreateCapability = {
469
642
  id: sandboxId,
470
643
  gpu: tier,
471
644
  createdAt: Date.now(),
472
- timeoutSeconds: raw.timeout ?? 300,
645
+ timeoutSeconds: timeoutSec,
473
646
  });
474
647
  // Stats — surface Modal usage in `franklin insights` like other paid tools.
648
+ // Record what settled, not the client's list price (see modalCharge).
649
+ const charge = modalCharge(res, price);
475
650
  try {
476
- recordUsage(`modal/${tier}`, 0, 0, price, latencyMs);
651
+ recordUsage(`modal/${tier}`, 0, 0, charge.usd, latencyMs, false, charge.estimated);
477
652
  }
478
653
  catch { /* ignore */ }
479
654
  return {
480
655
  output: `Sandbox created\n` +
481
656
  `- id: \`${sandboxId}\`\n` +
482
657
  `- tier: ${tier === 'cpu' ? 'CPU only' : `GPU ${tier}`}\n` +
483
- `- timeout: ${raw.timeout ?? 300}s\n` +
484
- `- charged: ${fmtUsd(price)}\n\n` +
658
+ `- timeout: ${timeoutSec}s (billed lifetime; terminating early refunds nothing)\n` +
659
+ `- charged: ${describeCharge(charge)} (${billingLine})\n\n` +
485
660
  `Next: ModalExec({ sandbox_id: "${sandboxId}", command: ["python","-c","print(1)"] })`,
486
661
  };
487
662
  }
@@ -506,7 +681,7 @@ export const modalExecCapability = {
506
681
  ' exec2: ["sh","-c","tail -50 /workspace/log"] (poll progress, <1s) ' +
507
682
  ' exec3: ["sh","-c","kill -0 $(cat /workspace/pid) 2>/dev/null && echo RUN || echo DONE"] (check live) ' +
508
683
  'This decouples actual work duration from the per-exec 60s ceiling, but the sandbox ' +
509
- 'itself still dies at 300s wall-clock — total useful work fits in ~5 minutes.',
684
+ 'itself still dies when its create `timeout` (billed lifetime, default 300 s, max 24 h) runs out.',
510
685
  input_schema: {
511
686
  type: 'object',
512
687
  properties: {
@@ -536,10 +711,12 @@ export const modalExecCapability = {
536
711
  isError: true,
537
712
  };
538
713
  }
714
+ // Hold the ceiling the quote guard may sign (list + Base fee + 1 unit),
715
+ // not the bare list price. For micro-cost calls a null hold (insufficient)
716
+ // does not block — the guard still caps what can be signed.
539
717
  let reservation = null;
540
718
  try {
541
- reservation = await walletReservation.hold(EXEC_PRICE_USD);
542
- // For micro-cost calls don't hard-block on insufficient — just proceed.
719
+ reservation = await walletReservation.hold(maxSignableUsd(EXEC_PRICE_USD));
543
720
  }
544
721
  catch { /* ignore */ }
545
722
  try {
@@ -566,7 +743,7 @@ export const modalExecCapability = {
566
743
  if (coercedTimeout !== undefined)
567
744
  body.timeout = coercedTimeout;
568
745
  const callStartedAt = Date.now();
569
- const res = await postWithPayment(modalEndpoint('exec'), body, 'Franklin Modal sandbox exec', ctx.abortSignal, Math.max(30_000, ((coercedTimeout ?? 300) + 30) * 1000), reservation);
746
+ const res = await postWithPayment(modalEndpoint('exec'), body, 'Franklin Modal sandbox exec', ctx.abortSignal, Math.max(30_000, ((coercedTimeout ?? 300) + 30) * 1000), reservation, EXEC_PRICE_USD);
570
747
  const latencyMs = Date.now() - callStartedAt;
571
748
  if (!res.ok) {
572
749
  // 400 here usually means the agent built the wrong shape (bad
@@ -597,8 +774,9 @@ export const modalExecCapability = {
597
774
  null;
598
775
  const hasAnyOutput = stdout.length > 0 || stderr.length > 0;
599
776
  const exitCode = rawExit !== null ? rawExit : (hasAnyOutput ? 0 : -1);
777
+ const charge = modalCharge(res, EXEC_PRICE_USD);
600
778
  try {
601
- recordUsage('modal/exec', 0, 0, EXEC_PRICE_USD, latencyMs);
779
+ recordUsage('modal/exec', 0, 0, charge.usd, latencyMs, false, charge.estimated);
602
780
  }
603
781
  catch { /* ignore */ }
604
782
  const summary = `exit ${exitCode}` + (rawExit === null ? ' (inferred — no exit_code field in response)' : '');
@@ -642,19 +820,20 @@ export const modalStatusCapability = {
642
820
  return { output: 'Error: sandbox_id is required', isError: true };
643
821
  let reservation = null;
644
822
  try {
645
- reservation = await walletReservation.hold(STATUS_PRICE_USD);
823
+ reservation = await walletReservation.hold(maxSignableUsd(STATUS_PRICE_USD));
646
824
  }
647
825
  catch { /* ignore */ }
648
826
  try {
649
827
  const callStartedAt = Date.now();
650
- const res = await postWithPayment(modalEndpoint('status'), { sandbox_id }, 'Franklin Modal sandbox status', ctx.abortSignal, 30_000, reservation);
828
+ const res = await postWithPayment(modalEndpoint('status'), { sandbox_id }, 'Franklin Modal sandbox status', ctx.abortSignal, 30_000, reservation, STATUS_PRICE_USD);
651
829
  const latencyMs = Date.now() - callStartedAt;
652
830
  if (!res.ok) {
653
831
  const err = res.body.error ? String(res.body.error) : res.raw.slice(0, 300);
654
832
  return { output: `ModalStatus failed (${res.status}): ${err}`, isError: true };
655
833
  }
834
+ const charge = modalCharge(res, STATUS_PRICE_USD);
656
835
  try {
657
- recordUsage('modal/status', 0, 0, STATUS_PRICE_USD, latencyMs);
836
+ recordUsage('modal/status', 0, 0, charge.usd, latencyMs, false, charge.estimated);
658
837
  }
659
838
  catch { /* ignore */ }
660
839
  const status = res.body.status || 'unknown';
@@ -670,11 +849,12 @@ export const modalStatusCapability = {
670
849
  export const modalTerminateCapability = {
671
850
  spec: {
672
851
  name: 'ModalTerminate',
673
- description: 'Terminate a Modal sandbox and release its resources. Charges $0.001. ' +
674
- 'Strongly recommended after every successful ModalExec sequence — ' +
675
- 'Modal bills wall-clock GPU time until the sandbox terminates or hits ' +
676
- 'its `timeout`. Session-end auto-cleanup also calls this for any sandboxes ' +
677
- 'the agent forgot, but explicit is better.',
852
+ description: 'Terminate a Modal sandbox: stops it and anything running in it, frees its resources, ' +
853
+ 'and ModalExec on that id fails afterwards. Charges $0.001. ' +
854
+ 'It does NOT refund anything: ModalCreate already charged the full requested `timeout` ' +
855
+ 'upfront, so terminating early saves no money. Choose the timeout the work needs at ' +
856
+ 'ModalCreate. Call this when you are done with a sandbox so it does not hold resources ' +
857
+ 'until its timeout; nothing terminates sandboxes automatically when the session ends.',
678
858
  input_schema: {
679
859
  type: 'object',
680
860
  properties: {
@@ -690,25 +870,38 @@ export const modalTerminateCapability = {
690
870
  return { output: 'Error: sandbox_id is required', isError: true };
691
871
  let reservation = null;
692
872
  try {
693
- reservation = await walletReservation.hold(TERMINATE_PRICE_USD);
873
+ reservation = await walletReservation.hold(maxSignableUsd(TERMINATE_PRICE_USD));
694
874
  }
695
875
  catch { /* ignore */ }
696
876
  try {
697
877
  const callStartedAt = Date.now();
698
- const res = await postWithPayment(modalEndpoint('terminate'), { sandbox_id }, 'Franklin Modal sandbox terminate', ctx.abortSignal, 30_000, reservation);
878
+ const res = await postWithPayment(modalEndpoint('terminate'), { sandbox_id }, 'Franklin Modal sandbox terminate', ctx.abortSignal, 30_000, reservation, TERMINATE_PRICE_USD);
699
879
  const latencyMs = Date.now() - callStartedAt;
700
- // Always remove from tracker — even on failure, retrying is wasteful.
701
- sessionSandboxTracker.remove(sandbox_id);
702
880
  if (!res.ok) {
703
881
  const err = res.body.error ? String(res.body.error) : res.raw.slice(0, 300);
882
+ // 402 (a quote-guard refusal or failed signing: nothing was paid, so the
883
+ // terminate never ran) and 5xx leave the sandbox running as far as we
884
+ // know. Keep it tracked and report an error. Other 4xx (e.g. already
885
+ // terminated, unknown id) are benign: drop it from the tracker.
886
+ if (res.status === 402 || res.status >= 500) {
887
+ return {
888
+ output: `ModalTerminate failed (${res.status}): ${err}\n\n` +
889
+ `The sandbox \`${sandbox_id}\` is probably still running and is still tracked. ` +
890
+ `It stops by itself at its create timeout (already paid for). Retry ModalTerminate if you need it stopped now.`,
891
+ isError: true,
892
+ };
893
+ }
894
+ sessionSandboxTracker.remove(sandbox_id);
704
895
  return {
705
896
  output: `ModalTerminate returned ${res.status}: ${err}\n\n` +
706
- `(Removed from local tracker regardless. Modal-side cleanup will happen at the timeout.)`,
707
- isError: res.status >= 500, // 4xx (e.g. already-terminated) is benign
897
+ `(Removed from local tracker: the gateway reports no sandbox to terminate.)`,
898
+ isError: false,
708
899
  };
709
900
  }
901
+ sessionSandboxTracker.remove(sandbox_id);
902
+ const charge = modalCharge(res, TERMINATE_PRICE_USD);
710
903
  try {
711
- recordUsage('modal/terminate', 0, 0, TERMINATE_PRICE_USD, latencyMs);
904
+ recordUsage('modal/terminate', 0, 0, charge.usd, latencyMs, false, charge.estimated);
712
905
  }
713
906
  catch { /* ignore */ }
714
907
  return { output: `Sandbox \`${sandbox_id}\` terminated.` };
@@ -720,11 +913,11 @@ export const modalTerminateCapability = {
720
913
  };
721
914
  // ─── Bulk session cleanup ────────────────────────────────────────────────
722
915
  /**
723
- * Terminate every sandbox the current session has created. Called from
724
- * vscode-session.ts at session end (and the SessionToolGuard cleanup path)
725
- * so a missed agent ModalTerminate doesn't leave Modal billing the user
726
- * up to the per-sandbox timeout. Best-effort: failures are logged but
727
- * don't block session shutdown.
916
+ * Terminate every sandbox the current session has created. Written for a
917
+ * session-end hook that no longer exists, so nothing calls it today.
918
+ * Terminating refunds nothing (each lifetime was charged upfront at create);
919
+ * it only stops sandboxes left running. Best-effort: failures are returned,
920
+ * not thrown.
728
921
  */
729
922
  export async function terminateAllSessionSandboxes(opts = {}) {
730
923
  const ids = sessionSandboxTracker.drainIds();
@@ -742,7 +935,7 @@ export async function terminateAllSessionSandboxes(opts = {}) {
742
935
  // simple.
743
936
  for (const id of ids) {
744
937
  try {
745
- const res = await postWithPayment(modalEndpoint('terminate'), { sandbox_id: id }, 'Franklin Modal sandbox cleanup', ctrl.signal, 20_000);
938
+ const res = await postWithPayment(modalEndpoint('terminate'), { sandbox_id: id }, 'Franklin Modal sandbox cleanup', ctrl.signal, 20_000, null, TERMINATE_PRICE_USD);
746
939
  if (res.ok)
747
940
  succeeded++;
748
941
  else
@@ -76,6 +76,10 @@ declare class WalletReservationManager {
76
76
  * Try to reserve `amountUsd`. Returns a token on success, or null if
77
77
  * insufficient (balance - already-reserved < amountUsd). Caller MUST
78
78
  * release the token after the actual payment resolves, success or fail.
79
+ *
80
+ * Throws on an amount that is not a finite number. A NaN hold used to be
81
+ * granted (every comparison with NaN is false) and then poisoned the
82
+ * reserved total, so every later hold passed whatever the balance.
79
83
  */
80
84
  hold(amountUsd: number): Promise<ReservationToken | null>;
81
85
  /**
@@ -150,8 +150,15 @@ class WalletReservationManager {
150
150
  * Try to reserve `amountUsd`. Returns a token on success, or null if
151
151
  * insufficient (balance - already-reserved < amountUsd). Caller MUST
152
152
  * release the token after the actual payment resolves, success or fail.
153
+ *
154
+ * Throws on an amount that is not a finite number. A NaN hold used to be
155
+ * granted (every comparison with NaN is false) and then poisoned the
156
+ * reserved total, so every later hold passed whatever the balance.
153
157
  */
154
158
  async hold(amountUsd) {
159
+ if (typeof amountUsd !== 'number' || !Number.isFinite(amountUsd)) {
160
+ throw new RangeError(`cannot reserve a non-finite amount (${String(amountUsd)})`);
161
+ }
155
162
  if (amountUsd <= 0) {
156
163
  // Free / zero-cost calls don't need accounting.
157
164
  return { id: `free-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`, amountUsd: 0 };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blockrun/franklin",
3
- "version": "3.49.26",
3
+ "version": "3.49.29",
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": {
@@ -75,7 +75,7 @@
75
75
  "node": ">=20.19.0"
76
76
  },
77
77
  "dependencies": {
78
- "@blockrun/llm": "^3.19.1",
78
+ "@blockrun/llm": "^3.26.5",
79
79
  "@blockrun/model-catalog": "https://codeload.github.com/BlockRunAI/model-catalog/tar.gz/aecf20b4d5ee51af4a38a69a1b9c81e3e64b955c",
80
80
  "@blockrun/router-core": "https://codeload.github.com/BlockRunAI/router-core/tar.gz/273c2af0a9abe70212efbad7117b72eb3038cffc",
81
81
  "@colbymchenry/codegraph": "^1.5.0",