@blockrun/franklin 3.15.10 → 3.15.11

package/README.md

@@ -71,6 +71,8 @@ That's it. Zero signup, zero credit card, zero phone verification. Send **$5 of
 
 ### Prefer a GUI? Try Franklin for VS Code
 
+[![Franklin for VS Code — Beta is here](assets/franklin-vscode-banner.png)](https://marketplace.visualstudio.com/items?itemName=blockrun.franklin-vscode)
+
 The same agent ships as a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=blockrun.franklin-vscode) — chat panel, model picker, wallet balance, image / video generation, inline diff cards — all driven by the wallet you already funded for the CLI.
 
 ```

package/dist/agent/loop.js

@@ -20,6 +20,7 @@ import { createActivateToolCapability } from '../tools/activate.js';
 import { recordUsage } from '../stats/tracker.js';
 import { recordSessionUsage } from '../stats/session-tracker.js';
 import { appendAudit, extractLastUserPrompt } from '../stats/audit.js';
+import { logger, setDebugMode } from '../logger.js';
 import { estimateCost, OPUS_PRICING } from '../pricing.js';
 import { maybeMidSessionExtract } from '../learnings/extractor.js';
 import { extractMentions, buildEntityContext, loadEntities } from '../brain/store.js';
@@ -325,6 +326,9 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
     // fool Edit/Write into skipping the read-before-edit check or serve cached
     // webfetch content fetched under the previous session's intent.
     resetToolSessionState();
+    // Wire stderr-mirroring of log lines to the same flag the agent already
+    // uses to gate verbose console output. File writes happen regardless.
+    setDebugMode(!!config.debug);
     const client = new ModelClient({
         apiUrl: config.apiUrl,
         chain: config.chain,
@@ -725,16 +729,12 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                             kind: 'text_delta',
                             text: `\n*🗜 Auto-compacted: ~${(beforeTokens / 1000).toFixed(0)}K → ~${(afterTokens / 1000).toFixed(0)}K tokens (saved ${pct}%)*\n\n`,
                         });
-                        if (config.debug) {
-                            console.error(`[franklin] History compacted: ~${afterTokens} tokens`);
-                        }
+                        logger.info(`[franklin] History compacted: ~${afterTokens} tokens`);
                     }
                 }
                 catch (compactErr) {
                     compactFailures++;
-                    if (config.debug) {
-                        console.error(`[franklin] Compaction failed (${compactFailures}/3): ${compactErr.message}`);
-                    }
+                    logger.warn(`[franklin] Compaction failed (${compactFailures}/3): ${compactErr.message}`);
                 }
             }
             // Inject ultrathink instruction when mode is active
@@ -939,9 +939,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         const oldModel = config.model;
                         config.model = nextModel;
                         config.onModelChange?.(nextModel, 'system');
-                        if (config.debug) {
-                            console.error(`[franklin] ${oldModel} returned empty — switching to ${nextModel}`);
-                        }
+                        logger.warn(`[franklin] ${oldModel} returned empty — switching to ${nextModel}`);
                         onEvent({ kind: 'text_delta', text: `\n*${oldModel} returned empty — switching to ${nextModel}*\n` });
                         continue;
                     }
@@ -973,9 +971,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 // ── Media size error recovery (strip images/PDFs + retry) ──
                 if (isMediaSizeError(errMsg) && recoveryAttempts < MAX_RECOVERY_ATTEMPTS) {
                     recoveryAttempts++;
-                    if (config.debug) {
-                        console.error(`[franklin] Media too large — stripping and retrying (attempt ${recoveryAttempts})`);
-                    }
+                    logger.warn(`[franklin] Media too large — stripping and retrying (attempt ${recoveryAttempts})`);
                     const { history: stripped, stripped: didStrip } = stripMediaFromHistory(history);
                     if (didStrip) {
                         replaceHistory(history, stripped);
@@ -989,9 +985,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 // the prompt is too long, so we must compact regardless of our threshold estimate.
                 if (classified.category === 'context_limit' && recoveryAttempts < MAX_RECOVERY_ATTEMPTS) {
                     recoveryAttempts++;
-                    if (config.debug) {
-                        console.error(`[franklin] Prompt too long — force compacting (attempt ${recoveryAttempts})`);
-                    }
+                    logger.warn(`[franklin] Prompt too long — force compacting (attempt ${recoveryAttempts})`);
                     onEvent({ kind: 'text_delta', text: '\n*Context limit hit — compacting conversation...*\n' });
                     const { history: compactedAgain } = await forceCompact(history, config.model, client, config.debug);
                     replaceHistory(history, compactedAgain);
@@ -1017,9 +1011,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                             const continuationPrompt = buildContinuationPrompt();
                             history.push(continuationPrompt);
                             persistSessionMessage(continuationPrompt);
-                            if (config.debug) {
-                                console.error(`[franklin] Stream timeout on ${resolvedModel} — auto-continuing with chunked-task prompt`);
-                            }
+                            logger.warn(`[franklin] Stream timeout on ${resolvedModel} — auto-continuing with chunked-task prompt`);
                             onEvent({
                                 kind: 'text_delta',
                                 text: '\n*Task too big for one streaming turn — auto-continuing with a smaller chunk...*\n',
@@ -1031,10 +1023,8 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         const costText = retryDecision.estimatedReplayCostUsd > 0
                             ? ` and at least $${retryDecision.estimatedReplayCostUsd.toFixed(4)} in input charges`
                             : '';
-                        if (config.debug) {
-                            console.error(`[franklin] Timeout retry skipped for ${resolvedModel}: ` +
-                                `~${tokenText} input tokens, replayCost=$${retryDecision.estimatedReplayCostUsd.toFixed(4)}`);
-                        }
+                        logger.warn(`[franklin] Timeout retry skipped for ${resolvedModel}: ` +
+                            `~${tokenText} input tokens, replayCost=$${retryDecision.estimatedReplayCostUsd.toFixed(4)}`);
                         onEvent({
                             kind: 'turn_done',
                             reason: 'error',
@@ -1079,9 +1069,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     }
                     recoveryAttempts++;
                     const backoffMs = getBackoffDelay(recoveryAttempts);
-                    if (config.debug) {
-                        console.error(`[franklin] ${classified.label} error — retrying in ${(backoffMs / 1000).toFixed(1)}s (attempt ${recoveryAttempts}/${effectiveMaxRetries}): ${errMsg.slice(0, 100)}`);
-                    }
+                    logger.warn(`[franklin] ${classified.label} error — retrying in ${(backoffMs / 1000).toFixed(1)}s (attempt ${recoveryAttempts}/${effectiveMaxRetries}): ${errMsg.slice(0, 100)}`);
                     // Surface the actual error + model so the user can see which model
                     // is failing and what the upstream said. Old "Retrying after Server
                     // error" was uninformative — users couldn't tell whether to wait,
@@ -1249,9 +1237,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 if (maxTokensOverride === undefined) {
                     // First hit: escalate to 64K
                     maxTokensOverride = ESCALATED_MAX_TOKENS;
-                    if (config.debug) {
-                        console.error(`[franklin] Max tokens hit — escalating to ${maxTokensOverride}`);
-                    }
+                    logger.warn(`[franklin] Max tokens hit — escalating to ${maxTokensOverride}`);
                 }
                 // Append what we got + a continuation prompt with last-line anchor
                 const partialAssistant = { role: 'assistant', content: responseParts };
@@ -1293,9 +1279,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             // the existing recovery flow handle it.
             const gatewayErr = looksLikeGatewayErrorAsText(responseParts);
             if (gatewayErr.match) {
-                if (config.debug) {
-                    console.error(`[franklin] Gateway returned an error text in lieu of an answer (${resolvedModel}): ${gatewayErr.message}`);
-                }
+                logger.error(`[franklin] Gateway returned an error text in lieu of an answer (${resolvedModel}): ${gatewayErr.message}`);
                 throw new Error(gatewayErr.message);
             }
             // Reset recovery counter on successful completion
@@ -1572,9 +1556,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             }
             // Hard stop: if cap exceeded, force end this agent loop iteration
             if (turnToolCalls >= MAX_TOOL_CALLS_PER_TURN) {
-                if (config.debug) {
-                    console.error(`[franklin] Tool call cap hit: ${turnToolCalls} calls this turn`);
-                }
+                logger.warn(`[franklin] Tool call cap hit: ${turnToolCalls} calls this turn`);
                 // Don't break — let the model respond one more time to summarize,
                 // but inject the stop signal above so it knows to finish up.
             }

package/dist/agent/tool-guard.js

@@ -188,9 +188,23 @@ export class SessionToolGuard {
         }
     }
     async beforeExecute(invocation, scope) {
-        // Hard-block tools that have failed too many times this session
+        // Hard-block tools that have failed too many times this session.
+        // Modal lifecycle tools are exempt: orphan sandboxes keep billing
+        // GPU time, and ModalTerminate is the only way to recover from
+        // agent-side. Auto-disabling it after 3 transient errors would
+        // strand a $0.40/hr H100 until the session ends. Same logic for
+        // media-gen tools: failures are usually transient (gateway hiccup,
+        // prompt rejection) and the user often wants to retry.
+        const FAILURE_EXEMPT = new Set([
+            'ImageGen',
+            'VideoGen',
+            'ModalCreate',
+            'ModalExec',
+            'ModalStatus',
+            'ModalTerminate',
+        ]);
         const errorCount = this.toolErrorCounts.get(invocation.name) ?? 0;
-        if (errorCount >= 3) {
+        if (errorCount >= 3 && !FAILURE_EXEMPT.has(invocation.name)) {
             return {
                 output: `${invocation.name} has failed ${errorCount} times this session and is now disabled. ` +
                     'Tell the user what went wrong and suggest alternatives.',

package/dist/logger.d.ts

@@ -0,0 +1,10 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare function setDebugMode(enabled: boolean): void;
+export declare function isDebugMode(): boolean;
+export declare function getLogFilePath(): string;
+export declare const logger: {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+};

package/dist/logger.js

@@ -0,0 +1,74 @@
+/**
+ * Unified logger — always persists to ~/.blockrun/franklin-debug.log,
+ * optionally mirrors to stderr when debug mode is on.
+ *
+ * Why this exists: before this module, agent diagnostics were emitted with
+ * `if (config.debug) console.error(...)`. That meant `franklin logs` showed
+ * nothing in normal use because the events never hit the file. Now every
+ * level writes to disk; stderr mirroring is the opt-in part.
+ *
+ * Errors during a log write are swallowed — the agent loop must never die
+ * because the disk is full or the home dir is read-only.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR } from './config.js';
+const LOG_FILE = path.join(BLOCKRUN_DIR, 'franklin-debug.log');
+// Strip ANSI escapes + carriage returns so the log stays grep-able.
+const ANSI_RE = /\x1b\[[0-9;]*m|\x1b\][^\x07]*\x07|\r/g;
+let debugMode = false;
+let dirEnsured = false;
+export function setDebugMode(enabled) {
+    debugMode = enabled;
+}
+export function isDebugMode() {
+    return debugMode;
+}
+export function getLogFilePath() {
+    return LOG_FILE;
+}
+function ensureDir() {
+    if (dirEnsured)
+        return;
+    try {
+        fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+        dirEnsured = true;
+    }
+    catch { /* readonly mount / disk full — keep trying so a remount recovers */ }
+}
+function writeFile(level, msg) {
+    ensureDir();
+    try {
+        const clean = msg.replace(ANSI_RE, '');
+        fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [${level.toUpperCase()}] ${clean}\n`);
+    }
+    catch { /* best-effort — never break the agent on log failure */ }
+}
+function writeStderr(msg) {
+    try {
+        process.stderr.write(msg + '\n');
+    }
+    catch { /* swallow */ }
+}
+export const logger = {
+    debug(msg) {
+        writeFile('debug', msg);
+        if (debugMode)
+            writeStderr(msg);
+    },
+    info(msg) {
+        writeFile('info', msg);
+        if (debugMode)
+            writeStderr(msg);
+    },
+    warn(msg) {
+        writeFile('warn', msg);
+        if (debugMode)
+            writeStderr(msg);
+    },
+    error(msg) {
+        writeFile('error', msg);
+        if (debugMode)
+            writeStderr(msg);
+    },
+};

package/dist/stats/audit.d.ts

@@ -24,6 +24,12 @@ export interface AuditEntry {
     routingTier?: string;
 }
 export declare function appendAudit(entry: AuditEntry): void;
+/**
+ * Trim the audit log to the last MAX_AUDIT_ENTRIES lines if it has grown
+ * past the cap. Exported so admin/debug tooling (and tests) can force a
+ * compaction without waiting for the next interval probe.
+ */
+export declare function enforceRetention(): void;
 export declare function getAuditFilePath(): string;
 export declare function readAudit(): AuditEntry[];
 /** Pull the last user message from a Dialogue history, flatten, and strip newlines. */

package/dist/stats/audit.js

@@ -13,6 +13,18 @@ import path from 'node:path';
 import { BLOCKRUN_DIR } from '../config.js';
 const AUDIT_FILE = path.join(BLOCKRUN_DIR, 'franklin-audit.jsonl');
 const PROMPT_PREVIEW_CHARS = 240;
+// Cap the audit log at the most recent N entries. Without this the file
+// grew unbounded — verified ~3.6k lines on a single dev machine after a
+// few weeks of light use, so a months-old install would be in the GB
+// range and slow `franklin insights` to a crawl.
+const MAX_AUDIT_ENTRIES = 10_000;
+// Each entry is roughly 300–800 bytes. We only re-read the file when it
+// looks plausibly over the cap, so we don't pay an O(n) scan on every
+// append. 200 bytes/entry is a conservative lower bound.
+const TRIM_PROBE_BYTES = MAX_AUDIT_ENTRIES * 200;
+// Probe size every N appends — amortizes the stat() call.
+const TRIM_CHECK_INTERVAL = 200;
+let appendsSinceCheck = 0;
 export function appendAudit(entry) {
     try {
         fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
@@ -21,11 +33,39 @@ export function appendAudit(entry) {
             prompt: entry.prompt ? truncate(entry.prompt, PROMPT_PREVIEW_CHARS) : undefined,
         };
         fs.appendFileSync(AUDIT_FILE, JSON.stringify(safe) + '\n');
+        appendsSinceCheck++;
+        if (appendsSinceCheck >= TRIM_CHECK_INTERVAL) {
+            appendsSinceCheck = 0;
+            enforceRetention();
+        }
     }
     catch {
         /* best-effort — never break the agent loop on audit-write failure */
     }
 }
+/**
+ * Trim the audit log to the last MAX_AUDIT_ENTRIES lines if it has grown
+ * past the cap. Exported so admin/debug tooling (and tests) can force a
+ * compaction without waiting for the next interval probe.
+ */
+export function enforceRetention() {
+    try {
+        if (!fs.existsSync(AUDIT_FILE))
+            return;
+        const stat = fs.statSync(AUDIT_FILE);
+        if (stat.size < TRIM_PROBE_BYTES)
+            return;
+        const content = fs.readFileSync(AUDIT_FILE, 'utf-8');
+        const lines = content.split('\n').filter(Boolean);
+        if (lines.length <= MAX_AUDIT_ENTRIES)
+            return;
+        const kept = lines.slice(lines.length - MAX_AUDIT_ENTRIES);
+        fs.writeFileSync(AUDIT_FILE, kept.join('\n') + '\n');
+    }
+    catch {
+        /* best-effort */
+    }
+}
 export function getAuditFilePath() {
     return AUDIT_FILE;
 }

package/dist/stats/insights.d.ts

@@ -49,6 +49,25 @@ export interface InsightsReport {
     avgRequestCostUsd: number;
     /** Efficiency: cost per 1K tokens */
     costPer1KTokens: number;
+    /**
+     * Cost breakdown by capability category. Lets the UI show a clean
+     * "where did your USDC go" split alongside the per-model bar list.
+     *   - chat:    LLM token-billed calls (anything with non-zero tokens)
+     *   - media:   ImageGen / VideoGen / MusicGen (per_image / per_second / per_track)
+     *   - sandbox: Modal GPU sandbox lifecycle (create / exec / status / terminate)
+     *
+     * Categorization is by `model` name prefix:
+     *   - `modal/*`              → sandbox
+     *   - rows with 0 input + 0 output tokens → media (image/video/music are
+     *     stored with 0 tokens by recordUsage; modal/* matches first)
+     *   - everything else        → chat
+     */
+    byCategory: {
+        chatCostUsd: number;
+        mediaCostUsd: number;
+        sandboxCostUsd: number;
+        sandboxRequests: number;
+    };
 }
 export declare function generateInsights(days?: number): InsightsReport;
 export declare function formatInsights(report: InsightsReport, days: number): string;

package/dist/stats/insights.js

@@ -23,11 +23,28 @@ export function generateInsights(days = 30) {
     let totalCost = 0;
     let totalInput = 0;
     let totalOutput = 0;
+    // Category totals — see InsightsReport.byCategory doc.
+    let chatCost = 0;
+    let mediaCost = 0;
+    let sandboxCost = 0;
+    let sandboxRequests = 0;
     const modelAgg = new Map();
     for (const r of windowHistory) {
         totalCost += r.costUsd;
         totalInput += r.inputTokens;
         totalOutput += r.outputTokens;
+        // Categorize: modal/* always goes to sandbox; zero-token entries are
+        // media (image/video/music recordUsage stores 0/0 tokens); rest = chat.
+        if (r.model.startsWith('modal/')) {
+            sandboxCost += r.costUsd;
+            sandboxRequests++;
+        }
+        else if ((r.inputTokens + r.outputTokens) === 0) {
+            mediaCost += r.costUsd;
+        }
+        else {
+            chatCost += r.costUsd;
+        }
         const existing = modelAgg.get(r.model) ?? {
             requests: 0,
             costUsd: 0,
@@ -101,6 +118,12 @@ export function generateInsights(days = 30) {
         projections,
         avgRequestCostUsd,
         costPer1KTokens,
+        byCategory: {
+            chatCostUsd: chatCost,
+            mediaCostUsd: mediaCost,
+            sandboxCostUsd: sandboxCost,
+            sandboxRequests,
+        },
     };
 }
 // ─── Format for Display ───────────────────────────────────────────────────

package/dist/tools/index.js

@@ -29,6 +29,7 @@ import { jupiterQuoteCapability, jupiterSwapCapability } from './jupiter.js';
 import { base0xQuoteCapability, base0xSwapCapability } from './zerox-base.js';
 import { base0xGaslessSwapCapability } from './zerox-gasless.js';
 import { defiLlamaProtocolsCapability, defiLlamaProtocolCapability, defiLlamaChainsCapability, defiLlamaYieldsCapability, defiLlamaPriceCapability, } from './defillama.js';
+import { modalCapabilities } from './modal.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
 import { RiskEngine } from '../trading/risk.js';
@@ -158,6 +159,11 @@ export const allCapabilities = [
     defiLlamaChainsCapability,
     defiLlamaYieldsCapability,
     defiLlamaPriceCapability,
+    // Modal GPU sandbox tools — registered but hidden by default (not in
+    // CORE_TOOL_NAMES). Agent must `ActivateTool({names:["ModalCreate",...]})`
+    // before they appear in its tool inventory. High-cost ($0.40/H100 create)
+    // operations should not be in the default surface.
+    ...modalCapabilities, // ModalCreate, ModalExec, ModalStatus, ModalTerminate
 ];
 export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, detachCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/modal.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Modal Sandbox capabilities — spin up GPU/CPU compute on Modal Labs via the
+ * BlockRun gateway's x402-paid passthrough at /v1/modal/sandbox/{create, exec,
+ * status, terminate}. See https://modal.com/docs/guide/sandboxes for the
+ * underlying primitives.
+ *
+ * Pricing (per-call, USDC):
+ *   create: $0.01 (CPU) / $0.05 (T4) / $0.08 (L4) / $0.10 (A10G) / $0.20 (A100) / $0.40 (H100)
+ *   exec: $0.001
+ *   status: $0.001
+ *   terminate: $0.001
+ *
+ * Gateway constraints (probed 2026-05-02):
+ *   - image is fixed at python:3.11 — no custom containers yet.
+ *   - command is execve-style (string[]), not a shell string. We accept a
+ *     plain string from the LLM and auto-wrap to ["sh","-c", string].
+ *   - No stdin / env / workdir / streaming on exec — keep commands self-
+ *     contained and idempotent.
+ *   - No upload/download endpoints — files in/out via exec heredoc / curl.
+ *
+ * Lifecycle:
+ *   ModalCreate → returns sandbox_id, charged at GPU tier
+ *   ModalExec   → sync, returns { stdout, stderr, exit_code }
+ *   ModalStatus → check running/terminated
+ *   ModalTerminate → release; called automatically at session end via
+ *                    the SessionSandboxTracker registry.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export interface SandboxRecord {
+    id: string;
+    gpu: string;
+    createdAt: number;
+    timeoutSeconds?: number;
+}
+declare class SessionSandboxTracker {
+    private sandboxes;
+    add(rec: SandboxRecord): void;
+    remove(id: string): void;
+    list(): SandboxRecord[];
+    /** Snapshot then clear — used by the session cleanup hook. */
+    drainIds(): string[];
+}
+export declare const sessionSandboxTracker: SessionSandboxTracker;
+export declare const modalCreateCapability: CapabilityHandler;
+export declare const modalExecCapability: CapabilityHandler;
+export declare const modalStatusCapability: CapabilityHandler;
+export declare const modalTerminateCapability: CapabilityHandler;
+/**
+ * Terminate every sandbox the current session has created. Called from
+ * vscode-session.ts at session end (and the SessionToolGuard cleanup path)
+ * so a missed agent ModalTerminate doesn't leave Modal billing the user
+ * up to the per-sandbox timeout. Best-effort: failures are logged but
+ * don't block session shutdown.
+ */
+export declare function terminateAllSessionSandboxes(opts?: {
+    abortSignal?: AbortSignal;
+}): Promise<{
+    attempted: number;
+    succeeded: number;
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+}>;
+export declare const modalCapabilities: CapabilityHandler[];
+export {};

package/dist/tools/modal.js

@@ -0,0 +1,639 @@
+/**
+ * Modal Sandbox capabilities — spin up GPU/CPU compute on Modal Labs via the
+ * BlockRun gateway's x402-paid passthrough at /v1/modal/sandbox/{create, exec,
+ * status, terminate}. See https://modal.com/docs/guide/sandboxes for the
+ * underlying primitives.
+ *
+ * Pricing (per-call, USDC):
+ *   create: $0.01 (CPU) / $0.05 (T4) / $0.08 (L4) / $0.10 (A10G) / $0.20 (A100) / $0.40 (H100)
+ *   exec: $0.001
+ *   status: $0.001
+ *   terminate: $0.001
+ *
+ * Gateway constraints (probed 2026-05-02):
+ *   - image is fixed at python:3.11 — no custom containers yet.
+ *   - command is execve-style (string[]), not a shell string. We accept a
+ *     plain string from the LLM and auto-wrap to ["sh","-c", string].
+ *   - No stdin / env / workdir / streaming on exec — keep commands self-
+ *     contained and idempotent.
+ *   - No upload/download endpoints — files in/out via exec heredoc / curl.
+ *
+ * Lifecycle:
+ *   ModalCreate → returns sandbox_id, charged at GPU tier
+ *   ModalExec   → sync, returns { stdout, stderr, exit_code }
+ *   ModalStatus → check running/terminated
+ *   ModalTerminate → release; called automatically at session end via
+ *                    the SessionSandboxTracker registry.
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, VERSION } from '../config.js';
+import { walletReservation } from '../wallet/reservation.js';
+import { recordUsage } from '../stats/tracker.js';
+// ─── Pricing table (probed from /.well-known/x402 + 402 responses) ─────────
+const CREATE_PRICE_USD = {
+    cpu: 0.01,
+    T4: 0.05,
+    L4: 0.08,
+    A10G: 0.10,
+    A100: 0.20,
+    H100: 0.40,
+};
+const EXEC_PRICE_USD = 0.001;
+const STATUS_PRICE_USD = 0.001;
+const TERMINATE_PRICE_USD = 0.001;
+const VALID_GPUS = new Set(Object.keys(CREATE_PRICE_USD).filter(g => g !== 'cpu'));
+class SessionSandboxTracker {
+    sandboxes = new Map();
+    add(rec) {
+        this.sandboxes.set(rec.id, rec);
+    }
+    remove(id) {
+        this.sandboxes.delete(id);
+    }
+    list() {
+        return [...this.sandboxes.values()].sort((a, b) => b.createdAt - a.createdAt);
+    }
+    /** Snapshot then clear — used by the session cleanup hook. */
+    drainIds() {
+        const ids = [...this.sandboxes.keys()];
+        this.sandboxes.clear();
+        return ids;
+    }
+}
+export const sessionSandboxTracker = new SessionSandboxTracker();
+// ─── x402 payment signing — same shape as imagegen's helper ───────────────
+async function signPayment(response, chain, endpoint, resourceDescription) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+            const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+            const feePayer = details.extra?.feePayer || details.recipient;
+            const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || resourceDescription,
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        else {
+            const wallet = getOrCreateWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired);
+            const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || resourceDescription,
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+    }
+    catch (err) {
+        console.error(`[franklin] Modal payment error: ${err.message}`);
+        return null;
+    }
+}
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.json());
+            if (body.x402 || body.accepts) {
+                header = btoa(JSON.stringify(body));
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return header;
+}
+/**
+ * Generic POST-with-x402-retry helper used by all four Modal endpoints. The
+ * first POST gets a 402 with payment requirements; we sign and retry once
+ * with the X-PAYMENT header. Returns the parsed JSON body and the raw
+ * Response (callers may need status code).
+ */
+async function postWithPayment(endpoint, body, resourceDescription, abortSignal, timeoutMs) {
+    const chain = loadChain();
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': `franklin/${VERSION}`,
+    };
+    const ctrl = new AbortController();
+    const onParentAbort = () => ctrl.abort();
+    abortSignal.addEventListener('abort', onParentAbort, { once: true });
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const payload = JSON.stringify(body);
+        let response = await fetch(endpoint, { method: 'POST', signal: ctrl.signal, headers, body: payload });
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint, resourceDescription);
+            if (!paymentHeaders) {
+                return { ok: false, status: 402, body: { error: 'payment signing failed' }, raw: '' };
+            }
+            response = await fetch(endpoint, {
+                method: 'POST',
+                signal: ctrl.signal,
+                headers: { ...headers, ...paymentHeaders },
+                body: payload,
+            });
+        }
+        const raw = await response.text().catch(() => '');
+        let parsed = {};
+        try {
+            parsed = raw ? JSON.parse(raw) : {};
+        }
+        catch { /* leave as {} */ }
+        return { ok: response.ok, status: response.status, body: parsed, raw };
+    }
+    finally {
+        clearTimeout(timer);
+        abortSignal.removeEventListener('abort', onParentAbort);
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────
+function modalEndpoint(path) {
+    const chain = loadChain();
+    return `${API_URLS[chain]}/v1/modal/sandbox/${path}`;
+}
+/**
+ * Normalize the agent's `command` input into the execve-style array Modal
+ * expects. LLMs frequently pass a shell string ("pip install torch && python
+ * train.py"); auto-wrap that into ["sh","-c", string] so the agent doesn't
+ * have to know the difference. Arrays are passed through verbatim.
+ */
+function normalizeCommand(input) {
+    if (Array.isArray(input)) {
+        if (input.every(x => typeof x === 'string') && input.length > 0) {
+            return input;
+        }
+        return null;
+    }
+    if (typeof input === 'string' && input.trim().length > 0) {
+        return ['sh', '-c', input];
+    }
+    return null;
+}
+function fmtUsd(n) {
+    if (n < 0.01)
+        return `$${n.toFixed(4)}`;
+    return `$${n.toFixed(2)}`;
+}
+export const modalCreateCapability = {
+    spec: {
+        name: 'ModalCreate',
+        description: 'Create a Modal Python 3.11 sandbox (CPU or GPU) via the BlockRun gateway. ' +
+            'Returns a sandbox_id you pass to ModalExec. Charged once per create at the ' +
+            'GPU tier price: CPU $0.01, T4 $0.05, L4 $0.08, A10G $0.10, A100 $0.20, H100 $0.40. ' +
+            'IMPORTANT — current limitations (BlockRun gateway is in early-access for sandboxes):\n' +
+            '  - sandbox lifetime: 5 minutes MAX (gateway hard-cap, regardless of GPU tier)\n' +
+            '  - per ModalExec call: 60 seconds MAX wall-clock\n' +
+            '  - Python 3.11 only, no custom images yet\n' +
+            '  - 1 vCPU, 1 GiB RAM defaults\n' +
+            '  - GPU access is preview-tier (officially "coming later" in docs)\n' +
+            '  - No setup-time provisioning — every sandbox starts empty\n' +
+            'These limits make this tool suitable for: GPU benchmarks (nvidia-smi, matmul), ' +
+            'small model inference (≤3B params if weights pre-cached), CUDA kernel validation, ' +
+            'short ad-hoc Python tasks. NOT suitable for: full LoRA / fine-tuning runs, ' +
+            'pip install + model download + training (pip alone burns 1-2 min of the 5-min budget). ' +
+            'Custom images + longer lifetime + GPU production tier are documented as "coming later" ' +
+            'by BlockRun — for serious ML workloads tell the user to use Modal directly until then. ' +
+            'Always call ModalTerminate when done. ' +
+            'Long-running command pattern: each ModalExec call is itself capped at 60s wall-clock. ' +
+            'For work that takes >60s (pip install, model download, training), use the ' +
+            'fire-and-poll pattern: ModalExec(["sh","-c","nohup <cmd> > /workspace/log 2>&1 &"]) ' +
+            'returns in <1s, then poll with subsequent ModalExec(["cat","/workspace/log"]) calls.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                gpu: { type: 'string', description: 'GPU tier. One of T4, L4, A10G, A100, H100. Omit for CPU-only ($0.01).' },
+                timeout: { type: 'number', description: 'Lifetime cap in seconds. Default + Max = 300 (5 min). Gateway rejects values > 300 with HTTP 400.' },
+                cpu: { type: 'number', description: 'Number of CPU cores. Default 0.125, max 8.' },
+                memory: { type: 'number', description: 'Memory MB. Default 128, max 32768.' },
+            },
+        },
+    },
+    concurrent: false,
+    async execute(input, ctx) {
+        const raw = input;
+        // ── Client-side coercion ────────────────────────────────────────────
+        // LLMs routinely pass numeric fields as strings ("timeout":"300") and
+        // GPU tier in lowercase ("t4"). The gateway's schema is strict and
+        // 400s on either, leaving the agent confused (it sees "Invalid
+        // request body" with no actionable hint). Fix the obvious mistakes
+        // before they leave the client.
+        let gpu = raw.gpu;
+        if (typeof gpu === 'string') {
+            const matched = [...VALID_GPUS].find(g => g.toLowerCase() === gpu.toLowerCase());
+            if (matched)
+                gpu = matched;
+        }
+        if (gpu && !VALID_GPUS.has(gpu)) {
+            return {
+                output: `Error: invalid gpu "${gpu}". Allowed: ${[...VALID_GPUS].join(', ')} (or omit for CPU).`,
+                isError: true,
+            };
+        }
+        const tier = gpu ?? 'cpu';
+        const price = CREATE_PRICE_USD[tier];
+        // Coerce numeric fields. Reject NaN explicitly so we don't ship
+        // garbage to the gateway.
+        const coerceNum = (v, name) => {
+            if (v === undefined || v === null || v === '')
+                return undefined;
+            const n = typeof v === 'string' ? Number(v) : v;
+            if (typeof n !== 'number' || !Number.isFinite(n)) {
+                return { error: `${name} must be a number, got ${typeof v}: ${JSON.stringify(v)}` };
+            }
+            return n;
+        };
+        const timeoutCoerced = coerceNum(raw.timeout, 'timeout');
+        const cpuCoerced = coerceNum(raw.cpu, 'cpu');
+        const memoryCoerced = coerceNum(raw.memory, 'memory');
+        for (const c of [timeoutCoerced, cpuCoerced, memoryCoerced]) {
+            if (c && typeof c === 'object' && 'error' in c) {
+                return { output: `Error: ${c.error}`, isError: true };
+            }
+        }
+        // Gateway hard-caps sandbox lifetime at 300s. Cap client-side so we
+        // surface a clear error instead of letting the user pay $0.20 for a
+        // create that 400s on the wire.
+        const CREATE_TIMEOUT_MAX = 300;
+        if (typeof timeoutCoerced === 'number' && timeoutCoerced > CREATE_TIMEOUT_MAX) {
+            return {
+                output: `Error: timeout ${timeoutCoerced}s exceeds gateway max of ${CREATE_TIMEOUT_MAX}s. ` +
+                    `BlockRun caps Modal sandbox lifetime at 5 minutes regardless of GPU tier. ` +
+                    `For longer workloads, the work must be split across multiple sandboxes ` +
+                    `(checkpoint + reload) or you need to ask BlockRun to lift this cap.`,
+                isError: true,
+            };
+        }
+        // ── AskUser cost preview (skipped if env auto-approve or non-UI mode) ──
+        const autoApprove = process.env.FRANKLIN_MEDIA_AUTO_APPROVE_ALL === '1';
+        if (ctx.onAskUser && !autoApprove) {
+            const timeoutSec = raw.timeout ?? 300;
+            const lines = [
+                `Create Modal sandbox?`,
+                ``,
+                `  Tier:        ${tier === 'cpu' ? 'CPU only' : `GPU ${tier}`}`,
+                `  Image:       python:3.11`,
+                `  Timeout:     ${timeoutSec}s (${(timeoutSec / 60).toFixed(1)} min)`,
+                ...(raw.cpu ? [`  CPU cores:   ${raw.cpu}`] : []),
+                ...(raw.memory ? [`  Memory:      ${raw.memory} MB`] : []),
+                ``,
+                `Create cost:   ${fmtUsd(price)} (one-time)`,
+                `Each exec:     ${fmtUsd(EXEC_PRICE_USD)}`,
+                `Terminate:     ${fmtUsd(TERMINATE_PRICE_USD)}`,
+            ];
+            try {
+                const answer = await ctx.onAskUser(lines.join('\n'), ['Approve', 'Cancel']);
+                if (answer !== 'Approve') {
+                    return { output: '## Sandbox creation cancelled\n\nNo USDC was spent.' };
+                }
+            }
+            catch {
+                // askUser failed (UI gone) — fall through and create. Better than
+                // silently aborting in headless contexts.
+            }
+        }
+        // Wallet reservation — block over-spend if other in-flight calls hold balance.
+        let reservation = null;
+        try {
+            reservation = await walletReservation.hold(price);
+            if (!reservation) {
+                return {
+                    output: `Insufficient USDC for ModalCreate (${tier}, ~${fmtUsd(price)}). ` +
+                        `Other in-flight paid calls may be holding your balance — wait or fund the wallet.`,
+                    isError: true,
+                };
+            }
+        }
+        catch { /* fall through, x402 will surface real error */ }
+        try {
+            const body = {};
+            if (gpu)
+                body.gpu = gpu;
+            if (typeof timeoutCoerced === 'number')
+                body.timeout = timeoutCoerced;
+            if (typeof cpuCoerced === 'number')
+                body.cpu = cpuCoerced;
+            if (typeof memoryCoerced === 'number')
+                body.memory = memoryCoerced;
+            const res = await postWithPayment(modalEndpoint('create'), body, 'Franklin Modal sandbox create', ctx.abortSignal, 90_000);
+            if (!res.ok) {
+                const err = res.body.error ? String(res.body.error) : res.raw.slice(0, 300);
+                // Surface the per-field validation issues — usually the
+                // actionable bit ("expected number, received string at path
+                // ['timeout']").
+                const details = Array.isArray(res.body.details)
+                    ? '\nDetails: ' + res.body.details.map((d) => `${d.path?.join('.') ?? '?'}: ${d.message ?? JSON.stringify(d)}`).join('; ')
+                    : '';
+                return {
+                    output: `ModalCreate failed (${res.status}): ${err}${details}`,
+                    isError: true,
+                };
+            }
+            const sandboxId = (typeof res.body.sandbox_id === 'string' && res.body.sandbox_id) ||
+                (typeof res.body.id === 'string' && res.body.id) ||
+                '';
+            if (!sandboxId) {
+                return {
+                    output: `ModalCreate returned no sandbox_id. Raw: ${res.raw.slice(0, 300)}`,
+                    isError: true,
+                };
+            }
+            sessionSandboxTracker.add({
+                id: sandboxId,
+                gpu: tier,
+                createdAt: Date.now(),
+                timeoutSeconds: raw.timeout ?? 300,
+            });
+            // Stats — surface Modal usage in `franklin insights` like other paid tools.
+            try {
+                recordUsage(`modal/${tier}`, 0, 0, price, 0);
+            }
+            catch { /* ignore */ }
+            return {
+                output: `Sandbox created\n` +
+                    `- id: \`${sandboxId}\`\n` +
+                    `- tier: ${tier === 'cpu' ? 'CPU only' : `GPU ${tier}`}\n` +
+                    `- timeout: ${raw.timeout ?? 300}s\n` +
+                    `- charged: ${fmtUsd(price)}\n\n` +
+                    `Next: ModalExec({ sandbox_id: "${sandboxId}", command: ["python","-c","print(1)"] })`,
+            };
+        }
+        finally {
+            walletReservation.release(reservation);
+        }
+    },
+};
+export const modalExecCapability = {
+    spec: {
+        name: 'ModalExec',
+        description: 'Run a command inside a Modal sandbox (must already exist via ModalCreate). ' +
+            '`command` accepts either an execve-style array (e.g. ["python","-c","print(1)"]) ' +
+            'or a shell string (e.g. "pip install torch && python train.py") which is auto-wrapped ' +
+            'as ["sh","-c", <string>]. Returns stdout, stderr, exit_code synchronously. ' +
+            'Each call charges $0.001. The sandbox keeps state across exec calls (filesystem, ' +
+            'installed pip packages, etc) until ModalTerminate. ' +
+            'CRITICAL: timeout is HARD-CAPPED at 60 seconds by the gateway — anything longer ' +
+            'returns HTTP 400. For long-running commands (pip install large packages, model ' +
+            'downloads, training loops), use the fire-and-poll pattern: ' +
+            '  exec1: ["sh","-c","nohup <slow-cmd> > /workspace/log 2>&1 & echo $! > /workspace/pid"] (<1s) ' +
+            '  exec2: ["sh","-c","tail -50 /workspace/log"] (poll progress, <1s) ' +
+            '  exec3: ["sh","-c","kill -0 $(cat /workspace/pid) 2>/dev/null && echo RUN || echo DONE"] (check live) ' +
+            'This decouples actual work duration from the per-exec 60s ceiling, but the sandbox ' +
+            'itself still dies at 300s wall-clock — total useful work fits in ~5 minutes.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                sandbox_id: { type: 'string', description: 'Sandbox id from ModalCreate.' },
+                command: {
+                    description: 'Execve-style array OR shell string. Strings are wrapped as ["sh","-c", string].',
+                },
+                timeout: { type: 'number', description: 'Per-exec timeout in seconds. Default 60, MAX 60 (gateway hard cap). Use fire-and-poll for longer work.' },
+            },
+            required: ['sandbox_id', 'command'],
+        },
+    },
+    concurrent: false,
+    async execute(input, ctx) {
+        const raw = input;
+        if (!raw.sandbox_id)
+            return { output: 'Error: sandbox_id is required', isError: true };
+        const command = normalizeCommand(raw.command);
+        if (!command) {
+            // JSON.stringify(undefined) returns undefined — guard the slice call.
+            const got = raw.command === undefined
+                ? 'undefined (missing)'
+                : JSON.stringify(raw.command);
+            return {
+                output: `Error: invalid command. Expected a non-empty string or string[] of length >= 1. ` +
+                    `Got: ${(got ?? 'undefined').slice(0, 100)}`,
+                isError: true,
+            };
+        }
+        let reservation = null;
+        try {
+            reservation = await walletReservation.hold(EXEC_PRICE_USD);
+            // For micro-cost calls don't hard-block on insufficient — just proceed.
+        }
+        catch { /* ignore */ }
+        try {
+            // Same string-as-number guard as ModalCreate. LLMs love
+            // "timeout":"300".
+            let coercedTimeout;
+            if (raw.timeout !== undefined && raw.timeout !== null && raw.timeout !== '') {
+                const n = typeof raw.timeout === 'string' ? Number(raw.timeout) : raw.timeout;
+                if (typeof n === 'number' && Number.isFinite(n))
+                    coercedTimeout = n;
+            }
+            // Gateway hard-caps exec timeout at 60s. Cap client-side so we
+            // never burn an x402 round-trip on a 400. Default to 60s if
+            // unset since "I want it to actually run" is a more sensible
+            // default than the lib's smaller value.
+            const EXEC_TIMEOUT_MAX = 60;
+            if (coercedTimeout === undefined || coercedTimeout > EXEC_TIMEOUT_MAX) {
+                coercedTimeout = EXEC_TIMEOUT_MAX;
+            }
+            const body = {
+                sandbox_id: raw.sandbox_id,
+                command,
+            };
+            if (coercedTimeout !== undefined)
+                body.timeout = coercedTimeout;
+            const res = await postWithPayment(modalEndpoint('exec'), body, 'Franklin Modal sandbox exec', ctx.abortSignal, Math.max(30_000, ((coercedTimeout ?? 300) + 30) * 1000));
+            if (!res.ok) {
+                // 400 here usually means the agent built the wrong shape (bad
+                // sandbox_id, malformed command). Dump the full raw body so the
+                // agent can see exactly what the gateway complained about and
+                // self-correct on the next turn instead of looping blind.
+                const err = res.body.error ? String(res.body.error) : '(no error field)';
+                const details = res.body.details ? `\nDetails: ${JSON.stringify(res.body.details)}` : '';
+                const raw = res.raw.length > 500 ? res.raw.slice(0, 500) + '…' : res.raw;
+                return {
+                    output: `ModalExec failed (${res.status}): ${err}${details}\n` +
+                        `Raw response: ${raw}\n` +
+                        `Sent: command=${JSON.stringify(command).slice(0, 200)}`,
+                    isError: true,
+                };
+            }
+            const stdout = typeof res.body.stdout === 'string' ? res.body.stdout : '';
+            const stderr = typeof res.body.stderr === 'string' ? res.body.stderr : '';
+            // Gateway field shape isn't 100% pinned — accept exit_code, exitCode,
+            // returncode, code (in priority order). If NONE of them are present
+            // but stdout/stderr came back, treat as success (exit 0) rather than
+            // poisoning the failure counter on a healthy run with an unfamiliar
+            // response shape.
+            const rawExit = typeof res.body.exit_code === 'number' ? res.body.exit_code :
+                typeof res.body.exitCode === 'number' ? res.body.exitCode :
+                    typeof res.body.returncode === 'number' ? res.body.returncode :
+                        typeof res.body.code === 'number' ? res.body.code :
+                            null;
+            const hasAnyOutput = stdout.length > 0 || stderr.length > 0;
+            const exitCode = rawExit !== null ? rawExit : (hasAnyOutput ? 0 : -1);
+            try {
+                recordUsage('modal/exec', 0, 0, EXEC_PRICE_USD, 0);
+            }
+            catch { /* ignore */ }
+            const summary = `exit ${exitCode}` + (rawExit === null ? ' (inferred — no exit_code field in response)' : '');
+            const sections = [
+                `\`${command.join(' ')}\` → ${summary}`,
+            ];
+            if (stdout)
+                sections.push(`--- stdout ---\n${stdout}`);
+            if (stderr)
+                sections.push(`--- stderr ---\n${stderr}`);
+            // Only mark as error when we have a real non-zero exit code OR
+            // we have nothing at all (no stdout / stderr / exit_code) which
+            // suggests an actual problem rather than a parsing edge case.
+            const isError = rawExit !== null ? rawExit !== 0 : !hasAnyOutput;
+            return { output: sections.join('\n\n'), isError };
+        }
+        finally {
+            walletReservation.release(reservation);
+        }
+    },
+};
+// ─── ModalStatus ─────────────────────────────────────────────────────────
+export const modalStatusCapability = {
+    spec: {
+        name: 'ModalStatus',
+        description: 'Check the status of a Modal sandbox (running / terminated). Charges $0.001. ' +
+            'Useful when you suspect a sandbox died or you want to confirm a previous ' +
+            'ModalTerminate succeeded.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                sandbox_id: { type: 'string' },
+            },
+            required: ['sandbox_id'],
+        },
+    },
+    concurrent: false,
+    async execute(input, ctx) {
+        const sandbox_id = input.sandbox_id;
+        if (!sandbox_id)
+            return { output: 'Error: sandbox_id is required', isError: true };
+        let reservation = null;
+        try {
+            reservation = await walletReservation.hold(STATUS_PRICE_USD);
+        }
+        catch { /* ignore */ }
+        try {
+            const res = await postWithPayment(modalEndpoint('status'), { sandbox_id }, 'Franklin Modal sandbox status', ctx.abortSignal, 30_000);
+            if (!res.ok) {
+                const err = res.body.error ? String(res.body.error) : res.raw.slice(0, 300);
+                return { output: `ModalStatus failed (${res.status}): ${err}`, isError: true };
+            }
+            try {
+                recordUsage('modal/status', 0, 0, STATUS_PRICE_USD, 0);
+            }
+            catch { /* ignore */ }
+            const status = res.body.status || 'unknown';
+            const extra = JSON.stringify(res.body, null, 2);
+            return { output: `Sandbox \`${sandbox_id}\` status: **${status}**\n\n${extra}` };
+        }
+        finally {
+            walletReservation.release(reservation);
+        }
+    },
+};
+// ─── ModalTerminate ──────────────────────────────────────────────────────
+export const modalTerminateCapability = {
+    spec: {
+        name: 'ModalTerminate',
+        description: 'Terminate a Modal sandbox and release its resources. Charges $0.001. ' +
+            'Strongly recommended after every successful ModalExec sequence — ' +
+            'Modal bills wall-clock GPU time until the sandbox terminates or hits ' +
+            'its `timeout`. Session-end auto-cleanup also calls this for any sandboxes ' +
+            'the agent forgot, but explicit is better.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                sandbox_id: { type: 'string' },
+            },
+            required: ['sandbox_id'],
+        },
+    },
+    concurrent: false,
+    async execute(input, ctx) {
+        const sandbox_id = input.sandbox_id;
+        if (!sandbox_id)
+            return { output: 'Error: sandbox_id is required', isError: true };
+        let reservation = null;
+        try {
+            reservation = await walletReservation.hold(TERMINATE_PRICE_USD);
+        }
+        catch { /* ignore */ }
+        try {
+            const res = await postWithPayment(modalEndpoint('terminate'), { sandbox_id }, 'Franklin Modal sandbox terminate', ctx.abortSignal, 30_000);
+            // Always remove from tracker — even on failure, retrying is wasteful.
+            sessionSandboxTracker.remove(sandbox_id);
+            if (!res.ok) {
+                const err = res.body.error ? String(res.body.error) : res.raw.slice(0, 300);
+                return {
+                    output: `ModalTerminate returned ${res.status}: ${err}\n\n` +
+                        `(Removed from local tracker regardless. Modal-side cleanup will happen at the timeout.)`,
+                    isError: res.status >= 500, // 4xx (e.g. already-terminated) is benign
+                };
+            }
+            try {
+                recordUsage('modal/terminate', 0, 0, TERMINATE_PRICE_USD, 0);
+            }
+            catch { /* ignore */ }
+            return { output: `Sandbox \`${sandbox_id}\` terminated.` };
+        }
+        finally {
+            walletReservation.release(reservation);
+        }
+    },
+};
+// ─── Bulk session cleanup ────────────────────────────────────────────────
+/**
+ * Terminate every sandbox the current session has created. Called from
+ * vscode-session.ts at session end (and the SessionToolGuard cleanup path)
+ * so a missed agent ModalTerminate doesn't leave Modal billing the user
+ * up to the per-sandbox timeout. Best-effort: failures are logged but
+ * don't block session shutdown.
+ */
+export async function terminateAllSessionSandboxes(opts = {}) {
+    const ids = sessionSandboxTracker.drainIds();
+    const failed = [];
+    let succeeded = 0;
+    const ctrl = new AbortController();
+    if (opts.abortSignal) {
+        if (opts.abortSignal.aborted)
+            ctrl.abort();
+        else
+            opts.abortSignal.addEventListener('abort', () => ctrl.abort(), { once: true });
+    }
+    // Sequential — terminating a few sandboxes in parallel offers no real
+    // win over serial, and serial keeps the wallet-reservation accounting
+    // simple.
+    for (const id of ids) {
+        try {
+            const res = await postWithPayment(modalEndpoint('terminate'), { sandbox_id: id }, 'Franklin Modal sandbox cleanup', ctrl.signal, 20_000);
+            if (res.ok)
+                succeeded++;
+            else
+                failed.push({ id, error: String(res.body.error ?? res.raw.slice(0, 200)) });
+        }
+        catch (err) {
+            failed.push({ id, error: err.message });
+        }
+    }
+    return { attempted: ids.length, succeeded, failed };
+}
+// ─── All-in-one export for index.ts registration ─────────────────────────
+export const modalCapabilities = [
+    modalCreateCapability,
+    modalExecCapability,
+    modalStatusCapability,
+    modalTerminateCapability,
+];

package/dist/wallet/reservation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * WalletReservation — local accounting layer for concurrent paid tool calls.
+ *
+ * Problem this solves: when N batch tools (ImageGen / VideoGen) run in
+ * parallel, each independently checks balance and dispatches its x402
+ * payment. With balance $0.20 and 6 calls × $0.04 each, all 6 see "$0.20
+ * available, $0.04 fits" and start; only 5 can actually settle on-chain,
+ * the rest fail mid-flight with insufficient-funds and the user sees
+ * partial completion with no preflight warning.
+ *
+ * The fix is *not* on-chain — x402 is fire-and-forget per-request, there's
+ * no real "hold" capability. Instead this is a per-process bookkeeping
+ * layer:
+ *   1. Tool calls hold(amount) before paying.
+ *   2. hold() refuses if (balance - sum(active reservations)) < amount.
+ *   3. After payment succeeds OR fails, tool calls release(token).
+ *
+ * Single-process JS guarantees the check-and-set is atomic (no real race),
+ * and balance is cached briefly so we don't hit the RPC for every hold.
+ */
+export interface ReservationToken {
+    id: string;
+    amountUsd: number;
+}
+declare class WalletReservationManager {
+    private reserved;
+    private cachedBalance;
+    private balanceFetchInflight;
+    private fetchBalance;
+    private totalReserved;
+    /**
+     * Try to reserve `amountUsd`. Returns a token on success, or null if
+     * insufficient (balance - already-reserved < amountUsd). Caller MUST
+     * release the token after the actual payment resolves, success or fail.
+     */
+    hold(amountUsd: number): Promise<ReservationToken | null>;
+    /**
+     * Release a hold. Idempotent — releasing the same token twice is a no-op.
+     * Invalidate the balance cache so the next hold sees up-to-date state.
+     */
+    release(token: ReservationToken | string | null | undefined): void;
+    /** Force the next hold() to refetch balance from chain. */
+    invalidateBalance(): void;
+    /** Snapshot of current reservation state — diagnostic / testing only. */
+    snapshot(): {
+        count: number;
+        totalUsd: number;
+    };
+}
+export declare const walletReservation: WalletReservationManager;
+export {};

package/dist/wallet/reservation.js

@@ -0,0 +1,105 @@
+/**
+ * WalletReservation — local accounting layer for concurrent paid tool calls.
+ *
+ * Problem this solves: when N batch tools (ImageGen / VideoGen) run in
+ * parallel, each independently checks balance and dispatches its x402
+ * payment. With balance $0.20 and 6 calls × $0.04 each, all 6 see "$0.20
+ * available, $0.04 fits" and start; only 5 can actually settle on-chain,
+ * the rest fail mid-flight with insufficient-funds and the user sees
+ * partial completion with no preflight warning.
+ *
+ * The fix is *not* on-chain — x402 is fire-and-forget per-request, there's
+ * no real "hold" capability. Instead this is a per-process bookkeeping
+ * layer:
+ *   1. Tool calls hold(amount) before paying.
+ *   2. hold() refuses if (balance - sum(active reservations)) < amount.
+ *   3. After payment succeeds OR fails, tool calls release(token).
+ *
+ * Single-process JS guarantees the check-and-set is atomic (no real race),
+ * and balance is cached briefly so we don't hit the RPC for every hold.
+ */
+import { setupAgentWallet, setupAgentSolanaWallet } from '@blockrun/llm';
+import { loadChain } from '../config.js';
+const BALANCE_CACHE_MS = 5_000;
+class WalletReservationManager {
+    reserved = new Map();
+    cachedBalance = null;
+    balanceFetchInflight = null;
+    async fetchBalance() {
+        if (this.cachedBalance && Date.now() - this.cachedBalance.fetchedAt < BALANCE_CACHE_MS) {
+            return this.cachedBalance.value;
+        }
+        if (this.balanceFetchInflight)
+            return this.balanceFetchInflight;
+        const chain = loadChain();
+        this.balanceFetchInflight = (async () => {
+            try {
+                if (chain === 'solana') {
+                    const client = await setupAgentSolanaWallet({ silent: true });
+                    return await client.getBalance();
+                }
+                const client = setupAgentWallet({ silent: true });
+                return await client.getBalance();
+            }
+            catch {
+                // If balance fetch fails, return Infinity so reservations don't
+                // block — the actual payment will surface the real error. We'd
+                // rather under-protect than block all paid tools on RPC flakiness.
+                return Number.POSITIVE_INFINITY;
+            }
+        })()
+            .then((v) => {
+            this.cachedBalance = { value: v, fetchedAt: Date.now() };
+            this.balanceFetchInflight = null;
+            return v;
+        });
+        return this.balanceFetchInflight;
+    }
+    totalReserved() {
+        let sum = 0;
+        for (const v of this.reserved.values())
+            sum += v;
+        return sum;
+    }
+    /**
+     * Try to reserve `amountUsd`. Returns a token on success, or null if
+     * insufficient (balance - already-reserved < amountUsd). Caller MUST
+     * release the token after the actual payment resolves, success or fail.
+     */
+    async hold(amountUsd) {
+        if (amountUsd <= 0) {
+            // Free / zero-cost calls don't need accounting.
+            return { id: `free-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`, amountUsd: 0 };
+        }
+        const balance = await this.fetchBalance();
+        const available = balance - this.totalReserved();
+        if (available < amountUsd)
+            return null;
+        const id = `res-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.reserved.set(id, amountUsd);
+        return { id, amountUsd };
+    }
+    /**
+     * Release a hold. Idempotent — releasing the same token twice is a no-op.
+     * Invalidate the balance cache so the next hold sees up-to-date state.
+     */
+    release(token) {
+        if (!token)
+            return;
+        const id = typeof token === 'string' ? token : token.id;
+        if (this.reserved.delete(id)) {
+            // A real payment may have just settled on-chain; force re-fetch
+            // next time so subsequent holds see the post-payment balance.
+            this.cachedBalance = null;
+        }
+    }
+    /** Force the next hold() to refetch balance from chain. */
+    invalidateBalance() {
+        this.cachedBalance = null;
+    }
+    /** Snapshot of current reservation state — diagnostic / testing only. */
+    snapshot() {
+        return { count: this.reserved.size, totalUsd: this.totalReserved() };
+    }
+}
+export const walletReservation = new WalletReservationManager();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.15.10",
+  "version": "3.15.11",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {