@blockrun/franklin 3.15.14 → 3.15.15

package/dist/agent/loop.js

@@ -21,6 +21,7 @@ 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 { runDataHygiene } from '../storage/hygiene.js';
 import { estimateCost, OPUS_PRICING } from '../pricing.js';
 import { maybeMidSessionExtract } from '../learnings/extractor.js';
 import { extractMentions, buildEntityContext, loadEntities } from '../brain/store.js';
@@ -437,6 +438,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         persistSessionMeta();
     };
     pruneOldSessions(sessionId); // Cleanup old sessions on start, protect current
+    runDataHygiene(); // Trim ~/.blockrun/data + cost_log + remove legacy files
     persistSessionMeta();
     // Flush session meta on SIGINT/SIGTERM so mid-stream Ctrl+C doesn't
     // leave a stale .meta.json (wrong turnCount/messageCount/cost).

package/dist/session/storage.js

@@ -233,4 +233,40 @@ export function pruneOldSessions(activeSessionId) {
             catch { /* ok */ }
         }
     }
+    // Sweep orphan jsonl files (left over from a session-id format change in
+    // earlier releases — meta deleted, jsonl stranded). The pre-3.x naming
+    // didn't include the random suffix, so the meta-driven prune above has
+    // no record of them and they accumulate forever. Verified on a real
+    // user machine: 21 metas, 121 jsonl, 100 orphans = ~1 MB stranded.
+    pruneOrphanJsonlFiles(activeSessionId);
+}
+function pruneOrphanJsonlFiles(activeSessionId) {
+    const dir = getSessionsDir();
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return; // Sessions dir doesn't exist yet — nothing to prune.
+    }
+    const knownIds = new Set();
+    for (const f of entries) {
+        if (f.endsWith('.meta.json')) {
+            knownIds.add(f.slice(0, -'.meta.json'.length));
+        }
+    }
+    for (const f of entries) {
+        if (!f.endsWith('.jsonl'))
+            continue;
+        const id = f.slice(0, -'.jsonl'.length);
+        if (id === activeSessionId)
+            continue;
+        if (knownIds.has(id))
+            continue;
+        // No meta partner — orphan. Delete the jsonl.
+        try {
+            fs.unlinkSync(path.join(dir, f));
+        }
+        catch { /* ok */ }
+    }
 }

package/dist/storage/hygiene.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Data hygiene for ~/.blockrun/.
+ *
+ * Several files in this directory are written by the @blockrun/llm SDK or
+ * by older Franklin versions that didn't ship retention. Without periodic
+ * trimming they grow unbounded:
+ *
+ *   - ~/.blockrun/data/         — every paid API call gets a JSON blob
+ *                                 dropped here for forensic replay. SDK
+ *                                 has no rotation; verified 5.7 MB across
+ *                                 ~2 months of light use, will be 30 MB
+ *                                 by year-end and slow `franklin insights`.
+ *   - ~/.blockrun/cost_log.jsonl — append-only ledger of every paid call's
+ *                                 cost. Same SDK; no rotation.
+ *   - brcc-debug.log / brcc-stats.json / 0xcode-stats.json
+ *                               — legacy stats / log files from earlier
+ *                                 product names. Not written by any
+ *                                 current code path.
+ *
+ * Hygiene runs once per session start (cheap — just stat() + filter +
+ * unlinkSync). Best-effort: every operation is wrapped so a single failure
+ * never breaks agent boot.
+ */
+/**
+ * Top-level entry. Call once at agent session start. Catches its own
+ * errors so a bad disk never blocks startup.
+ */
+export declare function runDataHygiene(): void;

package/dist/storage/hygiene.js

@@ -0,0 +1,134 @@
+/**
+ * Data hygiene for ~/.blockrun/.
+ *
+ * Several files in this directory are written by the @blockrun/llm SDK or
+ * by older Franklin versions that didn't ship retention. Without periodic
+ * trimming they grow unbounded:
+ *
+ *   - ~/.blockrun/data/         — every paid API call gets a JSON blob
+ *                                 dropped here for forensic replay. SDK
+ *                                 has no rotation; verified 5.7 MB across
+ *                                 ~2 months of light use, will be 30 MB
+ *                                 by year-end and slow `franklin insights`.
+ *   - ~/.blockrun/cost_log.jsonl — append-only ledger of every paid call's
+ *                                 cost. Same SDK; no rotation.
+ *   - brcc-debug.log / brcc-stats.json / 0xcode-stats.json
+ *                               — legacy stats / log files from earlier
+ *                                 product names. Not written by any
+ *                                 current code path.
+ *
+ * Hygiene runs once per session start (cheap — just stat() + filter +
+ * unlinkSync). Best-effort: every operation is wrapped so a single failure
+ * never breaks agent boot.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR } from '../config.js';
+// Retention knobs. Tuned conservatively — a power user with 50+ calls/day
+// for 30 days still fits in DATA_DIR_MAX_FILES, and 5000 cost-log entries
+// covers months of normal use without truncating the running totals.
+const DATA_DIR_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const DATA_DIR_MAX_FILES = 2000;
+const COST_LOG_MAX_ENTRIES = 5000;
+// Cost log entries are tiny (~60 bytes — ts, endpoint, cost only). 40 bytes
+// per entry keeps the probe under the real average so a slightly-overlong
+// file always triggers the rescan rather than silently growing past cap.
+const COST_LOG_PROBE_BYTES = COST_LOG_MAX_ENTRIES * 40;
+// Legacy file names from earlier product iterations. All live directly in
+// BLOCKRUN_DIR (only Franklin writes here, so these are safe to remove).
+// `runcode-debug.log` is also handled by logs.ts's migration path; we
+// delete the residual after migration in case it lingered.
+const LEGACY_FILENAMES = [
+    'brcc-debug.log',
+    'brcc-stats.json',
+    '0xcode-stats.json',
+    'runcode-debug.log',
+];
+/**
+ * Top-level entry. Call once at agent session start. Catches its own
+ * errors so a bad disk never blocks startup.
+ */
+export function runDataHygiene() {
+    try {
+        trimDataDir();
+    }
+    catch { /* best effort */ }
+    try {
+        trimCostLog();
+    }
+    catch { /* best effort */ }
+    try {
+        removeLegacyFiles();
+    }
+    catch { /* best effort */ }
+}
+function trimDataDir() {
+    const dir = path.join(BLOCKRUN_DIR, 'data');
+    if (!fs.existsSync(dir))
+        return;
+    const entries = fs.readdirSync(dir);
+    if (entries.length === 0)
+        return;
+    const cutoff = Date.now() - DATA_DIR_MAX_AGE_MS;
+    const stats = [];
+    for (const name of entries) {
+        try {
+            const st = fs.statSync(path.join(dir, name));
+            if (!st.isFile())
+                continue;
+            stats.push({ name, mtime: st.mtimeMs });
+        }
+        catch {
+            // Best effort — skip unreadable entries.
+        }
+    }
+    // Pass 1: age-based delete.
+    for (const e of stats) {
+        if (e.mtime < cutoff) {
+            try {
+                fs.unlinkSync(path.join(dir, e.name));
+            }
+            catch { /* ok */ }
+        }
+    }
+    // Pass 2: file-count cap. After age trim, if we still have too many,
+    // drop the oldest until we're under the cap. Power users can hit this
+    // when running multiple paid tools in tight loops.
+    const survivors = stats
+        .filter(e => e.mtime >= cutoff)
+        .sort((a, b) => a.mtime - b.mtime); // oldest first
+    const excess = survivors.length - DATA_DIR_MAX_FILES;
+    if (excess > 0) {
+        for (let i = 0; i < excess; i++) {
+            try {
+                fs.unlinkSync(path.join(dir, survivors[i].name));
+            }
+            catch { /* ok */ }
+        }
+    }
+}
+function trimCostLog() {
+    const file = path.join(BLOCKRUN_DIR, 'cost_log.jsonl');
+    if (!fs.existsSync(file))
+        return;
+    // Cheap probe — skip the full read+rewrite when the file is small.
+    const stat = fs.statSync(file);
+    if (stat.size < COST_LOG_PROBE_BYTES)
+        return;
+    const lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
+    if (lines.length <= COST_LOG_MAX_ENTRIES)
+        return;
+    const kept = lines.slice(lines.length - COST_LOG_MAX_ENTRIES);
+    fs.writeFileSync(file, kept.join('\n') + '\n');
+}
+function removeLegacyFiles() {
+    for (const name of LEGACY_FILENAMES) {
+        const p = path.join(BLOCKRUN_DIR, name);
+        if (!fs.existsSync(p))
+            continue;
+        try {
+            fs.unlinkSync(p);
+        }
+        catch { /* ok */ }
+    }
+}

package/package.json

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