@blockrun/franklin 3.49.27 → 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.
- package/dist/agent/tool-guard.js +5 -4
- package/dist/tools/modal.d.ts +82 -19
- package/dist/tools/modal.js +312 -119
- package/dist/wallet/reservation.d.ts +4 -0
- package/dist/wallet/reservation.js +7 -0
- package/package.json +1 -1
package/dist/agent/tool-guard.js
CHANGED
|
@@ -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:
|
|
315
|
-
//
|
|
316
|
-
//
|
|
317
|
-
//
|
|
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([
|
package/dist/tools/modal.d.ts
CHANGED
|
@@ -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
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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
|
|
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 →
|
|
28
|
-
* the
|
|
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
|
|
35
|
-
*
|
|
36
|
-
* is
|
|
37
|
-
*
|
|
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
|
|
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.
|
|
85
|
-
*
|
|
86
|
-
*
|
|
87
|
-
*
|
|
88
|
-
*
|
|
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;
|
package/dist/tools/modal.js
CHANGED
|
@@ -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
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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
|
|
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 →
|
|
28
|
-
* the
|
|
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
|
|
47
|
-
// step with getModalCreatePricing in the gateway's
|
|
48
|
-
|
|
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
|
-
*
|
|
60
|
-
*
|
|
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
|
-
|
|
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
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
*
|
|
153
|
-
*
|
|
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
|
-
|
|
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 {
|
|
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
|
|
306
|
-
'
|
|
307
|
-
'
|
|
308
|
-
'
|
|
309
|
-
' -
|
|
310
|
-
'
|
|
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,
|
|
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
|
-
'
|
|
316
|
-
'
|
|
317
|
-
'
|
|
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: {
|
|
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
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
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
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
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
|
-
//
|
|
378
|
-
//
|
|
379
|
-
//
|
|
380
|
-
const
|
|
381
|
-
if (
|
|
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:
|
|
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 =
|
|
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
|
-
...(
|
|
402
|
-
...(
|
|
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(
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
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:
|
|
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,
|
|
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: ${
|
|
484
|
-
`- charged: ${
|
|
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
|
|
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,
|
|
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,
|
|
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
|
|
674
|
-
'
|
|
675
|
-
'
|
|
676
|
-
'
|
|
677
|
-
'
|
|
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
|
|
707
|
-
isError:
|
|
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,
|
|
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.
|
|
724
|
-
*
|
|
725
|
-
*
|
|
726
|
-
*
|
|
727
|
-
*
|
|
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