@blockrun/franklin 3.15.14 → 3.15.16

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).
@@ -1199,6 +1201,11 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 inputTokens,
                 outputTokens: usage.outputTokens,
                 costUsd: costEstimate,
+                // Any failed model this turn means the model that finally
+                // succeeded was a fallback. Without this, audit log read 0%
+                // fallbacks across 4k entries — useless for diagnosing whether
+                // the routing chain is healthy or hot.
+                fallback: turnFailedModels.size > 0,
                 source: 'agent',
                 workDir,
                 prompt: extractLastUserPrompt(history),

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/stats/audit.js

@@ -11,6 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { BLOCKRUN_DIR } from '../config.js';
+import { isTestFixtureModel } from './test-fixture.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
@@ -26,6 +27,12 @@ const TRIM_PROBE_BYTES = MAX_AUDIT_ENTRIES * 200;
 const TRIM_CHECK_INTERVAL = 200;
 let appendsSinceCheck = 0;
 export function appendAudit(entry) {
+    // Tests run interactiveSession() in-process with model="local/test*"
+    // and would otherwise pollute the user's real audit log. Drop the
+    // entry before any disk write rather than relying on every test to
+    // remember to redirect HOME.
+    if (isTestFixtureModel(entry.model))
+        return;
     try {
         fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
         const safe = {

package/dist/stats/test-fixture.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Test-fixture model detection.
+ *
+ * Tests in `test/local.mjs` run `interactiveSession()` in-process with
+ * model names like `local/test-model` and `local/test`. The agent loop
+ * persists every successful turn to `~/.blockrun/franklin-audit.jsonl`,
+ * `franklin-stats.json`, and the session store — which means tests
+ * pollute the user's real telemetry. Verified on a real machine:
+ * 2326 of 3969 audit entries (58.6%) and 84 of 1000 stats entries
+ * (8.4%) were `local/test*` test fixtures.
+ *
+ * The fix is to skip persistence when the model name follows the
+ * convention. Test prefixes are reserved (`local/test*` won't ever ship
+ * as a real model on the BlockRun gateway), so this is safe.
+ *
+ * Local LLMs that real users run (`local/llamafile`, `local/ollama`,
+ * `local/lmstudio`, etc.) are intentionally NOT filtered — only the
+ * `local/test` prefix.
+ */
+export declare function isTestFixtureModel(model: string | undefined | null): boolean;

package/dist/stats/test-fixture.js

@@ -0,0 +1,31 @@
+/**
+ * Test-fixture model detection.
+ *
+ * Tests in `test/local.mjs` run `interactiveSession()` in-process with
+ * model names like `local/test-model` and `local/test`. The agent loop
+ * persists every successful turn to `~/.blockrun/franklin-audit.jsonl`,
+ * `franklin-stats.json`, and the session store — which means tests
+ * pollute the user's real telemetry. Verified on a real machine:
+ * 2326 of 3969 audit entries (58.6%) and 84 of 1000 stats entries
+ * (8.4%) were `local/test*` test fixtures.
+ *
+ * The fix is to skip persistence when the model name follows the
+ * convention. Test prefixes are reserved (`local/test*` won't ever ship
+ * as a real model on the BlockRun gateway), so this is safe.
+ *
+ * Local LLMs that real users run (`local/llamafile`, `local/ollama`,
+ * `local/lmstudio`, etc.) are intentionally NOT filtered — only the
+ * `local/test` prefix.
+ */
+const TEST_FIXTURE_PREFIXES = [
+    'local/test',
+];
+export function isTestFixtureModel(model) {
+    if (!model)
+        return false;
+    for (const prefix of TEST_FIXTURE_PREFIXES) {
+        if (model.startsWith(prefix))
+            return true;
+    }
+    return false;
+}

package/dist/stats/tracker.js

@@ -7,6 +7,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { OPUS_PRICING } from '../pricing.js';
 import { BLOCKRUN_DIR } from '../config.js';
+import { isTestFixtureModel } from './test-fixture.js';
 let resolvedStatsFile = null;
 function preferredStatsFile() {
     return path.join(BLOCKRUN_DIR, 'franklin-stats.json');
@@ -156,6 +157,12 @@ export function flushStats() {
  * Record a completed request for stats tracking
  */
 export function recordUsage(model, inputTokens, outputTokens, costUsd, latencyMs, fallback = false) {
+    // Same rationale as appendAudit — tests run in-process with
+    // local/test* models and would otherwise mix into franklin-stats.json
+    // history (verified: 8.4% of a real user's 1000-entry history was
+    // test fixtures before this gate).
+    if (isTestFixtureModel(model))
+        return;
     const stats = getCachedStats();
     const now = Date.now();
     // Update totals

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.16",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {