@blockrun/franklin 3.15.9 → 3.15.11

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 {};