@blockrun/franklin 3.15.15 → 3.15.17

package/dist/agent/loop.js

@@ -22,6 +22,8 @@ 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 { isTestFixtureModel } from '../stats/test-fixture.js';
+import { setSessionPersistenceDisabled } from '../session/storage.js';
 import { estimateCost, OPUS_PRICING } from '../pricing.js';
 import { maybeMidSessionExtract } from '../learnings/extractor.js';
 import { extractMentions, buildEntityContext, loadEntities } from '../brain/store.js';
@@ -330,6 +332,14 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
     // 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);
+    // In-process tests run interactiveSession() with model="local/test*"
+    // and were creating real session files on the user's machine —
+    // verified 19 of 33 metas (57.6%) were polluted on a real install.
+    // Gate session persistence at the entry point so the rest of the
+    // loop doesn't have to thread the flag through. Tests that genuinely
+    // exercise the persistence path use a non-fixture model name like
+    // `zai/glm-5.1` (mock-server-backed) so they keep writing.
+    setSessionPersistenceDisabled(isTestFixtureModel(config.model));
     const client = new ModelClient({
         apiUrl: config.apiUrl,
         chain: config.chain,
@@ -1201,6 +1211,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/router/local-elo.js

@@ -8,6 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { BLOCKRUN_DIR } from '../config.js';
+import { isTestFixtureModel } from '../stats/test-fixture.js';
 const HISTORY_FILE = path.join(BLOCKRUN_DIR, 'router-history.jsonl');
 const MAX_RECORDS = 2000;
 const K_FACTOR = 32; // Elo K-factor — how much each outcome shifts the rating
@@ -15,6 +16,13 @@ const K_FACTOR = 32; // Elo K-factor — how much each outcome shifts the rating
  * Record a model outcome for local learning.
  */
 export function recordOutcome(category, model, outcome, toolCalls) {
+    // Defensive: same fixture-model gate as appendAudit / recordUsage.
+    // router-history.jsonl is currently clean (test runs typically have
+    // an empty `lastRoutedCategory` and the agent loop already guards
+    // against that), but a future change to category detection would
+    // immediately leak. Belt-and-braces.
+    if (isTestFixtureModel(model))
+        return;
     try {
         fs.mkdirSync(path.dirname(HISTORY_FILE), { recursive: true });
         const record = { ts: Date.now(), category, model, outcome, toolCalls };

package/dist/session/storage.d.ts

@@ -3,6 +3,8 @@
  * Saves conversation history as JSONL for resume capability.
  */
 import type { Dialogue } from '../agent/types.js';
+export declare function setSessionPersistenceDisabled(disabled: boolean): void;
+export declare function isSessionPersistenceDisabled(): boolean;
 export interface SessionMeta {
     id: string;
     model: string;

package/dist/session/storage.js

@@ -9,6 +9,20 @@ import { randomUUID } from 'node:crypto';
 import { BLOCKRUN_DIR } from '../config.js';
 const MAX_SESSIONS = 20; // Keep last 20 sessions
 let resolvedSessionsDir = null;
+// When in-process tests run interactiveSession() with model="local/test*",
+// session writes were creating real .jsonl + .meta.json files in the
+// user's ~/.blockrun/sessions/ — verified 19 of 33 metas (57.6%) on a
+// real machine. Toggled at session start by the agent loop based on the
+// model name; defaults to enabled so production never accidentally goes
+// silent. No-op writes when disabled — reads still work so resume tests
+// can pre-seed state with their own writes if they want to.
+let persistenceDisabled = false;
+export function setSessionPersistenceDisabled(disabled) {
+    persistenceDisabled = disabled;
+}
+export function isSessionPersistenceDisabled() {
+    return persistenceDisabled;
+}
 function getSessionsDir() {
     if (resolvedSessionsDir)
         return resolvedSessionsDir;
@@ -69,6 +83,8 @@ export function createSessionId() {
  * Save a message to the session transcript (append-only JSONL).
  */
 export function appendToSession(sessionId, message) {
+    if (persistenceDisabled)
+        return;
     const line = JSON.stringify(message) + '\n';
     withWritableSessionDir(() => {
         fs.appendFileSync(sessionPath(sessionId), line);
@@ -78,6 +94,8 @@ export function appendToSession(sessionId, message) {
  * Update session metadata.
  */
 export function updateSessionMeta(sessionId, meta) {
+    if (persistenceDisabled)
+        return;
     withWritableSessionDir(() => {
         const existing = loadSessionMeta(sessionId);
         const updated = {

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/package.json

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